lcbp3/specs/06-Decision-Records/ADR-037-unified-prompt-management-ux-ui.md

ADR-037: Unified Prompt Management UX/UI

Status: Draft Date: 2026-06-14 Decision Makers: Development Team, System Architect Supersedes: ADR-029: Dynamic Prompt Management (extends prompt_type scope) Related Documents:

• ADR-027: AI Admin Console and Dynamic Control
• ADR-030: Context-Aware Prompt Templates
• ADR-036: Unified AI Model Architecture
• ADR-035: AI Pipeline Flow Architecture

---

บริบทและปัญหา (Context and Problem Statement)

ADR-029 กำหนด architecture สำหรับ prompt management (ai_prompts table, versioning, activation) แต่จำกัด scope ไว้ที่ prompt_type='ocr_extraction' เดียว และไม่ได้ระบุ UX/UI อย่างละเอียด ทำให้เกิดปัญหาดังนี้:

1. Version History สับสน: ไม่แยกระหว่าง prompt types (OCR vs AI) ทำให้ admin ไม่รู้ว่า version ไหนใช้สำหรับ workflow ไหน
2. Sandbox Workflow ไม่ตรง Production: ปัจจุบันใช้ 2-step flow (OCR → AI Extract) แต่ production ใช้ 3-step flow (OCR → Extract → RAG Prep) ทำให้ sandbox ทดสอบไม่ครบ
3. Context Config UI ขาดไป: ADR-030 กำหนด context_config แต่ไม่มี UI สำหรับ View/Edit/Save/Apply ทำให้ไม่สามารถจัดการ context ได้
4. Config Types ไม่เคลียร์: Admin สับสนระหว่าง 3 config types:
   • Runtime Parameters (temperature, topP, ฯลฯ) - คุม AI model behavior
   • Context Config (projectId, contractId, ฯลฯ) - คุม data context
   • System Prompt (AI role/instruction) - คุม AI บทบาท

---

ปัจัยขับเคลื่อนการตัดสินใจ (Decision Drivers)

• Multi-Type Support: ระบบต้องรองรับหลาย prompt types (ocr_extraction, rag_query_prompt, rag_prep_prompt, classification_prompt) ตาม ADR-035 flows
• Sandbox-Production Parity: Sandbox ต้องทดสอบทั้ง pipeline ที่ใช้ใน production (OCR → Extract → RAG Prep) เพื่อให้ผลลัพธ์ตรงความจริง
• Context Config Management: Admin ต้องสามารถ View/Edit/Save/Apply context_config ได้ผ่าน UI
• Clear Separation: 3 config types (Runtime Parameters, Context Config, System Prompt) ต้องแยก UI ชัดเจนเพื่อลดความสับสน
• Single Page Layout: ตาม ADR-027, AI Admin Console ควรเป็น single page layout

---

ทางเลือกที่ถูกพิจารณา (Considered Options)

Option 1: แยกหน้าตาม Prompt Type

• ข้อดี: UI เรียบง่าย แต่ละ prompt type มีหน้าของตัวเอง
• ข้อเสีย: ไม่ consistent กับ ADR-027 (single page), ยากต่อการเปรียบเทียบระหว่าง types

Option 2: Single Page พร้อม Prompt Type Dropdown (ตัวเลือกที่ได้รับเลือก)

• ข้อดี: Consistent กับ ADR-027, ง่ายต่อการเปรียบเทียบ, ลดจำนวน components
• ข้อเสีย: UI ซับซ้อนขึ้นเล็กน้อย (ต้องจัดการ state หลาย prompt types)

---

ผลการตัดสินใจ (Decision Outcome)

ทางเลือกที่ได้รับเลือก: Option 2 — Single Page พร้อม Prompt Type Dropdown

---

ข้อตกลงหลัก (Core Decisions — Grilling Session 2026-06-14)

#	ประเด็น	การตัดสินใจ
1	Prompt Type Scope	รองรับ 4 types: ocr_extraction, rag_query_prompt, rag_prep_prompt, classification_prompt
2	Sandbox Workflow	Hybrid flow: OCR → Extract → Optional Review → RAG Prep
3	UX/UI Layout	Single Page พร้อม Prompt Type Dropdown
4	Context Config UI	View/Edit/Save/Apply ครบถ้วน
5	Runtime Parameters UI	แยกจาก Context Config UI ชัดเจน
6	Version History	แยกตาม prompt_type, แสดง active badge, test result
7	Sandbox to Production	สามารถส่งต่อผลลัพธ์ sandbox ไป activate version ได้
8	Supersede ADR-029	ใช่ - ขยาย prompt_type scope จากเดียวเป็นหลาย types

