From 198d85e3404df652469e38f775f212b74658a4fa Mon Sep 17 00:00:00 2001 From: Alaguraj0361 Date: Sat, 12 Sep 2026 21:28:25 +0530 Subject: [PATCH] docs: add comprehensive client handover document --- CLIENT_HANDOVER.md | 179 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 179 insertions(+) create mode 100644 CLIENT_HANDOVER.md diff --git a/CLIENT_HANDOVER.md b/CLIENT_HANDOVER.md new file mode 100644 index 0000000..f958b0c --- /dev/null +++ b/CLIENT_HANDOVER.md @@ -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:///social/meta/catalog_feed.xml` (RSS 2.0 / Google Merchant format). + * **JSON Catalog Feed**: Accessible at `https:///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:///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:///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*: ___________________________