MetatroncubeSoftwareSolutions/dine360-social-commerce

Alaguraj0361 d618c97918 first commit: Dine360 Meta, Instagram & WhatsApp Social Commerce integration for Odoo 17

2026-09-12 21:25:05 +05:30

22 KiB

Raw Blame History

Project Handover Document

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:

Meta / Facebook Commerce Catalog (Graph API v19.0 Batch Sync + RSS 2.0 XML / JSON Catalog Feed)
Instagram Shopping (discovery tagged on Instagram linking directly to Odoo product URLs and checkout)
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:
```
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.
- 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.

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 and 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 and 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 and 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:

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:

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

Go to Social Commerce > Dashboard.
Click Test Meta Connection to check Catalog ID and Token validity.
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

Navigate to Social Commerce > WhatsApp > Order Notifications.
Filter by Failed.
Click into the record to inspect the error message (e.g. invalid phone number, unapproved template).
Click Retry Dispatch once the underlying issue is resolved.

How to Monitor Customer Inquiries

Navigate to Social Commerce > WhatsApp > Customer Inquiries.
Inbound WhatsApp messages are automatically logged, matched to the customer partner by phone number, and linked to their sales order if mentioned.
Staff can view the customer chat history and order context directly in Odoo.

6. Verification Artifacts & Reference Links

Setup Documentation: SOCIAL_COMMERCE_SETUP.md
Full Test Report: SOCIAL_COMMERCE_TEST_REPORT.md
Interactive Visual Walkthrough: walkthrough.md
Backend Video Recording: social_commerce_demo.webp
Frontend Store Video: frontend_shop_wa.webp
Bug Fix Verification Video: verify_hs_code_fix.webp

22 KiB Raw Blame History