690519:1631 224 to 226 AI #01

2026-05-19 16:31:50 +07:00
parent 3e25097470
commit ea5499123e
127 changed files with 12387 additions and 42 deletions
@@ -0,0 +1,56 @@
+// 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)
+1. **รักษา Context ของเอกสารหลัก**: ผู้ใช้สามารถเห็น Drawing หรือเนื้อหา RFA ที่ฝั่งซ้ายของจอและแชทถาม AI ที่ฝั่งขวาของจอไปพร้อมกันได้ ทำให้ไม่เกิดปัญหาสลับหน้าจอไปมา (No Context Switching)
+2. **ความยืดหยุ่นและการขยายตัว**: ในอนาคตสามารถขยายความกว้างของ Panel หรือเปิดปิดได้อย่างง่ายดาย โดยไม่ขัดจังหวะการอ่านเอกสาร
+
+### ทางเลือกอื่นที่พิจารณา (Alternatives Considered)
+- **Modal dialog (แบบ Overlay)**: บดบังเอกสารหลักทั้งหมด ผู้ใช้งานไม่สามารถพิมพ์ถามและดูรูปภาพหรือข้อความของเอกสารหลักไปพร้อมๆ กันได้ จึงปฏิเสธทางเลือกนี้
+- **หน้าเพจเดี่ยวแยกต่างหาก (/documents/[id]/chat)**: บังคับให้ผู้ใช้งานสลับหน้าจอไปมาอย่างรุนแรง ทำให้สูญเสีย muscle memory และความลื่นไหลในการทำงาน
+
+---
+
+## 2. การเก็บข้อมูลสนทนาแบบชั่วคราว (Client-side Chat Session Persistence)
+
+### การตัดสินใจ (Decision)
+ใช้ **Session Storage** ของบราวเซอร์ในการบันทึกข้อความสนทนาในแต่ละ `documentPublicId` ในระหว่างที่มีการใช้งานบราวเซอร์เซสชันนั้น
+
+### เหตุผลสนับสนุน (Rationale)
+1. **ลดภาระฝั่งเซิร์ฟเวอร์**: สอดคล้องกับข้อกำหนด Phase 1 ที่ไม่ต้องการเก็บข้อมูลสนทนาย้อนหลังในฐานข้อมูลส่วนกลาง ช่วยลดการออกแบบ DB schema และการทำ API เคลียร์ข้อมูล
+2. **รักษา 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)
+1. **สอดคล้องกับสถาปัตยกรรม AI**: AI Gateway/Ollama สามารถแนะนำการดำเนินการตามบริบท (เช่น "ดูการส่ง RFA ล่าสุด", "สร้างฉบับร่างใหม่") ช่วยนำทางผู้ใช้ในระบบ Workflow ได้ดีขึ้น
+2. **การทำงานแบบรวดเร็ว**: ลดขั้นตอนการที่ผู้ใช้ต้องนั่งพิมพ์คำสั่งยาวๆ บนอุปกรณ์หน้าจอสัมผัสหรือแท็บเล็ตหน้างาน
+
+---
+
+## 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