---

รายละเอียดเชิงสถาปัตยกรรม (Implementation Details)

1. Database Schema Changes (ADR-009)

Table: ai_prompts (มีอยู่แล้วจาก ADR-029, ไม่ต้องเปลี่ยน)

• prompt_type VARCHAR(50) - รองรับหลาย types
• context_config JSON NULL - เพิ่มจาก ADR-030 (มีอยู่แล้ว)

Seed Data:

-- OCR Extraction Prompt (มีอยู่แล้วจาก ADR-029)
INSERT INTO ai_prompts (prompt_type, version_number, template, context_config, is_active, created_by)
VALUES ('ocr_extraction', 1, '<template with {{ocr_text}} and {{master_data_context}}>',
        '{"filter": null, "pageSize": 3, "language": "th", "outputLanguage": "th"}',
        1, 1);

-- RAG Query Prompt (ใหม่)
INSERT INTO ai_prompts (prompt_type, version_number, template, context_config, is_active, created_by)
VALUES ('rag_query_prompt', 1, '<template for RAG Q&A>',
        '{"filter": null, "language": "th"}',
        1, 1);

-- RAG Prep Prompt (ใหม่)
INSERT INTO ai_prompts (prompt_type, version_number, template, context_config, is_active, created_by)
VALUES ('rag_prep_prompt', 1, '<template for Semantic Chunking>',
        '{"filter": null, "language": "th"}',
        1, 1);

-- Classification Prompt (ใหม่)
INSERT INTO ai_prompts (prompt_type, version_number, template, context_config, is_active, created_by)
VALUES ('classification_prompt', 1, '<template for document classification>',
        '{"filter": null, "language": "th"}',
        1, 1);

2. Backend API Endpoints

Existing Endpoints (จาก ADR-029):

• GET /api/ai/prompts/:type - ดึง all versions ของ prompt_type
• POST /api/ai/prompts/:type - สร้าง version ใหม่
• DELETE /api/ai/prompts/:type/:version - ลบ version
• POST /api/ai/prompts/:type/:version/activate - Activate version
• PATCH /api/ai/prompts/:type/:version/note - บันทึก manual_note

New Endpoints (สำหรับ Context Config):

• GET /api/ai/prompts/:type/:version/context-config - ดึง context_config ของ version
• PUT /api/ai/prompts/:type/:version/context-config - อัปเดต context_config

Sandbox Endpoints (อัปเดตจาก ADR-035):

• POST /api/ai/admin/sandbox/ocr - Step 1: OCR (มีอยู่แล้ว)
• POST /api/ai/admin/sandbox/ai-extract - Step 2: AI Extract (มีอยู่แล้ว)
• POST /api/ai/admin/sandbox/rag-prep - Step 3: RAG Prep (ใหม่)

3. Frontend UX/UI Layout

Single Page Layout:

┌─────────────────────────────────────────────────────────────┐
│ AI Admin Console - Prompt Management                          │
├─────────────────────────────────────────────────────────────┤
│ Prompt Type: [Dropdown: OCR Extraction ▼]                    │
├──────────────────────┬──────────────────────────────────────┤
│  Left Panel          │  Right Panel                          │
│  ┌────────────────┐  │  ┌────────────────────────────────┐  │
│  │ Version History│  │  │ Prompt Editor + Context Config │  │
│  │ v3 (active) ✅ │  │  │ ┌────────────────────────────┐ │  │
│  │ v2 - 2026-05-24│  │  │ │ Prompt Template Editor     │ │  │
│  │ v1 - 2026-05-22│  │  │ └────────────────────────────┘ │  │
│  └────────────────┘  │  │ ┌────────────────────────────┐ │  │
│                      │  │ │ Context Config Editor     │ │  │
│                      │  │ │ - Project Filter          │ │  │
│                      │  │ │ - Contract Filter         │ │  │
│                      │  │ │ - Page Size               │ │  │
│                      │  │ │ - Language                │ │  │
│                      │  │ └────────────────────────────┘ │  │
│                      │  │ [Save New Version] [Activate] │  │
│                      │  └────────────────────────────────┘  │
├──────────────────────┴──────────────────────────────────────┤
│  Sandbox Tabs                                                    │
│  ┌────────────────────────────────────────────────────────┐  │
│  │ [OCR] [Extract] [RAG Prep]                              │  │
│  └────────────────────────────────────────────────────────┘  │
│  ┌────────────────────────────────────────────────────────┐  │
│  │ Sandbox Test Area                                      │  │
│  │ - Upload PDF                                           │  │
│  │ - Select Project/Contract                              │  │
│  │ - Run Test                                             │  │
│  │ - View Results                                        │  │
│  │ - [Activate This Version]                             │  │
│  └────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Components:

