---
title: "ข้อกำหนดความต้องการซอฟต์แวร์ (SRS)"
titleEn: "Software Requirements Specification (SRS)"
clauses: ["4.2.2", "7.1.2"]
phase: 1
category: "ออกแบบ"
generated: false
---

# ข้อกำหนดความต้องการซอฟต์แวร์ (Software Requirements Specification: SRS)

**โครงการ:** ระบบแชตบอตปัญญาประดิษฐ์เฉพาะทางพระพุทธศาสนาและเว็บไซต์ (MBU Buddhist AI)
**ผู้ว่าจ้าง:** มหาวิทยาลัยมหามกุฏราชวิทยาลัย (มมร.)
**อ้างอิง TOR:** ข้อ 4.2.2 (SRS: FR/NFR, Workflow, Architecture, Data Dictionary, User Flow/Wireframe, OpenAPI 3.0) และข้อ 7.1.2 (เอกสารส่งมอบงวดที่ 1)
**ฉบับ:** 1.0 (ระบบสาธิต) — วันที่ 3 ตุลาคม พ.ศ. 2569

> เอกสารนี้อธิบายความต้องการของระบบตามที่ **มีอยู่จริงในซอร์สโค้ด** ของระบบสาธิต (Next.js 15 + Prisma/SQLite) ทุกข้อกำหนดระบุไฟล์หรือ endpoint ที่ implement ไว้เพื่อให้ตรวจสอบย้อนกลับได้ ส่วนที่เป็นสถาปัตยกรรมระยะ Production (Kubernetes, PostgreSQL, Elasticsearch) ระบุแยกไว้ในหัวข้อ 5 พร้อมแผนที่การย่อส่วน

---

## 1. บทนำ

### 1.1 วัตถุประสงค์ของเอกสาร

1. กำหนดความต้องการเชิงหน้าที่ (Functional Requirements: FR) และไม่ใช่เชิงหน้าที่ (Non-Functional Requirements: NFR) โดยผูกรหัส `FR-xxx` / `NFR-xxx` กับข้อ TOR (clause id) ให้ตรวจสอบย้อนกลับได้
2. อธิบายลำดับการทำงานหลัก (Workflow) ได้แก่ การถาม-ตอบผ่าน RAG pipeline 8 โหนด การนำเข้าเอกสาร และการประเมินคุณภาพ AI
3. อธิบายสถาปัตยกรรมระบบ (ระบบสาธิตและการแมปไปยัง Production)
4. ให้พจนานุกรมข้อมูล (Data Dictionary) ครบทุก model/field ที่สร้างจาก `prisma/schema.prisma` จริง
5. สรุปกลุ่ม API ตามเอกสาร OpenAPI 3.0 ที่ระบบให้บริการที่ `/api/openapi.json`

รหัส FR ในเอกสารนี้ใช้อ้างอิงต่อใน **แผนการทดสอบหลัก** (`/documents/master-test-plan`) เพื่อทำ Traceability Matrix ระหว่าง SRS กับกรณีทดสอบ (TOR 4.7.1)

### 1.2 ขอบเขตของระบบ

ระบบประกอบด้วย 5 ส่วนตาม TOR ข้อ 4.4:

| ส่วน | ขอบเขต | ตำแหน่งในระบบสาธิต |
|---|---|---|
| (1) Frontend Website | หน้าแรก สมัคร/เข้าสู่ระบบ ถาม-ตอบ Dhamma Talk ประวัติ สิทธิเจ้าของข้อมูล ศูนย์เอกสาร ตาราง TOR | `src/app/[locale]/*`, `src/components/*` |
| (2) Backend Service & AI Engine | REST/SSE API, RAG pipeline (LangGraph.js), Guardrail, Token Budget, Ingestion | `src/app/api/*`, `src/application/*`, `src/server/*`, `src/domain/*` |
| (3) AI Evaluation & Benchmarking | ชุดทดสอบ 7 ชุด 3 workflow บันทึกเวอร์ชัน เปรียบเทียบรอบ | `src/application/evaluation/*`, `scripts/eval/run-acceptance.ts` |
| (4) Admin Portal | ผู้ใช้/PDPA/Audit, ตั้งค่า AI, Prompt, Guardrail, ฐานองค์ความรู้, Evaluation, Ops | `src/app/[locale]/admin/*`, `src/components/admin/*` |
| (5) Dashboard & Report | การใช้งาน โทเคน ค่าใช้จ่าย Feedback SLA Defect | `/admin/dashboard`, `/admin/sla-report`, `scripts/reports/*` |

**นอกขอบเขตของระบบสาธิต** (ระบุตาม Build Plan ข้อ 14): การติดตั้งบนคลาวด์/Kubernetes ของมหาวิทยาลัย โดเมน `dhammaverse.mbu.ac.th` จริง Auto Scaling จริง WAF/Anti-DDoS ระดับคลาวด์ OAuth กับ Google/Facebook ด้วย credential จริง SMTP จริง Elasticsearch/bge-m3 จริง และ **การทดสอบเจาะระบบ (Penetration Test) ซึ่งไม่ได้ดำเนินการในรอบนี้ตามคำสั่งของผู้ว่าจ้าง**

### 1.3 ผู้มีส่วนได้ส่วนเสียและบทบาทผู้ใช้

| บทบาท (`User.role`) | คำอธิบาย | สิทธิ์หลัก |
|---|---|---|
| `GENERAL_USER` | ผู้ใช้ทั่วไป (นักศึกษา พระภิกษุ ประชาชน) | ถาม-ตอบ ประวัติ สิทธิเจ้าของข้อมูล; Dhamma Talk เมื่อผู้ดูแลเปิดสิทธิ์ (`dhammaTalkEnabled`) |
| `ADMIN` | ผู้ดูแลระบบของมหาวิทยาลัย / คณะกรรมการตรวจรับ | Admin Portal ทั้งหมด ยกเว้นสำรองข้อมูล ทำลายข้อมูล และเปลี่ยน role |
| `SUPER_ADMIN` | ผู้ดูแลระบบสูงสุด | ทุกสิทธิ์ รวมสำรองข้อมูล (`/admin/backup`) ทำลายข้อมูล (`/admin/data-destruction`) และเปลี่ยน role |

บทบาททั้ง 3 นิยามใน `src/domain/identity/rbac.ts` (`ROLES`) และตรวจทุก endpoint ผ่าน `withApi({ auth })` ใน `src/server/api/with-api.ts`

### 1.4 นิยามศัพท์

| คำ | ความหมาย |
|---|---|
| RAG | Retrieval-Augmented Generation — ค้นข้อความอ้างอิงจากคลังก่อนให้ LLM สร้างคำตอบ |
| Chunk | หน่วยข้อความที่ทำดัชนี (พระไตรปิฎก/อรรถกถา = 1 ข้อ ต่อ 1 chunk) |
| Citation | การอ้างอิงในรูปแบบ `{abbreviation} ({edition}) {volume}/{item}/{page}` เช่น `ขุ.ขุ. (ไทย) 25/5/3` |
| Precedence | ลำดับความสำคัญของประเภทเอกสาร (พระไตรปิฎก 1.0 > อรรถกถา 0.9 > ฎีกา 0.8 > ร่วมสมัย 0.7 > ธรรมะพ่อแม่ครูอาจารย์ 0.6) |
| RRF | Reciprocal Rank Fusion — รวมผลค้นหาหลายรายการด้วย `Σ 1/(k + rank)` |
| SSE | Server-Sent Events — ส่งผลลัพธ์แบบ streaming จากเซิร์ฟเวอร์ |
| TTFT | Time To First Token — เวลาตั้งแต่รับคำถามจนได้โทเคนแรกของคำตอบ |
| Guardrail | กฎป้องกันคำถามนอกขอบเขต/อ่อนไหว/prompt injection และตรวจคำตอบ |
| Unavailable Mode | โหมดปิดบริการแชตชั่วคราว (สั่งโดยผู้ดูแล หรืออัตโนมัติเมื่อโทเคนใกล้เพดาน) |

### 1.5 เอกสารอ้างอิง

- `docs/build-plan.md` (แผนพัฒนาระบบสาธิต ครอบคลุม TOR 200 ข้อ) และตาราง TOR ที่หน้า `/tor` (`src/data/tor-map.ts`)
- `/documents/requirements-summary` — สรุปความต้องการ (TOR 4.2.1)
- `/documents/ux-deliverables` — User Flow/Wireframe/Prototype (TOR 4.3.1–4.3.3)
- `/documents/data-ingestion-plan` — แผนนำเข้าข้อมูล (TOR 4.5.1)
- `/documents/master-test-plan` — แผนการทดสอบหลักและ Traceability (TOR 4.7.1)
- `/api/openapi.json` — ข้อกำหนด API (OpenAPI 3.0.3)

---

## 2. ภาพรวมระบบ

### 2.1 เทคโนโลยีที่ใช้จริง (จาก `package.json`)

| ชั้น | เทคโนโลยี |
|---|---|
| Web/Backend | Next.js 15.5 (App Router, Route Handlers), React 19.1, TypeScript strict |
| UI | Tailwind CSS 4, `next-themes` (dark/light), `next-intl` 4 (th/en), `react-markdown` + `remark-gfm`, `recharts` |
| ข้อมูล | Prisma 6.19 + SQLite (`prisma/dev.db`; ชุดทดสอบใช้ฐานข้อมูลแยกต่อไฟล์) |
| AI Orchestration | `@langchain/langgraph` 1.4 (`StateGraph` 8 โหนด) + `@langchain/core` |
| LLM | Typhoon `typhoon-v2.5-30b-a3b-instruct` ผ่าน OpenAI-compatible API (ค่าเริ่มต้นใน `src/domain/config/ai-config.ts`) สลับเป็น OpenAI / Gemini / Claude / Mock ได้ |
| Auth/Security | `jose` (JWT HS256), `bcryptjs`, CSRF double-submit, zod v4 validation |
| Parsers | `unpdf` (PDF), `mammoth` (DOCX), `fast-xml-parser` (TEI-XML), `gray-matter`, `papaparse` (CSV), `diff` |
| ทดสอบ | vitest 5 + `@vitest/coverage-v8`, Testing Library (jsdom), Playwright 1.63 |

### 2.2 โครงสร้างชั้นซอฟต์แวร์ (Clean Architecture)

```mermaid
flowchart LR
  subgraph Presentation["src/app (หน้าเว็บ + Route Handlers)"]
    P1["[locale]/... pages"]
    P2["api/... route.ts (withApi)"]
  end
  subgraph Application["src/application (use cases)"]
    A1["chat/ask.ts"]
    A2["evaluation/runner.ts"]
    A3["ingestion/kb-admin.ts"]
    A4["privacy, identity, config, ops, report"]
  end
  subgraph Adapters["src/server (adapters)"]
    S1["ai/graph.ts (LangGraph)"]
    S2["llm/* (typhoon/openai-compatible, gemini, claude, mock)"]
    S3["retrieval/* (KnowledgeIndex, reranker)"]
    S4["ingestion/* (pipeline, parsers)"]
    S5["db.ts, repos, audit, notification, logger"]
  end
  subgraph Domain["src/domain (pure TypeScript)"]
    D1["ai: guardrail-policy, citation, token-budget-policy"]
    D2["retrieval: bm25, embedding, rrf, synonyms, heuristic-reranker, relevance-scoring"]
    D3["ingestion: chunking-policy, sanitize"]
    D4["identity, privacy, audit, evaluation, report, config"]
  end
  Presentation --> Application --> Adapters --> Domain
  Presentation --> Adapters
```

กติกา: `src/domain/*` ไม่ import framework ใด ๆ (ทดสอบหน่วยได้โดยตรง) ชั้นบนเรียกชั้นล่างเท่านั้น และ coverage gate ของ vitest วัดเฉพาะ `src/domain/**` + `src/application/**` (`vitest.config.ts`)

---

## 3. ความต้องการเชิงหน้าที่ (Functional Requirements)

ตารางต่อไปนี้ระบุรหัส FR, ข้อกำหนด, ข้อ TOR ที่รองรับ และตำแหน่งที่ implement ในระบบสาธิต

### 3.1 การยืนยันตัวตนและสิทธิ์ (Identity & Access)

| รหัส | ข้อกำหนด | TOR | Implement |
|---|---|---|---|
| FR-001 | ผู้ใช้สมัครสมาชิกด้วยอีเมล รหัสผ่าน ชื่อแสดง และติ๊กยินยอมนโยบาย เก็บเฉพาะข้อมูลที่จำเป็น บันทึก `consentVersion`/`consentAt` | ก.3.3.1, 14.2 | `/register`, `POST /api/auth/register` |
| FR-002 | เข้าสู่ระบบ/ออกจากระบบด้วยอีเมล+รหัสผ่าน ออก JWT (HS256 อายุ 24 ชม.) ใน httpOnly cookie `mbu_session`; บัญชีสถานะ `suspended`/`deleted` เข้าไม่ได้ | ก.3.3.1 | `/login`, `POST /api/auth/login`, `POST /api/auth/logout`, `src/server/auth/session.ts` |
| FR-003 | เข้าสู่ระบบด้วย Gmail/Facebook (OAuth 2.0 Authorization Code + state/PKCE) และ Mock Provider ภายในเมื่อยังไม่ตั้ง client id | ก.3.3.2 | `src/server/identity/oauth/*`, `/api/auth/oauth/[provider]/start|callback`, `/mock-oauth/authorize`, `/api/mock-oauth/*` |
| FR-004 | ป้องกัน brute force: ผิด 5 ครั้ง/15 นาที/บัญชี หรือ 20 ครั้ง/15 นาที/IP → ล็อก 15 นาที และ rate limit `/api/auth/login` 10 ครั้ง/นาที/IP | ก.2.1.4 | `src/domain/identity/lockout-policy.ts`, `LoginAttempt`, `src/middleware.ts` |
| FR-005 | ทุกคำขอ POST/PUT/PATCH/DELETE ต้องแนบ CSRF token (double-submit cookie + header `x-csrf-token`) มิฉะนั้นตอบ 403 `CSRF_INVALID` | ก.2.1.5 | `src/middleware.ts`, `GET /api/csrf` |
| FR-006 | ควบคุมสิทธิ์แบบ RBAC 3 บทบาท ทุก endpoint ประกาศสิทธิ์ (`public`/`user`/รายการ role) | ก.6.1.1, ก.7.1.3 | `src/domain/identity/rbac.ts`, `withApi({ auth })` |
| FR-007 | นโยบายรหัสผ่าน: ผู้ใช้ทั่วไป ≥8 ตัวมีตัวอักษรและตัวเลข; ผู้ดูแล ≥12 ตัวผสม 4 ชนิด; ส่วนผู้ดูแล (`/admin*`, `/api/admin*`) จำกัดเฉพาะ IP ใน `ADMIN_IP_ALLOWLIST` (นอกนั้นตอบ 403 และบันทึก audit) | ก.6.1.4 | `src/domain/identity/password-policy.ts`, `src/middleware.ts`, `/api/internal/security-event` |
| FR-008 | ผู้ใช้ดู/แก้ชื่อแสดงของตนเอง | ก.3.3.1 | `GET/PATCH /api/me` |

