x

PROJECT_SYSTEM_SUMMARY.md

@@ -0,0 +1,161 @@
+# ภาพรวมและสรุปรายละเอียดโปรเจกต์ HomAroma (Project Architecture & Feature Breakdown)
+
+> **ประเภทโปรเจกต์:** Omnichannel E-commerce & Marketing Technology (MarTech) Platform  
+> **หมวดหมู่ธุรกิจ:** Aroma, Essential Oils & Home Fragrance  
+> **สถาปัตยกรรม:** Monorepo (Bun Workspaces) Full-Stack TypeScript Architecture  
+
+---
+
+## 1. วัตถุประสงค์และภาพรวมสถาปัตยกรรม (System Architecture)
+
+**HomAroma** เป็นระบบ E-commerce และ Marketing Technology ครบวงจรที่พัฒนาขึ้นมาเพื่อตอบโจทย์ทั้งฝั่ง **Direct-to-Consumer (D2C)**, **Social Commerce บน LINE**, **Omnichannel Marketplace Integration (TikTok, Shopee, Lazada)** และระบบหลังบ้าน **Back-office CRM & Financial Analytics**
+
+ระบบถูกจัดโครงสร้างในรูปแบบ **Monorepo** โดยใช้ Bun เป็น Package Manager และแบ่ง Application ออกเป็น 5 ส่วนหลัก:
+
+```mermaid
+graph TD
+    subgraph "External Ecosystem"
+        DB[(PostgreSQL)]
+        LINE[LINE OA & LIFF Platform]
+        MKT[Marketplaces: TikTok / Shopee / Lazada]
+        AI[AI Agents / Claude / LLM]
+    end
+
+    subgraph "HomAroma Monorepo"
+        API["apps/backend<br/>(Bun + Elysia.js + Prisma 7)"]
+        ADMIN["apps/admin<br/>(React + Vite + D3.js)"]
+        WEB["apps/website<br/>(Next.js App Router SSR / SEO)"]
+        SPA["apps/spa<br/>(React + Vite + LINE LIFF)"]
+        MCP["apps/mcp-server<br/>(Model Context Protocol for AI)"]
+        TYPES["packages/types<br/>(Shared Data Contracts)"]
+    end
+
+    ADMIN -- REST API --> API
+    WEB -- REST API --> API
+    SPA -- REST API --> API
+    SPA -- Integration --> LINE
+    MCP -- Stdio / Tool Calls --> API
+    AI -- Agent Operations --> MCP
+    API -- Ingestion & Reconcile --> MKT
+    API -- Query / Mutate --> DB
+```
+
+---
+
+## 2. เจาะลึกความสามารถของแต่ละแอปพลิเคชัน (Application Details)
+
+### 2.1 Next.js Main Website (`apps/website`) — Public SEO & D2C Storefront
+ทำหน้าที่เป็นหน้าร้านหลักที่เน้นการทำ **Search Engine Optimization (SEO)** และสร้าง Brand Awareness:
+* **Next.js App Router & Server-Side Rendering (SSR):** โหลดรวดเร็ว รองรับ Web Vitals และ Bot ของ Search Engine ทุกประเภท
+* **Internationalization (i18n):** รองรับระบบหลายภาษาผ่าน Dynamic Route `/[lang]/...` (รองรับ th, en, ja, zh, vi, ko, lo, it)
+* **SEO Automation & Structured Data:**
+  - สร้าง Dynamic `sitemap.ts` และ `robots.ts` อัตโนมัติ
+  - รองรับ OpenGraph (OG), Twitter Card และ Schema.org (JSON-LD) สำหรับ Product, Breadcrumb และ Article
+* **Dynamic Headless Page Builder:** ระบบเรนเดอร์เนื้อหาจาก Database (`DynamicPageRenderer.tsx`) แสดงผล Component ต่างๆ ได้อย่างยืดหยุ่น เช่น Hero Banner, Editorial Carousels, Scent Profile Breakdown, Interactive Sticky Purchase Bar, Wishlist และ FAQ Accordion
+* **E-commerce Client Experience:**
+  - Dynamic Cart Drawer
+  - คูปองส่วนลดและระบบโปรโมชันอัตโนมัติ
+  - หน้า Checkout รองรับแนบสลิปชำระเงินและแจ้งโอน
+  - ระบบค้นหาและตัวกรองตามกลิ่น/คุณลักษณะ (Attribute Filters)
+
+---
+
+### 2.2 LINE Official Account (LINE OA) & LIFF Mobile App (`apps/spa`) — Social Commerce & Automated CRM
+ระบบถูกออกแบบมาเพื่อผสานเข้ากับ **LINE Ecosystem** อย่างสมบูรณ์แบบ ทั้งในส่วนของหน้าร้านบนมือถือ (LIFF) และระบบสื่อสารอัตโนมัติผ่านแชท (LINE Messaging API):
+
+#### 1. Seamless LINE Login & Auto-Authentication (LIFF SDK)
+* **Zero-Friction Registration:** เมื่อลูกค้าคลิกลิงก์จาก LINE OA หรือ Rich Menu ระบบจะทำการ Auto-login ด้วย `lineUserId` อัตโนมัติ โดยไม่ต้องให้ลูกค้าพิมพ์ Username/Password หรือจำรหัสผ่าน
+* **Customer Profile Sync:** ดึง Display Name และรูปโปรไฟล์จาก LINE เข้าสู่ฐานข้อมูลลูกค้า (`Customer`) ทันที พร้อมสร้างบัญชีสมาชิกให้โดยอัตโนมัติ
+
+#### 2. Automated Messaging API & Rich Flex Messages (ระบบแจ้งเตือนอัตโนมัติผ่าน LINE Chat)
+ระบบมีการเชื่อมต่อ **LINE Messaging API (`@line/bot-sdk`)** เพื่อยิงข้อความแบบ **Flex Message** ดีไซน์เฉพาะตัว สวยงามเหมือนการ์ดแอปพลิเคชัน แจ้งเตือนลูกค้าในทุกขั้นตอนของ Customer Journey:
+* **🔔 Order Created Notification:** ส่งการ์ดแจ้งยอดชำระ สรุปรายการสินค้า และเลขที่บัญชีธนาคารทันทีหลังกดสั่งซื้อ พร้อมปุ่ม Call-to-Action "แนบสลิปชำระเงิน" และ "ติดตามสถานะออเดอร์" ที่คลิกแล้วเปิดหน้าเว็บทำรายการต่อได้ทันที
+* **✨ Payment Confirmed & Points Notification:** เมื่อแอดมินหรือระบบอนุมัติสลิปโอนเงิน ระบบจะส่ง Flex Message ขอบคุณ พร้อมแจ้งแต้มสะสมที่ได้รับเพิ่มในออเดอร์นั้น (`+points`) และยอดคะแนนสะสมรวมทั้งหมด พร้อมปุ่มพาลูกค้าไปหน้า "แลกของรางวัล & คูปองสะสม"
+* **🚚 Order Shipped Notification:** เมื่อพัสดุถูกจัดส่ง ระบบจะยิงข้อความแจ้งเตือนพร้อมแสดง **Tracking Number** และปุ่ม "เช็คสถานะการจัดส่ง" แบบ 1-Click
+* **🚫 Order Cancelled & Auto-Refund Points:** หากคำสั่งซื้อถูกยกเลิก (เช่น เกินเวลาชำระเงิน) ระบบจะแจ้งเตือนพร้อมดำเนินการ **คืนแต้มสะสม (Refund Points)** กลับเข้ากระเป๋าลูกค้าทันทีโดยอัตโนมัติ
+
+#### 3. Social Commerce & Customer Loyalty Experience
+* **Loyalty Points Engine:** คำนวณแต้มสะสมตามยอดใช้จ่ายจริง (กำหนด Earn Rate ได้จากหลังบ้าน) ลูกค้าสามารถนำแต้มสะสมมาใช้เป็นส่วนลดเงินสดได้ในขั้นตอน Checkout
+* **Coupon & Promotion Wallet:** รองรับการใช้โค้ดส่วนลด โปรโมชันตามขั้นบันได (Tiered Promotions) และโค้ดส่งฟรี
+* **Customer Address Book:** บันทึกที่อยู่จัดส่งเริ่มต้น (Default Address) ของลูกค้าไว้ในระบบ ไม่ต้องพิมพ์ซ้ำเมื่อกลับมาซื้อใหม่
+* **Mobile Slip Upload:** ถ่ายรูปหรือแนบสลิปการโอนเงินผ่านมือถือได้ทันที ไม่ต้องสลับหน้าจอไปส่งในแชท
+
+#### 4. LINE Webhook Architecture & Security
+* รองรับ Webhook Signature Verification (`x-line-signature` ด้วย HMAC-SHA256) เพื่อความปลอดภัยสูงสุด ป้องกันข้อความปลอมแปลง
+* สถาปัตยกรรมรองรับการต่อยอดเป็น Interactive Chatbot และการ Broadcast ข้อความเฉพาะกลุ่ม (Audience-targeted Broadcast)
+
+---
+
+### 2.3 Admin Portal (`apps/admin`) — Back-office, MarTech & Financial Analytics
+ศูนย์บัญชาการธุรกิจสำหรับผู้บริหารและทีมการตลาด รวบรวมฟังก์ชันบริหารจัดการและ Data Analytics ขั้นสูง:
+
+#### ก. Marketing & CRM Suite
+1. **Predictive Repeat Customers Dashboard & Action Plan:**
+   - ระบบตรวจจับรอบการซื้อซ้ำของลูกค้า (`avgIntervalDays`) และทำนายวันที่ลูกค้าจะกลับมาซื้อใหม่ (`predictedNextOrderDate`)
+   - แบ่งกลุ่มลูกค้าตามสถานะความเสี่ยง:
+     - `VIP Rewards`: ลูกค้าชั้นดี ยอดซื้อสะสมสูง
+     - `Due Soon (Restock)`: สินค้าใกล้หมดตามสถิติ ต้องทักเตือน
+     - `Overdue / Churn Risk`: ลูกค้าหลุดรอบการซื้อเฉลี่ย ต้องดึงกลับด้วย Win-back Voucher
+     - `Healthy / Nurturing`: อยู่ในรอบปกติ ส่งคอนเทนต์สร้างสัมพันธ์
+   - **One-click Personalized Copywriting:** สร้างข้อความและคูปองเฉพาะบุคคล (เช่น RESTOCK10, COMEBACK20, VIPHOMAROMA) พร้อมปุ่ม Copy สคริปต์ไปส่งแชทได้ทันที
+   - **CRM Pipeline Tracking:** บันทึกสถานะการติดต่อ (Pending, Contacted, Converted, Unresponsive) พร้อมประวัติ Activity Logs
+2. **Geographic Sales Intelligence (Spatial Maps with D3.js):**
+   - แผนที่ยอดขายภูมิศาสตร์แบบ Vector SVG (Interactive Pan & Zoom, Choropleth Heatmap):
+     - **Thailand Sales Map:** เจาะลึกระดับ 77 จังหวัด
+     - **Malaysia Sales Map:** ครอบคลุม 13 รัฐ และเจาะลึก 160 เขต (Daerah)
+     - **Vietnam Sales Map:** ครอบคลุม 63 จังหวัด และเจาะลึก 708 อำเภอ (Quận/Huyện)
+   - ช่วยให้ทีมการตลาดทำ Geo-targeted Advertising (เช่น Facebook/TikTok Ads Location Targeting) ได้อย่างแม่นยำ
+
+#### ข. Marketplace Multi-channel Financials
+1. **Marketplace Ingestion & Settlement Reconciliation:**
+   - ดึงข้อมูล Order, SKU และ Settlement จาก **TikTok Shop, Shopee, Lazada**
+   - ตรวจสอบค่าธรรมเนียมจริง: Commission Fee, Affiliate Commission, Platform Growth Fee, Shipping Discounts
+   - คำนวณ Net Settlement (เงินเข้าบัญชีจริง) เปรียบเทียบกับ Gross Revenue
+2. **TikTok Price & Profit Simulator:**
+   - เครื่องมือจำลองราคาขายและโปรโมชัน ช่วยคำนวณกำไรสุทธิ (Net Margin) และจุดคุ้มทุน (Break-even) ทันทีหลังหักค่าธรรมเนียมแพลตฟอร์ม
+
+#### ค. Product & COGS Management
+1. **Master Catalog & SKU Mapping:** เชื่อมโยง SKU บนแต่ละมาร์เก็ตเพลสเข้าสู่ Master Product Catalog เดียวกัน เพื่อตัดสต็อกและวิเคราะห์ยอดขายรวม
+2. **Bill of Materials (BOM) & Raw Material Costing:**
+   - ผูกสูตรวัตถุดิบ (`RawMaterial`) เข้ากับสินค้า (`ProductVariant`)
+   - คำนวณต้นทุนสินค้าจริง (COGS) อัตโนมัติ เพื่อให้เห็น Gross Margin แท้จริงของแต่ละ SKU
+
+#### ง. Headless CMS & Visual Design Tokens
+1. **Dynamic Page Builder:** สร้างและแก้ไขหน้า Landing Page, จัดลำดับ Section, เพิ่มแบนเนอร์และวิดีโอแบบ Drag & Drop
+2. **Theme Customization Engine:** ปรับแต่ง Color Palette, Font Family, Header Layout, Scroll Reveal Animation ได้จากหน้าบ้านโดยไม่ต้องแก้โค้ด
+
+---
+
+### 2.4 High-Performance Backend API (`apps/backend`)
+* **Bun + Elysia.js:** เฟรมเวิร์กประสิทธิภาพสูง ประมวลผลเร็ว รองรับปริมาณ Traffic สูงด้วยการกินทรัพยากรที่ต่ำ
+* **Prisma 7 ORM & PostgreSQL:** โครงสร้างข้อมูลแบบ Relational แข็งแกร่ง รองรับการทำ Indexing, Foreign Keys, Cascades และ Audit Fields
+* **Modular Domain Architecture:**
+  - `businessAnalytics.ts` (ระบบประมวลผลสถิติและแผนที่ยอดขาย)
+  - `crm.ts` (ระบบจัดการลูกค้าสัมพันธ์และ Action Plan)
+  - `tiktokOrder.ts`, `shopee.ts`, `lazadaOrder.ts` (ประมวลผลข้อมูลมาร์เก็ตเพลส)
+  - `products.ts`, `orders.ts`, `coupons.ts`, `promotions.ts`, `payments.ts`
+
+---
+
+### 2.5 Model Context Protocol Server (`apps/mcp-server`) — AI-driven E-commerce
+* **Autonomous AI Tooling:** พัฒนาระบบเชื่อมต่อกับ AI Agents ผ่านมาตรฐาน Model Context Protocol (MCP)
+* ให้ AI (เช่น Claude หรือ Cursor/Antigravity) สามารถ:
+  - บริหารจัดการโครงสร้าง Mega Menu ข้ามภาษา
+  - อัปเดตข้อมูลสินค้าและแปลภาษาอัตโนมัติ (Automated Localization)
+  - บริหารจัดการเนื้อหาบน Page Builder ผ่าน Natural Language Command
+
+---
+
+## 3. สรุป Tech Stack ทั้งระบบ
+
+| Layer | เทคโนโลยีที่เลือกใช้ |
+| :--- | :--- |
+| **Runtime & Package Manager** | Bun (Monorepo Workspaces) |
+| **Backend Framework** | Elysia.js (TypeScript) |
+| **Database & ORM** | PostgreSQL, Prisma 7 |
+| **Main Website (D2C/SEO)** | Next.js 15 (App Router, SSR, Server Components), Tailwind CSS |
+| **Mobile App (LINE Commerce)** | React, Vite, LINE Front-end Framework (LIFF), Tailwind CSS |
+| **Admin Portal** | React, Vite, Tailwind CSS, D3.js (`d3-geo`), Lucide Icons |
+| **Data Visualization & GIS** | D3-geo, SVG Vector Maps, GeoJSON (Thailand, Malaysia, Vietnam) |
+| **AI Integration** | Model Context Protocol (MCP SDK, stdio transport) |
+| **DevOps & Infrastructure** | Linux, Nginx, PM2, Git Post-receive Hooks (Zero-downtime Deploy) |