diff --git a/HANDOVER.md b/HANDOVER.md deleted file mode 100644 index 5f06bcc..0000000 --- a/HANDOVER.md +++ /dev/null @@ -1,292 +0,0 @@ -# Project Handover Document -# Dine360 Social Commerce Integration (Odoo 17) - -**Document Version**: 1.0 -**Date**: September 12, 2026 -**System**: Odoo 17.0 Community (`odoo:17.0-20260217`, Python 3.10.12, PostgreSQL 15) -**Database**: `Antalya` (Port: `10050:8069`) -**Custom Module**: `dine360_meta_social` - ---- - -## 1. Executive Summary - -This handover document summarizes the architecture, configuration, operational procedures, and production launch checklist for the **Dine360 Social Commerce** integration on Odoo 17. - -The integration connects Odoo 17 eCommerce with: -1. **Meta / Facebook Commerce Catalog** (Graph API v19.0 Batch Sync + RSS 2.0 XML / JSON Catalog Feed) -2. **Instagram Shopping** (discovery tagged on Instagram linking directly to Odoo product URLs and checkout) -3. **WhatsApp Business Platform / Cloud API** (customer inquiries, automated order lifecycle notifications, bidirectional webhook, and communication history) - -### Authoritative Architecture Rule -Odoo remains the **sole source of truth** for: -* Products, variants, and product categories -* Pricing and currency -* Inventory and stock levels -* Customer contacts and delivery addresses -* Sales orders and fulfillment tracking - -All external API interactions are asynchronous and non-blocking: network issues or API failures from Meta/WhatsApp never interrupt Odoo eCommerce checkout, product page rendering, POS, or inventory movements. - ---- - -## 2. Codebase & Module Structure - -The custom module is located at: -`d:\ODOO\odoo antalya\addons\dine360_meta_social` - -``` -dine360_meta_social/ -├── __init__.py -├── __manifest__.py # Depends: base, web, website, website_sale, sale, stock, phone_validation -├── controllers/ -│ ├── __init__.py -│ ├── whatsapp_webhook.py # GET verification & POST event receiver (/social/whatsapp/webhook) -│ └── meta_feed.py # RSS 2.0 XML & JSON Product Feed (/social/meta/catalog_feed.xml) -├── models/ -│ ├── __init__.py -│ ├── res_company.py # Credentials for Meta and WhatsApp per company -│ ├── website.py # Multi-website overrides and chat URL builder -│ ├── res_config_settings.py # Configuration screens under Social Commerce -│ ├── product_template.py # Catalog sync fields, write/unlink triggers -│ ├── product_product.py # Retailer ID, variant sync payload builder -│ ├── sale_order.py # Order confirmed & processing notification triggers -│ ├── stock_picking.py # Order shipped notification trigger & stock move sync -│ ├── social_meta_catalog.py # Meta Commerce Graph API v19.0 client -│ ├── social_meta_sync_queue.py # Resilient asynchronous queue & retry engine -│ ├── social_whatsapp_api.py # WhatsApp Cloud API client (templates, text, signatures) -│ ├── social_whatsapp_template.py # Mapping Odoo business events to approved Meta templates -│ ├── social_whatsapp_notification.py # Full notification audit log & deduplication engine -│ ├── social_whatsapp_message.py # Inbound customer chat log & order matching -│ └── social_commerce_dashboard.py # Executive KPI dashboard & live test buttons -├── views/ -│ ├── menu_views.xml # Top-level "Social Commerce" menu & submenus -│ ├── social_dashboard_views.xml # Executive Command Center dashboard -│ ├── res_config_settings_views.xml# Settings screen for Meta & WhatsApp -│ ├── product_views.xml # Product form/tree sync badges & buttons -│ ├── sale_order_views.xml # Sale order WhatsApp tab & smart button -│ ├── whatsapp_template_views.xml # WhatsApp template configuration views -│ ├── whatsapp_notification_views.xml # Notification log & retry view -│ ├── whatsapp_message_views.xml # Customer chat log view -│ ├── social_sync_queue_views.xml # Meta sync queue view -│ └── website_whatsapp_templates.xml # Frontend floating & product page buttons -├── data/ -│ ├── whatsapp_template_data.xml # Default template mappings (confirmed, processing, shipped, delivered) -│ └── cron_data.xml # Automated crons (Catalog sync: 15m, WhatsApp retry: 5m) -├── security/ -│ ├── social_security.xml # Groups: Social User, Social Administrator -│ └── ir.model.access.csv # ACL rules for all models -├── static/ -│ ├── description/ -│ │ └── icon.png # App icon -│ └── src/ -│ ├── css/ -│ │ └── social_commerce.css # Floating button pulse animations & product page styling -│ └── js/ -│ └── whatsapp_button.js # Dynamic quantity & variant attribute tracking -└── tests/ - ├── __init__.py - ├── test_meta_sync.py # Meta payload, queue, price trigger unit tests - └── test_whatsapp.py # WhatsApp template, signature, deduplication unit tests -``` - ---- - -## 3. Handover Issue Resolutions & Technical Fixes - -During implementation, local testing, and user verification, several critical platform behaviors and edge cases were identified and permanently resolved. Below is the complete technical breakdown of each fix: - -### 3.1 Owl Error Fix: `"product.product"."hs_code" field is undefined` -* **Symptom**: When clicking on a product variant form view (`product.product`) from the Meta Sync Queue or Product Variants menu, Odoo's frontend crashed with the following error: - ``` - UncaughtPromiseError > OwlError - Error: "product.product"."hs_code" field is undefined. - at odoo.define.Field.parseFieldNode (web.assets_web.min.js) - ``` -* **Root Cause Analysis**: - - In standard Odoo 17, `stock_delivery` is an auto-install module depending on `sale_stock` and `delivery`. - - While initial base dependencies were loading, the XML view `stock_delivery.product_template_hs_code` had been inserted into `ir.ui.view` containing ``. - - However, the Python model extension in `stock_delivery` (which defines the ORM fields `hs_code` and `country_of_origin` on `product.template` and `product.product`) had not been initialized in the database registry. - - When Owl (Odoo's web client) loaded the form view, it parsed the XML node ``, but the field metadata did not exist in the client model definition, triggering a fatal lifecycle exception. -* **Direct Database Fix**: - 1. Executed full installation of `stock_delivery` into database `Antalya`: - ```bash - docker exec -i odoo_client50 odoo -d Antalya --db_host db --db_user odoo --db_password odoo -i stock_delivery --stop-after-init - ``` - 2. Verified fields `hs_code` and `country_of_origin` are registered in PostgreSQL and model registries. - 3. Restarted `odoo_client50` container to refresh web client registry cache. -* **Architectural Prevention (Code Level)**: - - Added `'stock_delivery'` to the `'depends'` list in [__manifest__.py](file:///d:/ODOO/odoo%20antalya/addons/dine360_meta_social/__manifest__.py). - - Any future installation or deployment of `dine360_meta_social` on clean databases will automatically install and initialize `stock_delivery` and its dependencies without manual intervention. -* **Verification**: - - Re-tested opening product variant `[MED-PLATTER-01] Antalya Mediterranean Platter`; view opened instantly with zero errors. - - Recorded browser verification session: [verify_hs_code_fix.webp](file:///C:/Users/LENOVO/.gemini/antigravity-ide/brain/8acb8378-f8ca-4bf7-a10c-56740729d844/verify_hs_code_fix_1789201524328.webp). - -### 3.2 Multi-Database Routing & Docker DBFILTER Fix -* **Symptom**: Incoming unauthenticated HTTP requests from external platforms (such as Meta's Webhook verification GET `/social/whatsapp/webhook` and Meta Commerce Catalog Feed pull `/social/meta/catalog_feed.xml`) were redirected to Odoo's database selector or returned HTTP 404/500 errors. -* **Root Cause**: - - In `docker-compose.yml`, the environment variable was set to `DBFILTER: "^aakriti$"`. - - When incoming requests arrive without an existing session cookie, Odoo matches the Host header or regex against `DBFILTER`. Because `aakriti` did not match the active database `Antalya`, Odoo could not select a database and refused to execute public controller routes. -* **Fix Applied**: - - Updated `docker-compose.yml` to `DBFILTER: ".*"` (or `DBFILTER: "^Antalya$"` for single-tenant production). - - Restarted the Odoo container. -* **Verification**: - - Executed automated curl tests against `/social/whatsapp/webhook` and `/social/meta/catalog_feed.xml`. Requests routed directly to `Antalya` with HTTP 200 success. - -### 3.3 International Phone Sanitization & Contact Matching -* **Symptom**: WhatsApp Cloud API sends incoming message notifications with sender phone numbers in raw international digit format (e.g. `15552345678`), while customer contacts in Odoo may have formatted strings such as `+1 (555) 234-5678`, `(555) 234-5678`, or `0555 234 5678`. -* **Fix Applied**: - - Implemented dual-strategy lookup in [social_whatsapp_message.py](file:///d:/ODOO/odoo%20antalya/addons/dine360_meta_social/models/social_whatsapp_message.py) and [whatsapp_webhook.py](file:///d:/ODOO/odoo%20antalya/addons/dine360_meta_social/controllers/whatsapp_webhook.py): - 1. Standard E.164 sanitized match against `phone_sanitized` (`+15552345678`). - 2. Fallback normalization using regex `re.sub(r'\D', '', phone)` across all partner records to strip non-digit characters and match the trailing 10 digits. -* **Verification**: - - Verified inbound customer messages match the correct partner record (`Sarah Customer`) regardless of telephone number formatting. - -### 3.4 Consumable / Restaurant Dish Stock Availability in Meta Feed -* **Symptom**: In restaurant and food service eCommerce, menu items are frequently configured as Consumables (`detailed_type == 'consu'`) or Services (`'service'`) because exact stock tracking is not used. Standard eCommerce inventory checks look for `qty_available > 0`, which caused all consumables to be exported as `"out of stock"`. -* **Fix Applied**: - - In [product_product.py](file:///d:/ODOO/odoo%20antalya/addons/dine360_meta_social/models/product_product.py) and [meta_feed.py](file:///d:/ODOO/odoo%20antalya/addons/dine360_meta_social/controllers/meta_feed.py), added product type detection: - - Consumables (`'consu'`) and Services (`'service'`) are automatically exported as `in stock`. - - Storable products (`'product'`) check live warehouse inventory (`qty_available > 0` = `in stock`, `<= 0` = `out of stock`). -* **Verification**: - - Checked `/social/meta/catalog_feed.xml`: food items correctly export as `in stock`. - -### 3.5 Non-Blocking Architecture & Webhook Deduplication Safeguard -* **Symptom**: Meta WhatsApp Cloud API retries webhooks if responses take longer than 3 seconds or if network drops occur. Without deduplication, duplicate notifications or chat messages could be created. Additionally, any external Meta API downtime could potentially freeze checkout. -* **Fix Applied**: - - All external API calls in [social_meta_catalog.py](file:///d:/ODOO/odoo%20antalya/addons/dine360_meta_social/models/social_meta_catalog.py) and [social_whatsapp_api.py](file:///d:/ODOO/odoo%20antalya/addons/dine360_meta_social/models/social_whatsapp_api.py) are wrapped in `try...except` with strict 10s timeouts. Failures are captured in queue records and never propagate to block Odoo checkout or order confirmation. - - Implemented deduplication on Meta message ID (`wamid`) in `social.whatsapp.message`. - - Implemented deduplication on `(order_id, event_type)` in `social.whatsapp.notification` to prevent double-messaging customers when sales orders are re-saved. -* **Verification**: - - Unit tests `test_03_order_confirmation_notification_dispatch` and `test_04_inbound_message_processing_and_order_matching` confirmed 100% duplicate suppression. - ---- - -## 4. Production Launch Checklist - -Before opening the system to public traffic, complete this comprehensive 6-phase checklist: - -### 4.1 Phase 1: Hosting, Reverse Proxy & SSL Configuration -- [ ] **Valid SSL/TLS Certificate**: Meta requires HTTPS signed by a recognized Certificate Authority (Let's Encrypt, Cloudflare, DigiCert). Self-signed certificates are rejected by Meta Cloud API and Commerce Manager. -- [ ] **Reverse Proxy (Nginx/Caddy) Headers**: Configure proxy headers so Odoo detects HTTPS correctly: - ```nginx - proxy_set_header Host $http_host; - proxy_set_header X-Forwarded-Host $http_host; - proxy_set_header X-Forwarded-Proto https; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - ``` -- [ ] **Odoo Proxy Mode Enabled**: Ensure `proxy_mode = True` in `/etc/odoo/odoo.conf` so canonical product links in feeds and WhatsApp notifications generate with `https://`. -- [ ] **Multi-Worker Configuration**: In `odoo.conf`, set `workers = 2` (or more) so cron tasks (e.g. batch catalog sync) execute on dedicated worker threads without starving HTTP requests. -- [ ] **Docker DBFILTER**: Ensure `docker-compose.yml` has `DBFILTER: "^$"` so unauthenticated webhook and feed requests resolve directly to the production database without triggering the database selector. -- [ ] **Public Endpoint Reachability**: - - Verify Webhook route: `curl -I https:///social/whatsapp/webhook` returns HTTP 403 (Method Not Allowed / Forbidden without challenge parameters). - - Verify Catalog Feed route: `curl -I https:///social/meta/catalog_feed.xml` returns HTTP 200 with `Content-Type: text/xml`. - -### 4.2 Phase 2: Codebase & Dependency Verification -- [ ] **Core Dependencies Installed**: Ensure `stock_delivery` is installed (`odoo -d -i stock_delivery --stop-after-init`) or pulled in via `dine360_meta_social` manifest. -- [ ] **Python Libraries**: Ensure `requests`, `cryptography`, and `phonenumbers` are installed in the container environment: - ```bash - docker exec -it odoo_client50 python3 -c "import requests, cryptography, phonenumbers; print('Dependencies OK')" - ``` -- [ ] **Background Cron Services Active**: - - `Dine360: Meta Commerce Catalog Synchronizer` (Model: `social.meta.sync.queue`, Interval: 15 minutes, Active: Yes). - - `Dine360: WhatsApp Notification Retry Service` (Model: `social.whatsapp.notification`, Interval: 5 minutes, Active: Yes). - -### 4.3 Phase 3: Meta Commerce & Instagram Shopping Launch -- [ ] **Meta Business Portfolio Active**: Verified business account on Meta Business Suite (`business.facebook.com`). -- [ ] **Permanent System User Created**: In **Business Settings > Users > System Users**, create a System User (Admin role) and generate a permanent token with: - - `catalog_management` - - `business_management` -- [ ] **Catalog Assigned to System User**: In Meta Commerce Manager > **Settings > Permissions**, assign the System User as Catalog Admin. -- [ ] **Catalog Credentials in Odoo**: - - In Odoo at **Social Commerce > Configuration > Settings**, enter: - - `Meta App ID` - - `Meta App Secret` - - `Meta System User Access Token` - - `Meta Commerce Catalog ID` -- [ ] **Test Meta Connection**: Click **Test Meta Connection** on the **Social Commerce Dashboard** and verify the green status. -- [ ] **Scheduled Data Feed in Meta**: - - In Meta Commerce Manager > **Catalog > Data Sources > Data Feeds**, add scheduled pull: - - URL: `https:///social/meta/catalog_feed.xml` - - Frequency: Hourly or Daily - - Currency: Matches Odoo company currency (e.g. USD, EUR, TRY) -- [ ] **Initial Catalog Population**: Click **Sync All Published Products Now** in Odoo Settings, and monitor **Sync Queue & Retries** until all items are in `done` state. -- [ ] **Instagram Business Account Connected**: Link Instagram Business Account to the Facebook Page and Commerce Catalog. -- [ ] **Domain Verification**: Verify your eCommerce domain under **Meta Business Settings > Brand Safety > Domains**. -- [ ] **Instagram Shopping Review**: Submit catalog for Instagram Shopping approval in Commerce Manager. - -### 4.4 Phase 4: WhatsApp Business Platform (Cloud API) Launch -- [ ] **WABA & Phone Number Active**: Official WhatsApp Business Account registered and phone number verified in Meta Developer Portal. -- [ ] **Permanent Token Permissions**: System User Token granted: - - `whatsapp_business_messaging` - - `whatsapp_business_management` -- [ ] **WhatsApp Credentials in Odoo**: - - Enter `WhatsApp Business Account ID (WABA ID)`, `Phone Number ID`, and `Webhook Verify Token` in Odoo Settings. -- [ ] **Meta Webhook Setup**: - - In Meta Developer Portal > WhatsApp > Configuration: - - Callback URL: `https:///social/whatsapp/webhook` - - Verify Token: Matches `whatsapp_verify_token` in Odoo - - Subscribed Fields: `messages`, `message_template_status_update` -- [ ] **Meta Message Templates Approved**: Submit and verify approval for all 4 transactional templates under category `UTILITY`: - - `order_confirmation_v1` (Variables: Customer Name, Order Ref, Total Amount, Details URL) - - `order_preparation_v1` (Variables: Customer Name, Order Ref) - - `order_shipped_v1` (Variables: Customer Name, Order Ref, Carrier, Tracking Reference) - - `order_delivered_v1` (Variables: Customer Name, Order Ref) -- [ ] **Template Mappings Verified in Odoo**: - - Under **Social Commerce > WhatsApp > Template Mappings**, ensure template names and language codes (`en_US`, `en`, etc.) match Meta approvals exactly. -- [ ] **Test WhatsApp API**: Click **Test WhatsApp API** on the **Social Commerce Dashboard** and confirm green status. -- [ ] **Live Notification Dispatch Test**: - - Place a test eCommerce order, confirm the order, validate delivery, and verify automated WhatsApp message delivery on a real mobile device. -- [ ] **Inbound Chat & Auto-Matching Test**: - - Reply to the WhatsApp message from the mobile device; verify message is logged under **Social Commerce > WhatsApp > Customer Inquiries** and linked to the partner. - -### 4.5 Phase 5: Frontend Storefront & User Experience -- [ ] **WhatsApp Contact Number**: Enter public customer support number in international format without `+` (e.g. `15551234567`) in Odoo Settings. -- [ ] **Floating Widget Verification**: Check that floating WhatsApp pulse button appears on all storefront pages (`/shop`, `/`, etc.) with responsive hover tooltip. -- [ ] **Product Page Button Verification**: Check that "Chat on WhatsApp" button appears near *Add to Cart* on single product pages. -- [ ] **Dynamic Variant & Quantity Tracking**: Verify that selecting variant attributes (size, options) or changing quantity updates the pre-filled WhatsApp message URL in real time. -- [ ] **Mobile Responsiveness**: Verify on iOS Safari and Android Chrome that clicking the button launches the native WhatsApp app seamlessly. - -### 4.6 Phase 6: Monitoring, Security & Maintenance -- [ ] **Security Group Audit**: Verify that only system administrators belong to `Social Commerce / Administrator` (`group_social_manager`). Store operators should only belong to `Social Commerce / User` (`group_social_user`). -- [ ] **Token Masking Verified**: Verify that tokens and secrets are masked with `password="True"` in settings and never printed in standard Odoo logs. -- [ ] **Dead-Letter Queue Process**: Train store operations staff to review: - - **Social Commerce > WhatsApp > Order Notifications** (Filter: `Failed`) - - **Social Commerce > Meta & Instagram > Sync Queue & Retries** (Filter: `Failed`) -- [ ] **Automated Database Backups**: Confirm that regular PostgreSQL database dumps (`pg_dump`) and Odoo filestore backups are scheduled. - ---- - -## 5. Operational Runbook - -### How to Test Connections -1. Go to **Social Commerce > Dashboard**. -2. Click **Test Meta Connection** to check Catalog ID and Token validity. -3. Click **Test WhatsApp API** to verify Phone Number ID and messaging credentials. - -### How to Force an Immediate Product Sync -* **Single Product**: Open the product in backend, go to the **Meta / Instagram Catalog** tab, and click **Sync to Meta Catalog** in the header. -* **All Products**: Go to **Social Commerce > Dashboard** and click **Sync Products to Meta** (or in Settings, click **Sync All Published Products Now**). - -### How to Handle Failed Notifications -1. Navigate to **Social Commerce > WhatsApp > Order Notifications**. -2. Filter by **Failed**. -3. Click into the record to inspect the error message (e.g. invalid phone number, unapproved template). -4. Click **Retry Dispatch** once the underlying issue is resolved. - -### How to Monitor Customer Inquiries -1. Navigate to **Social Commerce > WhatsApp > Customer Inquiries**. -2. Inbound WhatsApp messages are automatically logged, matched to the customer partner by phone number, and linked to their sales order if mentioned. -3. Staff can view the customer chat history and order context directly in Odoo. - ---- - -## 6. Verification Artifacts & Reference Links - -* **Setup Documentation**: [SOCIAL_COMMERCE_SETUP.md](file:///d:/ODOO/odoo%20antalya/SOCIAL_COMMERCE_SETUP.md) -* **Full Test Report**: [SOCIAL_COMMERCE_TEST_REPORT.md](file:///d:/ODOO/odoo%20antalya/SOCIAL_COMMERCE_TEST_REPORT.md) -* **Interactive Visual Walkthrough**: [walkthrough.md](file:///C:/Users/LENOVO/.gemini/antigravity-ide/brain/8acb8378-f8ca-4bf7-a10c-56740729d844/walkthrough.md) -* **Backend Video Recording**: [social_commerce_demo.webp](file:///C:/Users/LENOVO/.gemini/antigravity-ide/brain/8acb8378-f8ca-4bf7-a10c-56740729d844/social_commerce_demo_1789198084830.webp) -* **Frontend Store Video**: [frontend_shop_wa.webp](file:///C:/Users/LENOVO/.gemini/antigravity-ide/brain/8acb8378-f8ca-4bf7-a10c-56740729d844/frontend_shop_wa_1789198742990.webp) -* **Bug Fix Verification Video**: [verify_hs_code_fix.webp](file:///C:/Users/LENOVO/.gemini/antigravity-ide/brain/8acb8378-f8ca-4bf7-a10c-56740729d844/verify_hs_code_fix_1789201524328.webp)