// 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
