homaroma/PROJECT_DETAILS.md

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

โปรเจกต์นี้เป็นระบบ E-commerce สำหรับผลิตภัณฑ์เครื่องหอมและน้ำมันหอมระเหย (Aroma & Essential Oils) โดยมีการออกแบบสถาปัตยกรรมแบบ Monorepo ที่แบ่งส่วนการทำงานออกเป็น 4 ส่วนหลักในโฟลเดอร์ apps/ ดังนี้:

---

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, ssr, และ website

2. Admin Portal (apps/admin)

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

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

3. Main Website (apps/ssr)

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

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

4. LIFF Mobile App (apps/website)

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

• เทคโนโลยีที่ใช้: React, Vite, LINE Front-end Framework (LIFF), Tailwind CSS
• การทำงาน: เป็น Single Page Application (SPA) ที่ออกแบบมาเพื่อรันภายในแอปพลิเคชัน LINE โดยเฉพาะ ลูกค้าสามารถสั่งซื้อสินค้า, ติดตามสถานะคำสั่งซื้อ, และรับสิทธิพิเศษต่างๆ ได้ทันทีผ่าน LINE OA
• เป้าหมาย: เพื่อความสะดวกสบายของลูกค้าในการเข้าถึงร้านค้าผ่านช่องทางที่คุ้นเคย (LINE) และสร้างความผูกพันกับลูกค้า (Customer Loyalty)
• การเชื่อมโยง: เชื่อมต่อกับ LINE Platform ผ่าน LIFF API และเชื่อมต่อกับ backend เพื่อทำรายการสั่งซื้อและจัดการข้อมูลสมาชิก

---

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

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[LIFF App - React/Vite]
    end

    A -- API Calls --> B
    S -- API Calls --> B
    W -- API Calls --> B
    W -- Integration --> LINE
    B -- Query/Save --> PostgreSQL

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

---

5. การ Deployment และ CI/CD

โปรเจกต์นี้ใช้ระบบ 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. SSR Deployment:
   • Build Next.js app และ Sync ไปยัง /home/ti/projects/homaroma-ssr
   • Restart บริการด้วย PM2 (ชื่อ process: homaroma-ssr) บนพอร์ต 3001
5. Cleanup: ลบไฟล์ชั่วคราวที่ใช้ในการ Build ออก

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

• Website (SPA): https://homaroma.shop
• Admin Panel: https://admin.homaroma.shop
• API Backend: https://api.homaroma.shop
• SSR Next.js: https://ssr.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 โดยไม่ทำให้ข้อมูลเดิมสูญหาย