### 3.2 ถาม-ตอบ (Q&A)

| รหัส | ข้อกำหนด | TOR | Implement |
|---|---|---|---|
| FR-010 | ผู้ใช้ส่งคำถามแล้วได้คำตอบแบบ streaming (SSE) จาก RAG pipeline พร้อมอ้างอิงที่ตรวจสอบย้อนกลับได้ ในบุคลิกบรรณารักษ์ | 2.1, 2.4, ก.4.5.2 | `/chat`, `POST /api/chat/qa`, `src/application/chat/ask.ts` |
| FR-011 | คำตอบแสดง 2 ส่วน: (1) รายการอ้างอิง ≤10 รายการ แสดง 3 รายการแรก + ปุ่ม “แสดงผลทั้งหมด/Expand All” (2) บทสรุป และข้อความเตือนท้ายคำตอบ | ก.3.6.2 | `src/components/chat/AnswerParts.tsx`, config `retrieval.finalK` (≤10) |
| FR-012 | Citation ในบทสรุปใช้รูปแบบมาตรฐาน `{abbreviation} ({edition}) {volume}/{item}/{page}` แสดงเป็นชิปสีทอง คลิกเปิด Modal เนื้อหาเต็มพร้อม metadata | ก.3.6.3, ก.4.6.3 | `src/domain/ai/citation.ts`, `GET /api/chunks/[id]` |
| FR-013 | แสดงข้อความเตือนใต้กล่องพิมพ์คำถามตลอดเวลา | ก.3.6.1 | `src/components/chat/ChatApp.tsx` + `messages/*/` |
| FR-014 | ผู้ใช้ให้ Feedback 👍/👎 (พร้อมความเห็น) ต่อคำตอบ บันทึกลงตาราง `Feedback` (1 รายการต่อผู้ใช้ต่อข้อความ) | ก.3.8.1 | `POST /api/messages/[id]/feedback` |
| FR-015 | แสดง RAG Trace ของ 8 โหนด (เวลา ms และรายละเอียดแต่ละโหนด รวม model, prompt version, โทเคน) | ก.4.10.1 | `Message.traceJson`, SSE `done.trace` |
| FR-016 | ประวัติบทสนทนาของตนเอง แสดงวันหมดอายุ ลบ/เปลี่ยนชื่อได้; ระยะเก็บเริ่มต้น 90 วัน (`retention.conversationDays`) | ก.3.5.1 | `/chat/history`, `GET/PATCH/DELETE /api/conversations[/id]` |
| FR-017 | ผู้ใช้เข้าถึงได้เฉพาะบทสนทนาของตนเอง (ไม่ใช่เจ้าของ = 404 กัน IDOR) | ก.2.1.1 | `loadOwnedConversation()` ใน `src/application/chat/ask.ts` |

### 3.3 Dhamma Talk

| รหัส | ข้อกำหนด | TOR | Implement |
|---|---|---|---|
| FR-020 | สร้างบทธรรมบรรยายแบบ Artifact (Markdown) ทีละรอบ แสดงใน Response Modal แยก มีแท็บแก้ไข/ตัวอย่าง ผู้ใช้แก้ไขแล้วบันทึก และคำสั่งรอบถัดไปใช้ฉบับที่ผู้ใช้แก้ล่าสุดเป็นบริบท พร้อมข้อความเตือนในโหมดนี้ | ก.3.7.1–ก.3.7.4 | `/chat/dhamma-talk`, `POST /api/chat/dhamma-talk`, `PATCH /api/conversations/[id]` (`artifactMd`), `DhammaTalkApp.tsx` |
| FR-021 | สิทธิ์ใช้ Dhamma Talk แยกรายบัญชี ค่าเริ่มต้นปิด (`User.dhammaTalkEnabled = false`) ผู้ดูแลเปิด/ปิดได้ | ก.3.3.3, ก.6.1.3 | `PATCH /api/admin/users/[id]`, ตรวจสิทธิ์ใน route |

### 3.4 AI Engine และการค้นคืน (RAG)

| รหัส | ข้อกำหนด | TOR | Implement |
|---|---|---|---|
| FR-030 | Orchestrator ด้วย LangGraph.js `StateGraph` 8 โหนด และ LLM แบบ model-agnostic ผ่าน interface `LlmGateway` (typhoon/openai/gemini/claude/mock) เปลี่ยนได้จาก config โดยไม่แก้โค้ด | ก.4.1.2, 4.4.6, 2.6, ก.6.2.3 | `src/server/ai/graph.ts`, `src/server/llm/*` |
| FR-031 | Hybrid Search: BM25 (ตัดคำไทยด้วย `Intl.Segmenter`) + pseudo-embedding 512 มิติ (feature hashing) รวมด้วย RRF (k=60) รองรับไทย–บาลี–อังกฤษด้วยพจนานุกรม synonym | ก.4.6.1 | `src/domain/retrieval/{tokenizer,bm25,embedding,rrf,synonyms}.ts`, `src/server/retrieval/index.ts` |
| FR-032 | Query Expansion/Rewriting: ขยายคำพ้อง + ขอคำค้นเพิ่มจาก LLM ด้วย prompt `query-rewrite` (เมื่อใช้ LLM จริง) | ก.4.7.2 | โหนด `inputGuardrail`/`rewriteQuery` |
| FR-033 | Re-ranker เป็นโมดูลแยก สลับได้ด้วย `retrieval.reranker` (`heuristic` ค่าเริ่มต้น หรือ `tei` เมื่อตั้ง `TEI_RERANK_URL`) | ก.4.7.1 | `src/domain/retrieval/heuristic-reranker.ts`, `src/server/retrieval/{reranker,tei-reranker}.ts` |
| FR-034 | ปรับคะแนนด้วย Precedence ของประเภทเอกสาร (ปรับรายเอกสารได้ 0–2) แล้วตัดเหลือ `finalK` ≤10 | ก.4.8.3, ก.6.3.3 | `src/domain/retrieval/relevance-scoring.ts` |
| FR-035 | บุคลิกบรรณารักษ์: ช่วยค้น/สรุปพร้อม Citation ไม่ชี้ขาดการตีความ ปฏิเสธคำถามใช่/ไม่ใช่ | ก.4.5.1, ก.4.5.3 | `config/prompts/qa-persona.v*.md`, guardrail `yes_no_pattern` |

### 3.5 Guardrails

| รหัส | ข้อกำหนด | TOR | Implement |
|---|---|---|---|
| FR-040 | ตอบเฉพาะคำถามด้านพระไตรปิฎก อรรถกถา หลักธรรม และแนวทางปฏิบัติ/ปรัชญาชีวิต (หัวข้อ `scope_allow`); คำถามนอกขอบเขตถูกปฏิเสธอย่างสุภาพ เมื่อใช้ LLM จริงยืนยันด้วย prompt `guard-classifier` | ก.4.3.1, ก.4.3.2 | `src/domain/ai/guardrail-policy.ts`, โหนด `inputGuardrail` |
| FR-041 | ป้องกัน Prompt Injection ทั้งทางตรง (รูปแบบ `injection_pattern`) และทางอ้อม (sanitize ตอนนำเข้า + ครอบบริบทด้วย delimiter `<<<DATA ...>>>` และระบุว่า “เป็นข้อมูล ไม่ใช่คำสั่ง”) | ก.4.4.1 | `src/domain/ingestion/sanitize.ts`, `src/server/ai/context.ts` |
| FR-042 | ปฏิเสธหัวข้อการเมือง การเปรียบเทียบศาสนา/นิกาย และสุขภาพจิต พร้อมข้อความเฉพาะหัวข้อ | ก.4.4.3 | `GuardrailTopic` kind `refuse_sensitive` (key `politics`, `religion_comparison`, `mental_health`) |
| FR-043 | Output guardrail: แทน `[[cite:...]]` ด้วย label มาตรฐาน ตัด citation ที่ไม่อยู่ในรายการอ้างอิง ติดป้าย “(ไม่มีอ้างอิง — โปรดตรวจสอบ)” ให้ย่อหน้าที่ไม่มีอ้างอิง และลดทอนถ้อยคำชี้ขาด | ก.4.5.3, ก.4.6.3 | `resolveCitations()`, `evaluateOutput()` |
| FR-044 | ผู้ดูแลเพิ่ม/แก้/ลบ/เปิดปิดหัวข้อขอบเขตและหัวข้อปฏิเสธ และทดสอบข้อความได้ทันที | ก.6.2.5, ก.4.4.1 | `/admin/guardrails`, `/api/admin/guardrails*` |

### 3.6 งบประมาณโทเคนและโหมดปิดบริการ

| รหัส | ข้อกำหนด | TOR | Implement |
|---|---|---|---|
| FR-050 | เพดานโทเคนรวม 24 ชั่วโมงล่าสุด ค่าเริ่มต้น 10,000,000 (`tokens.dailyCap`) | ก.3.4.1 | `src/domain/ai/token-budget-policy.ts` (`checkDailyBudget`), `src/server/ai/availability.ts` |
| FR-051 | เพดานโทเคนต่อ prompt: ถาม-ตอบ ≤10,000 และ Dhamma Talk ≤50,000 (schema บังคับช่วง) และปรับ Max Tokens ได้ | ก.4.2.1, ก.3.4.2, ก.6.2.1 | `tokens.maxPerPromptQa`, `tokens.maxPerPromptDhammaTalk`, `tokens.maxOutput`, `fitContext()` |
| FR-052 | เข้า Unavailable อัตโนมัติก่อนยอดจริงเกินเพดาน (คำขอที่ทำให้ยอดจองเกินเพดานถูกปฏิเสธก่อนเรียก LLM; margin ≤10%) พร้อมแจ้งเตือน `auto_unavailable` | ก.3.4.4 | `checkAvailability()`, `reserveTokens()` |
| FR-053 | ป้องกัน Cost Surge: จำกัดความยาว input (`input.maxChars` ค่าเริ่มต้น 2,000 → 400 `INPUT_TOO_LONG`) และ thinking budget (`tokens.thinkingBudget`) | ก.4.4.2 | โหนด `checkAvailability`, `generate` |
| FR-054 | ผู้ดูแลเปิด Unavailable Mode พร้อมข้อความ ไทย/อังกฤษ ทุกหน้าแสดงแบนเนอร์ (อ่าน `/api/status`) และ API แชตตอบ 503 | ก.3.4.3, ก.6.6.1 | `/admin/unavailable`, `GET/PUT /api/admin/unavailable-mode`, `GET /api/status` |

### 3.7 การเก็บรักษาข้อมูลและ PDPA

| รหัส | ข้อกำหนด | TOR | Implement |
|---|---|---|---|
| FR-060 | ลบบทสนทนาที่พ้น `retentionUntil` อัตโนมัติทุก `retention.purgeIntervalMinutes` (ค่าเริ่มต้น 60 นาที) และสั่งทันทีได้ | ก.3.5.1, ก.6.2.2 | `src/application/privacy/purge.ts` (เริ่มใน `src/instrumentation-node.ts`), `POST /api/admin/maintenance/purge-conversations`, `npm run purge:conversations` |
| FR-061 | ผู้ใช้ดาวน์โหลดสำเนาข้อมูลตนเอง (JSON) และยื่นคำขอ `access_copy` / `erase` / `withdraw_consent` | 14.4 | `/privacy`, `GET /api/privacy/export`, `GET/POST /api/privacy/requests` |
| FR-062 | ผู้ดูแลดูและดำเนินการคำขอ PDPA (สร้างไฟล์สำเนา, ลบบทสนทนา+ทำให้ข้อมูลผู้ใช้เป็นนิรนาม, ระงับบัญชีเมื่อถอนยินยอม) และสร้างคำขอแทนผู้ใช้ | 14.4, ก.6.1.2 | `/admin/privacy-requests`, `/api/admin/privacy-requests*` |
| FR-063 | เข้ารหัสอีเมล/ชื่อด้วย AES-256-GCM (`DATA_ENCRYPTION_KEY`) ค้นหาด้วย `emailHash`; สร้างสำเนาข้อความที่ปิดบัง PII (`Message.contentMasked`) | 14.3 | `src/server/crypto.ts`, `src/server/repos/user-repo.ts`, `src/domain/privacy/pii-masking.ts` |
| FR-064 | แบนเนอร์ยินยอมคุกกี้ โหลด Google Analytics 4 เฉพาะเมื่อผู้ใช้ยินยอมและตั้ง `NEXT_PUBLIC_GA_ID`; หน้า `/privacy-policy` ระบุผู้ควบคุม/ผู้ประมวลผลข้อมูล | ก.1.1.3, ก.1.5.1, 14.1 | `src/components/layout/Banners.tsx`, `/privacy-policy` |

### 3.8 ฐานองค์ความรู้และการนำเข้า

