dine360-social-commerce/README.md

Dine360 Social Commerce Integration for Odoo 17

A production-ready social commerce integration suite for Odoo 17 eCommerce, connecting your store with:

1. Meta / Facebook Commerce Catalog (Graph API v19.0 Batch Sync & RSS 2.0 XML / JSON Scheduled Data Feed)
2. Instagram Shopping (Product tagging linking directly to canonical Odoo eCommerce product pages and checkout)
3. WhatsApp Business Platform / Cloud API (Customer inquiries, dynamic product inquiry pre-fills, automated order notifications with deduplication, and inbound chat history)

---

Authoritative Architecture Rule

Odoo remains the sole single source of truth for:

• Products & Variants: Attributes, images, descriptions, barcodes.
• Pricing: Currency, list price, taxes, and promotional pricelists.
• Inventory: Stock availability, warehouse quant movements.
• Customers: Contact details, delivery addresses, communication logs.
• Orders: Order states (draft → sent → sale → done / cancel), delivery tracking, invoices.

All external API calls to Meta and WhatsApp are asynchronous and non-blocking. Network latency or third-party API downtime will never disrupt Odoo eCommerce checkout, POS, or inventory operations.

---

Features

1. Meta Commerce Catalog Sync

• Real-Time Queue: Auto-enqueues sync events whenever a product's price, stock, variant, or publication status changes.
• Batch Graph API v19.0 Client: Sends up to 5,000 items per batch request to Meta's /items_batch endpoint.
• Scheduled Data Feed:
  • RSS 2.0 XML Product Feed: /social/meta/catalog_feed.xml
  • JSON Product Feed: /social/meta/catalog_feed.json
• Product Type Awareness: Automatically exports consumables (consu) and services (service) as in stock, while accurately reflecting warehouse inventory for storable products (product).

2. Instagram Shopping

• Canonical URLs generated from Odoo's website configuration for seamless shopping tags.
• Google Product Category (g:google_product_category), condition, and availability standard attributes supported.

3. WhatsApp Business Cloud API Integration

• Automated Order Lifecycle Notifications:
  • Order Confirmed: Triggered upon sale order confirmation / online checkout payment.
  • Order In Preparation: Triggered during kitchen/warehouse order processing.
  • Order Shipped: Triggered upon validation of stock delivery picking.
  • Order Delivered: Triggered upon completion of customer delivery.
• Deduplication Safeguard: Automatically suppresses duplicate messages if orders or shipments are re-saved.
• Bi-Directional Webhook (/social/whatsapp/webhook):
  • GET: Meta challenge verification with token authentication.
  • POST: Inbound message listener with HMAC-SHA256 signature verification (X-Hub-Signature-256).
• Customer Chat & Inquiries:
  • Incoming customer WhatsApp messages are logged in Odoo.
  • Smart sender phone matching against phone_sanitized and normalized regex numbers.
  • Automatic regex extraction of order references (e.g., SO00123).

4. Storefront UI Widgets

• Floating WhatsApp Button: Circular pulsating button fixed to the bottom-right corner of public storefront pages with responsive hover tooltip.
• Product Page Inquiry Button: Positioned beside Add to Cart on /shop product pages. Pre-fills message with product title and canonical store link.
• Dynamic Variant Tracking: Variant attribute selections and quantity changes dynamically update the WhatsApp chat URL in real time.

5. Executive Command Center Dashboard

• Real-time metrics: Catalog Sync Count, WhatsApp Notification Stats, Customer Inquiry Counter.
• Live Action Buttons:
  • Test Meta Connection
  • Sync Products to Meta
  • Test WhatsApp API
  • Retry Failed Operations

---

Repository Structure

dine360-social-commerce/
├── addons/
│   └── dine360_meta_social/       # Core Odoo 17 Custom Module
│       ├── __manifest__.py        # Dependencies: base, web, website, website_sale, sale, stock, phone_validation, stock_delivery
│       ├── controllers/
│       │   ├── meta_feed.py       # XML & JSON Catalog Feeds
│       │   └── whatsapp_webhook.py# Webhook challenge & event receiver
│       ├── models/                # Business logic & API clients
│       │   ├── product_product.py
│       │   ├── product_template.py
│       │   ├── res_company.py
│       │   ├── res_config_settings.py
│       │   ├── sale_order.py
│       │   ├── social_commerce_dashboard.py
│       │   ├── social_meta_catalog.py
│       │   ├── social_meta_sync_queue.py
│       │   ├── social_whatsapp_api.py
│       │   ├── social_whatsapp_message.py
│       │   ├── social_whatsapp_notification.py
│       │   ├── social_whatsapp_template.py
│       │   ├── stock_picking.py
│       │   └── website.py
│       ├── views/                 # Backend views, menus & dashboards
│       ├── static/                # CSS animations & frontend JS
│       ├── data/                  # Crons & default template data
│       ├── security/              # Access control lists & user groups
│       └── tests/                 # Unit & integration test suite (12/12 passing)
├── docker-compose.yml             # Local deployment setup (Odoo 17 + PostgreSQL 15)
├── HANDOVER.md                    # Detailed architectural handover & bug fix notes
├── SOCIAL_COMMERCE_SETUP.md       # Step-by-step credentials & configuration runbook
└── SOCIAL_COMMERCE_TEST_REPORT.md # Test matrix & verification logs

---

Quickstart (Docker)

1. Start Environment:

   docker-compose up -d
   

2. Access Odoo:
   • URL: http://localhost:10050
   • Storefront: http://localhost:10050/shop
3. Install / Upgrade Module:

   docker exec -it odoo_client50 odoo -d Antalya -u dine360_meta_social --stop-after-init
   

---

Running Automated Tests

Run the built-in unit and integration test suite:

docker exec -it odoo_client50 odoo -d Antalya --test-enable --test-tags /dine360_meta_social --stop-after-init

---

Documentation

• Project Handover & Architecture
• Production Setup & Credentials Guide
• Quality Assurance & Test Report

---

License

This software is licensed under the LGPL-3.0 License.