คู่มือระบบ

rootBot — แพลตฟอร์มแชตบอท white-label หลายผู้เช่า

แพลตฟอร์มเดียว เปิดให้ลูกค้า (tenant) หลายเจ้าใช้ร่วมกันได้ แต่ละเจ้ามีความรู้ · AI persona · ช่องทาง · branding ของตัวเอง และ ข้อมูลแยกขาดจากกันสนิท เอกสารนี้อธิบายโครงสร้างและวิธีใช้งานแบบเข้าใจง่าย

1 · ภาพรวม

rootBot คืออะไร และแก้ปัญหาอะไร

เดิมแชตบอทหนึ่งตัว = องค์กรเดียว (hardcode ทุกอย่าง) rootBot เปลี่ยนทุกอย่างที่เคย hardcode ให้มาจาก “config ต่อ tenant” → เพิ่มลูกค้าใหม่ได้โดยไม่ต้องเขียน/deploy โค้ดใหม่

Onboard ง่าย — สร้าง tenant ใหม่ผ่านคอนโซล ได้บอตพร้อม channel/ความรู้/persona ของตัวเอง
แยกข้อมูลเด็ดขาด — สนทนา/ความรู้/ผู้ใช้ของแต่ละเจ้า มองข้ามกันไม่ได้ (บังคับด้วย Postgres RLS)
หลายช่องทาง — Web Widget · LINE · Facebook · Mobile ด้วย credential ของแต่ละเจ้า
AI ในตัว — ตอบจากความรู้ (RAG) + ส่งต่อเจ้าหน้าที่ (live chat) ได้ทุกช่องทาง

2 · สถาปัตยกรรม

ภาพรวมว่าอะไรต่อกับอะไร

ทุก request จากทุกช่องทางวิ่งเข้า backend เดียว (NestJS บน Cloud Run) ซึ่ง resolve ว่าเป็นของ tenant ไหน แล้ว scope ทุกอย่างด้วย tenant_id

ภาพรวม: ช่องทาง → backend → ที่เก็บข้อมูล + AI

3 · Multi-tenant: Pool vs Silo

ลูกค้าเล็กใช้ร่วม · ลูกค้าใหญ่/รัฐแยกเดี่ยว

มี 2 รูปแบบการวางลูกค้า โดย โค้ดชุดเดียวกัน — แอปไม่รู้ว่าตัวเองเป็นแบบไหน TenantContext เป็นคนบอกว่าข้อมูลอยู่ที่ไหน

Pooled = DB เดียวหลายเจ้า (กันด้วย RLS) · Silo = deploy + DB แยก

หัวข้อ	Pooled	Silo
เหมาะกับ	เอกชน/ลูกค้าเล็ก	รัฐ/ข้อมูลอ่อนไหว
ข้อมูล	DB ร่วม + `tenant_id` (RLS)	DB แยกของตัวเอง
ต้นทุนเพิ่ม/เจ้า	~ศูนย์	มี (instance แยก)

การแยกข้อมูล (สำคัญสุด): ทุกตารางมี tenant_id และเปิด Postgres RLS แบบ FORCE — ต่อให้โค้ดพลาดลืมใส่เงื่อนไข ฐานข้อมูลก็ยังกันให้เห็นเฉพาะ row ของ tenant ตัวเอง (พิสูจน์ cross-tenant = 0)

4 · สองคอนโซล

ใครเห็นอะไร ทำอะไรได้

แยกหน้าที่: operator คุมแพลตฟอร์ม · tenant admin คุมเนื้อหาของตัวเอง

กฎเหล็ก (no silent god-mode): ชั้น platform อ่านเนื้อหาของ tenant แบบเงียบ ๆ ไม่ได้ — ทำได้แค่ provisioning/config/monitoring แบบรวม การเข้าถึงเนื้อหาจริงต้องผ่าน audited support-access เท่านั้น

5 · วงจรชีวิต tenant

ตั้งแต่เปิดลูกค้าใหม่จนปิด/ลบถาวร

onboard → active → (พัก 90 วัน) → export → ลบถาวร (ยืนยัน slug)

