lcbp3/specs/200-fullstacks/226-document-chat-ui-pattern/data-model.md

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

// ✅ สอดคล้องกับหลักการ 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)

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) ดังแผนภาพนี้:

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: ยกเลิกข้อเสนอแนะ
    }