| รหัส | ข้อกำหนด | TOR | Implement |
|---|---|---|---|
| FR-070 | อัปโหลดเอกสาร PDF / TXT / Markdown / TEI-XML / DOCX ≤20MB พร้อม metadata แล้วนำเข้าแบบ async | ก.4.8.1, ก.6.3.1 | `/admin/knowledge-base`, `POST /api/admin/knowledge-base/upload`, `src/server/ingestion/parsers/index.ts` |
| FR-071 | Chunking: พระไตรปิฎก/อรรถกถาแบ่ง 1 ข้อ = 1 chunk ไม่ตัดกลางข้อ (ข้อยาว >3,000 tokens ติดธง `oversized`); เอกสารอื่นใช้ semantic chunking (~400 tokens ตัดเมื่อ cosine ระหว่างย่อหน้า <0.35) | ก.4.8.2, ก.4.6.2 | `src/domain/ingestion/chunking-policy.ts` |
| FR-072 | Metadata: ปิฎก นิกาย สูตร เล่ม ข้อ หน้า ประเภทเอกสาร ฉบับ ตัวย่อ เล่ม มมร. คำบาลี และ precedence แก้ไขได้ (อัปเดตดัชนีทันที) | ก.4.8.3, ก.6.3.1, ก.6.3.3 | `PATCH /api/admin/knowledge-base/[id]` |
| FR-073 | Pipeline ปรับดัชนี: งาน `ingest` / `reindex_all` / `reindex_selected` / `delete` แสดงสถานะรายเอกสาร (stage parse→sanitize→chunk→embed→index) รายการที่ล้มเหลว และรันซ้ำเฉพาะที่ล้มเหลว | ก.4.5.3, ก.4.7.3, ก.6.3.2 | `src/server/ingestion/pipeline.ts`, `/admin/knowledge-base/jobs`, `/api/admin/knowledge-base/{reindex,jobs*}` |
| FR-074 | รายงานความครอบคลุมเทียบพระไตรปิฎกและอรรถกถาฉบับ มมร. 91 เล่ม | 4.5.2, 7.2.5, ข.1 | `GET /api/admin/knowledge-base/coverage`, `src/application/ingestion/coverage.ts`, `npm run report:ingestion` |
| FR-075 | Sanitize ข้อความก่อนนำเข้า: ตัด control/invisible chars และบรรทัดที่เข้ารูปแบบคำสั่งแฝง บันทึกจำนวนบรรทัดที่ตัด | ก.4.4.1 | `src/domain/ingestion/sanitize.ts`, `KnowledgeDocument.sanitizedLines` |

### 3.9 การตั้งค่า AI และ Prompt

| รหัส | ข้อกำหนด | TOR | Implement |
|---|---|---|---|
| FR-080 | ผู้ดูแลปรับค่า AI (provider/model, เพดานโทเคน, retention, retrieval, เกณฑ์ประเมิน ฯลฯ) มีผลทันทีโดยไม่ redeploy ทุกการแก้สร้าง `ConfigSnapshot` และย้อนกลับได้ | ก.6.2.1–ก.6.2.3, ก.6.2.6 | `/admin/ai-config`, `/api/admin/ai-config*`, `src/server/config/ai-config-store.ts` |
| FR-081 | ทดสอบการเชื่อมต่อ LLM และแสดงรายการ provider/model ที่ adapter รองรับ (ระบุว่าตั้ง API key แล้วหรือไม่ โดยไม่เปิดเผยค่า) | ก.6.2.3, 4.6.1 | `POST /api/admin/ai-config/test-llm`, `GET /api/admin/ai-config/models` |
| FR-082 | Prompt ไม่ hard-code: เก็บเป็นเวอร์ชัน (`PromptVersion`) ดู/เพิ่ม/แก้ (สร้างเวอร์ชันใหม่)/diff/activate (rollback) พร้อมผู้แก้และเวลา | ก.4.9.1, ก.6.2.4 | `/admin/prompts`, `/api/admin/prompts*` |
| FR-083 | Remote configuration ด้วยสคริปต์: `npm run prompts:publish` อ่าน `config/prompts/*.md` สร้างเวอร์ชันเมื่อเนื้อหาต่าง | ก.4.9.2 | `scripts/prompts/publish.ts` |
| FR-084 | กำหนดอัตราค่าโทเคนต่อ model (input/thinking/output ต่อ 1M) ใช้ประมาณค่าใช้จ่าย | ก.7.3.3 | `/admin/pricing`, `/api/admin/pricing*`, `LlmPricing` |

### 3.10 การประเมินคุณภาพ AI

| รหัส | ข้อกำหนด | TOR | Implement |
|---|---|---|---|
| FR-090 | ชุดทดสอบ 7 ชุด: DS-1 ธรรมศึกษาปรนัย 100, NT-2 นักธรรมตอบสั้น 50, RET-1/2/3 Retrieval วินัย/สุตตันตะ/อภิธรรม ชุดละ 100, GR-1 นอกขอบเขต 100, GR-2 หัวข้อสุ่มเสี่ยง 50 | ก.5.1.1–ก.5.1.7 | `seed/benchmarks/*.csv`, `seed/benchmarks/SOURCES.md` |
| FR-091 | จัดการชุดและข้อทดสอบผ่านเว็บ (เพิ่ม/แก้/ลบ) นำเข้า CSV และดาวน์โหลดแม่แบบ ทุกการเปลี่ยนข้อทดสอบเพิ่ม `version` | ก.5.2.1, ก.6.4.1, ก.5.2.4 | `/api/admin/evaluation/datasets*` |
| FR-092 | 3 workflow: Accuracy (exact match ตัวเลือก), Recall@5 (retrieval), LLM-as-Judge 0–3 และ Refusal (guardrail) ผ่าน pipeline จริง | ก.5.2.2 | `src/application/evaluation/runner.ts` (`evaluateItem`), `src/domain/evaluation/scorers.ts` |
| FR-093 | สั่งรันรายชุดแบบ async บันทึกผลรายข้อ + prompt version + dataset version + model + judge model | ก.5.2.3, ก.5.2.4, ก.6.4.2 | `POST/GET /api/admin/evaluation/runs*` |
| FR-094 | เปรียบเทียบผลระหว่าง 2 รอบของชุดเดียวกัน (รายข้อ + delta + เวอร์ชัน) | ก.6.4.3 | `GET /api/admin/evaluation/compare` |
| FR-095 | เกณฑ์ขั้นต่ำ (80% / Judge 2.00) และค่ารับประกันของผู้รับจ้าง แสดงผ่าน/ไม่ผ่านเกณฑ์ตรวจรับ | ก.5.3, ก.5.3.1, 16.2 | `GET /api/admin/evaluation/thresholds`, `eval.guaranteed` |
| FR-096 | รายงาน AI Security: รัน GR-1 + GR-2 + ชุด Prompt Injection 20 เคส แสดงอัตราป้องกันต่อชุด/ประเภทการโจมตี | 7.2.7 | `GET/POST /api/admin/evaluation/security-report` |
| FR-097 | ส่งออกรายงาน Baseline/Acceptance และ Guardrail เป็น Markdown ลง `docs/deliverables` | 4.7.7, 7.2.3 | `POST /api/admin/evaluation/export`, `npm run report:evaluation` |

### 3.11 ผู้ดูแลผู้ใช้ และบันทึกการตรวจสอบ (Audit)

| รหัส | ข้อกำหนด | TOR | Implement |
|---|---|---|---|
| FR-100 | ค้นหา/ดู/แก้/ระงับ/ลบ (soft) ผู้ใช้ แสดงสถานะ วันสมัคร การใช้งานล่าสุด สิทธิ์ Dhamma Talk | ก.6.1.2 | `/admin/users`, `/admin/users/[id]`, `/api/admin/users*` |
| FR-101 | การเปลี่ยน role ทำได้เฉพาะ `SUPER_ADMIN` และบันทึก audit `role_changed` | ก.6.1.1 | `PATCH /api/admin/users/[id]` |
| FR-102 | การเปิดดูบทสนทนาของผู้ใช้โดยผู้ดูแลถูกบันทึก audit `conversation_accessed` | ก.6.5.1 | `GET /api/admin/users/[id]/conversations` |
| FR-110 | บันทึก Audit: login/logout สำเร็จ-ไม่สำเร็จ สิทธิ์ config/prompt เอกสาร การเข้าถึงบทสนทนา การสั่งประเมิน คำขอ PDPA ทำลายข้อมูล defect พร้อม timestamp ผู้กระทำ IP ประเภท ก่อน/หลัง ผลลัพธ์ | ก.6.5.1, ก.6.5.2 | `src/server/audit/audit-logger.ts`, `AuditLog` |
| FR-111 | Audit Log แก้ไข/ลบไม่ได้ (SQLite trigger `audit_no_update`/`audit_no_delete`) และตรวจความสมบูรณ์ด้วย hash chain (sha256) | ก.6.5.3 | `prisma/migrations/20261002110735_audit_immutable`, `src/domain/audit/hash-chain.ts`, `GET /api/admin/audit-log/verify` |
| FR-112 | ค้นหา/กรอง Audit Log และส่งออก CSV หรือพิมพ์เป็น PDF | ก.6.5.4 | `/admin/audit-log`, `GET /api/admin/audit-log/export` |

### 3.12 Dashboard และการแจ้งเตือน

| รหัส | ข้อกำหนด | TOR | Implement |
|---|---|---|---|
| FR-120 | Dashboard (เฉพาะ ADMIN/SUPER_ADMIN): บัญชีทั้งหมด DAU MAU sessions queries เฉลี่ยต่อ session แยกโหมด เลือกช่วง วัน/สัปดาห์/เดือน/ปี/กำหนดเอง และเทียบช่วงก่อนหน้า ข้อมูลอ่านสดจากฐานข้อมูล | ก.7.1.1, ก.7.1.2, ก.7.1.3, ก.7.2.1, ก.7.2.2 | `/admin/dashboard`, `GET /api/admin/dashboard/usage` |
| FR-121 | โทเคน input/thinking/output รายวัน/เดือนเทียบเพดาน โทเคนเฉลี่ยต่อคำถาม/บทสนทนาเทียบเป้า ประมาณการค่าใช้จ่าย และ Top users | ก.7.3.1–ก.7.3.4 | `GET /api/admin/dashboard/tokens` |
| FR-122 | อัตรา Feedback 👍/👎 | ก.3.8.1 | `GET /api/admin/dashboard/feedback` |
| FR-130 | แจ้งเตือนทางอีเมล (SMTP เมื่อตั้งค่า มิฉะนั้นบันทึกใน `AlertEmailLog`): โทเคนถึงเกณฑ์ (`tokens.alertThresholdPct`), ค่าใช้จ่ายถึงเกณฑ์, error rate แชต >5% ใน 15 นาที, เข้า Unavailable อัตโนมัติ, งานนำเข้าล้มเหลว | ก.4.10.2, ก.7.3.5 | `src/server/notification/index.ts`, `src/server/ai/usage.ts`, `/admin/alerts` |

### 3.13 การปฏิบัติการ (Ops) และเว็บไซต์

| รหัส | ข้อกำหนด | TOR | Implement |
|---|---|---|---|
| FR-140 | Defect Log: ความรุนแรง critical/high = 24 ชม., medium = 48 ชม., low = 80 ชม. ทำการ (10 วันทำการ) คำนวณ deadline แบบชั่วโมงทำการ ปิด high/critical ต้องมี resolutionNote การยืนยันของมหาวิทยาลัยคำนวณชั่วโมงเกินและค่าปรับ 0.025%/ชม. | 12.3, 12.4, 10.2, 4.7.8 | `/admin/defect-log`, `src/domain/report/sla-policy.ts` |
| FR-141 | รายงาน SLA: Availability, p95 latency, TTFT p95, error rate, defect เกิน SLA ส่งออกรายงานรายเดือน | 12.1, 12.2, 12.5 | `/admin/sla-report`, `/api/admin/sla-report*`, `npm run report:sla` |
| FR-142 | สำรองฐานข้อมูลและไฟล์อัปโหลด (SUPER_ADMIN) พร้อมคำสั่งกู้คืน | ก.1.6.3 | `/admin/backup`, `scripts/backup-db.sh`, `scripts/restore-db.sh` |
| FR-143 | ทำลายข้อมูลตามขอบเขตที่เลือกพร้อมหนังสือรับรอง (SUPER_ADMIN, ต้องพิมพ์ข้อความยืนยัน) | 4.11.3 | `/admin/data-destruction`, `POST /api/admin/data-destruction` |
| FR-144 | Health/Status/OpenAPI: `/api/health` (สถานะ DB และจำนวน chunk), `/api/status` (Unavailable + % งบโทเคน ไม่เปิดเผยความลับ), `/api/openapi.json` | ก.4.1.1 | `src/app/api/{health,status,openapi.json}` |
| FR-145 | Logging: JSON lines ลง `logs/app.log` + stdout และบันทึกทุกคำขอ API ลง `ApiRequestLog` (path, status, durationMs, ttftMs) | ก.4.10.1 | `src/server/logger.ts`, `withApi` |
| FR-150 | สองภาษา ไทย/อังกฤษ (`/th`, `/en`) มีเมนูสลับภาษาทุกหน้า | ก.3.2.1 | `next-intl`, `messages/{th,en}/*.json`, `LanguageSwitcher.tsx` |
| FR-151 | ธีมมืด/สว่าง พร้อมปุ่มสลับทุกหน้า | ก.3.1.3 | `next-themes`, `ThemeToggle.tsx` |
| FR-152 | Responsive รองรับมือถือ แท็บเล็ต เดสก์ท็อป (390/768/1280 px) ไม่มี horizontal scroll | ก.1.2.1, 4.3.3 | Tailwind, Playwright 3 viewport |
| FR-153 | หน้า `/tor` (ตาราง 200 ข้อ ค้นหา/กรอง/ส่งออก CSV) และศูนย์เอกสาร `/documents` (ดาวน์โหลด .md / พิมพ์ PDF) | 7.5, 4.4 | `src/app/[locale]/{tor,documents}` |
| FR-154 | หน้า `/help` วิธีใช้และช่องทางติดต่อช่วงรับประกัน | 11.2 | `src/app/[locale]/help` |

---

## 4. ความต้องการที่ไม่ใช่เชิงหน้าที่ (Non-Functional Requirements)

