homaroma/PROJECT_DETAILS.md

รายละเอียดโปรเจกต์ DBK Platform

DBK Platform เป็นระบบ E-commerce แบบ multi-tenant / white-label สำหรับหลายประเภทธุรกิจ โดยออกแบบเป็น Monorepo ที่มี shared commerce capabilities สำหรับแต่ละ tenant. HomAroma เป็น reference tenant สำหรับสินค้า Aroma & Essential Oils ไม่ใช่ข้อจำกัดของแพลตฟอร์ม

Source of truth สำหรับคำศัพท์และขอบเขต platform/tenant: docs/PLATFORM_OVERVIEW.md

---

1. Backend (apps/backend)

ศูนย์กลางการประมวลผลและฐานข้อมูล

• เทคโนโลยีที่ใช้: Bun, Elysia.js, Prisma 7, PostgreSQL
• การทำงาน: ทำหน้าที่เป็น RESTful API Server ที่จัดการข้อมูลทั้งหมดของระบบ ตั้งแต่การตรวจสอบสิทธิ์ (Authentication), การจัดการสินค้า (Products), หมวดหมู่ (Categories), คำสั่งซื้อ (Orders) ไปจนถึงการตั้งค่าต่างๆ ของร้านค้า
• เป้าหมาย: เพื่อให้เป็นจุดเชื่อมต่อข้อมูลเดียว (Single Source of Truth) ที่มีความรวดเร็วสูงด้วย Bun และมีความปลอดภัยในการเข้าถึงข้อมูล
• การเชื่อมโยง: เชื่อมต่อกับฐานข้อมูล PostgreSQL และให้บริการ API แก่ admin, website, และ spa

2. Admin Portal (apps/admin)

ระบบจัดการหลังบ้าน (Back-office)

• เทคโนโลยีที่ใช้: React, Vite, Tailwind CSS
• การทำงาน: เป็น Web Application สำหรับผู้ดูแลระบบ (Admin) เพื่อใช้ในการจัดการสต็อกสินค้า, ดูรายงานยอดขาย, จัดการบทความ (Articles), และควบคุมการตั้งค่าหน้าร้าน
• เป้าหมาย: เพื่อให้ผู้ดูแลระบบสามารถบริหารจัดการร้านค้าได้อย่างมีประสิทธิภาพผ่าน Interface ที่ใช้งานง่าย
• การเชื่อมโยง: เชื่อมต่อกับ backend ผ่าน API เพื่อดึงและอัปเดตข้อมูลต่างๆ

3. Main Website (apps/website)

เว็บไซต์หลัก (Public Interface)

• เทคโนโลยีที่ใช้: Next.js (React), Tailwind CSS
• การทำงาน: เป็นส่วนการแสดงผลที่ใช้ Server-Side Rendering (SSR) เพื่อให้รองรับการทำ SEO (Search Engine Optimization) ได้ดีที่สุด โดยจะเน้นการแสดงสินค้าและบทความให้แก่บุคคลทั่วไป
• เป้าหมาย: เพื่อสร้างการรับรู้แบรนด์ (Brand Awareness) และช่วยให้ลูกค้าค้นหาพบผ่าน Search Engine ได้ง่าย
• การเชื่อมโยง: เชื่อมต่อกับ backend เพื่อดึงข้อมูลสินค้าและเนื้อหามาแสดงผลบนหน้าเว็บ

4. Mobile / Social-commerce SPA (apps/spa)

หน้าร้านมือถือสำหรับลูกค้า (Customer Interface)

• เทคโนโลยีที่ใช้: React, Vite, LINE Front-end Framework (LIFF), Tailwind CSS
• การทำงาน: เป็น Single Page Application (SPA) สำหรับ mobile commerce. Tenant สามารถเปิดใช้ LINE LIFF เพื่อให้ลูกค้าสั่งซื้อ ติดตามสถานะ และรับสิทธิพิเศษผ่าน LINE OA ได้
• เป้าหมาย: ให้ tenant เลือกช่องทาง mobile/social commerce ที่เหมาะกับลูกค้าและกลยุทธ์ retention
• การเชื่อมโยง: เชื่อมต่อกับ backend; การเชื่อมต่อ LINE Platform ผ่าน LIFF API เป็น tenant-specific integration

---

สรุปการเชื่อมโยงของระบบ