• PromptTypeDropdown: เลือก prompt_type (ocr_extraction, rag_query_prompt, rag_prep_prompt, classification_prompt)
• VersionHistory: แสดง versions ของ prompt_type ที่เลือก (แยกตาม type)
• PromptEditor: Textarea สำหรับแก้ prompt template (validate {{ocr_text}} หรือ placeholders อื่นๆ)
• ContextConfigEditor: Form สำหรับ edit context_config (projectId, contractId, pageSize, language)
• SandboxTabs: Tabs สำหรับทดสอบแต่ละ step (OCR, Extract, RAG Prep)
• RuntimeParametersPanel: Sliders สำหรับ runtime parameters (temperature, topP, repeatPenalty, ฯลฯ) - แยกจาก Context Config

4. Sandbox Workflow (Hybrid Flow)

Step 1: OCR

Admin Upload PDF
  → POST /api/ai/admin/sandbox/ocr
  → BullMQ (ai-realtime) job type: "sandbox-ocr-only"
  → OcrService → Sidecar (typhoon-np-dms-ocr)
  → Raw OCR text

Step 2: AI Extract

Admin Select Prompt Version
  → POST /api/ai/admin/sandbox/ai-extract
  → BullMQ (ai-realtime) job type: "sandbox-ai-extract"
  → Load prompt from ai_prompts (selected version)
  → OllamaService → typhoon2.5-np-dms
  → Structured metadata (JSON)

Step 3: RAG Prep (Optional)

Admin Click "Test RAG Prep" (optional)
  → POST /api/ai/admin/sandbox/rag-prep
  → BullMQ (ai-realtime) job type: "sandbox-rag-prep"
  → OllamaService → typhoon2.5-np-dms (Semantic Chunking)
  → Sidecar → BGE-M3 (Embedding)
  → Chunks + Vectors

Activate to Production:

Admin Click "Activate This Version"
  → POST /api/ai/prompts/:type/:version/activate
  → Update is_active flag
  → Invalidate Redis cache
  → Production jobs use new version

5. Three Config Types Separation

Runtime Parameters Panel (ADR-036):

• อยู่ใน Sandbox Tab
• Sliders: Temperature, Top-P, Repeat Penalty, Max Tokens, Ctx Size, Keep-Alive
• เก็บใน ai_execution_profiles (global per profile)
• Apply workflow: Sandbox draft → Apply to Production
• วัตถุประสงค์: คุม AI model behavior (LLM ตอบสนองอย่างไร)

Context Config Editor (ADR-030):

• อยู่ใน Prompt Editor Panel
• Form: Project Filter, Contract Filter, Page Size, Language
• เก็บใน ai_prompts (per prompt version)
• Apply workflow: Save version → Activate version
• วัตถุประสงค์: คุม data context ที่ AI เห็น (master data อะไรบ้าง)

System Prompt Editor (ADR-029 + ADR-036):

• อยู่ใน Prompt Editor Panel (รวมกับ Prompt Template)
• Textarea: System instruction สำหรับ AI model (เช่น "คุณคือเอนจิ้นสกัดข้อมูล...")
• เก็บใน ai_prompts (per prompt version) - เป็นส่วนหนึ่งของ template field
• Apply workflow: Save version → Activate version
• วัตถุประสงค์: กำหนดบทบาทและโครงสร้างผลลัพธ์ของ AI

Summary Table:

Config Type	Table	Per Version?	Purpose	Apply Workflow
Runtime Parameters	ai_execution_profiles	ไม่ (global)	คุม AI model behavior	Sandbox draft → Production
Context Config	ai_prompts	ใช่	คุม data context	Save version → Activate
System Prompt	ai_prompts (template)	ใช่	คุม AI role/instruction	Save version → Activate

---

ผลกระทบ (Consequences)

ผลดี

• Admin จัดการ prompt ได้ครบทุก type (OCR, RAG, Classification)
• Sandbox ทดสอบครบ pipeline ตรงกับ production
• Context config มี UI ครบถ้วน (View/Edit/Save/Apply)
• Runtime Parameters กับ Context Config แยกชัดเจน
• Single page layout consistent กับ ADR-027

ผลเสีย / ข้อระวัง

• UI ซับซ้อนขึ้นเล็กน้อย (ต้องจัดการ state หลาย prompt types)
• ต้องเพิ่ม backend endpoints สำหรับ context config CRUD
• ต้องเพิ่ม sandbox endpoint สำหรับ RAG Prep
• ต้อง seed data สำหรับ prompt types ใหม่

---

Migration Plan

Phase 1: Database

1. Run seed data สำหรับ prompt types ใหม่ (rag_query_prompt, rag_prep_prompt, classification_prompt)
2. Verify context_config column มีอยู่แล้ว (จาก ADR-030)

Phase 2: Backend

1. เพิ่ม endpoints สำหรับ context config CRUD
2. เพิ่ม sandbox endpoint สำหรับ RAG Prep
3. Update AiPromptsService รองรับหลาย prompt types

Phase 3: Frontend

1. สร้าง PromptTypeDropdown component
2. อัปเดต VersionHistory แยกตาม prompt_type
3. สร้าง ContextConfigEditor component
4. อัปเดต SandboxTabs เพิ่ม RAG Prep tab
5. แยก Runtime Parameters Panel ออกจาก Context Config Editor

Phase 4: Testing

1. Unit tests สำหรับ context config CRUD
2. Integration tests สำหรับ sandbox RAG Prep
3. E2E tests สำหรับ full workflow (OCR → Extract → RAG Prep → Activate)

---

Grilling Session Log

2026-06-14 — grilling session ผ่าน Devin Cascade
Q1: ปัญหาหลัก → B + C (UX ไม่ครอบคลุม + ใช้งานยาก)
Q2: UX ปัจจุบันอยู่ที่ไหน → OcrSandboxPromptManager + PromptVersionHistory
Q3: Context config คืออะไร → JSON column ใน ai_prompts (filter, pageSize, language)
Q4: Context config ใช้ที่ไหน → ทั้ง sandbox และ production
Q5: Context config เก็บที่ไหน → A (ใน ai_prompts per version)
Q6: ปัญหา UX ละเอียด → 6.1 Version ไม่แยก OCR/AI, 6.2 2-step flow ไม่เหมือ production, 6.3 Context config UI ขาด
Q7: Prompt type รองรับอะไร → D (ocr_extraction, rag_query_prompt, rag_prep_prompt, classification_prompt)
Q8: Sandbox workflow เพิ่มอะไร → A (RAG Prep step)
Q9: UX layout อย่างไร → A (Single Page พร้อม Dropdown + ส่งต่อผลลัพธ์)
Q10: Sandbox workflow อย่างไร → C (Hybrid: OCR → Extract → Optional Review → RAG Prep)
Q11: ขัดแย้ง ADR-029 → สร้าง ADR ใหม่ supersede
Q12: ขัดแย้ง ADR-027 → ไม่ขัดแย้ง (single page ยังใช้ได้)
Q13: ขัดแย้ง ADR-036 → ไม่ขัดแย้ง (runtime vs context แยก concern)
Q14: Runtime vs Context แตกต่างอย่างไร → Runtime คุม AI, Context คุม data
Q15: ADR ชื่ออะไร → A (ADR-037: Unified Prompt Management UX/UI)
Q16: Scope อะไร → C (UX/UI + Backend API + Database)

---

Related ADRs

• ADR-029: Dynamic Prompt Management (superseded - extends prompt_type scope)
• ADR-027: AI Admin Console and Dynamic Control (single page layout)
• ADR-030: Context-Aware Prompt Templates (context_config architecture)
• ADR-036: Unified AI Model Architecture (runtime parameters management)
• ADR-035: AI Pipeline Flow Architecture (sandbox + production flows)