| รหัส | หมวด | ข้อกำหนด | TOR | วิธีรองรับ/ตรวจวัดในระบบสาธิต |
|---|---|---|---|---|
| NFR-001 | ประสิทธิภาพ | FCP ≤5 วินาที, TTFT ≤15 วินาที, Error rate ≤5% ที่ p95 | 12.2 | วัด TTFT ทุกคำขอ (`Message.ttftMs`, `ApiRequestLog.ttftMs`); E2E ตรวจ FCP <5s; `npm run report:perf` → `/documents/performance-report` |
| NFR-002 | รองรับผู้ใช้พร้อมกัน | ≥500 concurrent sessions | ก.1.4.1, 4.7.6 | ทดสอบโหลดระดับเครื่องเดียวด้วย `scripts/perf/load-test.ts`; ระดับ 500 ต้องใช้สถาปัตยกรรม Production (HPA) |
| NFR-003 | ขนาดข้อมูลผู้ใช้ | รองรับ 1,000,000 บัญชี | ก.1.4.2 | `npm run seed:perf-users -- --count=1000000` ลง `prisma/perf.db` แล้ววัดเวลาค้นหา (index `emailHash` unique) |
| NFR-004 | ความพร้อมใช้งาน | ≥95% ต่อเดือน | 12.1, ก.1.6.1 | คำนวณจาก uptime ของ process + ช่วง 5xx (`/admin/sla-report`); Production ใช้ replica ≥2 + probe |
| NFR-005 | การขยายระบบ | Microservices, Horizontal/Auto Scaling | ก.1.3.1, ก.1.3.2, ก.1.6.2 | โค้ดแบ่ง bounded context; Helm chart 8 deployment + HPA (CPU 70%) ที่ `infra/helm/mbu-buddhist-ai/` |
| NFR-006 | ความมั่นคงปลอดภัย | OWASP Top 10, TLS, Server-side validation, CSRF, Brute force, Security headers, Rate limit, WAF | ก.2.1.1–ก.2.1.5, ก.2.2.1, ก.1.1.2 | zod ทุก endpoint, Prisma (parameterized), CSP/X-Frame-Options/nosniff/Referrer-Policy/Permissions-Policy/COOP (`next.config.ts`), HSTS เมื่อ `ENABLE_HSTS=1`, rate limit 10/60/600 ต่อนาที, TLS self-signed (`server.https.js`); WAF เป็นตัวอย่างใน Helm values |
| NFR-007 | ความเป็นส่วนตัว | PDPA: minimisation, consent, เข้ารหัส in transit/at rest, ปิดบัง PII, สิทธิเจ้าของข้อมูล | 14.1–14.4, ก.1.1.3 | FR-001, FR-061–FR-064 |
| NFR-008 | การเข้าถึง | Contrast ≥4.5:1 (ข้อความปกติ) / ≥3:1 (ข้อความใหญ่) ทั้ง light/dark; มาตรฐานเว็บไซต์ภาครัฐ 3.0 | ก.3.1.1, ก.1.1.1 | `src/styles/tokens.ts` (`contrastPairs`) + `tests/unit/contrast.test.ts`; ประเมินตนเองใน `/documents/test-checklist` |
| NFR-009 | ความเข้ากันได้ | Chrome Android/Safari iOS, Chrome/Firefox/Safari/Edge | ก.1.2.1, ก.1.2.2 | ทดสอบอัตโนมัติด้วย Chromium 3 viewport (เบราว์เซอร์อื่นยังไม่ได้ทดสอบใน sandbox) |
| NFR-010 | การบำรุงรักษา | แยกชั้น, Unit coverage ≥80% (ไม่นับ config) | 4.7.3 | coverage gate lines/functions/statements ≥80%, branches ≥75% (`vitest.config.ts`) |
| NFR-011 | การติดตาม/วินิจฉัย | Log เพียงพอต่อการวินิจฉัย | ก.4.10.1 | FR-145, RAG Trace (FR-015), `x-request-id` ทุกคำขอ |
| NFR-012 | ความยืดหยุ่นของโมเดล | เปลี่ยน LLM/องค์ประกอบ AI โดยไม่กระทบระบบ | 4.4.6, 2.6 | `LlmGateway`, `SearchGateway`, `RerankerGateway`, `NotificationGateway` |
| NFR-013 | ความถูกต้องของ Audit | เก็บ ≥90 วัน แก้/ลบไม่ได้ | ก.6.5.3 | ไม่มีกลไกลบ AuditLog (trigger ห้าม UPDATE/DELETE; ทำลายข้อมูลไม่ลบ AuditLog) |
| NFR-014 | การสำรองและกู้คืน | คู่มือ + ทดสอบ restore ≥1 ครั้ง | ก.1.6.3 | `/documents/backup-restore-guide`, `npm run report:restore-test` → `/documents/restore-test-report` |
| NFR-015 | ความน่าเชื่อถือของคำตอบ | ทุกคำตอบอ้างอิงตรวจสอบย้อนกลับได้ ไม่ตัดตอนพระไตรปิฎก | 2.1, ก.4.6.2 | FR-012, FR-043, FR-071 |
| NFR-016 | ภาษาและวันที่ | วันที่แสดงเป็นพุทธศักราชเมื่อ locale = th | ก.3.2.1 | `fmtDate(d, locale)` |

---

## 5. สถาปัตยกรรมระบบ

### 5.1 แผนภาพสถาปัตยกรรมระบบสาธิต

```mermaid
flowchart TB
  U["ผู้ใช้ / ผู้ดูแล (เบราว์เซอร์)"] -->|HTTPS (server.https.js :3443) หรือ HTTP| MW["middleware.ts<br/>requestId · rate limit · CSRF · admin IP allowlist · locale"]
  MW --> PAGES["หน้าเว็บ src/app/[locale]/*"]
  MW --> API["Route Handlers src/app/api/* (withApi: RBAC · zod · audit · ApiRequestLog)"]
  API --> UC["Use cases src/application/*"]
  UC --> GRAPH["LangGraph StateGraph 8 โหนด<br/>src/server/ai/graph.ts"]
  GRAPH --> IDX["KnowledgeIndex (in-memory)<br/>BM25 + pseudo-embedding 512 + RRF"]
  GRAPH --> RR["Reranker: Heuristic | TEI"]
  GRAPH --> LLM["LlmGateway<br/>Typhoon (OpenAI-compatible) · OpenAI · Gemini · Claude · Mock"]
  UC --> DB[("SQLite ผ่าน Prisma<br/>prisma/dev.db")]
  GRAPH --> DB
  UC --> ING["Ingestion pipeline<br/>parse → sanitize → chunk → embed → index"]
  ING --> STORE[["storage/uploads"]]
  ING --> IDX
  UC --> NOTI["NotificationGateway<br/>AlertEmailLog | SMTP"]
  API --> LOG[["logs/app.log (JSON lines)"]]
  LLM -.->|HTTPS| TY["api.opentyphoon.ai/v1"]
```

### 5.2 การแมปสถาปัตยกรรม Production ↔ ระบบสาธิต

| Production (Solution Architecture) | ระบบสาธิต |
|---|---|
| 8 microservices (NestJS) บน Kubernetes: identity, chat, ai-orchestrator, retrieval, ingestion, evaluation, config, report | Next.js 15 แอปเดียว แบ่ง bounded context ใน `src/domain`, `src/application`, `src/server` + Helm chart 8 deployment ที่ `infra/helm/mbu-buddhist-ai/` |
| PostgreSQL 16 / Redis 7 (token budget, lockout, config pub/sub, BullMQ) | SQLite (Prisma) / ตาราง `TokenUsage`, `LoginAttempt`; config อ่านจาก DB ทุกคำขอ (hot reload); คิวงาน = `IngestionJob` ประมวลผล async ใน process เดียว |
| Elasticsearch BM25 + kNN (bge-m3) + RRF | BM25 in-memory (ตัดคำไทย `Intl.Segmenter`) + pseudo-embedding 512 มิติ + RRF (`SearchGateway`; มี `ElasticsearchSearchAdapter` เป็นโครง) |
| bge-reranker-v2-m3 (TEI) | `HeuristicReranker` (สลับเป็น `TeiRerankerAdapter` ได้เมื่อตั้ง `TEI_RERANK_URL`) |
| LangGraph.js | LangGraph.js จริง (`@langchain/langgraph`) |
| SMTP / S3 / cert-manager / Prometheus | `AlertEmailLog` (หรือ SMTP เมื่อตั้งค่า) / `storage/uploads` / self-signed TLS / `logs/app.log` + `ApiRequestLog` |
| GitHub Actions + Helm + HPA + WAF | ไฟล์ส่งมอบ `.github/workflows/ci-cd.yml`, `infra/helm/` (ยังไม่ได้ deploy จริง และยังไม่ได้รันบน GitHub Actions) |

### 5.3 Workflow: ถาม-ตอบผ่าน RAG pipeline 8 โหนด

ลำดับโหนดใน `src/server/ai/graph.ts`: `checkAvailability → inputGuardrail → rewriteQuery → hybridSearch → rerank → generate → outputGuardrail → persist` โดย refusal ที่โหนด 1–2 ข้ามไปโหนด `persist` ทันที (conditional edge) ก่อนเปิด SSE ระบบตรวจ availability ล่วงหน้าเพื่อให้ตอบ HTTP 503/400 เป็น JSON ได้

```mermaid
sequenceDiagram
  autonumber
  actor U as ผู้ใช้ (/chat)
  participant API as POST /api/chat/qa (withApi)
  participant UC as askStream (application/chat/ask.ts)
  participant G as ragGraph (LangGraph)
  participant IDX as KnowledgeIndex
  participant L as LlmGateway (Typhoon)
  participant DB as SQLite (Prisma)
  U->>API: { question, conversationId?, locale } + cookie + x-csrf-token
  API->>UC: ตรวจสิทธิ์ user + zod
  UC->>DB: โหลดบทสนทนา (ownership) + getAiConfig()
  UC->>UC: checkAvailability (unavailable / เพดาน 24 ชม. / input.maxChars)
  alt ไม่ผ่าน
    UC-->>U: HTTP 503 SERVICE_UNAVAILABLE หรือ 400 INPUT_TOO_LONG (บันทึก refusal)
  else ผ่าน
    UC-->>U: เปิด SSE (text/event-stream)
    UC->>G: runRagGraph(input) + reserveTokens()
    G->>G: 1 checkAvailability (trace)
    G->>DB: 2 inputGuardrail โหลด GuardrailTopic
    opt LLM จริง
      G->>L: guard-classifier + query-rewrite (ขนานกัน)
    end
    alt ถูกปฏิเสธ (scope/injection/sensitive/yes_no)
      G->>DB: 8 persist (Message.refusalReason)
      G-->>U: event: refusal
    else ผ่าน
      G->>G: 3 rewriteQuery (synonym ไทย-บาลี-อังกฤษ + LLM queries)
      G->>IDX: 4 hybridSearch BM25 + vector + RRF (candidateK=50)
      G->>G: 5 rerank (Heuristic) + precedence → finalK ≤10
      G-->>U: event: references
      G->>L: 6 generate (persona + DATA delimiters, fitContext ≤ maxPerPrompt)
      loop streaming
        L-->>G: delta
        G-->>U: event: delta (วัด TTFT)
      end
      G->>G: 7 outputGuardrail (resolveCitations, evaluateOutput)
      G->>DB: 8 persist (Message + contentMasked + Citation + TokenUsage + traceJson)
    end
    G->>DB: afterUsageRecorded (threshold / error-rate alerts)
    UC-->>U: event: done {conversationId, messageId, answer, references, usage, trace, ttftMs, latencyMs, model, promptVersion}
  end
  Note over UC,U: ข้อผิดพลาดระหว่างสร้างคำตอบ → event: error {code: GENERATION_FAILED}
```

**Dhamma Talk** (`POST /api/chat/dhamma-talk`) ใช้กราฟเดียวกันด้วย `mode = DHAMMA_TALK`: โหนด `rewriteQuery` เพิ่มหัวเรื่องของ artifact เป็นคำค้น โหนด `generate` ใช้ prompt `dhamma-talk` พร้อม artifact ฉบับที่ผู้ใช้แก้ล่าสุดครอบด้วย `<<<ARTIFACT>>>` เพดาน `tokens.maxPerPromptDhammaTalk` และโหนด `persist` บันทึก `Conversation.artifactMd`

### 5.4 Workflow: การนำเข้าเอกสาร (Ingestion)

```mermaid
sequenceDiagram
  autonumber
  actor A as ผู้ดูแล (/admin/knowledge-base)
  participant API as POST /api/admin/knowledge-base/upload
  participant FS as storage/uploads
  participant DB as SQLite
  participant Q as enqueueJob (job chain ใน process)
  participant P as pipeline.ts
  participant IDX as KnowledgeIndex
  A->>API: multipart: file (pdf/txt/md/xml/docx ≤20MB) + metadata
  API->>FS: บันทึกไฟล์
  API->>DB: KnowledgeDocument (pending) + IngestionJob(ingest) + IngestionJobItem + audit document_imported
  API-->>A: { document, jobId }
  API->>Q: enqueueJob(jobId)
  Q->>P: runJob
  P->>DB: item.stage = parse
  P->>P: parseFile (unpdf / mammoth / TEI→marker / txt) + stripFrontmatter
  P->>P: sanitize (ตัด control chars + บรรทัดคำสั่งแฝง)
  P->>P: chunk (ChunkingPolicy: ตามข้อ หรือ semantic)
  P->>P: embed (pseudo-embedding 512 มิติ)
  P->>DB: index: transaction ลบ/อัปเดต/สร้าง Chunk (คง id ของ chunk ที่เนื้อหาเดิม)
  P->>IDX: reindexDocument(documentId)
  alt สำเร็จทุก item
    P->>DB: job.status = completed
  else มีรายการล้มเหลว
    P->>DB: job.status = partial | failed + item.errorMsg
    P->>DB: AlertEmailLog (ingestion_failed)
  end
  A->>API: GET /api/admin/knowledge-base/jobs/[id] (ติดตามสถานะ) / POST .../retry-failed
```