graph TD
    subgraph "External Platforms"
        PostgreSQL[(Database)]
        LINE[LINE Platform]
    end

    subgraph "Internal Apps"
        B[Backend - ElysiaJS]
        A[Admin - React/Vite]
        S[Main Website - Next.js]
    W[SPA - React/Vite]
    end

    A -- API Calls --> B
    S -- API Calls --> B
    W -- API Calls --> B
    W -. Tenant-specific integration .-> LINE
    B -- Query/Save --> PostgreSQL

• Backend คือหัวใจหลักที่ทุกส่วนต้องวิ่งมาหา
• Admin จัดการข้อมูลทั้งหมดผ่าน Backend
• Main Website (SSR) ดึงข้อมูลไปแสดงเพื่อผลทางด้าน Google Search/SEO
• SPA/LIFF เป็นช่องทาง social commerce ที่ tenant เปิดใช้ได้ตามความเหมาะสม

---

5. Deployment และ CI/CD ของ HomAroma reference tenant

ส่วนนี้เป็น operational runbook ของ HomAroma reference tenant. ชื่อ remote, host, PM2 process และ domain ที่มี homaroma เป็น legacy infrastructure identifiers ไม่ใช่ชื่อของ DBK Platform

โปรเจกต์นี้ใช้ระบบ Git Hooks (post-receive) ในการทำ Automated Deployment เมื่อมีการ Push โค้ดไปยังเซิร์ฟเวอร์

Git Remote Configuration

คุณสามารถส่งโค้ดขึ้นเซิร์ฟเวอร์เพื่อ Deploy ได้ผ่านคำสั่ง:

git push server master

• Remote Name: server
• Remote URL: ti@kitizone.com:/home/ti/git/homaroma.git

ขั้นตอนการทำงานของสคริปต์ Deployment (post-receive)

เมื่อมีการ Push โค้ด สคริปต์จะทำงานโดยอัตโนมัติดังนี้:

1. Checkout & Build: ดึงโค้ดล่าสุดมายังโฟลเดอร์ชั่วคราวและรัน bun install
2. Frontend Deployment:
   • Build website และ admin (Vite)
   • Deploy ไฟล์ dist ไปยัง Nginx paths (/home/ti/projects/MyNginxMain/nginx/html/homaroma.shop/)
3. Backend Deployment:
   • Sync โค้ดไปยัง /home/ti/projects/homaroma-api
   • รัน prisma generate และ prisma migrate deploy เพื่ออัปเดตฐานข้อมูล
   • Restart บริการด้วย PM2 (ชื่อ process: homaroma-backend)
4. Website (SSR) Deployment:
   • Build Next.js app และ Sync ไปยัง /home/ti/projects/homaroma-website
   • Restart บริการด้วย PM2 (ชื่อ process: homaroma-website) บนพอร์ต 3002
5. Cleanup: ลบไฟล์ชั่วคราวที่ใช้ในการ Build ออก

สรุป URL การเข้าใช้งาน (Production)

• Website (SSR Next.js): https://homaroma.shop
• SPA (LIFF Mobile App): https://spa.homaroma.shop
• Admin Panel: https://admin.homaroma.shop
• API Backend: https://api.homaroma.shop

---

6. ข้อควรปฏิบัติในการอัปเดตฐานข้อมูล (Prisma)

เพื่อให้ระบบ Deployment อัปเดตฐานข้อมูลบนเซิร์ฟเวอร์ได้อย่างถูกต้องและปลอดภัย ควรปฏิบัติตามขั้นตอนนี้:

1. ที่เครื่องคอมพิวเตอร์ของคุณ (Local):
   • ทำการแก้ไขไฟล์ apps/backend/prisma/schema.prisma ตามต้องการ
   • รันคำสั่งเพื่อสร้างไฟล์ Migration ใหม่:

     npx prisma migrate dev --name <ระบุชื่อการเปลี่ยนแปลง>
     

   • Prisma จะสร้างไฟล์ในโฟลเดอร์ apps/backend/prisma/migrations/
2. การ Commit โค้ด:
   • ต้องทำการ Commit ทั้งไฟล์ schema.prisma และ โฟลเดอร์ migrations ที่เกิดขึ้นใหม่เข้าไปใน Git ด้วยทุกครั้ง
3. การ Deploy:
   • เมื่อสั่ง git push server master ระบบ Git Hook บนเซิร์ฟเวอร์จะตรวจพบไฟล์ Migration ใหม่
   • สคริปต์จะรัน prisma migrate deploy ให้โดยอัตโนมัติ เพื่อนำความเปลี่ยนแปลงเข้าสู่ฐานข้อมูล Production โดยไม่ทำให้ข้อมูลเดิมสูญหาย