7.1 KiB
// File: specs/200-fullstacks/226-document-chat-ui-pattern/research.md // Change Log: // - 2026-05-19: Initial research and technical decisions for Document Chat UI Pattern
Research & Technical Decisions: Document Chat UI Pattern
เอกสารนี้ระบุการตัดสินใจทางเทคนิค การเลือกเครื่องมือ และทางเลือกอื่นที่ได้รับการประเมินสำหรับงานออกแบบระบบ Document Chat UI (226)
1. การจัดวางและพฤติกรรมของ UI Panel (UI Layout & Placement)
การตัดสินใจ (Decision)
เลือกรูปแบบ Right-side collapsible side-panel (แผงควบคุมด้านขวาที่สามารถยับเลื่อนปิดได้) บน Desktop และ Tablet และแสดงผลแบบ Bottom Sheet สำหรับหน้าจอมือถือ (Mobile)
เหตุผลสนับสนุน (Rationale)
- รักษา Context ของเอกสารหลัก: ผู้ใช้สามารถเห็น Drawing หรือเนื้อหา RFA ที่ฝั่งซ้ายของจอและแชทถาม AI ที่ฝั่งขวาของจอไปพร้อมกันได้ ทำให้ไม่เกิดปัญหาสลับหน้าจอไปมา (No Context Switching)
- ความยืดหยุ่นและการขยายตัว: ในอนาคตสามารถขยายความกว้างของ Panel หรือเปิดปิดได้อย่างง่ายดาย โดยไม่ขัดจังหวะการอ่านเอกสาร
ทางเลือกอื่นที่พิจารณา (Alternatives Considered)
- Modal dialog (แบบ Overlay): บดบังเอกสารหลักทั้งหมด ผู้ใช้งานไม่สามารถพิมพ์ถามและดูรูปภาพหรือข้อความของเอกสารหลักไปพร้อมๆ กันได้ จึงปฏิเสธทางเลือกนี้
- หน้าเพจเดี่ยวแยกต่างหาก (/documents/[id]/chat): บังคับให้ผู้ใช้งานสลับหน้าจอไปมาอย่างรุนแรง ทำให้สูญเสีย muscle memory และความลื่นไหลในการทำงาน
2. การเก็บข้อมูลสนทนาแบบชั่วคราว (Client-side Chat Session Persistence)
การตัดสินใจ (Decision)
ใช้ Session Storage ของบราวเซอร์ในการบันทึกข้อความสนทนาในแต่ละ documentPublicId ในระหว่างที่มีการใช้งานบราวเซอร์เซสชันนั้น
เหตุผลสนับสนุน (Rationale)
- ลดภาระฝั่งเซิร์ฟเวอร์: สอดคล้องกับข้อกำหนด Phase 1 ที่ไม่ต้องการเก็บข้อมูลสนทนาย้อนหลังในฐานข้อมูลส่วนกลาง ช่วยลดการออกแบบ DB schema และการทำ API เคลียร์ข้อมูล
- รักษา Context ระหว่างการนำทาง: หากผู้ใช้สลับไปดูแท็บอื่นหรือหน้าอื่นชั่วคราวแล้วคลิกกลับมา ข้อมูลการคุยกับ AI สำหรับเอกสารนี้จะยังคงอยู่ จนกว่าจะมีการปิดแท็บบราวเซอร์หรือทำการรีเฟรชแบบรุนแรง (Hard Reload)
ทางเลือกอื่นที่พิจารณา (Alternatives Considered)
- Local Storage: ข้อมูลจะค้างอยู่ตลอดไปแม้ปิดบราวเซอร์แล้ว ซึ่งอาจนำไปสู่ปัญหาข้อมูลค้างล้าสมัยหรือความเสี่ยงเรื่องข้อมูลความลับของโครงการในกรณีแชร์บอร์ดคอมพิวเตอร์
- Redux / Zustand state (In-memory เท่านั้น): ข้อมูลหายทันทีเมื่อผู้ใช้เผลอกดโหลดหน้าซ้ำ (Soft Reload) ซึ่งขัดกับความสะดวกในการทำงานต่อเนื่อง
3. การแสดงผล Suggested Actions
การตัดสินใจ (Decision)
AI Gateway จะส่งข้อเสนอการกระทำถัดไป (Suggested Actions) ในรูปแบบอาร์เรย์ข้อความและคำสั่งใน payload การตอบกลับ จากนั้น Frontend จะเรนเดอร์ในรูปแบบ Radix UI/shadcn Badge/Button Chip ที่สามารถกดใช้งานได้ทันที
เหตุผลสนับสนุน (Rationale)
- สอดคล้องกับสถาปัตยกรรม AI: AI Gateway/Ollama สามารถแนะนำการดำเนินการตามบริบท (เช่น "ดูการส่ง RFA ล่าสุด", "สร้างฉบับร่างใหม่") ช่วยนำทางผู้ใช้ในระบบ Workflow ได้ดีขึ้น
- การทำงานแบบรวดเร็ว: ลดขั้นตอนการที่ผู้ใช้ต้องนั่งพิมพ์คำสั่งยาวๆ บนอุปกรณ์หน้าจอสัมผัสหรือแท็บเล็ตหน้างาน
4. API Endpoints & Contract Design
การตัดสินใจ (Decision)
ออกแบบ API Route หลักที่ /api/ai/chat โดยมีโครงสร้างการคุยแบบบูรณาการกับ CASL permission layer ของ NestJS เสมอ
เหตุผลสนับสนุน (Rationale)
- เพื่อให้มั่นใจว่าคำร้องขอของ AI Subsystem ทั้งหมดอยู่ภายใต้ข้อจำกัดสิทธิ์ Tenant/Project Isolation (ADR-016 & ADR-023A) และไม่หลุดพ้นขอบเขต CASL