การลบ (purge) ปลอดภัยโดยออกแบบ: รันผ่าน app_role + RLS → ลบข้ามไปโดน tenant อื่น เป็นไปไม่ได้ (พิสูจน์: ลบ A แล้ว B ครบ 100%)

6 · ฟีเจอร์ Tenant Admin

เมนูในคอนโซลของแต่ละ tenant ทำอะไรได้บ้าง

Dashboard / Reports

ตัวเลขเรียลไทม์ + กราฟ (ปริมาณ/อัตราตอบได้/รีวิวเฉลี่ย)

Knowledge / Q&A

อัปโหลดเอกสาร (PDF/DOCX) + Q&A → embed เข้า pgvector (RAG)

Live chat

รับช่วงต่อจากบอท คุยกับลูกค้าสดทุกช่องทาง (realtime)

ประวัติการสนทนา

ค้น/กรอง + เปิด transcript + ดูคะแนนรีวิว 4 มิติ

Flows

สร้าง conversational form (เก็บข้อมูลเป็นขั้น + action) แบบ tenant แก้เองได้

Channels

ผูก LINE OA / FB Page + credential ของตัวเอง

Broadcast

ส่งข้อความหาผู้ใช้ตามช่องทาง

Widget

ปรับแต่ง+พรีวิวสด (เปิดแท็บใหม่) · snippet ฝัง · ดาวน์โหลด SDK (.zip) · ฟอนต์/โลโก้ต่อ tenant

Settings — Branding

ชื่อบอท · สี · ฟอนต์ · โลโก้ · ข้อความต้อนรับ (ไทย/อังกฤษ) · timezone · persona

Settings — AI / สมองบอต

เลือกโมเดล Gemini + region · self-check · ลำดับความสำคัญ tool · สลับสมองเป็น N8N (webhook+HMAC)

Settings — ความรู้/ความจำ

Hybrid + Rerank search · ความจำระยะยาว (จำ fact/ข้ามเซสชัน/สรุป) · เสียบ MCP server

Members

จัดการทีม + สิทธิ์ (RBAC, server-enforced)

7 · บทสนทนา + รีวิว

ตั้งแต่ผู้ใช้ทักจนได้คะแนนความพึงพอใจ

bot ตอบจากความรู้ → ส่งต่อเจ้าหน้าที่ได้ → ปิดห้องแล้วเก็บรีวิว 4 มิติ

รีวิว 4 มิติ (ยก mechanic จาก OCPB): ความชัดเจน · ความครบถ้วน · ความรวดเร็ว · โดยรวม + ข้อเสนอแนะ — เก็บแบบ 1 บทสนทนา 1 รีวิว (ให้คะแนนใหม่ทับของเดิม)

8 · Deploy & Migration

ขึ้น prod อย่างไร และต้องระวังอะไร

deploy ด้วย gcloud builds submit --config cloudbuild.yaml (Cloud Build: test → build → deploy 3 service: chatplat-api · admin · platform + อัป widget ขึ้น GCS). git push ไม่ deploy (GitHub Actions ปิดใช้) — หรือพิมพ์ /deploy ให้ผมทำตาม runbook

ก่อน deploy ที่แก้ schema: ต้องรัน migration prod ก่อน (โดยตั้งใจไม่ผูกกับ CI เพื่อให้ CI ไม่ถือ DB root password)

bash scripts/migrate-prod.sh

หรือพิมพ์ /migrate-prod ให้ผมทำตาม runbook — เป็น migration ที่ idempotent (รันซ้ำไม่พัง)

ลำดับ deploy ที่ถูกต้อง

9 · Tech stack

เครื่องมือหลักที่ใช้

Backend

NestJS 11 · Drizzle ORM · PostgreSQL 18 + pgvector

Vertex AI (Gemini) · Vercel AI SDK · RAG (pgvector)

Frontend

Next.js 15 · React 19 · Tailwind v4 · shadcn (Base UI)

Widget

Vite UMD (bundle React) · Shadow DOM (drop-in)

Realtime

Socket.IO (Cloud Run min=1 + reconnect)

Infra

Cloud Run · Cloud SQL · BigQuery · GCS · Secret Manager

Isolation

Postgres RLS (FORCE) · run-as app_role

CI/CD

GitHub Actions + WIF (keyless) → Cloud Build