### 5.5 Workflow: การประเมินคุณภาพ AI (Evaluation)

```mermaid
sequenceDiagram
  autonumber
  actor A as ผู้ดูแล (/admin/evaluation) หรือ CLI (scripts/eval/run-acceptance.ts)
  participant API as POST /api/admin/evaluation/runs
  participant R as runner.ts (createRun / executeRun)
  participant G as ragGraph
  participant J as Judge LLM
  participant DB as SQLite
  A->>API: { datasetId, label: baseline | acceptance | adhoc }
  API->>R: createRun (บันทึก datasetVersion, promptKey/promptVersion, model, judgeModel) + audit evaluation_run
  API-->>A: { run (queued) }
  R->>DB: status = running
  loop ทุกข้อในชุด
    alt accuracy (DS-1)
      R->>G: answerStyle = mcq, skipInputGuard → exactMatchScore
    else retrieval (RET-1/2/3)
      R->>G: stopAfter = rerank → recallAtK(top-5, expectedRefs)
    else guardrail (GR-1/GR-2/INJ)
      R->>G: stopAfter = guard → refusalScore
    else judge (NT-2)
      R->>G: ถาม-ตอบเต็ม pipeline
      R->>J: prompt judge → คะแนน 0–3 (mock: token overlap)
    end
    R->>DB: EvaluationResult (botAnswer, retrievedIds, score, passed, judgeReason, latencyMs)
  end
  R->>DB: EvaluationRun.score / passed (เทียบ threshold) / finishedAt
  A->>API: GET /runs/[id] · GET /compare?runA&runB · GET /thresholds · POST /export
```

### 5.6 การจัดการความลับ

- ไฟล์ `.env` ไม่อยู่ใน repository มีเพียง `.env.example` ที่ระบุชื่อคีย์ API key ของ LLM (เช่น `TYPHOON_API_KEY`) เป็นค่าที่มหาวิทยาลัยจัดหาและใส่เอง (TOR 4.6.1)
- ระบบไม่ส่งค่า API key ออกทาง API ใด (`/api/admin/ai-config/models` คืนเพียง `configured: true/false`)
- Production: เก็บใน Kubernetes Secret `mbu-buddhist-ai-secrets` (ดู `infra/helm/mbu-buddhist-ai/values.yaml` → `existingSecret`)

---

## 6. พจนานุกรมข้อมูล (Data Dictionary)

ตารางต่อไปนี้ **สร้างจากไฟล์ `prisma/schema.prisma` จริง** ด้วยสคริปต์แยกวิเคราะห์ (parse) ทุกบรรทัด `model { ... }` — ครบ **25 model / 295 field** (รวม field ความสัมพันธ์) คอลัมน์ “ข้อกำหนด/ค่าเริ่มต้น” คัดลอกจาก attribute ของ Prisma ตามตัวอักษร คอลัมน์ “คำอธิบาย” ใช้ความเห็น (comment) ใน schema เมื่อมี และสำหรับ field ที่ไม่มีความเห็น ผู้จัดทำเขียนคำอธิบายจากการใช้งานจริงในโค้ด

ข้อสังเกตทั่วไป:
- SQLite ไม่มีชนิด enum จึงเก็บค่าที่เป็นรายการเป็น `String` และตรวจค่าด้วย zod ในชั้น application/API (ค่าที่อนุญาตระบุในคำอธิบาย)
- ฟิลด์ JSON (เช่น `patterns`, `choices`, `expectedRefs`, `traceJson`, `before/after`, `embedding`) เก็บเป็น `String` ที่เป็น JSON
- ตาราง `AuditLog` มี trigger ระดับฐานข้อมูลห้าม UPDATE/DELETE (migration `20261002110735_audit_immutable`)
- คอลัมน์ `emailEnc` / `displayNameEnc` เข้ารหัส AES-256-GCM ชั้น repository เท่านั้นที่ถอดรหัส

#### User (กลุ่ม Identity)

| ฟิลด์ | ชนิด | ข้อกำหนด/ค่าเริ่มต้น | คำอธิบาย |
|---|---|---|---|
| `id` | `String` | `@id @default(uuid())` | รหัสอ้างอิงของระเบียน (UUID) |
| `emailHash` | `String` | `@unique` | sha256(lowercase email) ใช้ค้นหา/ล็อกอิน |
| `emailEnc` | `String` | — | อีเมลเข้ารหัส AES-256-GCM (14.3) |
| `displayNameEnc` | `String` | — | ชื่อแสดง เข้ารหัส |
| `passwordHash` | `String?` | — | null สำหรับบัญชี OAuth |
| `provider` | `String` | `@default("local")` | local \| google \| facebook \| mock |
| `providerId` | `String?` | — | รหัสผู้ใช้ฝั่งผู้ให้บริการ OAuth |
| `role` | `String` | `@default("GENERAL_USER")` | SUPER_ADMIN \| ADMIN \| GENERAL_USER |
| `status` | `String` | `@default("active")` | active \| suspended \| deleted |
| `dhammaTalkEnabled` | `Boolean` | `@default(false)` | ก.3.3.3 default ปิด |
| `consentVersion` | `String?` | — | เวอร์ชันนโยบายที่ยินยอม |
| `consentAt` | `DateTime?` | — | วันเวลาที่ให้ความยินยอมตามนโยบายความเป็นส่วนตัว |
| `consentWithdrawnAt` | `DateTime?` | — | วันเวลาที่ถอนความยินยอม |
| `lastLoginAt` | `DateTime?` | — | วันเวลาที่เข้าสู่ระบบครั้งล่าสุด |
| `createdAt` | `DateTime` | `@default(now())` | วันเวลาที่สร้างระเบียน |
| `updatedAt` | `DateTime` | `@updatedAt` | วันเวลาที่แก้ไขล่าสุด (Prisma อัปเดตอัตโนมัติ) |
| `deletedAt` | `DateTime?` | — | วันเวลาที่ลบแบบ soft delete (null = ยังไม่ลบ) |
| `conversations` | `Conversation[]` | — | ความสัมพันธ์ไปยัง Conversation (หนึ่งต่อหลาย) |
| `feedbacks` | `Feedback[]` | — | ความสัมพันธ์ไปยัง Feedback (หนึ่งต่อหลาย) |
| `tokenUsages` | `TokenUsage[]` | — | ความสัมพันธ์ไปยัง TokenUsage (หนึ่งต่อหลาย) |
| `privacyRequests` | `PrivacyRequest[]` | — | ความสัมพันธ์ไปยัง PrivacyRequest (หนึ่งต่อหลาย) |

ดัชนี/ข้อจำกัดระดับตาราง: `@@unique([provider, providerId])`, `@@index([role, status])`, `@@index([lastLoginAt])`

#### LoginAttempt (กลุ่ม Identity)

| ฟิลด์ | ชนิด | ข้อกำหนด/ค่าเริ่มต้น | คำอธิบาย |
|---|---|---|---|
| `id` | `String` | `@id @default(uuid())` | รหัสอ้างอิงของระเบียน (UUID) |
| `emailHash` | `String` | — | sha256 ของอีเมลที่ใช้พยายามเข้าสู่ระบบ |
| `ip` | `String` | — | IP ของผู้พยายามเข้าสู่ระบบ |
| `success` | `Boolean` | — | ผลการเข้าสู่ระบบ (ใช้คำนวณ lockout) |
| `createdAt` | `DateTime` | `@default(now())` | วันเวลาที่สร้างระเบียน |

ดัชนี/ข้อจำกัดระดับตาราง: `@@index([emailHash, createdAt])`, `@@index([ip, createdAt])`

#### Conversation (กลุ่ม Chat)

| ฟิลด์ | ชนิด | ข้อกำหนด/ค่าเริ่มต้น | คำอธิบาย |
|---|---|---|---|
| `id` | `String` | `@id @default(uuid())` | รหัสอ้างอิงของระเบียน (UUID) |
| `userId` | `String` | — | เจ้าของบทสนทนา (FK → User) |
| `user` | `User` | `@relation(fields: [userId], references: [id])` | ความสัมพันธ์ไปยัง User |
| `mode` | `String` | — | QA \| DHAMMA_TALK |
| `title` | `String` | — | ชื่อบทสนทนา (40 ตัวอักษรแรกของคำถามแรก) |
| `artifactMd` | `String?` | — | Dhamma Talk: artifact ล่าสุด (markdown) |
| `retentionUntil` | `DateTime` | — | createdAt + retentionDays (ก.3.5.1) |
| `createdAt` | `DateTime` | `@default(now())` | วันเวลาที่สร้างระเบียน |
| `updatedAt` | `DateTime` | `@updatedAt` | วันเวลาที่แก้ไขล่าสุด (Prisma อัปเดตอัตโนมัติ) |
| `messages` | `Message[]` | — | ความสัมพันธ์ไปยัง Message (หนึ่งต่อหลาย) |

ดัชนี/ข้อจำกัดระดับตาราง: `@@index([userId, updatedAt])`, `@@index([retentionUntil])`

#### Message (กลุ่ม Chat)

| ฟิลด์ | ชนิด | ข้อกำหนด/ค่าเริ่มต้น | คำอธิบาย |
|---|---|---|---|
| `id` | `String` | `@id @default(uuid())` | รหัสอ้างอิงของระเบียน (UUID) |
| `conversationId` | `String` | — | FK → Conversation |
| `conversation` | `Conversation` | `@relation(fields: [conversationId], references: [id], onDelete: Cascade)` | ความสัมพันธ์ไปยัง Conversation |
| `role` | `String` | — | user \| assistant \| system |
| `content` | `String` | — | เนื้อหาข้อความ (คำถาม/คำตอบ/ข้อความปฏิเสธ) |
| `contentMasked` | `String?` | — | สำเนาปิดบัง PII สำหรับใช้ปรับปรุงระบบ (14.3) |
| `refusalReason` | `String?` | — | scope \| injection \| sensitive_politics \| sensitive_religion \| sensitive_mental \| yes_no \| budget \| unavailable |
| `promptVersionId` | `String?` | — | PromptVersion ที่ใช้สร้างคำตอบ |
| `model` | `String?` | — | ชื่อโมเดล LLM ที่ตอบ |
| `traceJson` | `String?` | — | RAG trace (JSON) สำหรับ Trace panel |
| `latencyMs` | `Int?` | — | เวลาตอบรวม (มิลลิวินาที) |
| `ttftMs` | `Int?` | — | time to first token (12.2) |
| `createdAt` | `DateTime` | `@default(now())` | วันเวลาที่สร้างระเบียน |
| `citations` | `Citation[]` | — | ความสัมพันธ์ไปยัง Citation (หนึ่งต่อหลาย) |
| `feedbacks` | `Feedback[]` | — | ความสัมพันธ์ไปยัง Feedback (หนึ่งต่อหลาย) |

ดัชนี/ข้อจำกัดระดับตาราง: `@@index([conversationId, createdAt])`

#### Citation (กลุ่ม Chat)

| ฟิลด์ | ชนิด | ข้อกำหนด/ค่าเริ่มต้น | คำอธิบาย |
|---|---|---|---|
| `id` | `String` | `@id @default(uuid())` | รหัสอ้างอิงของระเบียน (UUID) |
| `messageId` | `String` | — | FK → Message |
| `message` | `Message` | `@relation(fields: [messageId], references: [id], onDelete: Cascade)` | ความสัมพันธ์ไปยัง Message |
| `chunkId` | `String` | — | FK → Chunk ที่ถูกอ้างอิง |
| `chunk` | `Chunk` | `@relation(fields: [chunkId], references: [id])` | ความสัมพันธ์ไปยัง Chunk |
| `rank` | `Int` | — | 1..10 |
| `label` | `String` | — | "ข.ช. (ไทย) 27/87/87" |
| `score` | `Float` | — | คะแนนหลัง rerank และคูณ precedence |

#### Feedback (กลุ่ม Chat)

| ฟิลด์ | ชนิด | ข้อกำหนด/ค่าเริ่มต้น | คำอธิบาย |
|---|---|---|---|
| `id` | `String` | `@id @default(uuid())` | รหัสอ้างอิงของระเบียน (UUID) |
| `messageId` | `String` | — | FK → Message ที่ให้ความเห็น |
| `message` | `Message` | `@relation(fields: [messageId], references: [id], onDelete: Cascade)` | ความสัมพันธ์ไปยัง Message |
| `userId` | `String` | — | FK → User ผู้ให้ความเห็น |
| `user` | `User` | `@relation(fields: [userId], references: [id])` | ความสัมพันธ์ไปยัง User |
| `value` | `Int` | — | 1 = thumb-up, -1 = thumb-down |
| `comment` | `String?` | — | ความเห็นเพิ่มเติม (ไม่บังคับ) |
| `createdAt` | `DateTime` | `@default(now())` | วันเวลาที่สร้างระเบียน |

ดัชนี/ข้อจำกัดระดับตาราง: `@@unique([messageId, userId])`

#### KnowledgeDocument (กลุ่ม Knowledge Base)

