homaroma/PROJECT_SYSTEM_SUMMARY.md

ภาพรวมและสรุปรายละเอียด DBK Platform (Project Architecture & Feature Breakdown)

ประเภทโปรเจกต์: Omnichannel E-commerce & Marketing Technology (MarTech) Platform
โมเดลผลิตภัณฑ์: Multi-tenant / white-label commerce platform สำหรับหลาย verticals สถาปัตยกรรม: Monorepo (Bun Workspaces) Full-Stack TypeScript Architecture

Tenant context: HomAroma เป็น reference tenant ในกลุ่ม Aroma, Essential Oils & Home Fragrance; ตัวอย่าง vertical-specific ในเอกสารนี้ต้องตีความเป็น tenant capability ไม่ใช่ข้อกำหนดของ DBK Platform. ดู docs/PLATFORM_OVERVIEW.md

---

1. วัตถุประสงค์และภาพรวมสถาปัตยกรรม (System Architecture)

DBK Platform เป็นระบบ E-commerce และ Marketing Technology ที่ให้ shared capabilities สำหรับ tenant ในรูปแบบ Direct-to-Consumer (D2C), social commerce, marketplace integration และ back-office CRM/financial analytics. การเปิดใช้ channel, integration และ feature จริงขึ้นกับ tenant

ระบบถูกจัดโครงสร้างในรูปแบบ Monorepo โดยใช้ Bun เป็น Package Manager และแบ่ง Application ออกเป็น 5 ส่วนหลัก:

graph TD
    subgraph "External Ecosystem"
        DB[(PostgreSQL)]
        LINE[LINE OA & LIFF Platform]
        MKT[Marketplaces: TikTok / Shopee / Lazada]
        AI[AI Agents / Claude / LLM]
    end

    subgraph "DBK Platform 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, product attributes, 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)