74 lines
6.9 KiB
Markdown
74 lines
6.9 KiB
Markdown
// 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
|
|
```
|