MetatroncubeSoftwareSolutions/dine360-social-commerce
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

remove project handover document

Browse Source
This commit is contained in:
Alaguraj0361 2026-09-12 21:27:10 +05:30
parent d618c97918
commit a63af39ab3
1 changed files with 0 additions and 292 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

292
HANDOVER.md
View File

@ -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 `<field name="hs_code"/>`.
- 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 `<field name="hs_code"/>`, 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 `<g:availability>in stock</g:availability>`.
- 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: "^<production_db_name>$"` 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://<domain>/social/whatsapp/webhook` returns HTTP 403 (Method Not Allowed / Forbidden without challenge parameters).
- Verify Catalog Feed route: `curl -I https://<domain>/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 <db> -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://<domain>/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://<domain>/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)