From 8b723086b93e4d333b4ec52ee3743085a7deb401 Mon Sep 17 00:00:00 2001 From: gsinghpal Date: Wed, 1 Apr 2026 01:02:21 -0400 Subject: [PATCH] docs: add CLAUDE.md for both fusion_woocommerce and fusion-woodoo Co-Authored-By: Claude Opus 4.6 (1M context) --- fusion-woo-odoo/fusion-woodoo/CLAUDE.md | 68 +++++++++++++++++++ fusion-woo-odoo/fusion_woocommerce/CLAUDE.md | 70 ++++++++++++++++++++ 2 files changed, 138 insertions(+) create mode 100644 fusion-woo-odoo/fusion-woodoo/CLAUDE.md create mode 100644 fusion-woo-odoo/fusion_woocommerce/CLAUDE.md diff --git a/fusion-woo-odoo/fusion-woodoo/CLAUDE.md b/fusion-woo-odoo/fusion-woodoo/CLAUDE.md new file mode 100644 index 00000000..87f98245 --- /dev/null +++ b/fusion-woo-odoo/fusion-woodoo/CLAUDE.md @@ -0,0 +1,68 @@ +# Fusion WooDoo — WordPress Plugin + +## What This Is +Thin WordPress/WooCommerce plugin that pairs with the `fusion_woocommerce` Odoo module. Receives data from Odoo, displays documents in the customer My Account portal, and fires webhooks to notify Odoo of WC events. + +## Architecture +- **Receives from Odoo**: REST endpoints accept order status, invoices, deliveries, messages +- **Sends to Odoo**: WooCommerce webhooks fire on order/product/customer events +- **Displays to customers**: My Account tabs for sales orders, invoices, deliveries, returns, order timeline + +## Key Files +``` +fusion-woodoo.php — Plugin entry, activation/deactivation hooks +includes/class-fusion-woodoo.php — Singleton main class, loads all includes +includes/class-admin-settings.php — WP admin settings (Odoo URL, API key, toggles) +includes/class-rest-endpoints.php — REST API endpoints (receive from Odoo) +includes/class-webhooks.php — WC webhook registration/lifecycle +includes/class-my-account.php — My Account tab registration +includes/class-order-timeline.php — Visual order status timeline +includes/class-returns.php — Return/RMA request handling +includes/class-api-client.php — PHP client for calling Odoo API +templates/my-account/ — Customer portal templates +assets/css/my-account.css — Portal styles +assets/js/my-account.js — Portal JS (AJAX, reorder, returns) +``` + +## Authentication +- **Odoo → WP plugin**: Odoo API key as bearer token in Authorization header +- **WP plugin → Odoo**: Not direct — uses WC webhooks which Odoo validates via HMAC + +## PDF Storage +- Invoices: `wp-content/uploads/fusion-woodoo/invoices/` (`.htaccess` protected) +- Deliveries: `wp-content/uploads/fusion-woodoo/deliveries/` (`.htaccess` protected) +- Served via PHP handler that validates user owns the order + +## WordPress Options +- `fusion_woodoo_odoo_url` — Odoo instance URL +- `fusion_woodoo_api_key` — API key for Odoo auth +- `fusion_woodoo_show_sales_orders` — Toggle sales orders tab +- `fusion_woodoo_show_invoices` — Toggle invoices tab +- `fusion_woodoo_show_deliveries` — Toggle deliveries tab +- `fusion_woodoo_show_returns` — Toggle returns tab + +## WooCommerce Order Meta Keys +- `_odoo_order_id`, `_odoo_invoice_id` — Linked Odoo record IDs +- `_odoo_invoice_pdf`, `_odoo_delivery_pdf` — PDF file paths +- `_odoo_tracking_number`, `_odoo_shipping_carrier` — Shipping info +- `_odoo_order_status` — Status for timeline display +- `_odoo_messages` — JSON array of customer-visible messages + +## Deployment +```bash +# Deploy to westin WordPress +sshpass -p '9896924728Kk@@##' scp -r fusion-woo-odoo/fusion-woodoo/* westin@192.168.1.152:/tmp/fusion-woodoo/ +sshpass -p '9896924728Kk@@##' ssh westin@192.168.1.152 "echo '9896924728Kk@@##' | sudo -S cp -r /tmp/fusion-woodoo/* /home/westinwp/htdocs/westinhealthcare.ca/wp-content/plugins/fusion-woodoo/" +``` + +## Webhook Lifecycle +- Registered on plugin activation / settings save +- Unregistered on plugin deactivation +- Re-registered when Odoo URL changes +- Topics: order.created, order.updated, product.updated, customer.created, customer.updated + +## Requirements +- WordPress 6.0+ +- WooCommerce 8.0+ +- PHP 8.0+ +- Odoo 19 with fusion_woocommerce module installed diff --git a/fusion-woo-odoo/fusion_woocommerce/CLAUDE.md b/fusion-woo-odoo/fusion_woocommerce/CLAUDE.md new file mode 100644 index 00000000..94802763 --- /dev/null +++ b/fusion-woo-odoo/fusion_woocommerce/CLAUDE.md @@ -0,0 +1,70 @@ +# Fusion WooCommerce — Odoo Module + +## What This Is +Bidirectional Odoo 19 ↔ WooCommerce sync module. The "brain" — all sync logic, product mapping, scheduling, conflict resolution, and dashboards live here. Pairs with the `fusion-woodoo` WordPress plugin (thin display layer). + +## Architecture +- **Odoo calls WC** via REST API v3 (consumer key/secret auth) +- **WC calls Odoo** via webhooks (HMAC signature auth) and the WP plugin calls custom endpoints (bearer token auth) +- **Hybrid sync**: real-time webhooks + scheduled cron fallback + manual "Sync Now" + +## Critical Odoo 19 Rules +1. **Views**: `` NOT ``. `view_mode` uses `list,form` NOT `tree,form`. +2. **Search views**: NO `` wrapper — use bare `` with ``. +3. **No `attrs`**: Use inline `invisible="..."` / `readonly="..."` / `required="..."` directly. +4. **No `states`**: Use `invisible="state != 'draft'"` instead. +5. **HTTP routes**: `type="jsonrpc"` for internal. `type="http"` with `csrf=False` for WC webhooks (WC sends raw JSON, not JSON-RPC). +6. **OWL**: standalone `rpc()` from `@web/core/network/rpc`. `static props = []`. No globals like `Number()` in templates — use component methods. +7. **res.groups**: NO `category_id` field. +8. **API client in `lib/`** NOT `models/` — plain Python class, not an Odoo model. + +## Key Files +``` +lib/woo_api_client.py — WC REST API wrapper (NOT an Odoo model) +models/woo_instance.py — Core: connection config, sync methods, cron entry points +models/woo_product_map.py — Product mapping + price sync methods +models/woo_order.py — Order tracking + status push methods +controllers/webhook.py — Receives WC webhooks (type="http", HMAC auth) +controllers/api.py — REST endpoints for WP plugin (type="jsonrpc", bearer auth) +controllers/product_search.py — AJAX search for OWL mapping UI +static/src/js/product_mapping.js — OWL product mapping client action +static/src/js/dashboard.js — OWL dashboard client action +static/src/js/theme_detect.js — Reads color_scheme cookie, sets data-woo-theme on +static/src/css/woo_styles.css — Theme-aware CSS using var(--woo-*) custom properties +``` + +## Dark Mode +- Odoo 19 stores dark mode in `color_scheme` cookie ("dark" or "bright") +- `theme_detect.js` reads the cookie and sets `data-woo-theme="dark"` on `` +- All CSS uses `var(--woo-*)` custom properties with dark overrides under `html[data-woo-theme="dark"]` +- NEVER use hardcoded colours in templates — use `woo-badge-*`, `woo-text-muted`, `woo-code` classes +- NEVER use Bootstrap colour classes (`bg-primary`, `text-dark`, etc.) in OWL templates + +## WC Pricing Model +- WooCommerce has two prices: `regular_price` (standard) and `sale_price` +- Stored as `woo_regular_price` and `woo_sale_price` on `woo.product.map` +- Sync logic: if standard price is zero → sync sets regular_price. If standard exists → sync sets sale_price +- Standard price can never be less than sale price — validation enforced + +## Deployment +```bash +# Deploy to westin +ssh odoo-westin "rm -rf /opt/odoo/custom-addons/fusion_woocommerce" +scp -r fusion-woo-odoo/fusion_woocommerce odoo-westin:/opt/odoo/custom-addons/fusion_woocommerce +ssh odoo-westin "docker exec odoo-dev-app odoo -d westin-v19 -u fusion_woocommerce --stop-after-init --no-http" + +# IMPORTANT: Clear asset cache after JS/CSS changes +ssh odoo-westin "docker exec odoo-dev-db psql -U odoo -d westin-v19 -c \"DELETE FROM ir_attachment WHERE name LIKE '%assets_backend%' OR url LIKE '%/web/assets%';\"" +ssh odoo-westin "docker restart odoo-dev-app" +``` + +## Gotchas +- Health check cron only logs — never changes instance state (Docker can't reach external URLs) +- Product map state stays `mapped` even on sync errors/conflicts — conflicts tracked separately in `woo.conflict` +- Search endpoints return `{"results": [...], "total": count}` for pagination +- Existing products are skipped during fetch (dedup by `woo_product_id` + `instance_id`) +- After adding new DB fields, must run `-u fusion_woocommerce` before backfilling data + +## Spec & Plan +- Design spec: `docs/superpowers/specs/2026-03-31-fusion-woo-odoo-design.md` +- Implementation plan: `docs/superpowers/plans/2026-03-31-fusion-woo-odoo-plan.md`