| ฟิลด์ | ชนิด | ข้อกำหนด/ค่าเริ่มต้น | คำอธิบาย |
|---|---|---|---|
| `id` | `String` | `@id @default(uuid())` | รหัสอ้างอิงของระเบียน (UUID) |
| `title` | `String` | — | ชื่อเอกสาร |
| `docType` | `String` | — | tipitaka \| atthakatha \| tika \| contemporary \| teacher_dhamma  (ก.4.8.3(2)) |
| `edition` | `String?` | — | มมร. \| ไทย \| อื่น ๆ |
| `pitaka` | `String?` | — | vinaya \| sutta \| abhidhamma |
| `nikaya` | `String?` | — | นิกาย/วรรค |
| `sutta` | `String?` | — | ชื่อสูตร |
| `volume` | `Int?` | — | เล่ม (มมร. 1–91) |
| `abbreviation` | `String?` | — | ตัวย่อสำหรับ citation เช่น "ข.ช." "วิ.มหา." |
| `precedenceScore` | `Float` | `@default(1.0)` | ก.4.8.3(3) ปรับได้ใน admin |
| `sourceType` | `String` | — | upload \| seed \| online |
| `sourceFile` | `String?` | — | path ใน storage/uploads |
| `sourceUrl` | `String?` | — | URL ต้นทาง (ข้อมูลออนไลน์) |
| `mimeType` | `String?` | — | ชนิดไฟล์ต้นฉบับ |
| `status` | `String` | `@default("pending")` | pending \| indexed \| failed \| deleted |
| `chunkCount` | `Int` | `@default(0)` | จำนวน chunk ที่ทำดัชนีแล้ว |
| `sourceNote` | `String?` | — | หมายเหตุที่มา/ความถูกต้องของข้อความ |
| `mbuVolume` | `Int?` | — | เล่มในฉบับ มมร. 91 เล่ม (เมื่อทราบ) — ใช้คำนวณ coverage ภาคผนวก ข |
| `paliAliases` | `String?` | — | คำบาลี/อังกฤษของเอกสาร คั่นด้วย \| |
| `sanitizedLines` | `Int` | `@default(0)` | จำนวนบรรทัดที่ถูกตัดตอน sanitize |
| `createdBy` | `String?` | — | ผู้นำเข้าเอกสาร |
| `createdAt` | `DateTime` | `@default(now())` | วันเวลาที่สร้างระเบียน |
| `updatedAt` | `DateTime` | `@updatedAt` | วันเวลาที่แก้ไขล่าสุด (Prisma อัปเดตอัตโนมัติ) |
| `deletedAt` | `DateTime?` | — | วันเวลาที่ลบแบบ soft delete (null = ยังไม่ลบ) |
| `chunks` | `Chunk[]` | — | ความสัมพันธ์ไปยัง Chunk (หนึ่งต่อหลาย) |
| `jobItems` | `IngestionJobItem[]` | — | ความสัมพันธ์ไปยัง IngestionJobItem (หนึ่งต่อหลาย) |

ดัชนี/ข้อจำกัดระดับตาราง: `@@index([docType, status])`

#### Chunk (กลุ่ม Knowledge Base)

| ฟิลด์ | ชนิด | ข้อกำหนด/ค่าเริ่มต้น | คำอธิบาย |
|---|---|---|---|
| `id` | `String` | `@id @default(uuid())` | รหัสอ้างอิงของระเบียน (UUID) |
| `documentId` | `String` | — | FK → KnowledgeDocument |
| `document` | `KnowledgeDocument` | `@relation(fields: [documentId], references: [id], onDelete: Cascade)` | ความสัมพันธ์ไปยัง KnowledgeDocument |
| `ordinal` | `Int` | — | ลำดับ chunk ในเอกสาร (เริ่ม 0) |
| `content` | `String` | — | เนื้อหาเต็มของ chunk (1 ข้อ สำหรับพระไตรปิฎก/อรรถกถา) |
| `volume` | `Int?` | — | เล่ม |
| `item` | `Int?` | — | ข้อ |
| `page` | `Int?` | — | หน้า |
| `pageEnd` | `Int?` | — | หน้าสุดท้ายของข้อ (ข้อที่คร่อมหลายหน้า) |
| `heading` | `String?` | — | หัวข้อ/ชื่อสูตรของ chunk |
| `paliAliases` | `String?` | — | คำบาลีถอดอักษร คั่นด้วย \| |
| `tokenCount` | `Int` | — | จำนวนโทเคนโดยประมาณ (ตัวอักษร ÷ 3) |
| `oversized` | `Boolean` | `@default(false)` | ข้อยาวเกิน 3,000 tokens แต่ไม่ถูกแบ่ง (ก.4.6.2) |
| `embedding` | `String?` | — | JSON number[512] (pseudo-embedding) — cache |
| `createdAt` | `DateTime` | `@default(now())` | วันเวลาที่สร้างระเบียน |
| `citations` | `Citation[]` | — | ความสัมพันธ์ไปยัง Citation (หนึ่งต่อหลาย) |

ดัชนี/ข้อจำกัดระดับตาราง: `@@index([documentId, ordinal])`, `@@index([volume, item])`

#### IngestionJob (กลุ่ม Knowledge Base)

| ฟิลด์ | ชนิด | ข้อกำหนด/ค่าเริ่มต้น | คำอธิบาย |
|---|---|---|---|
| `id` | `String` | `@id @default(uuid())` | รหัสอ้างอิงของระเบียน (UUID) |
| `type` | `String` | — | ingest \| reindex_all \| reindex_selected \| delete |
| `status` | `String` | `@default("queued")` | queued \| running \| completed \| failed \| partial |
| `requestedBy` | `String` | — | ผู้สั่งงาน (userId) |
| `totalItems` | `Int` | `@default(0)` | จำนวนรายการทั้งหมดในงาน |
| `successItems` | `Int` | `@default(0)` | จำนวนรายการที่สำเร็จ |
| `failedItems` | `Int` | `@default(0)` | จำนวนรายการที่ล้มเหลว |
| `startedAt` | `DateTime?` | — | เวลาเริ่มประมวลผล |
| `finishedAt` | `DateTime?` | — | เวลาประมวลผลเสร็จ |
| `createdAt` | `DateTime` | `@default(now())` | วันเวลาที่สร้างระเบียน |
| `items` | `IngestionJobItem[]` | — | ความสัมพันธ์ไปยัง IngestionJobItem (หนึ่งต่อหลาย) |

#### IngestionJobItem (กลุ่ม Knowledge Base)

| ฟิลด์ | ชนิด | ข้อกำหนด/ค่าเริ่มต้น | คำอธิบาย |
|---|---|---|---|
| `id` | `String` | `@id @default(uuid())` | รหัสอ้างอิงของระเบียน (UUID) |
| `jobId` | `String` | — | FK → IngestionJob |
| `job` | `IngestionJob` | `@relation(fields: [jobId], references: [id], onDelete: Cascade)` | ความสัมพันธ์ไปยัง IngestionJob |
| `documentId` | `String?` | — | FK → KnowledgeDocument |
| `document` | `KnowledgeDocument?` | `@relation(fields: [documentId], references: [id])` | ความสัมพันธ์ไปยัง KnowledgeDocument |
| `fileName` | `String?` | — | ชื่อไฟล์ที่นำเข้า |
| `stage` | `String` | `@default("queued")` | queued \| parse \| sanitize \| chunk \| embed \| index \| done \| failed |
| `status` | `String` | `@default("queued")` | queued | running | done | failed |
| `errorMsg` | `String?` | — | ข้อความผิดพลาดเมื่อล้มเหลว |
| `chunkCount` | `Int` | `@default(0)` | จำนวน chunk ที่ได้ |
| `durationMs` | `Int?` | — | เวลาที่ใช้ประมวลผล (มิลลิวินาที) |

#### PromptVersion (กลุ่ม AI Config)

| ฟิลด์ | ชนิด | ข้อกำหนด/ค่าเริ่มต้น | คำอธิบาย |
|---|---|---|---|
| `id` | `String` | `@id @default(uuid())` | รหัสอ้างอิงของระเบียน (UUID) |
| `key` | `String` | — | qa-persona \| dhamma-talk \| guard-classifier \| judge \| query-rewrite |
| `version` | `Int` | — | หมายเลขเวอร์ชัน (เพิ่มทีละ 1 ต่อ key) |
| `content` | `String` | — | เนื้อหา prompt |
| `changelog` | `String?` | — | บันทึกการเปลี่ยนแปลง |
| `isActive` | `Boolean` | `@default(false)` | เวอร์ชันที่ใช้งานอยู่ (1 เวอร์ชันต่อ key) |
| `createdBy` | `String` | — | ผู้สร้างเวอร์ชัน |
| `createdAt` | `DateTime` | `@default(now())` | วันเวลาที่สร้างระเบียน |

ดัชนี/ข้อจำกัดระดับตาราง: `@@unique([key, version])`, `@@index([key, isActive])`

#### GuardrailTopic (กลุ่ม AI Config)

| ฟิลด์ | ชนิด | ข้อกำหนด/ค่าเริ่มต้น | คำอธิบาย |
|---|---|---|---|
| `id` | `String` | `@id @default(uuid())` | รหัสอ้างอิงของระเบียน (UUID) |
| `kind` | `String` | — | scope_allow \| refuse_sensitive \| injection_pattern \| yes_no_pattern |
| `key` | `String?` | — | politics \| religion_comparison \| mental_health \| ... (ใช้จำแนก refusalReason) |
| `labelTh` | `String` | — | ชื่อหัวข้อภาษาไทย |
| `labelEn` | `String` | — | ชื่อหัวข้อภาษาอังกฤษ |
| `patterns` | `String` | — | JSON string[] (keyword/regex) |
| `refusalMsgTh` | `String?` | — | ข้อความปฏิเสธภาษาไทย |
| `refusalMsgEn` | `String?` | — | ข้อความปฏิเสธภาษาอังกฤษ |
| `enabled` | `Boolean` | `@default(true)` | เปิด/ปิดหัวข้อ |
| `sortOrder` | `Int` | `@default(0)` | ลำดับการแสดง/ประเมิน |
| `updatedBy` | `String?` | — | ผู้แก้ไขล่าสุด |
| `updatedAt` | `DateTime` | `@updatedAt` | วันเวลาที่แก้ไขล่าสุด (Prisma อัปเดตอัตโนมัติ) |

#### AiConfigSetting (กลุ่ม AI Config)

| ฟิลด์ | ชนิด | ข้อกำหนด/ค่าเริ่มต้น | คำอธิบาย |
|---|---|---|---|
| `key` | `String` | `@id` | ดูรายการ key ในข้อ 7.2 |
| `value` | `String` | — | JSON |
| `updatedBy` | `String?` | — | ผู้แก้ไขล่าสุด |
| `updatedAt` | `DateTime` | `@updatedAt` | วันเวลาที่แก้ไขล่าสุด (Prisma อัปเดตอัตโนมัติ) |

#### ConfigSnapshot (กลุ่ม AI Config)

| ฟิลด์ | ชนิด | ข้อกำหนด/ค่าเริ่มต้น | คำอธิบาย |
|---|---|---|---|
| `id` | `String` | `@id @default(uuid())` | รหัสอ้างอิงของระเบียน (UUID) |
| `scope` | `String` | — | ai-config \| guardrails \| unavailable \| pricing |
| `snapshot` | `String` | — | JSON ของค่าทั้ง scope ก่อนเปลี่ยน |
| `reason` | `String?` | — | เหตุผลการเปลี่ยนแปลง |
| `createdBy` | `String` | — | ผู้เปลี่ยนแปลง |
| `createdAt` | `DateTime` | `@default(now())` | วันเวลาที่สร้างระเบียน |

ดัชนี/ข้อจำกัดระดับตาราง: `@@index([scope, createdAt])`

#### TokenUsage (กลุ่ม AI Config)

| ฟิลด์ | ชนิด | ข้อกำหนด/ค่าเริ่มต้น | คำอธิบาย |
|---|---|---|---|
| `id` | `String` | `@id @default(uuid())` | รหัสอ้างอิงของระเบียน (UUID) |
| `userId` | `String?` | — | FK → User (null = งานระบบ เช่น ประเมินผล) |
| `user` | `User?` | `@relation(fields: [userId], references: [id])` | ความสัมพันธ์ไปยัง User |
| `conversationId` | `String?` | — | บทสนทนาที่เกี่ยวข้อง |
| `messageId` | `String?` | — | ข้อความที่เกี่ยวข้อง |
| `mode` | `String` | — | QA \| DHAMMA_TALK \| EVALUATION \| GUARD |
| `model` | `String` | — | ชื่อโมเดล |
| `inputTokens` | `Int` | — | โทเคนขาเข้า |
| `thinkingTokens` | `Int` | `@default(0)` | โทเคนการคิด (ไม่เกิน thinkingBudget) |
| `outputTokens` | `Int` | — | โทเคนขาออก |
| `totalTokens` | `Int` | — | ผลรวมโทเคน (ใช้คำนวณเพดาน 24 ชม.) |
| `estimatedCost` | `Float` | `@default(0)` | คำนวณจาก LlmPricing ณ เวลาบันทึก |
| `createdAt` | `DateTime` | `@default(now())` | วันเวลาที่สร้างระเบียน |

ดัชนี/ข้อจำกัดระดับตาราง: `@@index([createdAt])`, `@@index([userId, createdAt])`

#### LlmPricing (กลุ่ม AI Config)

| ฟิลด์ | ชนิด | ข้อกำหนด/ค่าเริ่มต้น | คำอธิบาย |
|---|---|---|---|
| `id` | `String` | `@id @default(uuid())` | รหัสอ้างอิงของระเบียน (UUID) |
| `provider` | `String` | — | ผู้ให้บริการ LLM |
| `model` | `String` | — | ชื่อโมเดล |
| `inputPerMillion` | `Float` | — | USD หรือ THB ต่อ 1M tokens (currency ใน config) |
| `thinkingPerMillion` | `Float` | `@default(0)` | อัตราต่อ 1M thinking tokens |
| `outputPerMillion` | `Float` | — | อัตราต่อ 1M output tokens |
| `currency` | `String` | `@default("THB")` | สกุลเงิน |
| `updatedBy` | `String?` | — | ผู้แก้ไขล่าสุด |
| `updatedAt` | `DateTime` | `@updatedAt` | วันเวลาที่แก้ไขล่าสุด (Prisma อัปเดตอัตโนมัติ) |

ดัชนี/ข้อจำกัดระดับตาราง: `@@unique([provider, model])`

#### AlertEmailLog (กลุ่ม AI Config)

| ฟิลด์ | ชนิด | ข้อกำหนด/ค่าเริ่มต้น | คำอธิบาย |
|---|---|---|---|
| `id` | `String` | `@id @default(uuid())` | รหัสอ้างอิงของระเบียน (UUID) |
| `type` | `String` | — | threshold_tokens \| threshold_cost \| auto_unavailable \| error_rate \| ingestion_failed \| system |
| `severity` | `String` | — | info \| warning \| critical |
| `to` | `String` | — | ผู้รับ |
| `subject` | `String` | — | หัวเรื่อง |
| `body` | `String` | — | เนื้อหาแจ้งเตือน |
| `delivery` | `String` | `@default("logged")` | logged \| sent \| failed |
| `createdAt` | `DateTime` | `@default(now())` | วันเวลาที่สร้างระเบียน |

