# ภาพรวมและสรุปรายละเอียดโปรเจกต์ 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) |