docs: add tenant specification and domain blueprints for kittisak.com

2026-09-24 04:45:01 +07:00
1 parent 960ba2a0e8
commit 9fab97f0d8
@@ -0,0 +1,45 @@
+# Kittisak.com — Project Specification & Domain Blueprint
+
+เอกสารภาพรวมโครงการ วัตถุประสงค์ทางธุรกิจ สถาปัตยกรรมระบบ และข้อมูลทางเทคนิคของโดเมน `kittisak.com`
+
+---
+
+## 1. ข้อมูลทั่วไปและเป้าหมายโครงการ (Project Vision & Goals)
+
+- **Domain Name:** `kittisak.com`
+- **Tenant ID / Project Key:** `kittisak`
+- **ประเภทเว็บไซต์:** E-Commerce Platform & Digital Storefront (Next.js SSR + React SPA + Headless CMS Backend)
+- **วัตถุประสงค์หลัก:**
+  1. สร้างร้านค้าออนไลน์สำหรับแสดงและจำหน่ายสินค้า รองรับการทำ SEO คุณภาพสูง
+  2. มอบประสบการณ์การสั่งซื้อที่สะดวกสบายทั้งผ่าน Web Browser ทั่วไป และผ่าน **LINE Official Account (LIFF SPA)**
+  3. มีระบบจัดการหลังบ้าน (Admin CMS) สำหรับควบคุมสต็อก, ออเดอร์, คูปองส่วนลด และปรับแต่งเนื้อหาหน้าร้านได้อย่างยืดหยุ่น
+
+---
+
+## 2. โครงสร้างบริการและโดเมน (Service & URL Architecture)
+
+| Subdomain | บทบาทหน้าที่ (Service Role) | เทคโนโลยีหลัก (Tech Stack) | พอร์ตภายใน / โฟลเดอร์ |
+|---|---|---|---|
+| **`kittisak.com`** | Website หน้าบ้านหลัก สำหรับผู้เยี่ยมชมทั่วไปและ Search Engine (SEO) | Next.js SSR (Standalone) | Port `3005` (PM2: `kittisak-website`) |
+| **`spa.kittisak.com`** | Web App น้ำหนักเบา ออกแบบสำหรับเปิดใน LINE LIFF และ Mobile | React + Vite SPA | Static Nginx: `/html/kittisak/spa` |
+| **`admin.kittisak.com`** | ระบบจัดการหลังบ้านสำหรับผู้ดูแลร้าน (Admin Panel) | React + Vite SPA | Static Nginx: `/html/kittisak/admin` |
+| **`api.kittisak.com`** | REST API Backend, Authentication & Database Service | Bun + Elysia / Express + Prisma | Port `3054` (PM2: `kittisak-backend`) |
+
+---
+
+## 3. ข้อมูลสถาปัตยกรรมเซิร์ฟเวอร์ (Infrastructure & Environment)
+
+- **Host Server:** `ti@kitizone.com` (Ubuntu 24.04 LTS)
+- **Git Remote:** `ti@kitizone.com:/home/ti/git/kittisak.com.git` (Bare Repository + Auto Deploy Post-Receive Hook)
+- **ฐานข้อมูล:** PostgreSQL Database `kittisakdb` (เชื่อมต่อผ่าน Docker Container `arokro_postgres` พอร์ต `5132`)
+- **SSL Certificates:** Let's Encrypt Consolidated SAN Certificate (`/etc/letsencrypt/live/kittisak.com/fullchain.pem`)
+- **Reverse Proxy:** Dockerized Nginx (`/home/ti/projects/MyNginxMain/nginx/conf.d/*.kittisak.com.conf`)
+
+---
+
+## 4. โครงสร้างเอกสารในโฟลเดอร์นี้
+
+1. [brand-identity.md](file:///c:/Users/ti/git/homaroma/docs/tenants/kittisak.com/brand-identity.md) — รายละเอียดโทนสี (Theme Tokens), โลโก้, ฟอนต์, และการตั้งค่า SEO Metadata
+2. [user-flows.md](file:///c:/Users/ti/git/homaroma/docs/tenants/kittisak.com/user-flows.md) — แผนผังเส้นทางการใช้งานของลูกค้า (Customer Journey), สมาชิก LINE, และการจัดการของผู้ดูแลระบบ
+3. [integrations.md](file:///c:/Users/ti/git/homaroma/docs/tenants/kittisak.com/integrations.md) — การตั้งค่าระบบชำระเงิน (Omise), ระบบสมาชิก LINE OA (LIFF), และการติดตามพัสดุ
+4. [Runbook Deployment](file:///c:/Users/ti/git/homaroma/KITTISAK_DEPLOYMENT_RUNBOOK.md) — คู่มือคำสั่งการ Deploy และกู้คืนระบบ
@@ -0,0 +1,49 @@
+# Brand Identity & Theme Specification — Kittisak.com
+
+เอกสารกำหนดอัตลักษณ์ของแบรนด์ โทนสี ธีม ดีไซน์ และการตั้งค่า SEO Metadata สำหรับ `kittisak.com`
+
+---
+
+## 1. ข้อมูลแบรนด์และสโลแกน (Brand Profile)
+
+- **ชื่อแบรนด์ (Brand Name):** Kittisak Official Store
+- **สโลแกน / Positioning:** Premium Quality Products & Modern Shopping Experience
+- **ภาษาที่รองรับ (Languages):**
+  - ภาษาไทย (`th`) — ภาษาหลัก
+  - ภาษาอังกฤษ (`en`)
+  - ภาษาญี่ปุ่น (`ja`), ภาษาจีน (`zh`), ภาษาเวียดนาม (`vi`), ภาษาเกาหลี (`ko`)
+
+---
+
+## 2. โทนสีและการตั้งค่าธีม (Theme Tokens & Color Palette)
+
+ระบบรองรับการปรับแต่งธีมสีผ่าน Admin Panel (CMS Theme Settings) โดยใช้ตัวแปร CSS Tokens:
+
+| Token Name | ค่าแนะนำเริ่มต้น (Default) | ตัวอย่างการใช้งาน (Usage) |
+|---|---|---|
+| `--color-primary` | `#0f172a` (Slate 900) | สีหลักของแบรนด์, Navigation Bar, Header, Main Buttons |
+| `--color-secondary` | `#475569` (Slate 600) | สีข้อความรอง, Subtitles, Borders, Icons |
+| `--color-accent` | `#d97706` (Amber 600) | สีเน้นจุดเด่น, Badges, Promotion Tag, Call-to-Action |
+| `--color-background` | `#ffffff` (Light) / `#090d16` (Dark) | พื้นหลังหลักของหน้าเว็บ |
+| `--color-surface` | `#f8fafc` | พื้นหลังของ Card, Modal, Dropdown |
+
+---
+
+## 3. รูปภาพและสื่ออัตลักษณ์ (Brand Assets)
+
+- **Logo:**
+  - Desktop Logo: แนะนำสัดส่วน `4:1` หรือ `3:1` (เช่น `240x60px` หรือ SVG)
+  - Mobile / LIFF Header: แนะนำสัดส่วน `1:1` หรือ `2:1` (เช่น `120x60px`)
+- **Favicon:** `favicon.ico` / `favicon.png` (`32x32px`, `192x192px`)
+- **Open Graph Banner (Social Share):** ขนาด `1200x630px` สำหรับแสดงพรีวิวเมื่อแชร์ลิงก์ใน LINE / Facebook
+
+---
+
+## 4. มาตรฐาน SEO & Meta Tags
+
+- **Default Page Title:** `Kittisak | ร้านค้าออนไลน์และสินค้าคุณภาพระดับพรีเมียม`
+- **Default Meta Description:** `เลือกซื้อสินค้าคุณภาพระดับพรีเมียมจาก Kittisak Official พร้อมโปรโมชั่นพิเศษ สั่งซื้อง่ายและปลอดภัย จัดส่งรวดเร็วทั่วประเทศ`
+- **Canonical URL:** `https://kittisak.com/th`
+- **Robots.txt & Sitemap:**
+  - Sitemap: `https://kittisak.com/sitemap.xml`
+  - Robots: Allow all search engine bots for public routes (`/th/*`, `/en/*`)
@@ -0,0 +1,56 @@
+# Third-Party Integrations & Configurations — Kittisak.com
+
+เอกสารบันทึกรายละเอียดการเชื่อมต่อระบบภายนอก (Third-Party Services) คีย์สภาพแวดล้อม และสถานะการเปิดใช้งานสำหรับ `kittisak.com`
+
+---
+
+## 1. การเชื่อมต่อระบบชำระเงิน (Omise Payment Gateway)
+
+ระบบรองรับการรับชำระเงินผ่าน PromptPay QR และ Credit/Debit Card:
+
+- **สถานะปัจจุบัน:** รอการตั้งค่า Production Key
+- **ตัวแปรสภาพแวดล้อมที่ต้องใช้:**
+  - `OMISE_SECRET_KEY`: กำหนดใน `/home/ti/projects/kittisak-api/.env`
+  - `VITE_OMISE_PUBLIC_KEY`: กำหนดใน Environment ก่อน Build SPA (`apps/spa`)
+- **Webhook Endpoint:**
+  - URL: `https://api.kittisak.com/api/payments/webhook`
+  - Events ที่ต้อง Subscribe: `charge.complete`, `charge.create`
+
+---
+
+## 2. การเชื่อมต่อ LINE Official Account (LIFF & Messaging API)
+
+ระบบรองรับการล็อกอินอัตโนมัติผ่าน LINE LIFF และการส่งแจ้งเตือนสถานะออเดอร์:
+
+- **LINE LIFF App URL:** `https://spa.kittisak.com`
+- **ตัวแปรสภาพแวดล้อมที่เกี่ยวข้อง:**
+  - `VITE_LIFF_ID`: ID ของ LIFF App ที่สร้างใน LINE Developers Console
+  - `LINE_CHANNEL_SECRET`: ใช้สำหรับตรวจสอบความถูกต้องของ Webhook / Signature
+  - `LINE_CHANNEL_ACCESS_TOKEN`: ใช้สำหรับส่ง Push Message แจ้งสถานะสินค้าหาลูกค้า
+
+---
+
+## 3. การเชื่อมต่อระบบจัดส่งและติดตามพัสดุ (Logistics & Tracking)
+
+ระบบมีโมดูล Order Tracking ในตัว รองรับขนส่งหลักในประเทศไทย:
+
+- **ผู้ให้บริการที่รองรับ:**
+  - Flash Express
+  - Kerry Express / KEX
+  - ไปรษณีย์ไทย (Thailand Post / EMS)
+  - J&T Express
+- **Tracking URL สำหรับลูกค้า:**
+  - `https://kittisak.com/order-tracking?orderId=...` หรือค้นหาด้วยเลขพัสดุในหน้าเว็บ
+
+---
+
+## 4. Checklist สำหรับการขึ้น Production แบบสมบูรณ์ (Go-Live Checklist)
+
+- [x] ตรวจสอบ DNS ชี้มายัง IP Server ถูกต้อง (`58.136.41.148`)
+- [x] ติดตั้งและออกใบรับรอง SSL ครอบคลุมทั้ง 4 โดเมน
+- [x] สร้างฐานข้อมูล `kittisakdb` และรัน Migration
+- [x] ทำการ Seed ข้อมูลเบื้องต้น (Admin, หมวดหมู่, แบรนด์, สินค้า)
+- [ ] เปลี่ยนรหัสผ่านบัญชี Admin เริ่มต้น (`admin` / `homaroma123`)
+- [ ] อัปเดต Logo, Favicon, และ SEO Metadata ให้ตรงกับแบรนด์จริง
+- [ ] ใส่คีย์ Omise Payment Production Keys
+- [ ] สร้าง LINE LIFF App และใส่ `VITE_LIFF_ID`
@@ -0,0 +1,54 @@
+# User Flows & Operational Workflows — Kittisak.com
+
+เอกสารแสดงขั้นตอนการทำงานและเส้นทางประสบการณ์ผู้ใช้ (User Journeys) สำหรับ `kittisak.com`
+
+---
+
+## 1. Customer Shopping Flow (เส้นทางการสั่งซื้อของลูกค้า)
+
+```mermaid
+graph TD
+    A[ผู้ใช้งานเข้าเว็บ https://kittisak.com] --> B[ค้นหา/เลือกดูสินค้าตามหมวดหมู่หรือแบรนด์]
+    B --> C[หน้ารายละเอียดสินค้า Product Detail]
+    C --> D[เลือก Variant / ขนาด / สี / กลิ่น]
+    D --> E[เพิ่มสินค้าลงตะกร้า Add to Cart]
+    E --> F[หน้าตะกร้าสินค้า Cart & กรอกคูปองส่วนลด]
+    F --> G[หน้า Checkout กรอกที่อยู่จัดส่ง & ข้อมูลติดต่อ]
+    G --> H{เลือกวิธีการชำระเงิน}
+    H -->|PromptPay / Credit Card| I[ประมวลผลผ่าน Omise Gateway]
+    H -->|โอนเงิน / เก็บเงินปลายทาง| J[บันทึกคำสั่งซื้อรอชำระ]
+    I --> K[หน้า Order Success แสดง Order ID & Tracking Link]
+    J --> K
+```
+
+---
+
+## 2. LINE LIFF & Member Flow (เส้นทางสมาชิกผ่าน LINE Official Account)
+
+```mermaid
+graph TD
+    L[เปิดลิงก์ผ่าน LINE OA หรือ Rich Menu] --> M[เข้าสู่ https://spa.kittisak.com ผ่าน LIFF]
+    M --> N[ดึงข้อมูลโปรไฟล์ LINE อัตโนมัติ LINE OAuth Profile]
+    N --> O[ผูกบัญชีลูกค้า Customer ในระบบ Database]
+    O --> P[รับคูปองต้อนรับ / สิทธิ์สะสมแต้มสมาชิก]
+    P --> Q[เลือกซื้อสินค้าและ Checkout แบบ Quick Buy]
+    Q --> R[รับการแจ้งเตือนสถานะคำสั่งซื้อผ่าน LINE Message]
+```
+
+---
+
+## 3. Merchant & Store Operations (การทำงานของผู้ดูแลระบบหลังบ้าน)
+
+ผู้ดูแลระบบเข้าใช้งานผ่าน **`https://admin.kittisak.com`**:
+
+1. **การจัดการสินค้าและสต็อก (Product Management):**
+   - เพิ่ม/แก้ไข สินค้า, หมวดหมู่ (Categories), แบรนด์ (Brands), และ Matrix Variants
+   - กำหนดคุณสมบัติสินค้า (Product Attributes) และคำแปลหลายภาษา (Multilingual)
+2. **การจัดการคำสั่งซื้อ (Order Management):**
+   - ตรวจสอบรายการสั่งซื้อใหม่ (Pending Orders)
+   - อัปเดตสถานะการชำระเงิน และกรอกเลข Tracking พัสดุ (Flash, Kerry, Thailand Post)
+3. **การตกแต่งหน้าร้านผ่าน Headless CMS (Page Builder):**
+   - จัดลำดับ Hero Banner, Featured Products, Testimonials, และ Call-to-Action
+   - ปรับแต่งโทนสี Theme Colors และ Logo หน้าร้านได้ทันทีโดยไม่ต้องแก้โค้ด
+4. **การตลาดและโปรโมชั่น (Marketing & Promotions):**
+   - สร้างโค้ดคูปองส่วนลด (Coupon Codes) กำหนดวันหมดอายุและเงื่อนไขขั้นต่ำ