# Dine360 Social Commerce Integration for Odoo 17

[![Odoo Version](https://img.shields.io/badge/Odoo-17.0%20Community%20%2F%20Enterprise-875A7B.svg)](https://www.odoo.com/)
[![License](https://img.shields.io/badge/License-LGPL--3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0.html)
[![Meta Graph API](https://img.shields.io/badge/Meta%20Graph%20API-v19.0-0668E1.svg)](https://developers.facebook.com/)
[![WhatsApp Cloud API](https://img.shields.io/badge/WhatsApp%20Cloud%20API-v19.0-25D366.svg)](https://developers.facebook.com/docs/whatsapp/cloud-api)

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**:
   ```bash
   docker-compose up -d
   ```
2. **Access Odoo**:
   * URL: `http://localhost:10050`
   * Storefront: `http://localhost:10050/shop`
3. **Install / Upgrade Module**:
   ```bash
   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:
```bash
docker exec -it odoo_client50 odoo -d Antalya --test-enable --test-tags /dine360_meta_social --stop-after-init
```

---

## Documentation

* [Project Handover & Architecture](HANDOVER.md)
* [Production Setup & Credentials Guide](SOCIAL_COMMERCE_SETUP.md)
* [Quality Assurance & Test Report](SOCIAL_COMMERCE_TEST_REPORT.md)

---

## License

This software is licensed under the [LGPL-3.0 License](https://www.gnu.org/licenses/lgpl-3.0.html).