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

docs: add comprehensive client handover document

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

179
CLIENT_HANDOVER.md Normal file
View File

@ -0,0 +1,179 @@
# Client Handover Document
# Dine360 Social Commerce Integration (Odoo 17)
**Client / Project**: Dine360 – Antalya Mediterranean Restaurant & eCommerce
**System**: Odoo 17.0 Community / Enterprise
**Integration Module**: `dine360_meta_social`
**Date**: September 2026
**Target Audience**: Store Owners, eCommerce Managers, Customer Support Teams, and Marketing Directors
---
## 1. Welcome & Executive Overview
Welcome to your new **Dine360 Social Commerce** integration suite! This system seamlessly connects your existing Odoo 17 eCommerce website with the world's three largest social sales channels:
1. **Meta / Facebook Commerce Catalog**
2. **Instagram Shopping**
3. **WhatsApp Business Platform / Cloud API**
### The Core Principle: Odoo as the Single Source of Truth
To prevent inventory discrepancies, overselling, and pricing mismatches, **Odoo remains the sole and final authority** for:
* **Product Catalog**: Titles, descriptions, images, variants (sizes, options), and categories.
* **Pricing & Currency**: List prices, taxes, discounts, and currency settings.
* **Inventory & Stock**: Real-time warehouse availability.
* **Customer Contacts**: Customer names, phone numbers, delivery addresses, and message logs.
* **Orders & Invoices**: Order confirmations, payment receipts, kitchen/warehouse preparation, and delivery tracking.
Whenever you create a product, update a price, or sell an item in Odoo, the integration automatically synchronizes those changes with your Meta Catalog and Instagram Shop.
---
## 2. Key Features Delivered
### 2.1 Meta Commerce & Facebook Shop Catalog
* **Automated Product Sync**: Any changes to product price, description, images, or availability are automatically enqueued and synced to Meta Commerce Manager.
* **Multi-Format Product Feeds**:
* **Scheduled XML Data Feed**: Accessible at `https://<yourdomain>/social/meta/catalog_feed.xml` (RSS 2.0 / Google Merchant format).
* **JSON Catalog Feed**: Accessible at `https://<yourdomain>/social/meta/catalog_feed.json`.
* **Smart Stock Rules**: Restaurant dishes and food menu items marked as consumables are automatically maintained as "In Stock", while packaged goods strictly reflect live inventory.
### 2.2 Instagram Shopping
* **Product Tagging**: Tag items from your Odoo catalog in your Instagram posts, reels, and stories.
* **Direct Checkout Link**: Customers tapping an Instagram product tag are routed directly to the product's checkout page on your Odoo eCommerce store.
### 2.3 WhatsApp Business Platform (Cloud API)
* **Automated Order Lifecycle Notifications**:
* 🔔 **Order Confirmed**: Sent automatically as soon as an online order is placed and paid for.
* 🍳 **In Preparation**: Sent when the kitchen or fulfillment team begins processing the order.
* 🚚 **Order Shipped**: Sent when the delivery driver departs or shipment tracking is generated.
* ✅ **Order Delivered**: Sent upon successful delivery confirmation.
* **Anti-Spam Deduplication**: Prevents duplicate WhatsApp messages if orders or shipments are edited or re-saved.
* **Two-Way Customer Inquiries**:
* When customers message your WhatsApp number, messages are logged directly in Odoo under **Social Commerce > WhatsApp > Customer Inquiries**.
* Customer phone numbers are automatically linked to their existing customer profile.
* Order numbers mentioned in the chat (e.g. `SO00123`) are automatically linked to the corresponding Sales Order.
### 2.4 Storefront Experience
* **Floating WhatsApp Button**: Pulsing circular WhatsApp button fixed to the bottom-right corner of all web pages with a hover tooltip (*"Chat with our team on WhatsApp"*).
* **Product Page "Chat on WhatsApp" Button**: Located beside the *Add to Cart* button on `/shop` product pages. Clicking it opens WhatsApp with a pre-filled inquiry:
> *"Hi, I'm interested in Antalya Mediterranean Platter (http://.../shop/product/...)"*
* **Dynamic Variant Updates**: Selecting different sizes or changing quantities dynamically updates the pre-filled inquiry text.
* **Mobile Ready**: Seamlessly opens the native WhatsApp app on iPhone (iOS) and Android devices.
### 2.5 Executive Command Center Dashboard
* Located in your Odoo backend under **Social Commerce > Dashboard**.
* Live statistics: Total Products Synced, WhatsApp Messages Dispatched, Customer Inquiries Logged.
* One-click action buttons:
* **Test Meta Connection**: Verifies your Meta Catalog access token.
* **Sync Products to Meta**: Forces an immediate sync of all published products.
* **Test WhatsApp API**: Verifies your WhatsApp Cloud API connection.
* **Retry Failed Operations**: Retries any queued items that failed due to temporary network issues.
---
## 3. Store Staff Daily Operations Guide
### 3.1 How to Add or Update a Product for Social Commerce
1. Go to **Website > eCommerce > Products** (or **Social Commerce > Meta & Instagram > Published Products**).
2. Create or open an existing product.
3. Ensure the product is marked as **Published** on Website.
4. Go to the **Meta / Instagram Catalog** tab:
* **Include in Meta Catalog**: Checked by default for published products.
* **Google Product Category**: Select the relevant category (e.g. `Food, Beverages & Tobacco`).
* **Item Condition**: Defaults to `New`.
5. Click **Save**.
6. The system automatically enqueues the product for sync to Meta Commerce Manager within 15 minutes.
7. *Need it on Instagram immediately?* Click the **Sync to Meta Catalog** button in the top action bar.
### 3.2 How Order Notifications Work
1. **New Order Arrives**: When a customer completes checkout on `/shop`, the order is confirmed.
2. **Instant Message**: A WhatsApp notification is sent to the customer's phone number containing their order reference, total amount, and order status URL.
3. **Fulfillment Update**: When delivery staff validate the shipment in Odoo Inventory, the customer automatically receives the "Order Shipped" WhatsApp notification with tracking details.
4. **Audit Trail**: Every message sent is recorded in **Social Commerce > WhatsApp > Order Notifications** with delivery status, timestamp, and message ID.
### 3.3 How to View & Respond to Customer Inquiries
1. Open **Social Commerce > WhatsApp > Customer Inquiries**.
2. Staff can see all incoming customer questions, the sender phone number, the customer profile, and any related sales order.
3. Staff can click **Reply via WhatsApp** to open a direct WhatsApp chat window with the customer.
---
## 4. Account Setup & Meta Credentials Checklist
To connect your live store to your official Meta accounts, the following credentials must be configured:
### 4.1 Meta Business Manager Requirements
| Requirement | Where to Find in Meta | Configured in Odoo |
| :--- | :--- | :--- |
| **Meta App ID** | Meta Developer Portal > App Dashboard | **Social Commerce > Settings > Meta App ID** |
| **Meta App Secret** | Meta Developer Portal > App Settings > Basic | **Social Commerce > Settings > Meta App Secret** |
| **System User Token** | Business Settings > Users > System Users (Admin Token) | **Social Commerce > Settings > System User Token** |
| **Commerce Catalog ID** | Meta Commerce Manager > Catalog Settings | **Social Commerce > Settings > Catalog ID** |
| **Scheduled Data Feed URL** | Odoo Public URL | Add `https://<domain>/social/meta/catalog_feed.xml` in Commerce Manager Data Sources |
### 4.2 WhatsApp Business Platform Requirements
| Requirement | Where to Find in Meta | Configured in Odoo |
| :--- | :--- | :--- |
| **WhatsApp Phone Number** | Meta Developer Portal > WhatsApp > API Setup | **Social Commerce > Settings > Public WhatsApp Number** |
| **Phone Number ID** | Meta Developer Portal > WhatsApp > API Setup | **Social Commerce > Settings > Phone Number ID** |
| **WABA ID** | Meta Developer Portal > WhatsApp > API Setup | **Social Commerce > Settings > WABA ID** |
| **Webhook Callback URL** | Meta Developer Portal > WhatsApp > Configuration | Enter `https://<domain>/social/whatsapp/webhook` |
| **Webhook Verify Token** | Chosen secret token (e.g. `dine360_wa_token_secret`) | Enter matching token in both Meta and Odoo Settings |
### 4.3 Pre-Approved WhatsApp Message Templates
Meta requires transactional message templates to be submitted for approval under the `UTILITY` category:
1. `order_confirmation_v1`: Variables: `{{1}}` (Customer Name), `{{2}}` (Order Ref), `{{3}}` (Total), `{{4}}` (Order URL).
2. `order_preparation_v1`: Variables: `{{1}}` (Customer Name), `{{2}}` (Order Ref).
3. `order_shipped_v1`: Variables: `{{1}}` (Customer Name), `{{2}}` (Order Ref), `{{3}}` (Carrier), `{{4}}` (Tracking Number).
4. `order_delivered_v1`: Variables: `{{1}}` (Customer Name), `{{2}}` (Order Ref).
---
## 5. Frequently Asked Questions (FAQ)
### Q1: What happens if Meta or WhatsApp servers go down?
**A**: Your Odoo store will continue operating normally! Checkout, orders, payments, POS, and inventory movements will **never be blocked**. The system enqueues notifications and catalog updates, logging any network errors, and retries automatically once connectivity is restored.
### Q2: A customer claims they did not receive their WhatsApp notification. What should I check?
1. Open **Social Commerce > WhatsApp > Order Notifications**.
2. Search for the customer's Sales Order reference (e.g. `SO00123`).
3. Check the **Status**:
* If `sent`: The message was successfully dispatched by Meta's servers.
* If `failed`: Click on the record to view the error reason (e.g., phone number invalid, recipient not on WhatsApp, or unapproved template).
* If resolved, click **Retry Dispatch** to resend the message immediately.
### Q3: How do I change the public WhatsApp support number?
1. Navigate to **Social Commerce > Configuration > Settings**.
2. Under the **WhatsApp Business Cloud API** section, update the **Public WhatsApp Number** (enter in international format without `+` or spaces, e.g. `15551234567`).
3. Click **Save**. The floating button and product page inquiry buttons will immediately route to the new number.
### Q4: How long does it take for a new product to appear on Instagram?
* Direct sync events are sent to Meta's Batch API within 15 minutes.
* Scheduled data feeds run automatically every hour/day according to your Commerce Manager schedule.
* Once received by Meta, Instagram typically reviews and displays new catalog items within 1 to 2 hours.
---
## 6. Support & Reference Documentation
* **Technical Handover & Runbook**: [HANDOVER.md](HANDOVER.md)
* **Production Setup & Credentials Guide**: [SOCIAL_COMMERCE_SETUP.md](SOCIAL_COMMERCE_SETUP.md)
* **Quality Assurance Test Report**: [SOCIAL_COMMERCE_TEST_REPORT.md](SOCIAL_COMMERCE_TEST_REPORT.md)
* **Code Repository**: `https://git.metatroncube.in/MetatroncubeSoftwareSolutions/dine360-social-commerce.git`
---
## 7. Client Acceptance & Handover Sign-Off
| Milestone / Deliverable | Status | Verified By | Date |
| :--- | :--- | :--- | :--- |
| **Meta Commerce Catalog Integration** | Delivered & Tested | | |
| **Instagram Shopping Setup Readiness** | Delivered & Tested | | |
| **WhatsApp Automated Order Notifications** | Delivered & Tested | | |
| **Two-Way Webhook & Customer Chat Logs** | Delivered & Tested | | |
| **Floating & Product Page WhatsApp Buttons** | Delivered & Tested | | |
| **Executive KPI Dashboard & Controls** | Delivered & Tested | | |
| **Client Documentation & Training Runbook** | Delivered | | |
*Sign-Off Signature*: ___________________________
*Date*: ___________________________