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,73 @@
+// File: specs/200-fullstacks/226-document-chat-ui-pattern/plan.md
+// Change Log:
+// - 2026-05-19: Initial implementation plan for Document Chat UI Pattern
+
+# Implementation Plan: Document Chat UI Pattern
+
+**Branch**: `226-document-chat-ui-pattern` | **Date**: 2026-05-19 | **Spec**: [spec.md](./spec.md)
+**Input**: Feature specification from `/specs/200-fullstacks/226-document-chat-ui-pattern/spec.md`
+
+---
+
+## Summary (สรุปแนวทางเชิงเทคนิค)
+
+ฟีเจอร์นี้เป็นการพัฒนาส่วนต่อประสานกับผู้ใช้ (Frontend UI) ร่วมกับ Next.js 16 (App Router), TailwindCSS, Radix UI/shadcn, และ React Hook Form + Zod เพื่อสร้างแผงควบคุมระบบสนทนาของ AI Assistant ในหน้าแสดงผลเอกสารของระบบ LCBP3 DMS โดยจะประมวลผลข้อมูลผ่าน API `/api/ai/chat` โดยอัตโนมัติแนบบริบทของเอกสาร เช่น `documentType` และ UUIDv7 `publicId` (หลีกเลี่ยง Integer PK ตามกฎ Tier 1 ADR-019) และจัดเก็บการสนทนาทั้งหมดไว้ภายใน Session Storage (Client-side) ตามขอบเขตการทำงานของระยะแรก
+
+---
+
+## Technical Context (บริบททางเทคนิค)
+
+- **Language/Version**: TypeScript / Node.js >= 24 / Next.js 16
+- **Primary Dependencies**: Radix UI (Sheet / Dialog / ScrollArea / Button / Badge), TanStack React Query v5, TailwindCSS 3.4.3, Lucide React, Axios, Zod, Zustand
+- **Storage**: Client-side Session Storage สำหรับจัดเก็บข้อความแชทในปัจจุบันต่อเอกสารย่อย
+- **Testing**: Vitest + React Testing Library (สำหรับ Component Unit Tests)
+- **Target Platform**: เว็บเบราว์เซอร์ที่รองรับ Responsive ทั้งเครื่องคอมพิวเตอร์สำนักงาน (1920x1080) และแท็บเล็ตหน้างาน (768x1024)
+- **Project Type**: Next.js App Router Web Application (`frontend/`)
+- **Performance Goals**: การเปิด/ปิด Chat Panel Animation ต้องใช้เวลาเพียง 200ms เท่านั้น (Slide transition), UI ต้องตอบสนองต่อผู้ใช้ทันทีเมื่อมีสัญญาณเตือนหรือเกิดข้อผิดพลาด
+- **Constraints**: ต้องไม่มีการหลุดของ Integer Primary Key ไปยัง LLM หรือ API Payload เป็นอันขาด (Tier 1 Blocker), ต้องรองรับการกรองตามบริบทโครงการผ่าน CASL permissions
+
+---
+
+## Constitution Check (การตรวจสอบความถูกต้องร่วมกับรัฐธรรมนูญโครงการ)
+
+_GATE: ผ่านการทดสอบทั้งหมด_
+
+- [x] **UUID Strategy (ADR-019)**: ระบบใช้ UUIDv7 `publicId` เป็นตัวชี้วัดเอกสารในการแนบบริบท (Context Injection) เท่านั้น ไม่มีการใช้ integer id หรือ fallback `id ?? ''`
+- [x] **Security (ADR-016)**: API Route `/api/ai/chat` จะถูกคลุมด้วย Authentication Guard และมีการ Enforce CASL สิทธิ์ของผู้ใช้ในการอ่านเอกสารนั้นๆ ผ่าน AI Gateway ก่อนจะเรียกใช้งาน
+- [x] **AI Subsystem boundary (ADR-023A)**: AI Subsystem ทำงานแบบ Read-only Insight และ Action suggestion เท่านั้น ห้ามทำการเปลี่ยนสถานะเอกสาร (Transition) โดยตรงผ่านแชทโดยไม่มีการยืนยันจากผู้ใช้ (Human-in-the-loop)
+- [x] **Error Handling (ADR-007)**: มีการจัดการเครือข่ายขัดข้องและ AI Timeout อย่างสง่างาม แสดงคำอธิบายที่ใช้งานง่ายโดยไม่เปิดเผยข้อมูลเซิร์ฟเวอร์ภายใน
+
+---
+
+## Project Structure (โครงสร้างไฟล์ที่เกี่ยวข้องในฟีเจอร์นี้)
+
+### Documentation (เอกสารการออกแบบและพัฒนา)
+```text
+specs/200-fullstacks/226-document-chat-ui-pattern/
+├── spec.md              # Feature specification
+├── plan.md              # แผนการทางเทคนิคฉบับนี้
+├── research.md          # ผลวิจัยการจัดวางและการเก็บสถานะข้อมูล
+├── data-model.md        # รายละเอียดชนิดข้อมูลฝั่ง Frontend และ API Payload DTO
+├── quickstart.md        # คู่มือการเริ่มต้นพัฒนาและรัน Test
+└── contracts/
+    └── chat-api.yaml    # OpenAPI Specification ของ Chat Endpoint
+```
+
+### Source Code (โครงสร้างไฟล์โค้ดของระบบ)
+```text
+frontend/
+├── app/
+│   └── api/
+│       └── ai/
+│           └── chat/
+│               └── route.ts         # Next.js API Route สำหรับ Chat proxy ไปยัง Backend AI Gateway
+├── components/
+│   └── ai/
+│       ├── ai-chat-panel.tsx        # คอมโพเนนต์หลักที่ประกอบด้วย Sheet / Panel สำหรับแต่ละ Breakpoint
+│       ├── ai-chat-toggle.tsx       # ปุ่มสำหรับสลับเปิด/ปิด Chat Panel (และปุ่มลอยสำหรับอุปกรณ์พกพา)
+│       ├── ai-chat-messages.tsx     # รายการประวัติสนทนาและการเรนเดอร์ Message Bubbles ตาม Role
+│       ├── ai-chat-input.tsx        # ช่องพิมพ์คำสั่ง ปุ่มส่งคำถาม และปุ่มลัด
+│       └── ai-suggested-actions.tsx # แถบ Badge Chip แนะนำการทำงานต่อเนื่อง
+└── hooks/
+    └── use-ai-chat.ts               # React hook สำหรับจัดการ API และเก็บสถานะลง Session Storage
+```