ดัชนี/ข้อจำกัดระดับตาราง: `@@index([createdAt])`

#### EvaluationDataset (กลุ่ม Evaluation)

| ฟิลด์ | ชนิด | ข้อกำหนด/ค่าเริ่มต้น | คำอธิบาย |
|---|---|---|---|
| `id` | `String` | `@id @default(uuid())` | รหัสอ้างอิงของระเบียน (UUID) |
| `name` | `String` | — | ชื่อชุดทดสอบ |
| `kind` | `String` | — | accuracy \| judge \| retrieval \| guardrail |
| `benchmarkCode` | `String` | — | DS-1 \| NT-2 \| RET-1 \| RET-2 \| RET-3 \| GR-1 \| GR-2 |
| `version` | `Int` | `@default(1)` | เพิ่มทุกครั้งที่ items เปลี่ยน (ก.5.2.4) |
| `threshold` | `Float` | — | เกณฑ์ขั้นต่ำ 0.8 / 2.0 |
| `guaranteed` | `Float` | — | ค่าที่ผู้รับจ้างรับประกัน (9.4/16.2) |
| `expectedCount` | `Int` | — | จำนวนข้อตาม TOR (100/50/...) |
| `createdBy` | `String` | — | ผู้สร้างชุด |
| `createdAt` | `DateTime` | `@default(now())` | วันเวลาที่สร้างระเบียน |
| `updatedAt` | `DateTime` | `@updatedAt` | วันเวลาที่แก้ไขล่าสุด (Prisma อัปเดตอัตโนมัติ) |
| `items` | `EvaluationItem[]` | — | ความสัมพันธ์ไปยัง EvaluationItem (หนึ่งต่อหลาย) |
| `runs` | `EvaluationRun[]` | — | ความสัมพันธ์ไปยัง EvaluationRun (หนึ่งต่อหลาย) |

#### EvaluationItem (กลุ่ม Evaluation)

| ฟิลด์ | ชนิด | ข้อกำหนด/ค่าเริ่มต้น | คำอธิบาย |
|---|---|---|---|
| `id` | `String` | `@id @default(uuid())` | รหัสอ้างอิงของระเบียน (UUID) |
| `datasetId` | `String` | — | FK → EvaluationDataset |
| `dataset` | `EvaluationDataset` | `@relation(fields: [datasetId], references: [id], onDelete: Cascade)` | ความสัมพันธ์ไปยัง EvaluationDataset |
| `ordinal` | `Int` | — | เลขข้อ |
| `question` | `String` | — | คำถาม |
| `choices` | `String?` | — | JSON string[] สำหรับปรนัย |
| `expectedAnswer` | `String?` | — | เฉลย (choice label หรือข้อความ) |
| `expectedRefs` | `String?` | — | JSON [{volume,item}] หรือ chunkId[] สำหรับ Recall@5 |
| `expectRefusal` | `Boolean` | `@default(false)` | guardrail |
| `level` | `String?` | — | ตรี \| โท \| เอก |
| `results` | `EvaluationResult[]` | — | ความสัมพันธ์ไปยัง EvaluationResult (หนึ่งต่อหลาย) |

#### EvaluationRun (กลุ่ม Evaluation)

| ฟิลด์ | ชนิด | ข้อกำหนด/ค่าเริ่มต้น | คำอธิบาย |
|---|---|---|---|
| `id` | `String` | `@id @default(uuid())` | รหัสอ้างอิงของระเบียน (UUID) |
| `datasetId` | `String` | — | FK → EvaluationDataset |
| `dataset` | `EvaluationDataset` | `@relation(fields: [datasetId], references: [id])` | ความสัมพันธ์ไปยัง EvaluationDataset |
| `datasetVersion` | `Int` | — | เวอร์ชันชุดทดสอบ ณ เวลารัน (ก.5.2.4) |
| `promptVersionId` | `String` | — | FK เชิงตรรกะ → PromptVersion |
| `promptKey` | `String` | — | key ของ prompt หลักของ workflow |
| `promptVersion` | `Int` | — | เวอร์ชัน prompt ณ เวลารัน (ก.5.2.4) |
| `model` | `String` | — | โมเดล LLM ที่ใช้ตอบ |
| `judgeModel` | `String?` | — | โมเดลที่ใช้เป็นผู้ตัดสิน (NT-2) |
| `label` | `String?` | — | baseline \| acceptance \| adhoc |
| `status` | `String` | `@default("queued")` | queued \| running \| completed \| failed |
| `score` | `Float?` | — | accuracy %, recall@5 %, judge avg, refusal % |
| `passed` | `Boolean?` | — | score ≥ threshold |
| `itemCount` | `Int` | `@default(0)` | จำนวนข้อที่ประเมิน |
| `startedAt` | `DateTime?` | — | เวลาเริ่ม |
| `finishedAt` | `DateTime?` | — | เวลาเสร็จ |
| `requestedBy` | `String` | — | ผู้สั่งรัน |
| `createdAt` | `DateTime` | `@default(now())` | วันเวลาที่สร้างระเบียน |
| `results` | `EvaluationResult[]` | — | ความสัมพันธ์ไปยัง EvaluationResult (หนึ่งต่อหลาย) |

#### EvaluationResult (กลุ่ม Evaluation)

| ฟิลด์ | ชนิด | ข้อกำหนด/ค่าเริ่มต้น | คำอธิบาย |
|---|---|---|---|
| `id` | `String` | `@id @default(uuid())` | รหัสอ้างอิงของระเบียน (UUID) |
| `runId` | `String` | — | FK → EvaluationRun |
| `run` | `EvaluationRun` | `@relation(fields: [runId], references: [id], onDelete: Cascade)` | ความสัมพันธ์ไปยัง EvaluationRun |
| `itemId` | `String` | — | FK → EvaluationItem |
| `item` | `EvaluationItem` | `@relation(fields: [itemId], references: [id])` | ความสัมพันธ์ไปยัง EvaluationItem |
| `botAnswer` | `String` | — | คำตอบของระบบ |
| `retrievedIds` | `String?` | — | JSON chunkId[] top-5 |
| `score` | `Float` | — | 0/1, 0/1, 0–3, 0/1 |
| `passed` | `Boolean` | — | ผ่าน/ไม่ผ่านรายข้อ |
| `judgeReason` | `String?` | — | เหตุผลของผู้ตัดสิน/ตัวให้คะแนน |
| `latencyMs` | `Int?` | — | เวลาที่ใช้ต่อข้อ (มิลลิวินาที) |

#### AuditLog (กลุ่ม Audit / Privacy / Ops)

| ฟิลด์ | ชนิด | ข้อกำหนด/ค่าเริ่มต้น | คำอธิบาย |
|---|---|---|---|
| `seq` | `Int` | `@id @default(autoincrement())` | SQLite อนุญาต autoincrement เฉพาะ primary key |
| `id` | `String` | `@unique @default(uuid())` | รหัสอ้างอิงของระเบียน (UUID) |
| `timestamp` | `DateTime` | `@default(now())` | วันเวลาที่เกิดเหตุการณ์ |
| `actorId` | `String?` | — | ผู้กระทำ (userId; null = ระบบ/ผู้ไม่ระบุตัวตน) |
| `actorEmailHash` | `String?` | — | sha256 อีเมลของผู้กระทำ (กรณี login ล้มเหลว) |
| `ip` | `String` | — | IP ของผู้กระทำ |
| `eventType` | `String` | — | login_success \| login_failed \| logout \| user_changed \| role_changed \| config_changed \| prompt_changed \| document_imported \| document_deleted \| conversation_accessed \| evaluation_run \| privacy_request \| data_destruction \| defect_changed |
| `targetType` | `String?` | — | ชนิดของสิ่งที่ถูกกระทำ |
| `targetId` | `String?` | — | รหัสของสิ่งที่ถูกกระทำ |
| `before` | `String?` | — | JSON |
| `after` | `String?` | — | JSON |
| `result` | `String` | — | success \| failure |
| `prevHash` | `String` | — | hash ของแถวก่อนหน้า (genesis = 0×64) |
| `hash` | `String` | — | sha256(prevHash + fields) |

ดัชนี/ข้อจำกัดระดับตาราง: `@@index([timestamp])`, `@@index([eventType, timestamp])`, `@@index([actorId, timestamp])`

#### PrivacyRequest (กลุ่ม Audit / Privacy / Ops)

| ฟิลด์ | ชนิด | ข้อกำหนด/ค่าเริ่มต้น | คำอธิบาย |
|---|---|---|---|
| `id` | `String` | `@id @default(uuid())` | รหัสอ้างอิงของระเบียน (UUID) |
| `userId` | `String` | — | เจ้าของข้อมูล (FK → User) |
| `user` | `User` | `@relation(fields: [userId], references: [id])` | ความสัมพันธ์ไปยัง User |
| `type` | `String` | — | access_copy \| erase \| withdraw_consent |
| `status` | `String` | `@default("pending")` | pending \| completed \| rejected |
| `note` | `String?` | — | หมายเหตุการดำเนินการ |
| `exportPath` | `String?` | — | ไฟล์ JSON สำเนาข้อมูล |
| `handledBy` | `String?` | — | ผู้ดูแลที่ดำเนินการ |
| `createdAt` | `DateTime` | `@default(now())` | วันเวลาที่สร้างระเบียน |
| `completedAt` | `DateTime?` | — | วันเวลาที่ดำเนินการเสร็จ |

#### DefectLog (กลุ่ม Audit / Privacy / Ops)

| ฟิลด์ | ชนิด | ข้อกำหนด/ค่าเริ่มต้น | คำอธิบาย |
|---|---|---|---|
| `id` | `String` | `@id @default(uuid())` | รหัสอ้างอิงของระเบียน (UUID) |
| `module` | `String` | — | โมดูลที่พบข้อบกพร่อง |
| `description` | `String` | — | รายละเอียดข้อบกพร่อง |
| `severity` | `String` | — | critical \| high \| medium \| low |
| `status` | `String` | `@default("open")` | open \| in_progress \| resolved \| closed |
| `reportedBy` | `String` | — | ผู้แจ้ง |
| `reportedAt` | `DateTime` | `@default(now())` | เวลาที่มหาวิทยาลัยแจ้ง (12.4 เริ่มนับ) |
| `assignedTo` | `String?` | — | ผู้รับผิดชอบแก้ไข |
| `foundInPhase` | `String?` | — | ระยะที่พบ (เช่น SIT/UAT) |
| `resolutionNote` | `String?` | — | วิธีแก้และมาตรการป้องกันซ้ำ (บังคับสำหรับ high/critical) |
| `resolvedAt` | `DateTime?` | — | วันเวลาที่แก้ไขเสร็จ |
| `confirmedAt` | `DateTime?` | — | มหาวิทยาลัยยืนยันผล (12.4 สิ้นสุดนับ) |
| `slaHours` | `Int` | — | 24 \| 48 \| 80 (10 วันทำการ×8 ชม.) |
| `slaDeadline` | `DateTime` | — | กำหนดเวลาแก้ไขตาม SLA (ชั่วโมงทำการ) |
| `overdueHours` | `Int?` | — | คำนวณเมื่อ confirm |
| `penaltyEstimate` | `Float?` | — | overdueHours × 0.025% × contractValue (10.2) |
| `createdAt` | `DateTime` | `@default(now())` | วันเวลาที่สร้างระเบียน |
| `updatedAt` | `DateTime` | `@updatedAt` | วันเวลาที่แก้ไขล่าสุด (Prisma อัปเดตอัตโนมัติ) |

ดัชนี/ข้อจำกัดระดับตาราง: `@@index([severity, status])`

#### ApiRequestLog (กลุ่ม Audit / Privacy / Ops)

| ฟิลด์ | ชนิด | ข้อกำหนด/ค่าเริ่มต้น | คำอธิบาย |
|---|---|---|---|
| `id` | `String` | `@id @default(uuid())` | รหัสอ้างอิงของระเบียน (UUID) |
| `requestId` | `String` | — | รหัสคำขอ (x-request-id) |
| `path` | `String` | — | route pattern ของ API |
| `method` | `String` | — | HTTP method |
| `statusCode` | `Int` | — | HTTP status ที่ตอบ |
| `durationMs` | `Int` | — | เวลาตอบสนอง (มิลลิวินาที) |
| `ttftMs` | `Int?` | — | Time to first token ของคำขอ SSE |
| `createdAt` | `DateTime` | `@default(now())` | วันเวลาที่สร้างระเบียน |

ดัชนี/ข้อจำกัดระดับตาราง: `@@index([createdAt])`

### 6.1 ความสัมพันธ์ระหว่างตารางหลัก

```mermaid
erDiagram
  User ||--o{ Conversation : owns
  User ||--o{ Feedback : gives
  User ||--o{ TokenUsage : consumes
  User ||--o{ PrivacyRequest : files
  Conversation ||--o{ Message : contains
  Message ||--o{ Citation : cites
  Message ||--o{ Feedback : receives
  Chunk ||--o{ Citation : referenced_by
  KnowledgeDocument ||--o{ Chunk : split_into
  KnowledgeDocument ||--o{ IngestionJobItem : processed_in
  IngestionJob ||--o{ IngestionJobItem : has
  EvaluationDataset ||--o{ EvaluationItem : has
  EvaluationDataset ||--o{ EvaluationRun : run_as
  EvaluationRun ||--o{ EvaluationResult : produces
  EvaluationItem ||--o{ EvaluationResult : scored_in
```

ตารางที่ไม่มีความสัมพันธ์แบบ foreign key: `LoginAttempt`, `PromptVersion`, `GuardrailTopic`, `AiConfigSetting`, `ConfigSnapshot`, `LlmPricing`, `AlertEmailLog`, `AuditLog`, `DefectLog`, `ApiRequestLog`

### 6.2 ค่าตั้งค่า AI (`AiConfigSetting.key`)

