lcbp3/specs/200-fullstacks/226-document-chat-ui-pattern/quickstart.md

// File: specs/200-fullstacks/226-document-chat-ui-pattern/quickstart.md // Change Log: // - 2026-05-19: Initial developer quickstart guide for Document Chat UI Pattern

Developer Quickstart Guide: Document Chat UI Pattern

คู่มือแนะนำขั้นตอนการทำความเข้าใจ การทดสอบ และการตรวจสอบการทำงานของฟีเจอร์ AI Document Chat ในฝั่ง Frontend และการเชื่อมต่อกับ Backend AI Gateway (226)

---

1. การติดตั้งโค้ดและส่วนประกอบหลัก (Component Architecture)

โครงสร้างโฟลเดอร์ฝั่งไคลเอนต์จะอยู่ที่:

frontend/components/ai/
├── ai-chat-panel.tsx           # คอมโพเนนต์หลักที่ประกอบด้วย Sheet / Panel สำหรับแต่ละ Breakpoint
├── ai-chat-toggle.tsx          # ปุ่มสำหรับสลับเปิด/ปิด Chat Panel (และปุ่มลอยสำหรับอุปกรณ์พกพา)
├── ai-chat-messages.tsx        # รายการประวัติสนทนาและการเรนเดอร์ Message Bubbles ตาม Role
├── ai-chat-input.tsx           # กล่องพิมพ์คำสั่ง ปุ่มส่งคำถาม และปุ่มลัด
├── ai-suggested-actions.tsx    # แถบ Badge Chip แนะนำการทำงานต่อเนื่อง
└── hooks/
    └── use-ai-chat.ts          # คอนเท็กซ์และฮุกของ React / TanStack Query ในการจัดการ API และ State

---

2. การเปิดใช้งานและตั้งค่าพัฒนา (Development Setup)

2.1 รันระบบ Frontend ในโหมดพัฒนา

เปิด PowerShell (เนื่องจากทำงานบน Windows OS ตามกฎ) และรันคำสั่ง:

cd frontend
pnpm dev

ระบบจะเริ่มต้นที่พอร์ต http://localhost:3000

2.2 โครงสร้าง API Mockup สำหรับการพัฒนาช่วงแรก

ในระหว่างการพัฒนาฝั่ง Frontend สามารถเปิดการใช้งาน Mock Data ใน use-ai-chat.ts หรือจำลองการทำงานโดยการทดสอบผ่าน /api/ai/chat Mock Route ได้

---

3. ขั้นตอนการทดสอบการใช้งานด้วยตนเอง (Manual Testing Steps)

3.1 การตรวจสอบบน Desktop (ขนาดหน้าจอ ≥ 1024px)

1. เข้าสู่หน้าเอกสาร เช่น /rfas/019505a1-7c3e-7000-8000-abc123def456
2. มองหาปุ่ม AI Chat ทางขวาบนของเอกสาร
3. คลิกปุ่มเพื่อเปิดใช้งาน Chat Panel (จะเห็นการ Slide-in เข้ามาจากทางขวาอย่างราบรื่นใช้เวลา 200ms)
4. พิมพ์ทดสอบสนทนาในช่องพิมพ์ หรือกดคีย์ลัด Ctrl + . เพื่อเปิด/ปิด Panel

3.2 การตรวจสอบความเข้ากันได้ของการแสดงผล (Responsive Test)

1. เปิด Developer Tools ในเว็บเบราว์เซอร์ แล้วเลือกขนาดหน้าจอเป็น Tablet (768px - 1023px)
2. ตรวจสอบว่าขนาดของ Panel กว้างขึ้นเป็นประมาณ 30% ของ viewport หรือไม่
3. เปลี่ยนขนาดหน้าจอเป็น Mobile (< 768px)
4. ยืนยันว่าปุ่มสลับกลายเป็นปุ่มลอย และเมื่อกดแล้วแชทเลื่อนขึ้นมาจากด้านล่าง (Bottom Sheet สูง 60% ของจอ)

---

4. การรันชุดทดสอบอัตโนมัติ (Automated Testing)

ฟีเจอร์นี้ครอบคลุมการตรวจสอบความถูกต้องด้วยชุดทดสอบผ่าน Vitest ในฝั่ง Frontend:

# รันการทดสอบทั้งหมดของ AI module
cd frontend
pnpm test components/ai

สิ่งที่ชุดทดสอบจะยืนยัน:

• ai-chat-panel.tsx สามารถปิดและเปิดได้จริงเมื่อรับคำสั่ง Action
• use-ai-chat.ts สามารถแปลงและแนบพารามิเตอร์ contextType และ contextPublicId ได้อย่างสมบูรณ์โดยไม่มีการใช้ Integer ID หลุดออกไป (Tier 1 UUID Compliance)