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,86 @@
+// File: specs/200-fullstacks/226-document-chat-ui-pattern/data-model.md
+// Change Log:
+// - 2026-05-19: Initial data model specifications for Document Chat UI Pattern
+
+# Data Model & State Specifications: Document Chat UI Pattern
+
+เนื่องจากข้อตกลงใน ADR-026 กำหนดให้ระบบ Document Chat ใน v1 นี้ ทำงานแบบ **Client-side Persistence (Session Storage เท่านั้น)** ดังนั้นจึงไม่มีการเปลี่ยนแปลงโครงสร้างตารางฐานข้อมูล MariaDB หรือ Qdrant เพิ่มเติม เอกสารฉบับนี้จึงเน้นกำหนดโครงสร้างอ็อบเจกต์ข้อมูลในฝั่ง Frontend และ API Request/Response DTOs เพื่อความเป็นระเบียบและสอดคล้องกับมาตรฐานความปลอดภัย
+
+---
+
+## 1. Frontend Data Structures (โครงสร้างข้อมูลฝั่งไคลเอนต์)
+
+### 1.1 ChatMessage (โครงสร้างข้อความแชท)
+ใช้เก็บประวัติการสนทนาในแต่ละ Session
+
+| Field | Type | Description |
+|---|---|---|
+| `id` | `string` | รหัสเฉพาะของข้อความในรูปแบบ **UUIDv7 string** |
+| `role` | `'user' \| 'assistant' \| 'system'` | บทบาทของผู้ส่งข้อความ |
+| `content` | `string` | เนื้อหาของข้อความ (รองรับการเขียนแบบ Markdown พื้นฐาน) |
+| `timestamp` | `Date` | วันเวลาที่ส่งหรือได้รับข้อความ |
+| `suggestedActions` | `SuggestedAction[]` | รายการปุ่มสั่งการแนะนำที่ส่งมาพร้อมคำตอบของ AI (ถ้ามี) |
+| `isStreaming` | `boolean` | สถานะบ่งบอกว่าคำตอบนี้กำลังอยู่ในกระบวนการโหลดข้อมูลแบบ Stream |
+
+### 1.2 SuggestedAction (ปุ่มกระทำการแนะนำ)
+ปุ่มที่ปรากฏใต้ข้อความของ AI เพื่อช่วยให้ผู้ใช้กดสั่งการระบบต่อได้ง่ายขึ้น
+
+| Field | Type | Description |
+|---|---|---|
+| `label` | `string` | ข้อความที่จะแสดงบนปุ่ม Chip (เช่น "ดู Drawing ฉบับใหม่ล่าสุด") |
+| `query` | `string` | ข้อความที่จะถูกส่งเข้าสู่กล่องสนทนาแทนการพิมพ์เมื่อผู้ใช้กดคลิกปุ่มนี้ |
+
+---
+
+## 2. API DTOs (Data Transfer Objects)
+
+### 2.1 ChatRequestDto
+ข้อมูลที่ระบบส่งไปยัง API Endpoint `/api/ai/chat`
+
+```typescript
+// ✅ สอดคล้องกับหลักการ UUIDv7 และหลีกเลี่ยง Integer PK (ADR-019)
+export interface ChatRequestDto {
+  query: string; // ข้อความถามคำถามของผู้ใช้
+  context: {
+    type: 'drawing' | 'rfa' | 'transmittal' | 'correspondence'; // ประเภทเอกสารต้นทาง
+    publicId: string; // UUIDv7 publicId ของเอกสารนั้นๆ
+  };
+}
+```
+
+### 2.2 ChatResponseDto
+ข้อมูลที่ระบบตอบรับกลับมาจาก API (ในกรณีไม่เปิดใช้ Web Stream หรือเป็น Fallback)
+
+```typescript
+export interface ChatResponseDto {
+  messageId: string; // UUIDv7 string ของข้อความตอบกลับ
+  role: 'assistant';
+  content: string; // คำตอบของ AI (Markdown format)
+  suggestedActions?: SuggestedAction[]; // ปุ่มสั่งการแนะนำ
+  latencyMs: number; // ระยะเวลาการประมวลผลของ AI Subsystem
+}
+```
+
+---
+
+## 3. UI State Transitions (สถานะและการเปลี่ยนสถานะในระบบ UI)
+
+ระบบใช้วงจรสถานะแชท (Chat Panel State Life-cycle) ดังแผนภาพนี้:
+
+```mermaid
+stateDiagram-v2
+    [*] --> Closed: เริ่มต้น (Default ปิดแผง)
+    Closed --> Opened: กดปุ่ม Toggle หรือ Ctrl/.
+    Opened --> Closed: กดปุ่ม ปิด หรือสลับหน้าเอกสารอื่น
+    
+    state Opened {
+        [*] --> Idle: พร้อมใช้งาน
+        Idle --> Typing: ผู้ใช้พิมพ์ข้อความ
+        Typing --> Sending: กดส่งข้อความ (เรียก API)
+        Sending --> Receiving: เริ่มได้รับผลลัพธ์แบบ Stream
+        Receiving --> Idle: ประมวลผลเสร็จสิ้น
+        Sending --> ErrorState: เกิดความล่าช้า/ข้อผิดพลาดเครือข่าย
+        ErrorState --> Sending: ผู้ใช้กด Retry
+        ErrorState --> Idle: ยกเลิกข้อเสนอแนะ
+    }
+```