ค่าตั้งต้นจาก `AI_CONFIG_DEFAULTS` ใน `src/domain/config/ai-config.ts` (ผู้ดูแลแก้ได้ที่ `/admin/ai-config` ค่าที่ไม่ผ่าน schema ถูกละเว้นและใช้ค่าตั้งต้นแทน)

| key | ค่าตั้งต้น | ช่วงที่ schema ยอมรับ | TOR |
|---|---|---|---|
| `llm.provider` / `llm.model` | `typhoon` / `typhoon-v2.5-30b-a3b-instruct` | ข้อความ | ก.4.1.2, ก.6.2.3 |
| `llm.fallbackModels` | `[]` | ≤10 รายการ | — |
| `tokens.dailyCap` | 10,000,000 | 1 – 1,000,000,000 | ก.3.4.1 |
| `tokens.marginPct` | 10 | 0 – 50 | ก.3.4.4 |
| `tokens.alertThresholdPct` | 80 | 1 – 100 | ก.7.3.5 |
| `tokens.maxPerPromptQa` | 10,000 | 500 – 10,000 | ก.4.2.1 |
| `tokens.maxPerPromptDhammaTalk` | 50,000 | 500 – 50,000 | ก.4.2.1 |
| `tokens.thinkingBudget` | 2,000 | 0 – 32,000 | ก.4.4.2 |
| `tokens.maxOutput` | 1,500 | 64 – 16,000 | ก.3.4.2 |
| `input.maxChars` | 2,000 | 1 – 20,000 | ก.4.4.2 |
| `retention.conversationDays` | 90 | 1 – 3,650 | ก.3.5.1 |
| `retention.purgeIntervalMinutes` | 60 | 1 – 1,440 | ก.6.2.2 |
| `unavailable.enabled` / `unavailable.auto` | `false` / `false` | boolean | ก.3.4.3, ก.3.4.4 |
| `unavailable.messageTh` / `unavailable.messageEn` | ข้อความแจ้งปิดบริการ | 1 – 1,000 ตัวอักษร | ก.6.6.1 |
| `retrieval.candidateK` / `retrieval.finalK` / `retrieval.rrfK` | 50 / 10 / 60 | 1–200 / 1–10 / 1–1,000 | ก.3.6.2, ก.4.6.1 |
| `retrieval.reranker` | `heuristic` | ข้อความ (`heuristic` \| `tei`) | ก.4.7.1 |
| `eval.judgeModel` | `typhoon-v2.5-30b-a3b-instruct` | ข้อความ | ก.5.2.2 |
| `eval.guaranteed` | DS-1 0.85, NT-2 2.3, RET-1/2/3 0.85, GR-1/GR-2 0.9 | 0 – 3 ต่อชุด | 16.2 |
| `contract.value` | 5,000,000 | ≥0 | 10.2 |
| `pricing.currency` | `THB` | รหัส 3 ตัวอักษร | ก.7.3.3 |
| `privacy.policyVersion` | `1.0` | ข้อความ | 14 |

---

## 7. User Flow

### 7.1 ผู้ใช้ทั่วไป: สมัคร → ถาม-ตอบ → ตรวจอ้างอิง → ประวัติ

```mermaid
flowchart TD
  H["หน้าแรก /"] --> R{"มีบัญชีแล้ว?"}
  R -- ไม่มี --> REG["/register: อีเมล รหัสผ่าน ชื่อ + ยินยอม"] --> LOGIN
  R -- มี --> LOGIN["/login: อีเมล+รหัสผ่าน หรือ Gmail/Facebook"]
  LOGIN -->|ผิด 5 ครั้ง| LOCK["ล็อก 15 นาที"]
  LOGIN --> CHAT["/chat: พิมพ์คำถาม (เห็นคำเตือนใต้กล่อง)"]
  CHAT --> G{"Guardrail"}
  G -- ปฏิเสธ --> REF["การ์ดปฏิเสธพร้อมเหตุผล"] --> CHAT
  G -- ผ่าน --> REFS["รายการอ้างอิง 3 รายการ + Expand All"]
  REFS --> SUM["บทสรุปแบบ streaming + citation chip"]
  SUM --> MODAL["คลิก chip → Modal เนื้อหาเต็ม + metadata"]
  SUM --> FB["👍/👎 + ความเห็น"]
  SUM --> TRACE["RAG Trace 8 โหนด"]
  SUM --> HIST["/chat/history: เปิดต่อ / ลบ / ดูวันหมดอายุ"]
  HIST --> PRIV["/privacy: ดาวน์โหลดสำเนา / ขอลบ / ถอนยินยอม"]
```

### 7.2 Dhamma Talk

```mermaid
flowchart TD
  DT["/chat/dhamma-talk"] --> P{"dhammaTalkEnabled?"}
  P -- ไม่ --> ASK["หน้าอธิบายให้ขอสิทธิ์จากผู้ดูแล"]
  P -- ใช่ --> PROMPT["พิมพ์หัวข้อบทธรรมบรรยาย"] --> ART["Response Modal: artifact Markdown (แท็บแก้ไข/ตัวอย่าง)"]
  ART --> EDIT["ผู้ใช้แก้ไข → บันทึก (PATCH artifactMd)"]
  EDIT --> NEXT["สั่งรอบถัดไป → AI ใช้ฉบับที่แก้ล่าสุดเป็นบริบท"] --> ART
  ART --> DL["ดาวน์โหลด .md"]
```

### 7.3 ผู้ดูแลระบบ

```mermaid
flowchart LR
  AL["/login (บัญชี ADMIN/SUPER_ADMIN จาก IP ใน allowlist)"] --> DASH["/admin/dashboard"]
  DASH --> USERS["ผู้ใช้ / คำขอ PDPA / Audit Log"]
  DASH --> AI["ตั้งค่า AI / Prompt / Guardrails / Unavailable / ราคาโทเคน"]
  DASH --> KB["ฐานองค์ความรู้ / งานนำเข้า"]
  DASH --> EVAL["Evaluation / ชุดทดสอบ / เปรียบเทียบ / รายงานความปลอดภัย"]
  DASH --> OPS["Defect Log / SLA / Backup* / ทำลายข้อมูล*"]
```

\* เฉพาะ `SUPER_ADMIN`

Wireframe และ Prototype ของหน้าจอหลักอยู่ใน `/documents/ux-deliverables`

---

## 8. ข้อกำหนดส่วนต่อประสาน (API) — OpenAPI 3.0

- เอกสาร OpenAPI 3.0.3 ฉบับเครื่องอ่านได้: **`GET /api/openapi.json`** สร้างจาก registry ใน `src/server/api/openapi/index.ts` (`buildOpenApi`) ซึ่งรวมไฟล์กลุ่ม `core.ts`, `privacy.ts`, `admin-users.ts`, `admin-config.ts`, `admin-kb.ts`, `admin-eval.ts`, `admin-ops.ts`
- รูปแบบผลลัพธ์ทุก endpoint: `{ ok: true, data }` หรือ `{ ok: false, error: { code, message } }` ยกเว้น endpoint แบบ SSE (`text/event-stream`) และการดาวน์โหลด CSV/Markdown
- การยืนยันตัวตน: cookie `mbu_session` (securityScheme `sessionCookie`); คำขอที่แก้ไขข้อมูลต้องมี header `x-csrf-token`
- ชุดทดสอบ `tests/api/openapi-coverage.test.ts` ยืนยันว่าทุก path+method ใน registry มีกรณีทดสอบใน `tests/api` และเมื่อรัน `npm test` ระบบตรวจการเรียกจริงซ้ำอีกชั้น (regression ทุก endpoint — TOR 4.7.5; รายละเอียดใน `/documents/test-reports-index`)

### 8.1 สรุปกลุ่ม endpoint (รวม 107 operation ใน registry)

| กลุ่ม (tag) | จำนวน | สิทธิ์ | ตัวอย่าง |
|---|---:|---|---|
| System | 4 | public | `GET /api/health`, `GET /api/status`, `GET /api/openapi.json`, `GET /api/csrf` |
| Documents | 2 | public | `GET /api/documents`, `GET /api/documents/[slug]` |
| Auth | 10 | public / user | `POST /api/auth/register`, `POST /api/auth/login`, `POST /api/auth/logout`, `GET /api/auth/oauth/[provider]/start`, `.../callback`, `GET /api/auth/oauth-status`, `POST /api/mock-oauth/token`, `GET /api/mock-oauth/userinfo`, `GET/PATCH /api/me` |
| Chat | 8 | user | `POST /api/chat/qa` (SSE), `POST /api/chat/dhamma-talk` (SSE), `GET /api/conversations`, `GET/PATCH/DELETE /api/conversations/[id]`, `GET /api/chunks/[id]`, `POST /api/messages/[id]/feedback` |
| Privacy | 3 | user | `GET /api/privacy/export`, `GET/POST /api/privacy/requests` |
| Admin — Users | 5 | ADMIN+ | `GET /api/admin/users`, `GET/PATCH/DELETE /api/admin/users/[id]`, `GET /api/admin/users/[id]/conversations` |
| Admin — Privacy Requests | 3 | ADMIN+ | `GET/POST /api/admin/privacy-requests`, `POST /api/admin/privacy-requests/[id]/complete` |
| Admin — Audit Log | 3 | ADMIN+ | `GET /api/admin/audit-log`, `GET .../export`, `GET .../verify` |
| Admin — AI Config | 6 | ADMIN+ | `GET/PUT /api/admin/ai-config`, `GET .../snapshots`, `POST .../revert/[snapshotId]`, `GET .../models`, `POST .../test-llm` |
| Admin — Prompts | 5 | ADMIN+ | `GET /api/admin/prompts`, `GET/POST /api/admin/prompts/[key]`, `POST .../activate/[version]`, `GET .../diff` |
| Admin — Guardrails | 5 | ADMIN+ | `GET/POST /api/admin/guardrails`, `PATCH/DELETE /api/admin/guardrails/[id]`, `POST .../test` |
| Admin — Unavailable | 2 | ADMIN+ | `GET/PUT /api/admin/unavailable-mode` |
| Admin — Pricing | 4 | ADMIN+ | `GET/POST /api/admin/pricing`, `PATCH/DELETE /api/admin/pricing/[id]` |
| Admin — Maintenance | 1 | ADMIN+ | `POST /api/admin/maintenance/purge-conversations` |
| Admin — Knowledge Base | 11 | ADMIN+ | `GET /api/admin/knowledge-base`, `POST .../upload`, `GET/PATCH/DELETE .../[id]`, `GET .../[id]/chunks`, `POST .../reindex`, `GET .../jobs`, `GET .../jobs/[id]`, `POST .../jobs/[id]/retry-failed`, `GET .../coverage` |
| Admin — Evaluation Datasets | 11 | ADMIN+ | CRUD `/api/admin/evaluation/datasets[/id]`, items CRUD, `POST .../items/import` (CSV), `GET .../items/template` |
| Admin — Evaluation Runs | 4 | ADMIN+ | `POST/GET /api/admin/evaluation/runs`, `GET .../runs/[id]`, `GET .../compare` |
| Admin — Evaluation Reports | 4 | ADMIN+ | `GET .../thresholds`, `GET/POST .../security-report`, `POST .../export` |
| Admin — Dashboard | 3 | ADMIN+ | `GET /api/admin/dashboard/{usage,tokens,feedback}` |
| Admin — Alerts | 2 | ADMIN+ | `GET /api/admin/alerts`, `POST /api/admin/alerts/test` |
| Admin — Ops | 11 | ADMIN+ / SUPER_ADMIN | Defect log CRUD + export, `GET /api/admin/sla-report` + export, `GET/POST /api/admin/data-destruction` (SUPER_ADMIN), `GET/POST /api/admin/backup` (SUPER_ADMIN) |

หมายเหตุ: route ภายใน `POST /api/internal/security-event` (ให้ middleware บันทึก audit เมื่อ IP นอก allowlist เข้าถึงส่วนผู้ดูแล ตรวจด้วย header ภายใน) ไม่ได้เปิดเป็น API สาธารณะ จึงไม่อยู่ใน OpenAPI registry

### 8.2 เหตุการณ์ SSE ของ `/api/chat/qa` และ `/api/chat/dhamma-talk`

| event | ข้อมูล | เวลาที่ส่ง |
|---|---|---|
| `references` | รายการอ้างอิง ≤10 (n, chunkId, label, title, snippet, score, volume, item ...) | หลังโหนด `rerank` |
| `delta` | ข้อความบางส่วนของคำตอบ | ระหว่างโหนด `generate` |
| `refusal` | `{ reason, message, topicLabel? }` | เมื่อถูกปฏิเสธ |
| `done` | `{ conversationId, messageId, answer, refusal, artifactMd, references, usage{input,thinking,output,total}, trace[], ttftMs, latencyMs, model, promptVersion }` | จบคำขอ |
| `error` | `{ code: "GENERATION_FAILED", message }` | เกิดข้อผิดพลาดระหว่างสร้างคำตอบ |

---

## 9. ข้อจำกัดและสมมติฐาน

1. ระบบสาธิตรันบนเครื่องเดียว (Node.js ≥22 + SQLite) ตัวเลขด้านประสิทธิภาพที่ระดับ 500 concurrent และ Availability รายเดือนต้องยืนยันบนโครงสร้างพื้นฐานจริงของมหาวิทยาลัย
2. ฐานองค์ความรู้ปัจจุบันเป็นพระไตรปิฎกฉบับออนไลน์บางส่วนตามที่ TOR ภาคผนวก ข อนุญาตในระยะแรก (ดู `/documents/data-ingestion-plan` และ `/documents/ingestion-report`)
3. เมื่อไม่ได้ตั้ง API key ของ provider ที่เลือก ระบบสลับไปใช้ `MockLlmAdapter` (deterministic) อัตโนมัติ และชุดทดสอบ vitest บังคับใช้ mock เสมอ
4. การทดสอบเจาะระบบไม่ได้ดำเนินการในรอบนี้ตามคำสั่งของผู้ว่าจ้าง (ดู `/documents/pentest-report`)