87 lines
5.5 KiB
Markdown
87 lines
5.5 KiB
Markdown
// 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: ยกเลิกข้อเสนอแนะ
|
|
}
|
|
```
|