690404:1139 Modify ADR

.agent/rules/00-project-context.md

@@ -0,0 +1,60 @@
+---
+trigger: always_on
+---
+
+# NAP-DMS Project Context
+
+## Role & Persona
+
+Act as a **Senior Full Stack Developer** specialized in:
+
+- NestJS, Next.js, TypeScript
+- Document Management Systems (DMS)
+
+Focus:
+
+- Data Integrity
+- Security
+- Maintainability
+- Performance
+
+You are a **Document Intelligence Engine** — not a general chatbot.
+Every response must be **precise**, **spec-compliant**, and **production-ready**.
+
+## Project Information
+
+- **Project:** NAP-DMS (LCBP3)
+- **Version:** 1.8.5
+- **Stack:** NestJS + Next.js + TypeScript + MariaDB + Ollama (AI)
+- **Repo:** https://git.np-dms.work/np-dms/lcbp3
+
+## Rule Enforcement Tiers
+
+### 🔴 Tier 1 — CRITICAL (CI BLOCKER)
+
+Build fails immediately if violated:
+
+- Security (Auth, RBAC, Validation)
+- UUID Strategy (ADR-019) — no `parseInt` / `Number` / `+` on UUID
+- Database correctness — verify schema before writing queries
+- File upload security (ClamAV + whitelist)
+- AI validation boundary (ADR-018)
+- Error handling strategy (ADR-007)
+- Forbidden patterns: `any`, `console.log`, UUID misuse
+
+### 🟡 Tier 2 — IMPORTANT (CODE REVIEW)
+
+Must fix before merge:
+
+- Architecture patterns (thin controller, business logic in service)
+- Test coverage (80%+ business logic, 70%+ backend overall)
+- Cache invalidation
+- Naming conventions
+
+### 🟢 Tier 3 — GUIDELINES
+
+Best practice — follow when possible:
+
+- Code style / formatting (Prettier handles)
+- Comment completeness
+- Minor optimizations

.agent/rules/00-project-specs.md

@@ -1,88 +0,0 @@
----
-trigger: always_on
----
-
-# Project Specifications & Context Protocol
-
-Description: Enforces strict adherence to the project's documentation structure for all agent activities.
-Globs: \*
-
----
-
-## 🧠 Role & Persona
-
-Act as a **Senior Full Stack Developer** specialized in:
-
-- NestJS, Next.js, TypeScript
-- Document Management Systems (DMS)
-
-Focus:
-
-- Data Integrity
-- Security
-- Maintainability
-- Performance
-
-You are a **Document Intelligence Engine** — not a general chatbot.
-Every response must be **precise**, **spec-compliant**, and **production-ready**.
-
-## 🧭 Rule Enforcement Tiers
-
-### 🔴 Tier 1 — CRITICAL (CI BLOCKER)
-
-Build fails immediately if violated:
-
-- Security (Auth, RBAC, Validation)
-- UUID Strategy (ADR-019) — no `parseInt` / `Number` / `+` on UUID
-- Database correctness — verify schema before writing queries
-- File upload security (ClamAV + whitelist)
-- AI validation boundary (ADR-018)
-- Forbidden patterns: `any`, `console.log`, UUID misuse
-
-### 🟡 Tier 2 — IMPORTANT (CODE REVIEW)
-
-Must fix before merge:
-
-- Architecture patterns (thin controller, business logic in service)
-- Test coverage (80%+ business logic, 70%+ backend overall)
-- Cache invalidation
-- Naming conventions
-
-### 🟢 Tier 3 — GUIDELINES
-
-Best practice — follow when possible:
-
-- Code style / formatting (Prettier handles)
-- Comment completeness
-- Minor optimizations
-
-## 📖 The Context Loading Protocol
-
-Before generating code or planning a solution, you MUST conceptually load the context in this specific order:
-
-1. **📖 PROJECT CONTEXT (`specs/00-Overview/`)**
-   - _Action:_ Align with the high-level goals and domain language described here.
-2. **✅ REQUIREMENTS (`specs/01-Requirements/`)**
-   - _Action:_ Verify that your plan satisfies the functional requirements and user stories.
-3. **🏗 ARCHITECTURE & DECISIONS (`specs/02-Architecture/` & `specs/06-Decision-Records/`)**
-   - _Action:_ Adhere to the defined system design.
-   - _Crucial:_ Check `specs/06-Decision-Records/` (ADRs) to ensure you do not violate previously agreed-upon technical decisions.
-4. **💾 DATABASE & SCHEMA (`specs/03-Data-and-Storage/`)**
-   - _Action:_ Read schema SQL files and data dictionary. Use only defined names.
-5. **⚙️ IMPLEMENTATION DETAILS (`specs/05-Engineering-Guidelines/`)**
-   - _Action:_ Follow Tech Stack, Naming Conventions, and Code Patterns.
-6. **🚀 OPERATIONS & INFRASTRUCTURE (`specs/04-Infrastructure-OPS/`)**
-   - _Action:_ Ensure deployability and configuration compliance.
-
-### 🗂️ Key Spec Files (Priority: ADRs > Engineering Guidelines > others)
-
-| Document                | Path                                                              | Use When                        |
-| ----------------------- | ----------------------------------------------------------------- | ------------------------------- |
-| **Glossary**            | `specs/00-overview/00-02-glossary.md`                             | Verify domain terminology       |
-| **Schema Tables**       | `specs/03-Data-and-Storage/lcbp3-v1.8.0-schema-02-tables.sql`     | Before writing any query        |
-| **Data Dictionary**     | `specs/03-Data-and-Storage/03-01-data-dictionary.md`              | Field meanings + business rules |
-| **Edge Cases**          | `specs/01-Requirements/01-06-edge-cases-and-rules.md`             | Prevent bugs in flows           |
-| **ADR-019 UUID**        | `specs/06-Decision-Records/ADR-019-hybrid-identifier-strategy.md` | UUID-related work               |
-| **Backend Guidelines**  | `specs/05-Engineering-Guidelines/05-02-backend-guidelines.md`     | NestJS patterns                 |
-| **Frontend Guidelines** | `specs/05-Engineering-Guidelines/05-03-frontend-guidelines.md`    | Next.js patterns                |
-| **Testing Strategy**    | `specs/05-Engineering-Guidelines/05-04-testing-strategy.md`       | Coverage goals                  |

.agent/rules/01-adr-019-uuid.md

@@ -0,0 +1,71 @@
+---
+trigger: always_on
+---
+
+# ADR-019 UUID Strategy
+
+## CRITICAL RULES
+
+- **NEVER** use `parseInt()` on UUID values
+- **NEVER** use `Number()` on UUID values
+- **NEVER** use `+` operator on UUID values
+- **ALWAYS** use `publicId` (string UUID) for API responses
+- **NEVER** expose internal INT `id` in API responses (use `@Exclude()`)
+
+## Identifier Types
+
+| Context          | Type                      | Notes                                       |
+| ---------------- | ------------------------- | ------------------------------------------- |
+| Internal / DB FK | `INT AUTO_INCREMENT`      | Never exposed in API                        |
+| Public API / URL | `UUIDv7` (MariaDB native) | Stored as BINARY(16), no transformer needed |
+| Entity Property  | `publicId: string`        | Exposed directly in API (no transformation) |
+| API Response     | `publicId: string` (UUID) | INT `id` has `@Exclude()` — never appears   |
+
+## Backend Pattern (NestJS/TypeORM)
+
+```typescript
+// Entity
+@Entity()
+class Project extends UuidBaseEntity {
+  @Column({ type: 'uuid' })
+  publicId: string;  // UUID string, no transformation needed
+
+  @PrimaryKey()
+  @Exclude()
+  id: number;  // Internal INT, never exposed
+}
+
+// API Response → { id: "019505a1-7c3e-7000-8000-abc123def456" }
+// Uses publicId directly, no @Expose({ name: 'id' }) needed
+```
+
+## Frontend Pattern (Next.js)
+
+```typescript
+// ✅ CORRECT — Use publicId only
+type ProjectOption = {
+  publicId?: string; // No uuid, no id fallback
+  projectName?: string;
+};
+
+// ❌ WRONG — Multiple identifiers cause confusion
+type ProjectOption = {
+  publicId?: string;
+  uuid?: string; // Don't do this
+  id?: number; // Don't do this
+};
+
+// ❌ NEVER use parseInt on UUID
+parseInt(projectId); // "0195..." → 19 (WRONG!)
+
+// ❌ NEVER use id ?? '' fallback
+const value = c.publicId ?? c.id ?? ''; // Wrong!
+
+// ✅ CORRECT — Use publicId only
+const value = c.publicId; // "019505a1-7c3e-7000-8000-abc123def456"
+```
+
+## Related Documents
+
+- `specs/06-Decision-Records/ADR-019-hybrid-identifier-strategy.md`
+- `specs/05-Engineering-Guidelines/05-07-hybrid-uuid-implementation-plan.md`

.agent/rules/01-code-execution.md

@@ -1,41 +0,0 @@
----
-trigger: always_on
-description: Control which shell commands the agent may run automatically.
-allowAuto:
-  - 'pnpm test:watch'
-  - 'pnpm test:debug'
-  - 'pnpm test:e2e'
-  - 'git status'
-  - 'git log --oneline'
-  - 'git diff'
-  - 'git branch'
-  - 'tsc --noEmit'
-denyAuto:
-  - 'rm -rf'
-  - 'Remove-Item'
-  - 'git push --force'
-  - 'git reset --hard'
-  - 'git clean -fd'
-  - 'curl | bash'
-  - 'docker compose down'
-  - 'DROP TABLE'
-  - 'TRUNCATE'
-  - 'DELETE FROM'
-  - 'pnpm migration:*'
-  - 'npm run migration:*'
-  - 'npx auth secret'
-alwaysReview: true
-scopes:
-  - 'backend/src/**'
-  - 'backend/test/**'
-  - 'frontend/app/**'
----
-
-# Execution Rules
-
-- Only auto-execute commands that are explicitly listed in `allowAuto`.
-- Commands in `denyAuto` must always be blocked, even if manually requested.
-- All shell operations that create, modify, or delete files in `backend/src/`, `backend/test/`, or `frontend/app/` require human review.
-- Alert before running any SQL that modifies data (INSERT/UPDATE/DELETE/DROP/TRUNCATE).
-- Alert if environment variables related to DB connection or secrets (DATABASE_URL, JWT_SECRET, passwords) would be displayed or logged.
-- Never auto-execute commands that expose sensitive credentials via MCP tools or shell output.

.agent/rules/02-identifier-strategy.md

@@ -1,18 +0,0 @@
----
-trigger: always_on
----
-
-# 🆔 Identifier Strategy (ADR-019) — CRITICAL
-
-| Context          | Type                      | Notes                                       |
-| ---------------- | ------------------------- | ------------------------------------------- |
-| Internal / DB FK | `INT AUTO_INCREMENT`      | Never exposed in API                        |
-| Public API / URL | `UUIDv7` (MariaDB native) | Stored as BINARY(16), no transformer needed |
-| Entity Property  | `publicId: string`        | Exposed directly in API (no transformation) |
-
-**CRITICAL RULES:**
-
-- **NEVER** use `parseInt`, `Number()`, or `+` on UUID values.
-- **NEVER** use `id ?? ''` fallback for identifiers in the frontend.
-- Use `publicId` only in frontend and public API responses.
-- `INT id` has `@Exclude()` on the backend — it must never appear in API responses.

.agent/rules/02-security.md

@@ -0,0 +1,36 @@
+---
+trigger: always_on
+---
+
+# Security Rules (Non-Negotiable)
+
+## Mandatory Security Requirements
+
+1. **Idempotency:** All critical `POST`/`PUT`/`PATCH` MUST validate `Idempotency-Key` header
+2. **Two-Phase File Upload:** Upload → Temp → Commit → Permanent
+3. **Race Conditions:** Redis Redlock + TypeORM `@VersionColumn` for Document Numbering
+4. **Validation:** Zod (frontend) + class-validator (backend DTO)
+5. **Password:** bcrypt 12 salt rounds, min 8 chars, rotate every 90 days
+6. **Rate Limiting:** `ThrottlerGuard` on all auth endpoints
+7. **File Upload:** Whitelist PDF/DWG/DOCX/XLSX/ZIP, max 50MB, ClamAV scan
+8. **AI Isolation (ADR-018):** Ollama on Admin Desktop ONLY — NO direct DB/storage access
+9. **Error Handling (ADR-007):** Use layered error classification with user-friendly messages
+10. **AI Integration (ADR-020):** RFA-First approach with unified pipeline architecture
+11. **AI Audit Trail:** Log all AI interactions and human validations
+12. **Rate Limiting:** Apply to AI endpoints to prevent abuse
+
+## Full Documentation
+
+`specs/06-Decision-Records/ADR-016-security-authentication.md`
+
+## Security Checklist (Before Every Commit)
+
+- [ ] Input validation implemented (Zod/class-validator)
+- [ ] RBAC/CASL permissions checked
+- [ ] No SQL injection vulnerabilities
+- [ ] File upload validation (whitelist + ClamAV)
+- [ ] Rate limiting applied to auth endpoints
+- [ ] AI boundary enforcement (ADR-018) - no direct DB/storage access
+- [ ] AI audit logging implemented for AI interactions
+- [ ] Error handling follows ADR-007 layered classification
+- [ ] OWASP Top 10 review passed

.agent/rules/03-security-rules.md

@@ -1,23 +0,0 @@
----
-trigger: always_on
----
-
-# 🛡️ Security Rules (Non-Negotiable)
-
-1. **Idempotency:** All critical `POST`/`PUT`/`PATCH` MUST validate `Idempotency-Key` header
-2. **Two-Phase File Upload:** Upload → Temp → Commit → Permanent
-3. **Race Conditions:** Redis Redlock + TypeORM `@VersionColumn` for Document Numbering
-4. **Validation:** Zod (frontend) + class-validator (backend DTO)
-5. **AI Isolation (ADR-018):** Ollama on Admin Desktop ONLY — NO direct DB/storage access
-
-## 🚫 Forbidden Actions
-
-| ❌ Forbidden                                    | ✅ Correct Approach                           |
-| ----------------------------------------------- | --------------------------------------------- |
-| SQL Triggers for business logic                 | NestJS Service methods                        |
-| TypeORM migration files                         | Edit schema SQL directly (ADR-009)            |
-| `any` TypeScript type                           | Proper types / generics                       |
-| `console.log` in committed code                 | NestJS Logger (backend) / remove (frontend)   |
-| Direct file operations bypassing StorageService | `StorageService` for all file moves           |
-| Inline email/notification sending               | BullMQ queue job                              |
-| `parseInt()` on UUID values                     | Use UUID string directly (ADR-019)            |

.agent/rules/03-typescript.md

@@ -0,0 +1,32 @@
+---
+trigger: always_on
+---
+
+# TypeScript Rules
+
+## Strict Requirements
+
+- **Strict Mode** — all strict checks enforced
+- **ZERO `any` types** — use proper types or `unknown` + narrowing
+- **ZERO `console.log`** — NestJS `Logger` (backend); remove before commit (frontend)
+
+## Comment Language Policy
+
+- **Comments:** Thai (เข้าใจง่ายสำหรับทีมไทย)
+- **Code Identifiers:** English (variables, functions, classes)
+
+## Error Handling Pattern
+
+```typescript
+// Backend (NestJS)
+import { Logger } from '@nestjs/common';
+const logger = new Logger('ServiceName');
+
+// Use logger instead of console.log
+logger.error('Error message', error.stack);
+throw new HttpException('Message', HttpStatus.BAD_REQUEST);
+
+// Frontend (Next.js)
+// Remove all console.log before commit
+// Use proper error boundaries and toast notifications
+```

.agent/rules/04-development-standards.md

@@ -1,24 +0,0 @@
----
-trigger: always_on
----
-
-# 📐 TypeScript Rules
-
-- **Strict Mode** — all strict checks enforced
-- **ZERO `any` types** — use proper types or `unknown` + narrowing
-- **ZERO `console.log`** — NestJS `Logger` (backend); remove before commit (frontend)
-
-## 🏷️ Domain Terminology (Thai Comments, English Code)
-
-| ✅ Use             | ❌ Don't Use                          |
-| ------------------ | ------------------------------------- |
-| Correspondence     | Letter, Communication, Document       |
-| RFA                | Approval Request, Submit for Approval |
-| Workflow Engine    | Approval Flow, Process Engine         |
-| Document Numbering | Document ID, Auto Number              |
-
-## 🔄 Development Flow (Tiered)
-
-- **🔴 Critical (DB/API/Security):** MUST follow all Context Protocol steps.
-- **🟡 Normal (UI/Feature):** Follow existing patterns, check spec for relevant module.
-- **🟢 Quick Fix:** Fix directly, check forbidden patterns before commit.

.agent/rules/04-domain-terminology.md

@@ -0,0 +1,38 @@
+---
+trigger: always_on
+---
+
+# Domain Terminology
+
+## DMS Glossary
+
+| ✅ Use             | ❌ Don't Use                          |
+| ------------------ | ------------------------------------- |
+| Correspondence     | Letter, Communication, Document       |
+| RFA                | Approval Request, Submit for Approval |
+| Transmittal        | Delivery Note, Cover Letter           |
+| Circulation        | Distribution, Routing                 |
+| Shop Drawing       | Construction Drawing                  |
+| Contract Drawing   | Design Drawing, Blueprint             |
+| Workflow Engine    | Approval Flow, Process Engine         |
+| Document Numbering | Document ID, Auto Number              |
+| RBAC               | Permission System (generic)           |
+
+## Full Glossary
+
+`specs/00-overview/00-02-glossary.md`
+
+## Key Spec Files Priority
+
+Spec priority: **`06-Decision-Records`** > **`05-Engineering-Guidelines`** > others
+
+| Document                | Path                                                              | Use When                        |
+| ----------------------- | ----------------------------------------------------------------- | ------------------------------- |
+| **Glossary**            | `specs/00-overview/00-02-glossary.md`                             | Verify domain terminology       |
+| **Schema Tables**       | `specs/03-Data-and-Storage/lcbp3-v1.8.0-schema-02-tables.sql`     | Before writing any query        |
+| **Data Dictionary**     | `specs/03-Data-and-Storage/03-01-data-dictionary.md`              | Field meanings + business rules |
+| **Edge Cases**          | `specs/01-Requirements/01-06-edge-cases-and-rules.md`             | Prevent bugs in flows           |
+| **ADR-019 UUID**        | `specs/06-Decision-Records/ADR-019-hybrid-identifier-strategy.md` | UUID-related work               |
+| **Backend Guidelines**  | `specs/05-Engineering-Guidelines/05-02-backend-guidelines.md`     | NestJS patterns                 |
+| **Frontend Guidelines** | `specs/05-Engineering-Guidelines/05-03-frontend-guidelines.md`    | Next.js patterns                |
+| **Testing Strategy**    | `specs/05-Engineering-Guidelines/05-04-testing-strategy.md`       | Coverage goals                  |

.agent/rules/05-forbidden-actions.md

@@ -0,0 +1,41 @@
+---
+trigger: always_on
+---
+
+# Forbidden Actions
+
+## ❌ Never Do This
+
+| ❌ Forbidden                                    | ✅ Correct Approach                             |
+| ----------------------------------------------- | ----------------------------------------------- |
+| SQL Triggers for business logic                 | NestJS Service methods                          |
+| `.env` files in production                      | `docker-compose.yml` environment section        |
+| TypeORM migration files                         | Edit schema SQL directly (ADR-009)              |
+| Inventing table/column names                    | Verify against `schema-02-tables.sql`           |
+| `any` TypeScript type                           | Proper types / generics                         |
+| `console.log` in committed code                 | NestJS Logger (backend) / remove (frontend)     |
+| `req: any` in controllers                       | `RequestWithUser` typed interface               |
+| `parseInt()` on UUID values                     | Use UUID string directly (ADR-019)              |
+| Exposing INT PK in API responses                | UUIDv7 (ADR-019)                                |
+| AI accessing DB/storage directly                | AI → DMS API → DB (ADR-018)                     |
+| Direct file operations bypassing StorageService | `StorageService` for all file moves             |
+| Inline email/notification sending               | BullMQ queue job                                |
+| Deploying without Release Gates                 | Complete `04-08-release-management-policy.md`   |
+| AI direct cloud API calls                       | On-premises Ollama only (ADR-018)               |
+| AI outputs without human validation             | Human-in-the-loop validation required (ADR-020) |
+
+## Schema Changes (ADR-009)
+
+- **NO TypeORM migrations** — edit SQL schema directly
+- Always check `specs/03-Data-and-Storage/lcbp3-v1.8.0-schema-02-tables.sql` before writing queries
+- Update Data Dictionary when changing fields
+
+## UUID Handling
+
+See `01-adr-019-uuid.md` for complete UUID rules.
+
+Quick reminder:
+
+- ❌ `parseInt(uuid)` → NEVER
+- ❌ `Number(uuid)` → NEVER
+- ✅ Use UUID string directly

.agent/rules/05-precommit-checklist.md

@@ -1,13 +0,0 @@
----
-trigger: always_on
----
-
-# ✅ Quick Reference Checklist (Before Every Commit)
-
-- [ ] UUID pattern verified (no parseInt on UUID)
-- [ ] No `any` types in TypeScript
-- [ ] No `console.log` in committed code
-- [ ] Comments in Thai, Code identifiers in English
-- [ ] Schema changes via SQL directly (not migration)
-- [ ] Relevant ADRs checked (ADR-009, ADR-018, ADR-019)
-- [ ] i18n keys used instead of hardcode text

.agent/rules/06-backend-patterns.md

@@ -0,0 +1,63 @@
+---
+trigger: always_on
+globs:
+  - "backend/**/*.service.ts"
+  - "backend/**/*.controller.ts"
+  - "backend/**/*.dto.ts"
+  - "backend/**/*.entity.ts"
+---
+
+# Backend Patterns (NestJS)
+
+## Architecture
+
+- **Thin Controller** — business logic in Service layer
+- **DTO Validation** — class-validator + class-transformer
+- **RBAC** — CASL for authorization
+- **Error Handling** — Logger + HttpException
+
+## UUID Resolution Pattern
+
+```typescript
+// Controller - accept UUID in DTO
+@Post()
+async create(@Body() dto: CreateCorrespondenceDto) {
+  // Resolve UUID to internal ID
+  const contract = await this.contractService.findOneByUuid(dto.contractUuid);
+  const contractId = contract.id; // Internal INT for DB queries
+
+  return this.service.create(dto, contractId);
+}
+
+// Service - use internal ID for DB operations
+async create(dto: CreateCorrespondenceDto, contractId: number) {
+  // Use contractId (INT) for database queries
+  const correspondence = this.repo.create({
+    contractId,  // FK is INT
+    // ... other fields
+  });
+  return this.repo.save(correspondence);
+}
+```
+
+## API Response Pattern
+
+```typescript
+// Entity
+@Entity()
+class Contract extends UuidBaseEntity {
+  @Column({ type: 'uuid' })
+  publicId: string;
+
+  @PrimaryKey()
+  @Exclude()
+  id: number;
+}
+
+// Response automatically includes publicId as 'id'
+// { id: "019505a1-7c3e-7000-8000-abc123def456", ... }
+```
+
+## Full Guidelines
+
+`specs/05-Engineering-Guidelines/05-02-backend-guidelines.md`

.agent/rules/07-frontend-patterns.md

@@ -0,0 +1,54 @@
+---
+trigger: always_on
+globs:
+  - "frontend/**/*.tsx"
+  - "frontend/**/*.ts"
+  - "frontend/**/*.css"
+---
+
+# Frontend Patterns (Next.js)
+
+## Form Handling
+
+- **RHF** (React Hook Form) for form management
+- **Zod** for validation schema
+- **TanStack Query** for server state
+
+## UUID Handling
+
+```typescript
+// ✅ CORRECT - Use publicId only
+interface ProjectOption {
+  publicId?: string;
+  projectName?: string;
+}
+
+// Select options
+const options = contracts.map(c => ({
+  label: `${c.contractName} (${c.contractCode})`,
+  value: c.publicId!, // Use publicId, no fallback to id
+}));
+
+// ❌ WRONG - Never use these patterns
+const value = c.publicId ?? c.id ?? ''; // Wrong!
+const id = parseInt(projectId); // Wrong - parseInt on UUID!
+```
+
+## API Client Pattern
+
+```typescript
+// Use publicId directly in API calls
+const contract = await contractService.getById(publicId);
+
+// Form submission with UUID
+const onSubmit = async (data: FormData) => {
+  await correspondenceService.create({
+    contractUuid: selectedContract.publicId!, // UUID string
+    // ... other fields
+  });
+};
+```
+
+## Full Guidelines
+
+`specs/05-Engineering-Guidelines/05-03-frontend-guidelines.md`

.agent/rules/08-development-flow.md

@@ -0,0 +1,42 @@
+---
+trigger: always_on
+---
+
+# Development Flow
+
+## 🔴 Critical Work — DB / API / Security / Workflow Engine
+
+**MUST complete all steps:**
+
+1. **Glossary check** — verify domain terms in `00-02-glossary.md`
+2. **Read the spec** — select from Key Spec Files table
+3. **Check schema** — verify table/column in `schema-02-tables.sql`
+4. **Check data dictionary** — confirm field meanings + business rules
+5. **Scan edge cases** — `01-06-edge-cases-and-rules.md`
+6. **Check ADRs** — verify decisions align (ADR-009, ADR-018, ADR-019)
+7. **Write code** — TypeScript strict, no `any`, no `console.log`
+
+## 🟡 Normal Work — UI / Feature / Integration
+
+- Follow existing patterns in codebase
+- Check spec for relevant module only
+- No need to read all specs
+
+## 🟢 Quick Fix — Bug Fix / Typo / Style
+
+- Fix directly
+- Add minimal test if logic changed
+- Check forbidden patterns before commit
+
+## Context-Aware Triggers
+
+| Request              | Files to Check                                          | Expected Response                                   |
+| -------------------- | ------------------------------------------------------- | --------------------------------------------------- |
+| "สร้าง API ใหม่"     | `05-02-backend-guidelines.md`, `schema-02-tables.sql`   | NestJS Controller + Service + DTO + CASL Guard      |
+| "แก้ฟอร์ม frontend"  | `05-03-frontend-guidelines.md`, `01-06-edge-cases.md`   | RHF+Zod + TanStack Query + Thai comments            |
+| "เพิ่ม field ใหม่"   | `ADR-009`, `data-dictionary.md`, `schema-02-tables.sql` | Edit SQL directly + update Data Dictionary + Entity |
+| "ตรวจสอบ UUID"       | `ADR-019`, `05-07-hybrid-uuid-implementation-plan.md`   | UUIDv7 MariaDB native UUID + TransformInterceptor   |
+| "สร้าง migration"    | `ADR-009`, `03-06-migration-business-scope.md`          | Edit SQL schema directly + n8n workflow             |
+| "ตรวจสอบ permission" | `seed-permissions.sql`, `ADR-016`                       | CASL 4-Level RBAC matrix                            |
+| "deploy production"  | `04-08-release-management-policy.md`, `ADR-015`         | Release Gates + Blue-Green strategy                 |
+| "เพิ่ม test"         | `05-04-testing-strategy.md`                             | Coverage goals + test patterns                      |

.agent/rules/09-commit-checklist.md

@@ -0,0 +1,36 @@
+---
+trigger: always_on
+---
+
+# Commit Checklist
+
+## Pre-Commit Verification
+
+- [ ] UUID pattern verified (no parseInt on UUID)
+- [ ] No `any` types in TypeScript
+- [ ] No `console.log` in committed code
+- [ ] Comments in Thai
+- [ ] Code identifiers in English
+- [ ] Schema changes via SQL directly (not migration)
+- [ ] Test coverage meets targets (Backend 70%+, Business Logic 80%+)
+- [ ] Relevant ADRs checked (ADR-009, ADR-018, ADR-019)
+- [ ] Glossary terms used correctly
+- [ ] Error handling complete (Logger + HttpException)
+- [ ] i18n keys used instead of hardcode text
+- [ ] Cache invalidation when data modified
+- [ ] Security checklist passed (OWASP Top 10)
+
+## Commit Message Format
+
+```
+type(scope): description
+
+[optional body]
+```
+
+Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
+
+Examples:
+- `feat(correspondence): add originator organization validation`
+- `fix(uuid): correct parseInt usage to string comparison`
+- `spec(agents): bump to v1.8.5 - refactor structure`

.agent/rules/10-error-handling.md

@@ -0,0 +1,78 @@
+---
+trigger: always_on
+---
+
+# ADR-007 Error Handling Strategy
+
+## CRITICAL RULES
+
+- **ALWAYS** use layered error classification (Validation, Business, System)
+- **NEVER** expose technical details to end users
+- **ALWAYS** provide user-friendly error messages with recovery guidance
+- **ALWAYS** log technical details for debugging
+- **NEVER** use generic error messages without context
+
+## Error Classification
+
+| Error Type | Description | User Message | Technical Log |
+|------------|-------------|--------------|---------------|
+| **Validation** | Input validation failures | Clear field-level errors | Full validation details |
+| **Business** | Business rule violations | Actionable guidance | Business context + user ID |
+| **System** | Infrastructure failures | Generic "try again" | Full stack trace + metrics |
+
+## Backend Pattern (NestJS)
+
+```typescript
+// Custom Exception Hierarchy
+export class BusinessException extends HttpException {
+  constructor(
+    message: string,
+    userMessage: string,
+    recoveryAction?: string,
+    errorCode?: string
+  ) {
+    super({ message, userMessage, recoveryAction, errorCode }, 400);
+  }
+}
+
+// Global Exception Filter
+@Catch()
+export class GlobalExceptionFilter implements ExceptionFilter {
+  catch(exception: unknown, host: ArgumentsHost) {
+    // Classify error and provide appropriate response
+    // Log technical details
+    // Return user-friendly message
+  }
+}
+```
+
+## Frontend Pattern (Next.js)
+
+```typescript
+// Error Display Component
+const ErrorDisplay = ({ error, onRetry }) => {
+  const userMessage = error.userMessage || 'เกิดข้อผิดพลาด';
+  const recoveryAction = error.recoveryAction;
+
+  return (
+    <div>
+      <p>{userMessage}</p>
+      {recoveryAction && <p>{recoveryAction}</p>}
+      {onRetry && <button onClick={onRetry}>ลองใหม่</button>}
+    </div>
+  );
+};
+```
+
+## Required Implementation
+
+- [ ] Global Exception Filter with layered classification
+- [ ] Custom exception hierarchy (Validation, Business, System)
+- [ ] Standardized error response DTOs
+- [ ] Frontend error display components
+- [ ] Error recovery mechanisms where applicable
+
+## Related Documents
+
+- `specs/06-Decision-Records/ADR-007-error-handling-strategy.md`
+- `specs/06-Decision-Records/ADR-010-logging-monitoring-strategy.md`

.agent/rules/11-ai-integration.md

@@ -0,0 +1,100 @@
+---
+trigger: always_on
+---
+
+# ADR-020 AI Integration Architecture
+
+## CRITICAL RULES
+
+- **ALWAYS** follow ADR-018 AI boundary policy (isolation on Admin Desktop)
+- **ALWAYS** use RFA-First approach for AI implementation
+- **NEVER** allow AI direct database/storage access
+- **ALWAYS** implement human-in-the-loop validation
+- **NEVER** send sensitive data to cloud AI services
+
+## AI Integration Patterns
+
+### Architecture Overview
+
+```
+Frontend → AI Gateway API → Admin Desktop (Ollama) → Backend Validation
+```
+
+### Key Components
+
+| Component | Location | Purpose |
+|-----------|----------|---------|
+| **AI Gateway** | Backend (NestJS) | API endpoints, validation, audit logging |
+| **Ollama Engine** | Admin Desktop (Desk-5439) | LLM inference (Gemma 4) |
+| **OCR Engine** | Admin Desktop (Desk-5439) | Thai/English text extraction |
+| **Orchestrator** | QNAP NAS (n8n) | Workflow management |
+
+## Backend Implementation (NestJS)
+
+```typescript
+// AI Module with boundary enforcement
+@Module({
+  controllers: [AiController],
+  providers: [AiService, AiGateway],
+  exports: [AiService],
+})
+export class AiModule {
+  constructor() {
+    // Enforce ADR-018 boundaries
+  }
+}
+
+// AI Service with validation
+@Injectable()
+export class AiService {
+  async extractMetadata(documentId: string): Promise<AIMetadata> {
+    // 1. Validate permissions
+    // 2. Send to Admin Desktop AI
+    // 3. Validate AI response
+    // 4. Log audit trail
+    // 5. Return validated results
+  }
+}
+```
+
+## Frontend Pattern (Next.js)
+
+```typescript
+// Document Review Form (reusable component)
+const DocumentReviewForm = ({ document, aiSuggestions }) => {
+  return (
+    <form>
+      <Field label="Document Type" suggestions={aiSuggestions.documentType} />
+      <Field label="Project Code" suggestions={aiSuggestions.projectCode} />
+      <Field label="Discipline" suggestions={aiSuggestions.discipline} />
+
+      <ConfidenceScore score={aiSuggestions.confidence} />
+      <HumanValidationActions />
+    </form>
+  );
+};
+```
+
+## Security Requirements
+
+- **AI Isolation:** All AI processing on Admin Desktop only
+- **Data Privacy:** No cloud AI services, on-premises only
+- **Audit Trail:** Log all AI interactions and human validations
+- **Rate Limiting:** Prevent AI abuse and resource exhaustion
+- **Validation:** All AI outputs must be validated before use
+
+## Required Implementation
+
+- [ ] AiModule with ADR-018 boundary enforcement
+- [ ] AI Gateway API endpoints with validation
+- [ ] DocumentReviewForm reusable component
+- [ ] Admin Desktop Ollama + PaddleOCR setup
+- [ ] n8n workflow orchestration
+- [ ] AI audit logging and monitoring
+- [ ] Human-in-the-loop validation workflows
+
+## Related Documents
+
+- `specs/06-Decision-Records/ADR-018-ai-boundary.md`
+- `specs/06-Decision-Records/ADR-020-ai-intelligence-integration.md`
+- `specs/06-Decision-Records/ADR-017-ollama-data-migration.md`

.agent/rules/workflows/00-speckit.all.md

@@ -0,0 +1,85 @@
+---
+description: Run the full speckit pipeline from specification to analysis in one command.
+---
+
+# Workflow: speckit.all
+
+This meta-workflow orchestrates the **complete development lifecycle**, from specification through implementation and validation. For the preparation-only pipeline (steps 1-5), use `/speckit.prepare` instead.
+
+## Preparation Phase (Steps 1-5)
+
+1. **Specify** (`/speckit.specify`):
+   - Use the `view_file` tool to read: `.agents/skills/speckit.specify/SKILL.md`
+   - Execute with user's feature description
+   - Creates: `spec.md`
+
+2. **Clarify** (`/speckit.clarify`):
+   - Use the `view_file` tool to read: `.agents/skills/speckit.clarify/SKILL.md`
+   - Execute to resolve ambiguities
+   - Updates: `spec.md`
+
+3. **Plan** (`/speckit.plan`):
+   - Use the `view_file` tool to read: `.agents/skills/speckit.plan/SKILL.md`
+   - Execute to create technical design
+   - Creates: `plan.md`
+
+4. **Tasks** (`/speckit.tasks`):
+   - Use the `view_file` tool to read: `.agents/skills/speckit.tasks/SKILL.md`
+   - Execute to generate task breakdown
+   - Creates: `tasks.md`
+
+5. **Analyze** (`/speckit.analyze`):
+   - Use the `view_file` tool to read: `.agents/skills/speckit.analyze/SKILL.md`
+   - Execute to validate consistency across spec, plan, and tasks
+   - Output: Analysis report
+   - **Gate**: If critical issues found, stop and fix before proceeding
+
+## Implementation Phase (Steps 6-7)
+
+6. **Implement** (`/speckit.implement`):
+   - Use the `view_file` tool to read: `.agents/skills/speckit.implement/SKILL.md`
+   - Execute all tasks from `tasks.md` with anti-regression protocols
+   - Output: Working implementation
+
+7. **Check** (`/speckit.checker`):
+   - Use the `view_file` tool to read: `.agents/skills/speckit.checker/SKILL.md`
+   - Run static analysis (linters, type checkers, security scanners)
+   - Output: Checker report
+
+## Verification Phase (Steps 8-10)
+
+8. **Test** (`/speckit.tester`):
+   - Use the `view_file` tool to read: `.agents/skills/speckit.tester/SKILL.md`
+   - Run tests with coverage
+   - Output: Test + coverage report
+
+9. **Review** (`/speckit.reviewer`):
+   - Use the `view_file` tool to read: `.agents/skills/speckit.reviewer/SKILL.md`
+   - Perform code review
+   - Output: Review report with findings
+
+10. **Validate** (`/speckit.validate`):
+    - Use the `view_file` tool to read: `.agents/skills/speckit.validate/SKILL.md`
+    - Verify implementation matches spec requirements
+    - Output: Validation report (pass/fail)
+
+## Usage
+
+```
+/speckit.all "Build a user authentication system with OAuth2 support"
+```
+
+## Pipeline Comparison
+
+| Pipeline           | Steps                     | Use When                               |
+| ------------------ | ------------------------- | -------------------------------------- |
+| `/speckit.prepare` | 1-5 (Specify → Analyze)   | Planning only — you'll implement later |
+| `/speckit.all`     | 1-10 (Specify → Validate) | Full lifecycle in one pass             |
+
+## On Error
+
+If any step fails, stop the pipeline and report:
+
+- Which step failed
+- The error message
+- Suggested remediation (e.g., "Run `/speckit.clarify` to resolve ambiguities before continuing")

.agent/rules/workflows/01-speckit.constitution.md

@@ -0,0 +1,18 @@
+---
+description: Create or update the project constitution from interactive or provided principle inputs, ensuring all dependent templates stay in sync.
+---
+
+# Workflow: speckit.constitution
+
+1. **Context Analysis**:
+   - The user has provided an input prompt. Treat this as the primary input for the skill.
+
+2. **Load Skill**:
+   - Use the `view_file` tool to read the skill file at: `.agents/skills/speckit.constitution/SKILL.md`
+
+3. **Execute**:
+   - Follow the instructions in the `SKILL.md` exactly.
+   - Apply the user's prompt as the input arguments/context for the skill's logic.
+
+4. **On Error**:
+   - If `.specify/` directory doesn't exist: Initialize the speckit structure first

.agent/rules/workflows/02-speckit.specify.md

@@ -0,0 +1,19 @@
+---
+description: Create or update the feature specification from a natural language feature description.
+---
+
+# Workflow: speckit.specify
+
+1. **Context Analysis**:
+   - The user has provided an input prompt. Treat this as the primary input for the skill.
+   - This is typically the starting point of a new feature.
+
+2. **Load Skill**:
+   - Use the `view_file` tool to read the skill file at: `.agents/skills/speckit.specify/SKILL.md`
+
+3. **Execute**:
+   - Follow the instructions in the `SKILL.md` exactly.
+   - Apply the user's prompt as the feature description for the skill's logic.
+
+4. **On Error**:
+   - If no feature description provided: Ask the user to describe the feature they want to specify

.agent/rules/workflows/03-speckit.clarify.md

@@ -0,0 +1,18 @@
+---
+description: Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec.
+---
+
+# Workflow: speckit.clarify
+
+1. **Context Analysis**:
+   - The user has provided an input prompt. Treat this as the primary input for the skill.
+
+2. **Load Skill**:
+   - Use the `view_file` tool to read the skill file at: `.agents/skills/speckit.clarify/SKILL.md`
+
+3. **Execute**:
+   - Follow the instructions in the `SKILL.md` exactly.
+   - Apply the user's prompt as the input arguments/context for the skill's logic.
+
+4. **On Error**:
+   - If `spec.md` is missing: Run `/speckit.specify` first to create the feature specification

.agent/rules/workflows/04-speckit.plan.md

@@ -0,0 +1,18 @@
+---
+description: Execute the implementation planning workflow using the plan template to generate design artifacts.
+---
+
+# Workflow: speckit.plan
+
+1. **Context Analysis**:
+   - The user has provided an input prompt. Treat this as the primary input for the skill.
+
+2. **Load Skill**:
+   - Use the `view_file` tool to read the skill file at: `.agents/skills/speckit.plan/SKILL.md`
+
+3. **Execute**:
+   - Follow the instructions in the `SKILL.md` exactly.
+   - Apply the user's prompt as the input arguments/context for the skill's logic.
+
+4. **On Error**:
+   - If `spec.md` is missing: Run `/speckit.specify` first to create the feature specification

.agent/rules/workflows/05-speckit.tasks.md

@@ -0,0 +1,19 @@
+---
+description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts.
+---
+
+# Workflow: speckit.tasks
+
+1. **Context Analysis**:
+   - The user has provided an input prompt. Treat this as the primary input for the skill.
+
+2. **Load Skill**:
+   - Use the `view_file` tool to read the skill file at: `.agents/skills/speckit.tasks/SKILL.md`
+
+3. **Execute**:
+   - Follow the instructions in the `SKILL.md` exactly.
+   - Apply the user's prompt as the input arguments/context for the skill's logic.
+
+4. **On Error**:
+   - If `plan.md` is missing: Run `/speckit.plan` first
+   - If `spec.md` is missing: Run `/speckit.specify` first

.agent/rules/workflows/06-speckit.analyze.md

@@ -0,0 +1,22 @@
+---
+description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation.
+---
+
+// turbo-all
+
+# Workflow: speckit.analyze
+
+1. **Context Analysis**:
+   - The user has provided an input prompt. Treat this as the primary input for the skill.
+
+2. **Load Skill**:
+   - Use the `view_file` tool to read the skill file at: `.agents/skills/speckit.analyze/SKILL.md`
+
+3. **Execute**:
+   - Follow the instructions in the `SKILL.md` exactly.
+   - Apply the user's prompt as the input arguments/context for the skill's logic.
+
+4. **On Error**:
+   - If `spec.md` is missing: Run `/speckit.specify` first
+   - If `plan.md` is missing: Run `/speckit.plan` first
+   - If `tasks.md` is missing: Run `/speckit.tasks` first

.agent/rules/workflows/07-speckit.implement.md

@@ -0,0 +1,20 @@
+---
+description: Execute the implementation plan by processing and executing all tasks defined in tasks.md
+---
+
+# Workflow: speckit.implement
+
+1. **Context Analysis**:
+   - The user has provided an input prompt. Treat this as the primary input for the skill.
+
+2. **Load Skill**:
+   - Use the `view_file` tool to read the skill file at: `.agents/skills/speckit.implement/SKILL.md`
+
+3. **Execute**:
+   - Follow the instructions in the `SKILL.md` exactly.
+   - Apply the user's prompt as the input arguments/context for the skill's logic.
+
+4. **On Error**:
+   - If `tasks.md` is missing: Run `/speckit.tasks` first
+   - If `plan.md` is missing: Run `/speckit.plan` first
+   - If `spec.md` is missing: Run `/speckit.specify` first

.agent/rules/workflows/08-speckit.checker.md

@@ -0,0 +1,21 @@
+---
+description: Run static analysis tools and aggregate results.
+---
+
+// turbo-all
+
+# Workflow: speckit.checker
+
+1. **Context Analysis**:
+   - The user may specify paths to check or run on entire project.
+
+2. **Load Skill**:
+   - Use the `view_file` tool to read the skill file at: `.agents/skills/speckit.checker/SKILL.md`
+
+3. **Execute**:
+   - Follow the instructions in the `SKILL.md` exactly.
+   - Apply the user's prompt as the input arguments/context for the skill's logic.
+
+4. **On Error**:
+   - If no linting tools available: Report which tools to install based on project type
+   - If tools fail: Show raw error and suggest config fixes

.agent/rules/workflows/09-speckit.tester.md

@@ -0,0 +1,21 @@
+---
+description: Execute tests, measure coverage, and report results.
+---
+
+// turbo-all
+
+# Workflow: speckit.tester
+
+1. **Context Analysis**:
+   - The user may specify test paths, options, or just run all tests.
+
+2. **Load Skill**:
+   - Use the `view_file` tool to read the skill file at: `.agents/skills/speckit.tester/SKILL.md`
+
+3. **Execute**:
+   - Follow the instructions in the `SKILL.md` exactly.
+   - Apply the user's prompt as the input arguments/context for the skill's logic.
+
+4. **On Error**:
+   - If no test framework detected: Report "No test framework found. Install Jest, Vitest, Pytest, or similar."
+   - If tests fail: Show failure details and suggest fixes

.agent/rules/workflows/10-speckit.reviewer.md

@@ -0,0 +1,19 @@
+---
+description: Perform code review with actionable feedback and suggestions.
+---
+
+# Workflow: speckit.reviewer
+
+1. **Context Analysis**:
+   - The user may specify files to review, "staged" for git staged changes, or "branch" for branch diff.
+
+2. **Load Skill**:
+   - Use the `view_file` tool to read the skill file at: `.agents/skills/speckit.reviewer/SKILL.md`
+
+3. **Execute**:
+   - Follow the instructions in the `SKILL.md` exactly.
+   - Apply the user's prompt as the input arguments/context for the skill's logic.
+
+4. **On Error**:
+   - If no files to review: Ask user to stage changes or specify file paths
+   - If not a git repo: Review current directory files instead

.agent/rules/workflows/11-speckit.validate.md

@@ -0,0 +1,19 @@
+---
+description: Validate that implementation matches specification requirements.
+---
+
+# Workflow: speckit.validate
+
+1. **Context Analysis**:
+   - The user has provided an input prompt. Treat this as the primary input for the skill.
+
+2. **Load Skill**:
+   - Use the `view_file` tool to read the skill file at: `.agents/skills/speckit.validate/SKILL.md`
+
+3. **Execute**:
+   - Follow the instructions in the `SKILL.md` exactly.
+   - Apply the user's prompt as the input arguments/context for the skill's logic.
+
+4. **On Error**:
+   - If `tasks.md` is missing: Run `/speckit.tasks` first
+   - If implementation not started: Run `/speckit.implement` first

.agent/rules/workflows/create-backend-module.md

@@ -0,0 +1,51 @@
+---
+description: Create a new NestJS backend feature module following project standards
+---
+
+# Create NestJS Backend Module
+
+Use this workflow when creating a new feature module in `backend/src/modules/`.
+Follows `specs/05-Engineering-Guidelines/05-02-backend-guidelines.md` and ADR-005.
+
+## Steps
+
+// turbo
+
+1. **Verify requirements exist** — confirm the feature is in `specs/01-Requirements/` before starting
+
+// turbo 2. **Check schema** — read `specs/03-Data-and-Storage/lcbp3-v1.7.0-schema.sql` for relevant tables
+
+3. **Scaffold module folder**
+
+```
+backend/src/modules/<module-name>/
+├── <module-name>.module.ts
+├── <module-name>.controller.ts
+├── <module-name>.service.ts
+├── dto/
+│   ├── create-<module-name>.dto.ts
+│   └── update-<module-name>.dto.ts
+├── entities/
+│   └── <module-name>.entity.ts
+└── <module-name>.controller.spec.ts
+```
+
+4. **Create Entity** — map ONLY columns defined in the schema SQL. Use TypeORM decorators. Add `@VersionColumn()` if the entity needs optimistic locking.
+
+5. **Create DTOs** — use `class-validator` decorators. Never use `any`. Validate all inputs.
+
+6. **Create Service** — inject repository via constructor DI. Use transactions for multi-step writes. Add `Idempotency-Key` guard for POST/PUT/PATCH operations.
+
+7. **Create Controller** — apply `@UseGuards(JwtAuthGuard, CaslAbilityGuard)`. Use proper HTTP status codes. Document with `@ApiTags` and `@ApiOperation`.
+
+8. **Register in Module** — add to `imports`, `providers`, `controllers`, `exports` as needed.
+
+9. **Register in AppModule** — import the new module in `app.module.ts`.
+
+// turbo 10. **Write unit test** — cover service methods with Jest mocks. Run:
+
+```bash
+pnpm test:watch
+```
+
+// turbo 11. **Citation** — confirm implementation references `specs/01-Requirements/` and `specs/05-Engineering-Guidelines/05-02-backend-guidelines.md`

.agent/rules/workflows/create-frontend-page.md

@@ -0,0 +1,64 @@
+---
+description: Create a new Next.js App Router page following project standards
+---
+
+# Create Next.js Frontend Page
+
+Use this workflow when creating a new page in `frontend/app/`.
+Follows `specs/05-Engineering-Guidelines/05-03-frontend-guidelines.md`, ADR-011, ADR-012, ADR-013, ADR-014.
+
+## Steps
+
+1. **Determine route** — decide the route path, e.g. `app/(dashboard)/documents/page.tsx`
+
+2. **Classify components** — decide what is Server Component (default) vs Client Component (`'use client'`)
+   - Server Component: initial data load, static content, SEO
+   - Client Component: interactivity, forms, TanStack Query hooks, Zustand
+
+3. **Create page file** — Server Component by default:
+
+```typescript
+// app/(dashboard)/<route>/page.tsx
+import { Metadata } from 'next';
+
+export const metadata: Metadata = {
+  title: '<Page Title> | LCBP3-DMS',
+};
+
+export default async function <PageName>Page() {
+  return (
+    <div>
+      {/* Page content */}
+    </div>
+  );
+}
+```
+
+4. **Create API hook** (if client-side data needed) — add to `hooks/use-<feature>.ts`:
+
+```typescript
+'use client';
+import { useQuery } from '@tanstack/react-query';
+import { apiClient } from '@/lib/api-client';
+
+export function use<Feature>() {
+  return useQuery({
+    queryKey: ['<feature>'],
+    queryFn: () => apiClient.get('<endpoint>'),
+  });
+}
+```
+
+5. **Build UI components** — use Shadcn/UI primitives. Place reusable components in `components/<feature>/`.
+
+6. **Handle forms** — use React Hook Form + Zod schema validation. Never access form values without validation.
+
+7. **Handle errors** — add `error.tsx` alongside `page.tsx` for route-level error boundaries.
+
+8. **Add loading state** — add `loading.tsx` for Suspense fallback if page does async work.
+
+9. **Add to navigation** — update sidebar/nav config if the page should appear in the menu.
+
+10. **Access control** — ensure page checks CASL permissions. Redirect unauthorized users via middleware or `notFound()`.
+
+11. **Citation** — confirm implementation references `specs/01-Requirements/` and `specs/05-Engineering-Guidelines/05-03-frontend-guidelines.md`

.agent/rules/workflows/deploy.md

@@ -0,0 +1,71 @@
+---
+description: Deploy the application via Gitea Actions to QNAP Container Station
+---
+
+# Deploy to Production
+
+Use this workflow to deploy updated backend and/or frontend to QNAP via Gitea Actions CI/CD.
+Follows `specs/04-Infrastructure-OPS/` and ADR-015.
+
+## Pre-deployment Checklist
+
+- [ ] All tests pass locally (`pnpm test:watch`)
+- [ ] No TypeScript errors (`tsc --noEmit`)
+- [ ] No `any` types introduced
+- [ ] Schema changes applied to `specs/03-Data-and-Storage/lcbp3-v1.7.0-schema.sql`
+- [ ] Environment variables documented (NOT in `.env` files)
+
+## Steps
+
+1. **Commit and push to Gitea**
+
+```bash
+git status
+git add .
+git commit -m "feat(<scope>): <description>"
+git push origin main
+```
+
+2. **Monitor Gitea Actions** — open Gitea web UI → Actions tab → verify pipeline starts
+
+3. **Pipeline stages (automatic)**
+   - `build-backend` → Docker image build + push to registry
+   - `build-frontend` → Docker image build + push to registry
+   - `deploy` → SSH to QNAP → `docker compose pull` + `docker compose up -d`
+
+4. **Verify backend health**
+
+```bash
+curl http://<QNAP_IP>:3000/health
+# Expected: { "status": "ok" }
+```
+
+5. **Verify frontend**
+
+```bash
+curl -I http://<QNAP_IP>:3001
+# Expected: HTTP 200
+```
+
+6. **Check logs in Grafana** — navigate to Grafana → Loki → filter by container name
+   - Backend: `container_name="lcbp3-backend"`
+   - Frontend: `container_name="lcbp3-frontend"`
+
+7. **Verify database** — confirm schema changes are reflected (if any)
+
+8. **Rollback (if needed)**
+
+```bash
+# SSH into QNAP
+docker compose pull <service>=<previous-image-tag>
+docker compose up -d <service>
+```
+
+## Common Issues
+
+| Symptom           | Cause                 | Fix                                 |
+| ----------------- | --------------------- | ----------------------------------- |
+| Backend unhealthy | DB connection failed  | Check MariaDB container + env vars  |
+| Frontend blank    | Build error           | Check Next.js build logs in Grafana |
+| 502 Bad Gateway   | Container not started | `docker compose ps` to check status |
+| Pipeline stuck    | Gitea runner offline  | Restart runner on QNAP              |

.agent/rules/workflows/review.md

@@ -0,0 +1,62 @@
+---
+auto_execution_mode: 0
+description: Review code changes for bugs, security issues, and improvements
+---
+
+You are a senior software engineer performing a thorough code review to identify potential bugs.
+
+Your task is to find all potential bugs and code improvements in the code changes. Focus on:
+
+1. Logic errors and incorrect behavior
+2. Edge cases that aren't handled
+3. Null/undefined reference issues
+4. Race conditions or concurrency issues
+5. Security vulnerabilities
+6. Improper resource management or resource leaks
+7. API contract violations
+8. Incorrect caching behavior, including cache staleness issues, cache key-related bugs, incorrect cache invalidation, and ineffective caching
+9. Violations of existing code patterns or conventions
+
+## 🔴 Tier 1 Critical Rules (CI Blockers)
+
+The following are **CI-blocking issues** that must be caught in code review. These align with project specs in `specs/05-Engineering-Guidelines/` and `specs/06-Decision-Records/`:
+
+### ADR-019: UUID Handling
+
+- **❌ NEVER use `parseInt()`, `Number()`, or `+` operator on UUID values**
+  - Example of violation: `parseInt(projectId)` where `projectId` is UUID string
+  - ✅ Correct: Use UUID string directly without conversion
+- **❌ NEVER expose internal INT PK in API responses**
+  - API must expose only `publicId` (transformed to `id` via `@Expose()`)
+  - Verify DTOs have `@Exclude()` on `id: number` field
+
+### TypeScript Strict Rules
+
+- **❌ ZERO `any` types allowed** — use proper types or `unknown` + narrowing
+- **❌ ZERO `console.log`** — must use NestJS `Logger` (backend) or remove (frontend)
+- **❌ NO `req: any` in controllers** — use `RequestWithUser` typed interface
+
+### Database & Architecture
+
+- **❌ NO SQL Triggers for business logic** — use NestJS Service methods instead
+- **❌ NO `.env` files in production** — use Docker environment variables
+- **❌ NO direct table/column name invention** — verify against `specs/03-Data-and-Storage/lcbp3-v1.8.0-schema-02-tables.sql`
+
+### Security (ADR-016)
+
+- Idempotency validation for critical `POST`/`PUT`/`PATCH` endpoints
+- Two-phase file upload pattern (Upload → Temp → Commit → Permanent)
+- Input validation with class-validator (backend) and Zod (frontend)
+
+### Test Coverage Requirements
+
+- **Backend Services:** 80% minimum
+- **Backend Overall:** 70% minimum
+- **Business Logic:** 80% minimum
+
+Make sure to:
+
+1. If exploring the codebase, call multiple tools in parallel for increased efficiency. Do not spend too much time exploring.
+2. If you find any pre-existing bugs in the code, you should also report those since it's important for us to maintain general code quality for the user.
+3. Do NOT report issues that are speculative or low-confidence. All your conclusions should be based on a complete understanding of the codebase.
+4. Remember that if you were given a specific git commit, it may not be checked out and local code states may be different.

.agent/rules/workflows/schema-change.md

@@ -0,0 +1,108 @@
+---
+description: Manage database schema changes following ADR-009 (no migrations, modify SQL directly)
+---
+
+# Schema Change Workflow
+
+Use this workflow when modifying database schema for LCBP3-DMS.
+Follows `specs/06-Decision-Records/ADR-009-database-strategy.md` — **NO TypeORM migrations**.
+
+## Pre-Change Checklist
+
+- [ ] Change is required by a spec in `specs/01-Requirements/`
+- [ ] Existing data impact has been assessed
+- [ ] No SQL triggers are being added (business logic in NestJS only)
+
+## Steps
+
+1. **Read current schema** — load the full schema file:
+
+```
+specs/03-Data-and-Storage/lcbp3-v1.7.0-schema.sql
+```
+
+2. **Read data dictionary** — understand current field definitions:
+
+```
+specs/03-Data-and-Storage/03-01-data-dictionary.md
+```
+
+// turbo 3. **Identify impact scope** — determine which tables, columns, indexes, or constraints are affected. List:
+
+- Tables being modified/created
+- Columns being added/renamed/dropped
+- Foreign key relationships affected
+- Indexes being added/modified
+- Seed data impact (if any)
+
+4. **Modify schema SQL** — edit `specs/03-Data-and-Storage/lcbp3-v1.7.0-schema.sql`:
+   - Add/modify table definitions
+   - Maintain consistent formatting (uppercase SQL keywords, lowercase identifiers)
+   - Add inline comments for new columns explaining purpose
+   - Ensure `DEFAULT` values and `NOT NULL` constraints are correct
+   - Add `version` column with `@VersionColumn()` marker comment if optimistic locking is needed
+
+> [!CAUTION]
+> **NEVER use SQL Triggers.** All business logic must live in NestJS services.
+
+5. **Update data dictionary** — edit `specs/03-Data-and-Storage/03-01-data-dictionary.md`:
+   - Add new tables/columns with descriptions
+   - Update data types and constraints
+   - Document business rules for new fields
+   - Add enum value definitions if applicable
+
+6. **Update seed data** (if applicable):
+   - `specs/03-Data-and-Storage/lcbp3-v1.7.0-seed-basic.sql` — for reference/lookup data
+   - `specs/03-Data-and-Storage/lcbp3-v1.7.0-seed-permissions.sql` — for new CASL permissions
+
+7. **Update TypeORM entity** — modify corresponding `backend/src/modules/<module>/entities/*.entity.ts`:
+   - Map ONLY columns defined in schema SQL
+   - Use correct TypeORM decorators (`@Column`, `@PrimaryGeneratedColumn`, `@ManyToOne`, etc.)
+   - Add `@VersionColumn()` if optimistic locking is needed
+
+8. **Update DTOs** — if new columns are exposed via API:
+   - Add fields to `create-*.dto.ts` and/or `update-*.dto.ts`
+   - Add `class-validator` decorators for all new fields
+   - Never use `any` type
+
+// turbo 9. **Run type check** — verify no TypeScript errors:
+
+```bash
+cd backend && npx tsc --noEmit
+```
+
+10. **Generate SQL diff** — create a summary of changes for the user to apply manually:
+
+```
+-- Schema Change Summary
+-- Date: <current date>
+-- Feature: <feature name>
+-- Tables affected: <list>
+--
+-- ⚠️ Apply this SQL to the live database manually:
+
+ALTER TABLE ...;
+-- or
+CREATE TABLE ...;
+```
+
+11. **Notify user** — present the SQL diff and remind them:
+    - Apply the SQL change to the live database manually
+    - Verify the change doesn't break existing data
+    - Run `pnpm test` after applying to confirm entity mappings work
+
+## Common Patterns
+
+| Change Type | Template                                                       |
+| ----------- | -------------------------------------------------------------- |
+| Add column  | `ALTER TABLE \`table\` ADD COLUMN \`col\` TYPE DEFAULT value;` |
+| Add table   | Full `CREATE TABLE` with constraints and indexes               |
+| Add index   | `CREATE INDEX \`idx_table_col\` ON \`table\` (\`col\`);`       |
+| Add FK      | `ALTER TABLE \`child\` ADD CONSTRAINT ... FOREIGN KEY ...`     |
+| Add enum    | Add to data dictionary + `ENUM('val1','val2')` in column def   |
+
+## On Error
+
+- If schema SQL has syntax errors → fix and re-validate with `tsc --noEmit`
+- If entity mapping doesn't match schema → compare column-by-column against SQL
+- If seed data conflicts → check unique constraints and foreign keys

.agent/rules/workflows/speckit.prepare.md

@@ -0,0 +1,27 @@
+---
+description: Execute the full preparation pipeline (Specify -> Clarify -> Plan -> Tasks -> Analyze) in sequence.
+---
+
+# Workflow: speckit.prepare
+
+This workflow orchestrates the sequential execution of the Speckit preparation phase skills (02-06).
+
+1. **Step 1: Specify (Skill 02)**
+   - Goal: Create or update the `spec.md` based on user input.
+   - Action: Read and execute `.agents/skills/speckit.specify/SKILL.md`.
+
+2. **Step 2: Clarify (Skill 03)**
+   - Goal: Refine the `spec.md` by identifying and resolving ambiguities.
+   - Action: Read and execute `.agents/skills/speckit.clarify/SKILL.md`.
+
+3. **Step 3: Plan (Skill 04)**
+   - Goal: Generate `plan.md` from the finalized spec.
+   - Action: Read and execute `.agents/skills/speckit.plan/SKILL.md`.
+
+4. **Step 4: Tasks (Skill 05)**
+   - Goal: Generate actionable `tasks.md` from the plan.
+   - Action: Read and execute `.agents/skills/speckit.tasks/SKILL.md`.
+
+5. **Step 5: Analyze (Skill 06)**
+   - Goal: Validate consistency across all design artifacts (spec, plan, tasks).
+   - Action: Read and execute `.agents/skills/speckit.analyze/SKILL.md`.

.agent/rules/workflows/util-speckit.checklist.md

@@ -0,0 +1,18 @@
+---
+description: Generate a custom checklist for the current feature based on user requirements.
+---
+
+# Workflow: speckit.checklist
+
+1. **Context Analysis**:
+   - The user has provided an input prompt. Treat this as the primary input for the skill.
+
+2. **Load Skill**:
+   - Use the `view_file` tool to read the skill file at: `.agents/skills/speckit.checklist/SKILL.md`
+
+3. **Execute**:
+   - Follow the instructions in the `SKILL.md` exactly.
+   - Apply the user's prompt as the input arguments/context for the skill's logic.
+
+4. **On Error**:
+   - If `spec.md` is missing: Run `/speckit.specify` first to create the feature specification

.agent/rules/workflows/util-speckit.diff.md

@@ -0,0 +1,19 @@
+---
+description: Compare two versions of a spec or plan to highlight changes.
+---
+
+# Workflow: speckit.diff
+
+1. **Context Analysis**:
+   - The user has provided an input prompt (optional file paths or version references).
+
+2. **Load Skill**:
+   - Use the `view_file` tool to read the skill file at: `.agents/skills/speckit.diff/SKILL.md`
+
+3. **Execute**:
+   - Follow the instructions in the `SKILL.md` exactly.
+   - Apply the user's prompt as the input arguments/context for the skill's logic.
+
+4. **On Error**:
+   - If no files to compare: Use current feature's `spec.md` vs git HEAD
+   - If `spec.md` doesn't exist: Run `/speckit.specify` first

.agent/rules/workflows/util-speckit.migrate.md

@@ -0,0 +1,19 @@
+---
+description: Migrate existing projects into the speckit structure by generating spec.md, plan.md, and tasks.md from existing code.
+---
+
+# Workflow: speckit.migrate
+
+1. **Context Analysis**:
+   - The user has provided an input prompt (path to analyze, feature name).
+
+2. **Load Skill**:
+   - Use the `view_file` tool to read the skill file at: `.agents/skills/speckit.migrate/SKILL.md`
+
+3. **Execute**:
+   - Follow the instructions in the `SKILL.md` exactly.
+   - Apply the user's prompt as the input arguments/context for the skill's logic.
+
+4. **On Error**:
+   - If path doesn't exist: Ask user to provide valid directory path
+   - If no code found: Report that no analyzable code was detected

.agent/rules/workflows/util-speckit.quizme.md

@@ -0,0 +1,20 @@
+---
+description: Challenge the specification with Socratic questioning to identify logical gaps, unhandled edge cases, and robustness issues.
+---
+
+// turbo-all
+
+# Workflow: speckit.quizme
+
+1. **Context Analysis**:
+   - The user has provided an input prompt. Treat this as the primary input for the skill.
+
+2. **Load Skill**:
+   - Use the `view_file` tool to read the skill file at: `.agents/skills/speckit.quizme/SKILL.md`
+
+3. **Execute**:
+   - Follow the instructions in the `SKILL.md` exactly.
+   - Apply the user's prompt as the input arguments/context for the skill's logic.
+
+4. **On Error**:
+   - If required files don't exist, inform the user which prerequisite workflow to run first (e.g., `/speckit.specify` to create `spec.md`).

.agent/rules/workflows/util-speckit.status.md

@@ -0,0 +1,20 @@
+---
+description: Display a dashboard showing feature status, completion percentage, and blockers.
+---
+
+// turbo-all
+
+# Workflow: speckit.status
+
+1. **Context Analysis**:
+   - The user may optionally specify a feature to focus on.
+
+2. **Load Skill**:
+   - Use the `view_file` tool to read the skill file at: `.agents/skills/speckit.status/SKILL.md`
+
+3. **Execute**:
+   - Follow the instructions in the `SKILL.md` exactly.
+   - Apply the user's prompt as the input arguments/context for the skill's logic.
+
+4. **On Error**:
+   - If no features exist: Report "No features found. Run `/speckit.specify` to create your first feature."

.agent/rules/workflows/util-speckit.taskstoissues.md

@@ -0,0 +1,18 @@
+---
+description: Convert existing tasks into actionable, dependency-ordered GitHub issues for the feature based on available design artifacts.
+---
+
+# Workflow: speckit.taskstoissues
+
+1. **Context Analysis**:
+   - The user has provided an input prompt. Treat this as the primary input for the skill.
+
+2. **Load Skill**:
+   - Use the `view_file` tool to read the skill file at: `.agents/skills/speckit.taskstoissues/SKILL.md`
+
+3. **Execute**:
+   - Follow the instructions in the `SKILL.md` exactly.
+   - Apply the user's prompt as the input arguments/context for the skill's logic.
+
+4. **On Error**:
+   - If `tasks.md` is missing: Run `/speckit.tasks` first

.windsurf/rules/00-project-context.md

@@ -1,5 +1,5 @@
 ---
-always_on: true
+trigger: always_on
 ---
 
 # NAP-DMS Project Context
@@ -25,7 +25,7 @@ Every response must be **precise**, **spec-compliant**, and **production-ready**
 
 - **Project:** NAP-DMS (LCBP3)
 - **Version:** 1.8.5
-- **Stack:** NestJS + Next.js + TypeScript + MariaDB
+- **Stack:** NestJS + Next.js + TypeScript + MariaDB + Ollama (AI)
 - **Repo:** https://git.np-dms.work/np-dms/lcbp3
 
 ## Rule Enforcement Tiers
@@ -39,6 +39,7 @@ Build fails immediately if violated:
 - Database correctness — verify schema before writing queries
 - File upload security (ClamAV + whitelist)
 - AI validation boundary (ADR-018)
+- Error handling strategy (ADR-007)
 - Forbidden patterns: `any`, `console.log`, UUID misuse
 
 ### 🟡 Tier 2 — IMPORTANT (CODE REVIEW)

.windsurf/rules/01-adr-019-uuid.md

@@ -1,5 +1,5 @@
 ---
-always_on: true
+trigger: always_on
 ---
 
 # ADR-019 UUID Strategy
@@ -7,7 +7,7 @@ always_on: true
 ## CRITICAL RULES
 
 - **NEVER** use `parseInt()` on UUID values
-- **NEVER** use `Number()` on UUID values  
+- **NEVER** use `Number()` on UUID values
 - **NEVER** use `+` operator on UUID values
 - **ALWAYS** use `publicId` (string UUID) for API responses
 - **NEVER** expose internal INT `id` in API responses (use `@Exclude()`)
@@ -29,7 +29,7 @@ always_on: true
 class Project extends UuidBaseEntity {
   @Column({ type: 'uuid' })
   publicId: string;  // UUID string, no transformation needed
-  
+
   @PrimaryKey()
   @Exclude()
   id: number;  // Internal INT, never exposed

.windsurf/rules/02-security.md

@@ -1,5 +1,5 @@
 ---
-always_on: true
+trigger: always_on
 ---
 
 # Security Rules (Non-Negotiable)
@@ -14,6 +14,10 @@ always_on: true
 6. **Rate Limiting:** `ThrottlerGuard` on all auth endpoints
 7. **File Upload:** Whitelist PDF/DWG/DOCX/XLSX/ZIP, max 50MB, ClamAV scan
 8. **AI Isolation (ADR-018):** Ollama on Admin Desktop ONLY — NO direct DB/storage access
+9. **Error Handling (ADR-007):** Use layered error classification with user-friendly messages
+10. **AI Integration (ADR-020):** RFA-First approach with unified pipeline architecture
+11. **AI Audit Trail:** Log all AI interactions and human validations
+12. **Rate Limiting:** Apply to AI endpoints to prevent abuse
 
 ## Full Documentation
 
@@ -26,4 +30,7 @@ always_on: true
 - [ ] No SQL injection vulnerabilities
 - [ ] File upload validation (whitelist + ClamAV)
 - [ ] Rate limiting applied to auth endpoints
+- [ ] AI boundary enforcement (ADR-018) - no direct DB/storage access
+- [ ] AI audit logging implemented for AI interactions
+- [ ] Error handling follows ADR-007 layered classification
 - [ ] OWASP Top 10 review passed

.windsurf/rules/03-typescript.md

@@ -1,5 +1,5 @@
 ---
-always_on: true
+trigger: always_on
 ---
 
 # TypeScript Rules

.windsurf/rules/04-domain-terminology.md

@@ -1,5 +1,5 @@
 ---
-always_on: true
+trigger: always_on
 ---
 
 # Domain Terminology

.windsurf/rules/05-forbidden-actions.md

@@ -1,26 +1,28 @@
 ---
-always_on: true
+trigger: always_on
 ---
 
 # Forbidden Actions
 
 ## ❌ Never Do This
 
-| ❌ Forbidden                                    | ✅ Correct Approach                           |
-| ----------------------------------------------- | --------------------------------------------- |
-| SQL Triggers for business logic                 | NestJS Service methods                        |
-| `.env` files in production                      | `docker-compose.yml` environment section      |
-| TypeORM migration files                         | Edit schema SQL directly (ADR-009)            |
-| Inventing table/column names                    | Verify against `schema-02-tables.sql`         |
-| `any` TypeScript type                           | Proper types / generics                       |
-| `console.log` in committed code                 | NestJS Logger (backend) / remove (frontend)   |
-| `req: any` in controllers                       | `RequestWithUser` typed interface             |
-| `parseInt()` on UUID values                     | Use UUID string directly (ADR-019)            |
-| Exposing INT PK in API responses                | UUIDv7 (ADR-019)                              |
-| AI accessing DB/storage directly                | AI → DMS API → DB (ADR-018)                   |
-| Direct file operations bypassing StorageService | `StorageService` for all file moves           |
-| Inline email/notification sending               | BullMQ queue job                              |
-| Deploying without Release Gates                 | Complete `04-08-release-management-policy.md` |
+| ❌ Forbidden                                    | ✅ Correct Approach                             |
+| ----------------------------------------------- | ----------------------------------------------- |
+| SQL Triggers for business logic                 | NestJS Service methods                          |
+| `.env` files in production                      | `docker-compose.yml` environment section        |
+| TypeORM migration files                         | Edit schema SQL directly (ADR-009)              |
+| Inventing table/column names                    | Verify against `schema-02-tables.sql`           |
+| `any` TypeScript type                           | Proper types / generics                         |
+| `console.log` in committed code                 | NestJS Logger (backend) / remove (frontend)     |
+| `req: any` in controllers                       | `RequestWithUser` typed interface               |
+| `parseInt()` on UUID values                     | Use UUID string directly (ADR-019)              |
+| Exposing INT PK in API responses                | UUIDv7 (ADR-019)                                |
+| AI accessing DB/storage directly                | AI → DMS API → DB (ADR-018)                     |
+| Direct file operations bypassing StorageService | `StorageService` for all file moves             |
+| Inline email/notification sending               | BullMQ queue job                                |
+| Deploying without Release Gates                 | Complete `04-08-release-management-policy.md`   |
+| AI direct cloud API calls                       | On-premises Ollama only (ADR-018)               |
+| AI outputs without human validation             | Human-in-the-loop validation required (ADR-020) |
 
 ## Schema Changes (ADR-009)
 
@@ -33,6 +35,7 @@ always_on: true
 See `01-adr-019-uuid.md` for complete UUID rules.
 
 Quick reminder:
+
 - ❌ `parseInt(uuid)` → NEVER
 - ❌ `Number(uuid)` → NEVER
 - ✅ Use UUID string directly

.windsurf/rules/08-development-flow.md

@@ -1,5 +1,5 @@
 ---
-always_on: true
+trigger: always_on
 ---
 
 # Development Flow

.windsurf/rules/09-commit-checklist.md

@@ -1,5 +1,5 @@
 ---
-always_on: true
+trigger: always_on
 ---
 
 # Commit Checklist

.windsurf/rules/10-error-handling.md

@@ -0,0 +1,78 @@
+---
+trigger: always_on
+---
+
+# ADR-007 Error Handling Strategy
+
+## CRITICAL RULES
+
+- **ALWAYS** use layered error classification (Validation, Business, System)
+- **NEVER** expose technical details to end users
+- **ALWAYS** provide user-friendly error messages with recovery guidance
+- **ALWAYS** log technical details for debugging
+- **NEVER** use generic error messages without context
+
+## Error Classification
+
+| Error Type | Description | User Message | Technical Log |
+|------------|-------------|--------------|---------------|
+| **Validation** | Input validation failures | Clear field-level errors | Full validation details |
+| **Business** | Business rule violations | Actionable guidance | Business context + user ID |
+| **System** | Infrastructure failures | Generic "try again" | Full stack trace + metrics |
+
+## Backend Pattern (NestJS)
+
+```typescript
+// Custom Exception Hierarchy
+export class BusinessException extends HttpException {
+  constructor(
+    message: string,
+    userMessage: string,
+    recoveryAction?: string,
+    errorCode?: string
+  ) {
+    super({ message, userMessage, recoveryAction, errorCode }, 400);
+  }
+}
+
+// Global Exception Filter
+@Catch()
+export class GlobalExceptionFilter implements ExceptionFilter {
+  catch(exception: unknown, host: ArgumentsHost) {
+    // Classify error and provide appropriate response
+    // Log technical details
+    // Return user-friendly message
+  }
+}
+```
+
+## Frontend Pattern (Next.js)
+
+```typescript
+// Error Display Component
+const ErrorDisplay = ({ error, onRetry }) => {
+  const userMessage = error.userMessage || 'เกิดข้อผิดพลาด';
+  const recoveryAction = error.recoveryAction;
+
+  return (
+    <div>
+      <p>{userMessage}</p>
+      {recoveryAction && <p>{recoveryAction}</p>}
+      {onRetry && <button onClick={onRetry}>ลองใหม่</button>}
+    </div>
+  );
+};
+```
+
+## Required Implementation
+
+- [ ] Global Exception Filter with layered classification
+- [ ] Custom exception hierarchy (Validation, Business, System)
+- [ ] Standardized error response DTOs
+- [ ] Frontend error display components
+- [ ] Error recovery mechanisms where applicable
+
+## Related Documents
+
+- `specs/06-Decision-Records/ADR-007-error-handling-strategy.md`
+- `specs/06-Decision-Records/ADR-010-logging-monitoring-strategy.md`

.windsurf/rules/11-ai-integration.md

@@ -0,0 +1,100 @@
+---
+trigger: always_on
+---
+
+# ADR-020 AI Integration Architecture
+
+## CRITICAL RULES
+
+- **ALWAYS** follow ADR-018 AI boundary policy (isolation on Admin Desktop)
+- **ALWAYS** use RFA-First approach for AI implementation
+- **NEVER** allow AI direct database/storage access
+- **ALWAYS** implement human-in-the-loop validation
+- **NEVER** send sensitive data to cloud AI services
+
+## AI Integration Patterns
+
+### Architecture Overview
+
+```
+Frontend → AI Gateway API → Admin Desktop (Ollama) → Backend Validation
+```
+
+### Key Components
+
+| Component | Location | Purpose |
+|-----------|----------|---------|
+| **AI Gateway** | Backend (NestJS) | API endpoints, validation, audit logging |
+| **Ollama Engine** | Admin Desktop (Desk-5439) | LLM inference (Gemma 4) |
+| **OCR Engine** | Admin Desktop (Desk-5439) | Thai/English text extraction |
+| **Orchestrator** | QNAP NAS (n8n) | Workflow management |
+
+## Backend Implementation (NestJS)
+
+```typescript
+// AI Module with boundary enforcement
+@Module({
+  controllers: [AiController],
+  providers: [AiService, AiGateway],
+  exports: [AiService],
+})
+export class AiModule {
+  constructor() {
+    // Enforce ADR-018 boundaries
+  }
+}
+
+// AI Service with validation
+@Injectable()
+export class AiService {
+  async extractMetadata(documentId: string): Promise<AIMetadata> {
+    // 1. Validate permissions
+    // 2. Send to Admin Desktop AI
+    // 3. Validate AI response
+    // 4. Log audit trail
+    // 5. Return validated results
+  }
+}
+```
+
+## Frontend Pattern (Next.js)
+
+```typescript
+// Document Review Form (reusable component)
+const DocumentReviewForm = ({ document, aiSuggestions }) => {
+  return (
+    <form>
+      <Field label="Document Type" suggestions={aiSuggestions.documentType} />
+      <Field label="Project Code" suggestions={aiSuggestions.projectCode} />
+      <Field label="Discipline" suggestions={aiSuggestions.discipline} />
+
+      <ConfidenceScore score={aiSuggestions.confidence} />
+      <HumanValidationActions />
+    </form>
+  );
+};
+```
+
+## Security Requirements
+
+- **AI Isolation:** All AI processing on Admin Desktop only
+- **Data Privacy:** No cloud AI services, on-premises only
+- **Audit Trail:** Log all AI interactions and human validations
+- **Rate Limiting:** Prevent AI abuse and resource exhaustion
+- **Validation:** All AI outputs must be validated before use
+
+## Required Implementation
+
+- [ ] AiModule with ADR-018 boundary enforcement
+- [ ] AI Gateway API endpoints with validation
+- [ ] DocumentReviewForm reusable component
+- [ ] Admin Desktop Ollama + PaddleOCR setup
+- [ ] n8n workflow orchestration
+- [ ] AI audit logging and monitoring
+- [ ] Human-in-the-loop validation workflows
+
+## Related Documents
+
+- `specs/06-Decision-Records/ADR-018-ai-boundary.md`
+- `specs/06-Decision-Records/ADR-020-ai-intelligence-integration.md`
+- `specs/06-Decision-Records/ADR-017-ollama-data-migration.md`

.windsurfrules

@@ -1,6 +1,6 @@
 # NAP-DMS Project Context & Rules
  - For: Windsurf Cascade (and compatible: Codex CLI, opencode, Amp, Amazon Q, AGENTS.md tools)
-- Version: 1.8.5 (Refactored) | Last synced from repo: 2026-03-27
+- Version: 1.8.5 (Refactored) | Last synced from repo: 2026-04-04
 - Repo: [https://git.np-dms.work/np-dms/lcbp3](https://git.np-dms.work/np-dms/lcbp3)
 
 ---
@@ -35,6 +35,7 @@ Build fails immediately if violated:
 - Database correctness — verify schema before writing queries
 - File upload security (ClamAV + whitelist)
 - AI validation boundary (ADR-018)
+- Error handling strategy (ADR-007)
 - Forbidden patterns: `any`, `console.log`, UUID misuse
 
 ### 🟡 Tier 2 — IMPORTANT (CODE REVIEW)
@@ -66,7 +67,10 @@ Spec priority: **`06-Decision-Records`** > **`05-Engineering-Guidelines`** > oth
 | **Schema Tables**       | `specs/03-Data-and-Storage/lcbp3-v1.8.0-schema-02-tables.sql`     | Before writing any query        |
 | **Data Dictionary**     | `specs/03-Data-and-Storage/03-01-data-dictionary.md`              | Field meanings + business rules |
 | **Edge Cases**          | `specs/01-Requirements/01-06-edge-cases-and-rules.md`             | Prevent bugs in flows           |
+| **ADR-007 Error Handling** | `specs/06-Decision-Records/ADR-007-error-handling-strategy.md` | Error patterns & recovery |
+| **ADR-018 AI Boundary**  | `specs/06-Decision-Records/ADR-018-ai-boundary.md` | AI isolation rules |
 | **ADR-019 UUID**        | `specs/06-Decision-Records/ADR-019-hybrid-identifier-strategy.md` | UUID-related work               |
+| **ADR-020 AI Integration** | `specs/06-Decision-Records/ADR-020-ai-intelligence-integration.md` | AI architecture patterns |
 | **Backend Guidelines**  | `specs/05-Engineering-Guidelines/05-02-backend-guidelines.md`     | NestJS patterns                 |
 | **Frontend Guidelines** | `specs/05-Engineering-Guidelines/05-03-frontend-guidelines.md`    | Next.js patterns                |
 | **Testing Strategy**    | `specs/05-Engineering-Guidelines/05-04-testing-strategy.md`       | Coverage goals                  |
@@ -135,6 +139,8 @@ Read `specs/05-Engineering-Guidelines/05-07-hybrid-uuid-implementation-plan.md`
 6. **Rate Limiting:** `ThrottlerGuard` on all auth endpoints
 7. **File Upload:** Whitelist PDF/DWG/DOCX/XLSX/ZIP, max 50MB, ClamAV scan
 8. **AI Isolation (ADR-018):** Ollama on Admin Desktop ONLY — NO direct DB/storage access
+9. **Error Handling (ADR-007):** Use layered error classification with user-friendly messages
+10. **AI Integration (ADR-020):** RFA-First approach with unified pipeline architecture
 
 Full details: `specs/06-Decision-Records/ADR-016-security-authentication.md`
 
@@ -228,6 +234,8 @@ When user asks about... check these files:
 | "ตรวจสอบ permission" | `seed-permissions.sql`, `ADR-016`                       | CASL 4-Level RBAC matrix                            |
 | "deploy production"  | `04-08-release-management-policy.md`, `ADR-015`         | Release Gates + Blue-Green strategy                 |
 | "เพิ่ม test"         | `05-04-testing-strategy.md`                             | Coverage goals + test patterns                      |
+| "AI integration"   | `ADR-018`, `ADR-020`                                      | AI boundary + unified pipeline                      |
+| "Error handling"    | `ADR-007`                                                  | Layered error classification + recovery             |
 
 ---
 
@@ -240,7 +248,7 @@ When user asks about... check these files:
 - [ ] Code identifiers in English
 - [ ] Schema changes via SQL directly (not migration)
 - [ ] Test coverage meets targets (Backend 70%+, Business Logic 80%+)
-- [ ] Relevant ADRs checked (ADR-009, ADR-018, ADR-019)
+- [ ] Relevant ADRs checked (ADR-007, ADR-009, ADR-018, ADR-019, ADR-020)
 - [ ] Glossary terms used correctly
 - [ ] Error handling complete (Logger + HttpException)
 - [ ] i18n keys used instead of hardcode text
@@ -266,7 +274,7 @@ This file is a **quick reference**. For detailed information:
 
 | Version | Date       | Changes                                                             | Updated By     |
 | ------- | ---------- | ------------------------------------------------------------------- | -------------- |
-| 1.8.5   | 2026-03-27 | Refactored — moved detailed content to specs/, now quick reference  | Windsurf AI    |
+| 1.8.5   | 2026-04-04 | Added ADR-007 error handling, ADR-020 AI integration, updated security rules | Windsurf AI    |
 | 1.8.4   | 2026-03-24 | Phase 5.4→✅ DONE, Tailwind 3.4.3, ADR count(16), MariaDB UUID note | Windsurf AI    |
 | 1.8.3   | 2026-03-21 | + Rule Enforcement Tiers (🔴🟡🟢), + Tiered Development Flow        | Human Dev + AI |
 | 1.8.2   | 2026-03-21 | + Context Triggers, + Code Snippets, + Error Handling, + i18n       | Human Dev + AI |

AGENTS.md

@@ -1,7 +1,7 @@
 # NAP-DMS Project Context & Rules
 
 - For: Windsurf Cascade (and compatible: Codex CLI, opencode, Amp, Antigravity, AGENTS.md tools)
-- Version: 1.8.5 (Refactored) | Last synced from repo: 2026-03-27
+- Version: 1.8.5 (Refactored) | Last synced from repo: 2026-04-04
 - Repo: [https://git.np-dms.work/np-dms/lcbp3](https://git.np-dms.work/np-dms/lcbp3)
 
 ---
@@ -36,6 +36,7 @@ Build fails immediately if violated:
 - Database correctness — verify schema before writing queries
 - File upload security (ClamAV + whitelist)
 - AI validation boundary (ADR-018)
+- Error handling strategy (ADR-007)
 - Forbidden patterns: `any`, `console.log`, UUID misuse
 
 ### 🟡 Tier 2 — IMPORTANT (CODE REVIEW)
@@ -61,21 +62,24 @@ Best practice — follow when possible:
 
 Spec priority: **`06-Decision-Records`** > **`05-Engineering-Guidelines`** > others
 
-| Document                | Path                                                              | Use When                        |
-| ----------------------- | ----------------------------------------------------------------- | ------------------------------- |
-| **Glossary**            | `specs/00-overview/00-02-glossary.md`                             | Verify domain terminology       |
-| **Schema Tables**       | `specs/03-Data-and-Storage/lcbp3-v1.8.0-schema-02-tables.sql`     | Before writing any query        |
-| **Data Dictionary**     | `specs/03-Data-and-Storage/03-01-data-dictionary.md`              | Field meanings + business rules |
-| **Edge Cases**          | `specs/01-Requirements/01-06-edge-cases-and-rules.md`             | Prevent bugs in flows           |
-| **ADR-019 UUID**        | `specs/06-Decision-Records/ADR-019-hybrid-identifier-strategy.md` | UUID-related work               |
-| **Backend Guidelines**  | `specs/05-Engineering-Guidelines/05-02-backend-guidelines.md`     | NestJS patterns                 |
-| **Frontend Guidelines** | `specs/05-Engineering-Guidelines/05-03-frontend-guidelines.md`    | Next.js patterns                |
-| **Testing Strategy**    | `specs/05-Engineering-Guidelines/05-04-testing-strategy.md`       | Coverage goals                  |
-| **Git Conventions**     | `specs/05-Engineering-Guidelines/05-05-git-conventions.md`        | Commit/branch naming            |
-| **Code Snippets**       | `specs/05-Engineering-Guidelines/05-06-code-snippets.md`          | Reusable patterns               |
-| **i18n Guidelines**     | `specs/05-Engineering-Guidelines/05-08-i18n-guidelines.md`        | Localization rules              |
-| **Release Policy**      | `specs/04-Infrastructure-OPS/04-08-release-management-policy.md`  | Before deploy/hotfix            |
-| **UAT Criteria**        | `specs/01-Requirements/01-05-acceptance-criteria.md`              | Feature completeness            |
+| Document                   | Path                                                               | Use When                        |
+| -------------------------- | ------------------------------------------------------------------ | ------------------------------- |
+| **Glossary**               | `specs/00-overview/00-02-glossary.md`                              | Verify domain terminology       |
+| **Schema Tables**          | `specs/03-Data-and-Storage/lcbp3-v1.8.0-schema-02-tables.sql`      | Before writing any query        |
+| **Data Dictionary**        | `specs/03-Data-and-Storage/03-01-data-dictionary.md`               | Field meanings + business rules |
+| **Edge Cases**             | `specs/01-Requirements/01-06-edge-cases-and-rules.md`              | Prevent bugs in flows           |
+| **ADR-007 Error Handling** | `specs/06-Decision-Records/ADR-007-error-handling-strategy.md`     | Error patterns & recovery       |
+| **ADR-018 AI Boundary**    | `specs/06-Decision-Records/ADR-018-ai-boundary.md`                 | AI isolation rules              |
+| **ADR-019 UUID**           | `specs/06-Decision-Records/ADR-019-hybrid-identifier-strategy.md`  | UUID-related work               |
+| **ADR-020 AI Integration** | `specs/06-Decision-Records/ADR-020-ai-intelligence-integration.md` | AI architecture patterns        |
+| **Backend Guidelines**     | `specs/05-Engineering-Guidelines/05-02-backend-guidelines.md`      | NestJS patterns                 |
+| **Frontend Guidelines**    | `specs/05-Engineering-Guidelines/05-03-frontend-guidelines.md`     | Next.js patterns                |
+| **Testing Strategy**       | `specs/05-Engineering-Guidelines/05-04-testing-strategy.md`        | Coverage goals                  |
+| **Git Conventions**        | `specs/05-Engineering-Guidelines/05-05-git-conventions.md`         | Commit/branch naming            |
+| **Code Snippets**          | `specs/05-Engineering-Guidelines/05-06-code-snippets.md`           | Reusable patterns               |
+| **i18n Guidelines**        | `specs/05-Engineering-Guidelines/05-08-i18n-guidelines.md`         | Localization rules              |
+| **Release Policy**         | `specs/04-Infrastructure-OPS/04-08-release-management-policy.md`   | Before deploy/hotfix            |
+| **UAT Criteria**           | `specs/01-Requirements/01-05-acceptance-criteria.md`               | Feature completeness            |
 
 ---
 
@@ -136,6 +140,8 @@ Read `specs/05-Engineering-Guidelines/05-07-hybrid-uuid-implementation-plan.md`
 6. **Rate Limiting:** `ThrottlerGuard` on all auth endpoints
 7. **File Upload:** Whitelist PDF/DWG/DOCX/XLSX/ZIP, max 50MB, ClamAV scan
 8. **AI Isolation (ADR-018):** Ollama on Admin Desktop ONLY — NO direct DB/storage access
+9. **Error Handling (ADR-007):** Use layered error classification with user-friendly messages
+10. **AI Integration (ADR-020):** RFA-First approach with unified pipeline architecture
 
 Full details: `specs/06-Decision-Records/ADR-016-security-authentication.md`
 
@@ -229,6 +235,8 @@ When user asks about... check these files:
 | "ตรวจสอบ permission" | `seed-permissions.sql`, `ADR-016`                       | CASL 4-Level RBAC matrix                            |
 | "deploy production"  | `04-08-release-management-policy.md`, `ADR-015`         | Release Gates + Blue-Green strategy                 |
 | "เพิ่ม test"         | `05-04-testing-strategy.md`                             | Coverage goals + test patterns                      |
+| "AI integration"     | `ADR-018`, `ADR-020`                                    | AI boundary + unified pipeline                      |
+| "Error handling"     | `ADR-007`                                               | Layered error classification + recovery             |
 
 ---
 
@@ -241,7 +249,7 @@ When user asks about... check these files:
 - [ ] Code identifiers in English
 - [ ] Schema changes via SQL directly (not migration)
 - [ ] Test coverage meets targets (Backend 70%+, Business Logic 80%+)
-- [ ] Relevant ADRs checked (ADR-009, ADR-018, ADR-019)
+- [ ] Relevant ADRs checked (ADR-007, ADR-009, ADR-018, ADR-019, ADR-020)
 - [ ] Glossary terms used correctly
 - [ ] Error handling complete (Logger + HttpException)
 - [ ] i18n keys used instead of hardcode text
@@ -265,15 +273,15 @@ This file is a **quick reference**. For detailed information:
 
 ## 🔄 Change Log
 
-| Version | Date       | Changes                                                             | Updated By     |
-| ------- | ---------- | ------------------------------------------------------------------- | -------------- |
-| 1.8.5   | 2026-03-27 | Refactored — moved detailed content to specs/, now quick reference  | Windsurf AI    |
-| 1.8.4   | 2026-03-24 | Phase 5.4→✅ DONE, Tailwind 3.4.3, ADR count(16), MariaDB UUID note | Windsurf AI    |
-| 1.8.3   | 2026-03-21 | + Rule Enforcement Tiers (🔴🟡🟢), + Tiered Development Flow        | Human Dev + AI |
-| 1.8.2   | 2026-03-21 | + Context Triggers, + Code Snippets, + Error Handling, + i18n       | Human Dev + AI |
-| 1.8.1   | 2026-03-21 | + ADR-019 UUID patterns, + Phase 5.4 pending files                  | Claude Sonnet  |
-| 1.8.0   | 2026-03-19 | + Security overrides, + UAT criteria reference                      | Human Dev      |
-| 1.7.2   | 2026-03-15 | + AI Boundary rules (ADR-018)                                       | Gemini Pro     |
+| Version | Date       | Changes                                                                      | Updated By     |
+| ------- | ---------- | ---------------------------------------------------------------------------- | -------------- |
+| 1.8.5   | 2026-04-04 | Added ADR-007 error handling, ADR-020 AI integration, updated security rules | Windsurf AI    |
+| 1.8.4   | 2026-03-24 | Phase 5.4→✅ DONE, Tailwind 3.4.3, ADR count(16), MariaDB UUID note          | Windsurf AI    |
+| 1.8.3   | 2026-03-21 | + Rule Enforcement Tiers (🔴🟡🟢), + Tiered Development Flow                 | Human Dev + AI |
+| 1.8.2   | 2026-03-21 | + Context Triggers, + Code Snippets, + Error Handling, + i18n                | Human Dev + AI |
+| 1.8.1   | 2026-03-21 | + ADR-019 UUID patterns, + Phase 5.4 pending files                           | Claude Sonnet  |
+| 1.8.0   | 2026-03-19 | + Security overrides, + UAT criteria reference                               | Human Dev      |
+| 1.7.2   | 2026-03-15 | + AI Boundary rules (ADR-018)                                                | Gemini Pro     |
 
 ---
 

frontend/components/admin/user-dialog.tsx

@@ -107,7 +107,7 @@ export function UserDialog({ open, onOpenChange, user }: UserDialogProps) {
         lastName: user.lastName,
         isActive: user.isActive,
         lineId: user.lineId || '',
-        primaryOrganizationId: user.primaryOrganizationId?.toString() || ALL_ORGANIZATIONS_VALUE,
+        primaryOrganizationId: user.primaryOrganizationId || ALL_ORGANIZATIONS_VALUE,
         roleIds: user.roles?.map((r: { roleId?: number }) => r.roleId).filter((id): id is number => id !== undefined) || [],
         password: '',
         confirmPassword: '',

frontend/components/correspondences/form.tsx

@@ -77,15 +77,14 @@ interface DisciplineOption {
 }
 
 interface InitialCorrespondenceData {
-  projectId?: number | string;
+  projectId?: string;
   project?: { publicId?: string };
   contract?: { publicId?: string };
   correspondenceTypeId?: number;
-  type?: { id?: number; publicId?: string };
+  type?: { id?: number };
   disciplineId?: number;
   discipline?: {
     id?: number;
-    publicId?: string;
     contract?: { publicId?: string };
   };
   revisions?: Array<{
@@ -102,11 +101,11 @@ interface InitialCorrespondenceData {
     receivedDate?: string;
     details?: { importance: 'NORMAL' | 'HIGH' | 'URGENT' };
   }>;
-  originatorId?: number;
+  originatorId?: string;
   originator?: { publicId?: string };
   recipients?: Array<{
     recipientType: string;
-    recipientOrganizationId: number;
+    recipientOrganizationId?: string;
     recipientOrganization?: { publicId?: string };
   }>;
   correspondenceNumber?: string;

frontend/components/rfas/form.tsx

@@ -70,6 +70,7 @@ type RfaTypeOption = {
 };
 
 type CorrespondenceTypeOption = {
+  id: number; // Master data INT ID
   publicId: string; // ADR-019: public identifier
   typeCode?: string;
   typeName?: string;
@@ -272,8 +273,8 @@ export function RFAForm() {
       try {
         const res = await correspondenceService.previewNumber({
           projectId: selectedProjectId,
-          typeId: rfaCorrespondenceType.publicId,
-          disciplineId,
+          typeId: rfaCorrespondenceType.id,
+          disciplineId: Number(disciplineId || 0),
           recipients: [{ organizationId: toOrganizationId, type: 'TO' }],
           subject: watch('subject') || 'Preview Subject',
         });

frontend/types/dto/correspondence/create-correspondence.dto.ts

@@ -1,17 +1,17 @@
 // File: src/types/dto/correspondence/create-correspondence.dto.ts
 
 export interface CreateCorrespondenceDto {
-  /** ID or UUID ของโครงการ */
-  projectId: number | string;
+  /** UUID ของโครงการ (ADR-019) */
+  projectId: string;
 
-  /** ID ของประเภทเอกสาร (เช่น RFA, LETTER) - ADR-019: Accept UUID */
-  typeId: number | string;
+  /** ID ของประเภทเอกสาร (เช่น RFA, LETTER) - Master data ใช้ INT */
+  typeId: number;
 
-  /** [Req 6B] สาขางาน (เช่น GEN, STR) - ADR-019: Accept UUID */
-  disciplineId?: number | string;
+  /** [Req 6B] สาขางาน (เช่น GEN, STR) - Master data ใช้ INT */
+  disciplineId?: number;
 
-  /** [Req 6B] ประเภทย่อย (เช่น MAT, SHP สำหรับ Transmittal/RFA) - ADR-019: Accept UUID */
-  subTypeId?: number | string;
+  /** [Req 6B] ประเภทย่อย (เช่น MAT, SHP สำหรับ Transmittal/RFA) - Master data ใช้ INT */
+  subTypeId?: number;
 
   /** หัวข้อเอกสาร */
   subject: string;
@@ -44,13 +44,13 @@ export interface CreateCorrespondenceDto {
   isInternal?: boolean;
 
   /** * ✅ Field สำหรับ Impersonation (เลือกองค์กรผู้ส่ง)
-   * ใช้กรณี Admin สร้างเอกสารแทนผู้อื่น
+   * ใช้กรณี Admin สร้างเอกสารแทนผู้อื่น (ADR-019: UUID)
    */
-  originatorId?: number | string;
+  originatorId?: string;
 
   /** Temp IDs from two-phase file upload (POST /files/upload → tempId) */
   attachmentTempIds?: string[];
 
-  /** รายชื่อผู้รับ */
-  recipients?: { organizationId: number | string; type: 'TO' | 'CC' }[];
+  /** รายชื่อผู้รับ (ADR-019: organizationId เป็น UUID) */
+  recipients?: { organizationId: string; type: 'TO' | 'CC' }[];
 }

frontend/types/user.ts

@@ -21,7 +21,7 @@ export interface User {
   lastName: string;
   isActive: boolean;
   lineId?: string;
-  primaryOrganizationId?: number | string; // ADR-019: May be INT or UUID
+  primaryOrganizationId?: string; // ADR-019: UUID string only
   organization?: UserOrganization;
   roles?: Role[];
 
@@ -43,7 +43,7 @@ export interface CreateUserDto {
   password?: string;
   isActive: boolean;
   lineId?: string;
-  primaryOrganizationId?: number | string; // ADR-019: Accept UUID
+  primaryOrganizationId?: string; // ADR-019: UUID string only
   roleIds: number[];
 }
 
@@ -54,5 +54,5 @@ export interface SearchUserDto {
   limit?: number;
   search?: string;
   roleId?: number;
-  primaryOrganizationId?: number | string; // ADR-019: Accept UUID
+  primaryOrganizationId?: string; // ADR-019: UUID string only
 }

specs/06-Decision-Records/ADR-001-unified-workflow-engine.md

@@ -10,6 +10,20 @@
 
 ---
 
+## 🎯 Gap Analysis & Purpose
+
+### ปิด Gap จากเอกสาร:
+- **Unified Workflow Requirements** - Section 2.1: "LCBP3-DMS ต้องรองรับเอกสารหลายประเภทพร้อม Workflow ที่แตกต่างกัน"
+  - เหตุผล: ระบบเดิมไม่มีกลไกส่วนกลางสำหรับจัดการ Workflow ทำให้เกิด Code Duplication
+- **Software Architecture** - Section 3.2: "ระบบต้องมีความยืดหยุ่นในการเพิ่ม Document Type ใหม่"
+  - เหตุผล: การ Hard-code Workflow ทำให้การเพิ่มประเภทเอกสารใหม่ทำได้ยาก
+
+### แก้ไขความขัดแย้ง:
+- **Correspondence Requirements** vs **RFA Requirements**: ทั้งสอง Module ต้องการ State Management แต่ใช้วิธีต่างกัน
+  - การตัดสินใจนี้ช่วยแก้ไขโดย: สร้าง Unified Engine ที่รองรับทุก Document Type
+
+---
+
 ## Context and Problem Statement
 
 LCBP3-DMS ต้องจัดการเอกสารหลายประเภท (Correspondences, RFAs, Circulations) โดยแต่ละประเภทมี Workflow การเดินเอกสารที่แตกต่างกัน:
@@ -113,6 +127,74 @@ LCBP3-DMS ต้องจัดการเอกสารหลายประ
 
 ---
 
+## 🔍 Impact Analysis
+
+### Affected Components (ส่วนประกอบที่ได้รับผลกระทบ)
+
+| Component | Level | Impact Description | Required Action |
+|-----------|-------|-------------------|-----------------|
+| **Backend** | 🔴 High | ต้องสร้าง Workflow Engine Module ใหม่ และ Refactor ทุก Document Service | Implement WorkflowEngineService |
+| **Database** | 🔴 High | เพิ่ม Tables: workflow_definitions, workflow_instances, workflow_histories | Create new schema |
+| **Frontend** | 🟡 Medium | ต้อง Update UI สำหรับ Workflow Status และ Actions | Update components |
+| **API** | 🔴 High | ต้องสร้าง Workflow API endpoints และ Update ทุก Document API | New endpoints + updates |
+| **Testing** | 🟡 Medium | ต้องเขียน Tests สำหรับ Workflow Engine และ Integration Tests | New test suites |
+
+### Required Changes (การเปลี่ยนแปลงที่ต้องดำเนินการ)
+
+#### 🔴 Critical Changes (ต้องทำทันที)
+- [ ] **Create Workflow Engine Module** - backend/src/modules/workflow-engine/: สร้าง Engine หลัก
+- [ ] **Implement Database Schema** - specs/03-Data-and-Storage/: เพิ่ม workflow tables
+- [ ] **Refactor Correspondence Service** - backend/src/modules/correspondence/: ใช้ Workflow Engine
+- [ ] **Refactor RFA Service** - backend/src/modules/rfa/: ใช้ Workflow Engine
+- [ ] **Refactor Circulation Service** - backend/src/modules/circulation/: ใช้ Workflow Engine
+
+#### 🟡 Important Changes (ควรทำภายใน 2 สัปดาห์)
+- [ ] **Update Frontend Workflow Components** - frontend/components/workflow/: UI สำหรับ Workflow
+- [ ] **Create Workflow API Endpoints** - backend/src/modules/workflow-engine/controller.ts: REST API
+- [ ] **Add Workflow DSL Validation** - backend/src/modules/workflow-engine/dsl-validator.ts: JSON Schema validation
+- [ ] **Implement Workflow History Tracking** - backend/src/modules/workflow-engine/history.service.ts: Audit trail
+
+#### 🟢 Nice-to-Have (ทำถ้ามีเวลา)
+- [ ] **Create Admin UI for Workflow Design** - frontend/app/(admin)/admin/workflow/: Visual workflow builder
+- [ ] **Add Workflow Performance Monitoring** - backend/src/modules/workflow-engine/monitoring.service.ts: Metrics
+
+### Cross-Module Dependencies
+
+```mermaid
+graph TB
+    ADR[ADR-001 Workflow Engine] --> Corr[Correspondence Service]
+    ADR --> RFA[RFA Service]
+    ADR --> Circ[Circulation Service]
+    ADR --> DB[(Database Schema)]
+    ADR --> API[Workflow API]
+
+    Corr --> ADR002[ADR-002 Document Numbering]
+    RFA --> ADR002
+    Circ --> ADR002
+
+    API --> ADR006[ADR-006 Redis Caching]
+    DB --> ADR009[ADR-009 Migration Strategy]
+```
+
+---
+
+## 📋 Version Dependency Matrix
+
+| ADR | Version | Dependency Type | Affected Version(s) | Implementation Status |
+|-----|---------|-----------------|---------------------|----------------------|
+| **ADR-001** | 1.0 | Core | v1.8.0+ | ✅ Implemented |
+| **ADR-002** | 1.0 | Required By | v1.8.0+ | ✅ Implemented |
+| **ADR-006** | 1.0 | Uses | v1.8.0+ | ✅ Implemented |
+| **ADR-009** | 1.0 | Database Changes | v1.8.0+ | ✅ Implemented |
+
+### Version Compatibility Rules
+
+- **Minimum Version:** v1.8.0 (ADR มีผลบังคับใช้)
+- **Breaking Changes:** ไม่มี (Backward compatible API)
+- **Deprecation Timeline:** ไม่มี (Core architecture)
+
+---
+
 ## Implementation Details
 
 ### Database Schema
@@ -330,6 +412,26 @@ export class WorkflowEngineService {
 
 ---
 
+## 🔄 Review Cycle & Maintenance
+
+### Review Schedule
+- **Next Review:** 2026-08-24 (6 months from last review)
+- **Review Type:** Scheduled (Core Principle Review)
+- **Reviewers:** System Architect, Development Team Lead, Product Owner
+
+### Review Checklist
+- [ ] ยังคงเป็น Core Principle หรือไม่? (Workflow Engine เป็นหัวใจสำคัญของระบบ)
+- [ ] มีการเปลี่ยนแปลง Technology ที่กระทบหรือไม่? (New Workflow Engine alternatives)
+- [ ] มี Issue หรือ Bug ที่เกิดจาก ADR นี้หรือไม่? (Performance bottlenecks, State inconsistencies)
+- [ ] ต้องการ Update หรือ Deprecate หรือไม่? (DSL evolution, New document types)
+
+### Version History
+| Version | Date | Changes | Status |
+|---------|------|---------|--------|
+| 1.0 | 2026-02-24 | Initial version - DSL-based Unified Workflow Engine | ✅ Active |
+
+---
+
 ## Related ADRs
 
 - [ADR-002: Document Numbering Strategy](./ADR-002-document-numbering-strategy.md) - ใช้ Workflow Engine trigger Document Number Generation

specs/06-Decision-Records/ADR-002-document-numbering-strategy.md

@@ -10,6 +10,20 @@
 
 ---
 
+## 🎯 Gap Analysis & Purpose
+
+### ปิด Gap จากเอกสาร:
+- **Document Numbering Requirements** - Section 3.1: "เลขที่เอกสารต้องเป็นเลขที่อัตโนมัติ ไม่ซ้ำกัน และมีความหมาย"
+  - เหตุผล: ระบบเดิมไม่มีกลไกสร้างเลขที่อัตโนมัติที่ปลอดภัยต่อ Race Condition
+- **Acceptance Criteria** - AC-DOC-001: "เลขที่เอกสารต้องไม่ซ้ำกันแม้มีการสร้างพร้อมกันหลาย Request"
+  - เหตุผล: ต้องการ Mechanism ที่รับประกันความไม่ซ้ำกันในระดับ Mission-Critical
+
+### แก้ไขความขัดแย้ง:
+- **Performance Requirements** vs **Uniqueness Requirements**: ต้องการความเร็วสูงแต่ต้องรับประกันความไม่ซ้ำกัน 100%
+  - การตัดสินใจนี้ช่วยแก้ไขโดย: ใช้ Double-Lock Mechanism (Redis + Database) ที่ Balance ระหว่าง Performance และ Safety
+
+---
+
 ## Context and Problem Statement
 
 LCBP3-DMS ต้องสร้างเลขที่เอกสารอัตโนมัติสำหรับ Correspondence, RFA, Transmittal และ Drawing โดยเลขที่เอกสารต้อง:
@@ -116,6 +130,76 @@ LCBP3-DMS ต้องสร้างเลขที่เอกสารอั
 
 ---
 
+## 🔍 Impact Analysis
+
+### Affected Components (ส่วนประกอบที่ได้รับผลกระทบ)
+
+| Component | Level | Impact Description | Required Action |
+|-----------|-------|-------------------|-----------------|
+| **Backend** | 🔴 High | ต้องสร้าง DocumentNumberingService และ Update ทุก Document Service | Implement numbering service |
+| **Database** | 🔴 High | เพิ่ม Tables: document_number_formats, document_number_counters, document_number_audit | Create new schema |
+| **Redis** | 🔴 High | ต้องใช้ Redis สำหรับ Distributed Locking และ Rate Limiting | Configure Redis |
+| **API** | 🟡 Medium | ต้องสร้าง Numbering API endpoints | New endpoints |
+| **Testing** | 🟡 Medium | ต้องเขียน Concurrent Tests สำหรับ Race Condition | Performance tests |
+
+### Required Changes (การเปลี่ยนแปลงที่ต้องดำเนินการ)
+
+#### 🔴 Critical Changes (ต้องทำทันที)
+- [ ] **Create DocumentNumberingService** - backend/src/modules/document-numbering/: สร้าง Service หลัก
+- [ ] **Implement Database Schema** - specs/03-Data-and-Storage/: เพิ่ม numbering tables
+- [ ] **Configure Redis for Locking** - docker-compose.yml: Redis configuration
+- [ ] **Update Correspondence Service** - backend/src/modules/correspondence/: ใช้ numbering service
+- [ ] **Update RFA Service** - backend/src/modules/rfa/: ใช้ numbering service
+
+#### 🟡 Important Changes (ควรทำภายใน 1 สัปดาห์)
+- [ ] **Create Numbering API Endpoints** - backend/src/modules/document-numbering/controller.ts: REST API
+- [ ] **Add Rate Limiting** - backend/src/common/guards/: Prevent abuse
+- [ ] **Implement Audit Logging** - backend/src/modules/document-numbering/audit.service.ts: Track all numbers
+- [ ] **Add Error Handling** - backend/src/modules/document-numbering/: Retry logic
+
+#### 🟢 Nice-to-Have (ทำถ้ามีเวลา)
+- [ ] **Create Admin UI for Numbering Config** - frontend/app/(admin)/admin/numbering/: Configuration UI
+- [ ] **Add Numbering Performance Monitoring** - backend/src/modules/document-numbering/monitoring.service.ts: Metrics
+
+### Cross-Module Dependencies
+
+```mermaid
+graph TB
+    ADR[ADR-002 Numbering] --> Corr[Correspondence Service]
+    ADR --> RFA[RFA Service]
+    ADR --> Trans[Transmittal Service]
+    ADR --> Draw[Drawing Service]
+    ADR --> DB[(Database Schema)]
+    ADR --> Redis[(Redis)]
+
+    Corr --> ADR001[ADR-001 Workflow Engine]
+    RFA --> ADR001
+    Trans --> ADR001
+    Draw --> ADR001
+
+    Redis --> ADR006[ADR-006 Redis Caching]
+    DB --> ADR009[ADR-009 Migration Strategy]
+```
+
+---
+
+## 📋 Version Dependency Matrix
+
+| ADR | Version | Dependency Type | Affected Version(s) | Implementation Status |
+|-----|---------|-----------------|---------------------|----------------------|
+| **ADR-002** | 1.0 | Core | v1.8.0+ | ✅ Implemented |
+| **ADR-001** | 1.0 | Used By | v1.8.0+ | ✅ Implemented |
+| **ADR-006** | 1.0 | Required | v1.8.0+ | ✅ Implemented |
+| **ADR-009** | 1.0 | Database Changes | v1.8.0+ | ✅ Implemented |
+
+### Version Compatibility Rules
+
+- **Minimum Version:** v1.8.0 (ADR มีผลบังคับใช้)
+- **Breaking Changes:** ไม่มี (Backward compatible)
+- **Deprecation Timeline:** ไม่มี (Mission-critical component)
+
+---
+
 ## Implementation Details
 
 ### Database Schema
@@ -925,6 +1009,26 @@ ensure:
 
 ---
 
+## 🔄 Review Cycle & Maintenance
+
+### Review Schedule
+- **Next Review:** 2026-08-24 (6 months from last review)
+- **Review Type:** Scheduled (Core Principle Review)
+- **Reviewers:** System Architect, Database Administrator, Development Team Lead
+
+### Review Checklist
+- [ ] ยังคงเป็น Core Principle หรือไม่? (Document Numbering เป็น Mission-Critical)
+- [ ] มีการเปลิยนแปลง Technology ที่กระทบหรือไม่? (New locking mechanisms, Redis alternatives)
+- [ ] มี Issue หรือ Bug ที่เกิดจาก ADR นี้หรือไม่? (Race conditions, Performance issues)
+- [ ] ต้องการ Update หรือ Deprecate หรือไม่? (New numbering formats, Performance optimization)
+
+### Version History
+| Version | Date | Changes | Status |
+|---------|------|---------|--------|
+| 1.0 | 2026-02-24 | Initial version - Double-Lock Mechanism | ✅ Active |
+
+---
+
 ## Compliance
 
 เป็นไปตาม:

specs/06-Decision-Records/ADR-003-api-design-strategy.md

@@ -0,0 +1,422 @@
+# ADR-003: API Design Strategy
+
+**Status:** ✅ Accepted (Implementation Ready)
+**Date:** 2026-04-04
+**Decision Makers:** Development Team, System Architect
+**Related Documents:**
+
+- [API Design & Error Handling](../02-Architecture/02-04-api-design.md)
+- [Backend Guidelines](../05-Engineering-Guidelines/05-02-backend-guidelines.md)
+- [ADR-005: Technology Stack](./ADR-005-technology-stack.md)
+
+---
+
+## 🎯 Gap Analysis & Purpose
+
+### ปิด Gap จากเอกสาร:
+- **API Design & Error Handling** - Section 2: "ระบบต้องใช้ RESTful Principles และมีความสอดคล้องกัน"
+  - เหตุผล: ต้องการบันทึกการตัดสินใจเกี่ยวกับ API Design Patterns ที่ใช้จริงในระบบ
+- **Backend Guidelines** - Section 3: "การออกแบบ API ต้องรองรับ TypeScript และ NestJS Patterns"
+  - เหตุผล: ต้องการทำให้ API Design สอดคล้องกับ NestJS Ecosystem
+
+### แก้ไขความขัดแย้ง:
+- **REST Purity** vs **Pragmatic API Design**: ต้องการความสวยงามของ REST แต่ต้องรองรับ Business Logic ที่ซับซ้อน
+  - การตัดสินใจนี้ช่วยแก้ไขโดย: ใช้ RESTful หลักแต่เพิ่ม Pragmatic Patterns สำหรับ Workflow และ Business Operations
+
+---
+
+## Context and Problem Statement
+
+LCBP3-DMS ต้องการ API Design ที่:
+
+1. **Consistent:** ทุก Endpoint ใช้ Patterns เดียวกัน
+2. **Type-Safe:** รองรับ TypeScript และ DTO Validation
+3. **Business-Ready:** รองรับ Workflow Operations และ Complex Business Logic
+4. **Document-Driven:** Auto-generate Swagger Documentation
+5. **Performance-Oriented:** รองรับ Pagination, Filtering, และ Caching
+
+### Key Challenges
+
+1. **Resource Naming:** การตั้งชื่อ Resources ที่สะท้อน Business Domain
+2. **Complex Operations:** Workflow transitions, Document numbering ที่ไม่ใช่ CRUD ธรรมดา
+3. **Response Consistency:** การคืนค่าที่สม่ำเสมอทั้ง Single และ Collection
+4. **Error Handling:** การจัดการ Business Exceptions และ Validation Errors
+5. **Versioning:** การเตรียมพร้อมสำหรับ API Evolution
+
+---
+
+## Decision Drivers
+
+- **Developer Experience:** ง่ายต่อการใช้งานและ Debug
+- **Type Safety:** ป้องกัน Runtime Errors ด้วย TypeScript
+- **Business Alignment:** API สะท้อน Business Processes จริง
+- **Performance:** รองรับ High-volume Operations
+- **Documentation:** Auto-generated และ Up-to-date
+- **Testing:** ง่ายต่อการ Unit Test และ Integration Test
+
+---
+
+## Considered Options
+
+### Option 1: Pure REST with Resource Endpoints Only
+
+**แนวทาง:** ใช้ REST Resources เท่านั้น ไม่มี Action Endpoints
+
+**Pros:**
+
+- ✅ RESTful purity
+- ✅ Simple to understand
+- ✅ Standard HTTP semantics
+
+**Cons:**
+
+- ❌ Difficult for complex business operations
+- ❌ Workflow transitions become awkward
+- ❌ Document numbering doesn't fit resource model
+
+### Option 2: RPC-style with Action Endpoints
+
+**แนวทาง:** ใช้ Action Endpoints สำหรับทุก Business Operation
+
+**Pros:**
+
+- ✅ Clear business intent
+- ✅ Easy for complex operations
+- ✅ Direct mapping to use cases
+
+**Cons:**
+
+- ❌ Not RESTful
+- ❌ Inconsistent patterns
+- ❌ Hard to document with Swagger
+
+### Option 3: **Hybrid REST + Action Endpoints** ⭐ (Selected)
+
+**แนวทาง:** REST สำหรับ CRUD และ Action Endpoints สำหรับ Business Operations
+
+**Pros:**
+
+- ✅ **Best of Both Worlds:** REST ที่เหมาะสม + Actions ที่ชัดเจน
+- ✅ **Business Clarity:** Workflow actions อยู่ใน endpoints ที่เข้าใจง่าย
+- ✅ **Type Safety:** DTOs สำหรับทุก operation
+- ✅ **Documentation:** Swagger สามารถ document ได้ทั้งสองแบบ
+- ✅ **Consistency:** Clear naming conventions
+
+**Cons:**
+
+- ❌ Slightly more complex
+- ❌ Requires developer discipline
+
+---
+
+## Decision Outcome
+
+**Chosen Option:** Option 3 - Hybrid REST + Action Endpoints
+
+### Rationale
+
+เลือก Hybrid Approach เนื่องจาก:
+
+1. **Business Reality:** DMS มี Operations ที่ซับซ้อน (Workflow, Numbering) ที่ไม่ fit กับ pure REST
+2. **Developer Experience:** Actions ชัดเจนกว่าการยัด business logic ลงใน PATCH
+3. **Maintainability:** แยก concerns ระหว่าง data access และ business operations
+4. **Scalability:** สามารถเพิ่ม business operations ได้โดยไม่ทำให้ REST resources ซับซ้อน
+
+---
+
+## 🔍 Impact Analysis
+
+### Affected Components (ส่วนประกอบที่ได้รับผลกระทบ)
+
+| Component | Level | Impact Description | Required Action |
+|-----------|-------|-------------------|-----------------|
+| **API Controllers** | 🔴 High | ต้องใช้ Hybrid Pattern สำหรับทุก Module | Refactor controllers |
+| **DTOs** | 🔴 High | ต้องสร้าง DTOs สำหรับทุก Endpoint | Create comprehensive DTOs |
+| **Documentation** | 🟡 Medium | Swagger ต้อง cover ทั้ง REST และ Actions | Update Swagger config |
+| **Frontend API Client** | 🟡 Medium | ต้องรองรับทั้งสอง pattern | Update API service calls |
+| **Testing** | 🟡 Medium | ต้อง test ทั้ง resource และ action endpoints | Add integration tests |
+
+### Required Changes (การเปลี่ยนแปลงที่ต้องดำเนินการ)
+
+#### 🔴 Critical Changes (ต้องทำทันที)
+- [x] **Define API Standards** - สร้างมาตรฐานการตั้งชื่อและ patterns
+- [ ] **Refactor Correspondence API** - ใช้ hybrid pattern
+- [ ] **Update RFA API** - ใช้ action endpoints สำหรับ workflow
+- [ ] **Create Base Controller** - shared patterns และ utilities
+
+#### 🟡 Important Changes (ควรทำภายใน 1 สัปดาห์)
+- [ ] **Update API Documentation** - Swagger พร้อม examples
+- [ ] **Create API Client Library** - frontend TypeScript client
+- [ ] **Add Integration Tests** - test ทุก endpoint patterns
+- [ ] **Performance Testing** - ตรวจสอบ response times
+
+#### 🟢 Nice-to-Have (ทำถ้ามีเวลา)
+- [ ] **API Versioning Strategy** - prepare for v2
+- [ ] **OpenAPI Generator** - auto-generate clients
+- [ ] **API Analytics** - track usage patterns
+
+---
+
+## Implementation Details
+
+### API Design Patterns
+
+#### 1. Resource Endpoints (REST)
+
+```typescript
+// Standard CRUD operations
+GET    /api/v1/correspondences           // List with pagination
+GET    /api/v1/correspondences/:id       // Get by UUID
+POST   /api/v1/correspondences           // Create
+PUT    /api/v1/correspondences/:id       // Full update
+PATCH  /api/v1/correspondences/:id       // Partial update
+DELETE /api/v1/correspondences/:id       // Soft delete
+```
+
+#### 2. Action Endpoints (Business Operations)
+
+```typescript
+// Workflow actions
+POST /api/v1/correspondences/:id/submit
+POST /api/v1/correspondences/:id/approve
+POST /api/v1/correspondences/:id/reject
+POST /api/v1/correspondences/:id/forward
+
+// Document numbering
+POST /api/v1/document-numbering/reserve
+POST /api/v1/document-numbering/generate
+
+// Bulk operations
+POST /api/v1/correspondences/bulk-update
+POST /api/v1/correspondences/bulk-approve
+
+// Reports and exports
+GET /api/v1/reports/correspondence-summary
+GET /api/v1/exports/correspondences/:format
+```
+
+### Response Format Standards
+
+#### Success Response (Single Resource)
+
+```typescript
+{
+  "data": {
+    "id": "550e8400-e29b-41d4-a716-446655440000", // UUID (ADR-019)
+    "documentNumber": "LCBP3-CORR-2024-0001",
+    "subject": "Meeting minutes",
+    "status": "SUBMITTED",
+    "createdAt": "2024-01-01T00:00:00Z",
+    "updatedAt": "2024-01-01T00:00:00Z"
+  },
+  "meta": {
+    "timestamp": "2024-01-01T00:00:00Z",
+    "version": "1.0"
+  }
+}
+```
+
+#### Success Response (Collection)
+
+```typescript
+{
+  "data": [
+    { "id": "...", "documentNumber": "...", ... },
+    { "id": "...", "documentNumber": "...", ... }
+  ],
+  "meta": {
+    "pagination": {
+      "page": 1,
+      "limit": 20,
+      "total": 100,
+      "totalPages": 5
+    },
+    "filters": {
+      "status": "SUBMITTED",
+      "dateFrom": "2024-01-01"
+    },
+    "timestamp": "2024-01-01T00:00:00Z"
+  }
+}
+```
+
+#### Action Response
+
+```typescript
+{
+  "data": {
+    "action": "approve",
+    "result": "SUCCESS",
+    "nextStatus": "APPROVED",
+    "workflow": {
+      "id": "wf-123",
+      "currentState": "APPROVED",
+      "previousState": "PENDING_APPROVAL"
+    }
+  },
+  "meta": {
+    "timestamp": "2024-01-01T00:00:00Z",
+    "processedBy": "user-456"
+  }
+}
+```
+
+### Error Response Format
+
+```typescript
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Validation failed on input data",
+    "statusCode": 400,
+    "timestamp": "2024-01-01T00:00:00Z",
+    "path": "/api/v1/correspondences",
+    "details": [
+      {
+        "field": "subject",
+        "message": "Subject is required and must be at least 10 characters",
+        "value": null
+      }
+    ]
+  }
+}
+```
+
+### Naming Conventions
+
+#### URL Paths
+
+- **Resources:** Plural nouns, kebab-case
+  - `/correspondences`, `/projects`, `/organizations`
+- **Actions:** Verb-noun pattern, kebab-case
+  - `/correspondences/:id/submit`, `/document-numbering/generate`
+- **Nested Resources:** Parent-child relationship
+  - `/projects/:id/contracts`, `/contracts/:id/correspondences`
+
+#### JSON Properties
+
+- **Properties:** camelCase
+  - `documentNumber`, `createdAt`, `primaryOrganizationId`
+- **Enums:** UPPER_SNAKE_CASE
+  - `"SUBMITTED"`, `"IN_REVIEW"`, `"APPROVED"`
+- **Booleans:** is/has prefix
+  - `isActive`, `hasAttachments`, `canEdit`
+
+### DTO Examples
+
+#### Create DTO
+
+```typescript
+import { IsString, IsOptional, IsEnum, IsUUID } from 'class-validator';
+
+export class CreateCorrespondenceDto {
+  @IsString()
+  @MinLength(10)
+  subject: string;
+
+  @IsOptional()
+  @IsString()
+  content?: string;
+
+  @IsEnum(['LETTER', 'RFI', 'MEMO', 'NOTICE'])
+  type: CorrespondenceType;
+
+  @IsUUID()
+  @IsOptional()
+  originatorId?: string;
+
+  @IsUUID()
+  projectId: string;
+
+  @IsArray()
+  @IsUUID(4, { each: true })
+  recipientIds: string[];
+}
+```
+
+#### Action DTO
+
+```typescript
+export class ApproveCorrespondenceDto {
+  @IsString()
+  @MaxLength(1000)
+  comment?: string;
+
+  @IsOptional()
+  @IsArray()
+  @ValidateNested({ each: true })
+  @Type(() => AttachmentDto)
+  attachments?: AttachmentDto[];
+}
+```
+
+---
+
+## Consequences
+
+### Positive
+
+1. ✅ **Business Clarity:** Actions สะท้อน business operations ชัดเจน
+2. ✅ **Type Safety:** DTOs ป้องกัน runtime errors
+3. ✅ **Consistency:** Standard patterns ทั่วทั้ง API
+4. ✅ **Documentation:** Auto-generated Swagger ครบถ้วน
+5. ✅ **Maintainability:** แยก concerns ระหว่าง data และ business logic
+6. ✅ **Testing:** ง่ายต่อการ test ทุก endpoint
+
+### Negative
+
+1. ❌ **Learning Curve:** ต้องเรียนรู้ hybrid patterns
+2. ❌ **Documentation Complexity:** ต้องอธิบายทั้ง REST และ Actions
+3. ❌ **API Surface Area:** มี endpoints มากขึ้น
+
+### Mitigation Strategies
+
+- **Learning Curve:** Create comprehensive API guidelines and examples
+- **Documentation:** Use Swagger groups and descriptions
+- **API Surface:** Group related endpoints และใช้ consistent patterns
+
+---
+
+## 🔄 Review Cycle & Maintenance
+
+### Review Schedule
+- **Next Review:** 2026-10-04 (6 months from creation)
+- **Review Type:** Scheduled (API Strategy Review)
+- **Reviewers:** System Architect, Backend Team Lead, Frontend Team Lead
+
+### Review Checklist
+- [ ] ยังคงตอบโจทย์ Business Requirements หรือไม่?
+- [ ] มี API patterns ใหม่ที่ควรพิจารณาหรือไม่?
+- [ ] มีปัญหา Performance หรือ Usability หรือไม่?
+- [ ] ต้องการ Update หรือ Deprecate patterns ใดหรือไม่?
+
+### Version History
+| Version | Date | Changes | Status |
+|---------|------|---------|--------|
+| 1.0 | 2026-04-04 | Initial version - Hybrid REST + Action Strategy | ✅ Accepted |
+
+---
+
+## Compliance
+
+เป็นไปตาม:
+
+- [API Design & Error Handling](../02-Architecture/02-04-api-design.md)
+- [Backend Guidelines](../05-Engineering-Guidelines/05-02-backend-guidelines.md)
+- [ADR-019: Hybrid Identifier Strategy](./ADR-019-hybrid-identifier-strategy.md)
+
+---
+
+## Related ADRs
+
+- [ADR-005: Technology Stack](./ADR-005-technology-stack.md) - NestJS framework choice
+- [ADR-010: Logging & Monitoring](./ADR-010-logging-monitoring-strategy.md) - API request logging
+- [ADR-016: Security Authentication](./ADR-016-security-authentication.md) - API security
+
+---
+
+## References
+
+- [NestJS Documentation](https://docs.nestjs.com/)
+- [OpenAPI Specification](https://swagger.io/specification/)
+- [REST API Design Best Practices](https://restfulapi.net/)

specs/06-Decision-Records/ADR-004-database-schema-design-strategy.md

@@ -0,0 +1,483 @@
+# ADR-004: Database Schema Design Strategy
+
+**Status:** ✅ Accepted (Implementation Ready)
+**Date:** 2026-04-04
+**Decision Makers:** Development Team, System Architect, Database Administrator
+**Related Documents:**
+
+- [Database Schema Tables](../03-Data-and-Storage/lcbp3-v1.8.0-schema-02-tables.sql)
+- [Data Dictionary](../03-Data-and-Storage/03-01-data-dictionary.md)
+- [ADR-009: Database Migration Strategy](./ADR-009-database-migration-strategy.md)
+- [ADR-019: Hybrid Identifier Strategy](./ADR-019-hybrid-identifier-strategy.md)
+
+---
+
+## 🎯 Gap Analysis & Purpose
+
+### ปิด Gap จากเอกสาร:
+- **Database Schema Tables** - Section 1: "ตารางต้องมีโครงสร้างที่สอดคล้องกันและรองรับ Business Logic"
+  - เหตุผล: ต้องการบันทึกการตัดสินใจเกี่ยวกับ Schema Patterns ที่ใช้จริง
+- **Data Dictionary** - Section 2: "การตั้งชื่อคอลัมน์และความสัมพันธ์ต้องสอดคล้องกัน"
+  - เหตุผล: ต้องการทำให้ naming conventions เป็นมาตรฐานเดียวกัน
+
+### แก้ไขความขัดแย้ง:
+- **Normalization** vs **Performance**: ต้องการ Database Normalization แต่ต้องรักษา Performance สำหรับ DMS
+  - การตัดสินใจนี้ช่วยแก้ไขโดย: ใช้ selective denormalization และ strategic indexing
+
+---
+
+## Context and Problem Statement
+
+LCBP3-DMS ต้องการ Database Schema Design ที่:
+
+1. **Consistent:** ทุกตารางใช้ Patterns เดียวกัน
+2. **Scalable:** รองรับข้อมูลจำนวนมากและ Complex Queries
+3. **Maintainable:** ง่ายต่อการ Modify และ Debug
+4. **Performance:** รองรับ High-volume Operations พร้อม Concurrent Access
+5. **Audit-Ready:** รองรับ Audit Trail และ Compliance
+
+### Key Challenges
+
+1. **Identifier Strategy:** การใช้ทั้ง INT PK และ UUID (ADR-019)
+2. **Soft Delete:** การจัดการการลบข้อมูลแบบ Soft Delete
+3. **Audit Trail:** การติดตามการเปลี่ยนแปลงข้อมูล
+4. **Workflow State:** การจัดการ State Machines ใน Database
+5. **Document Relationships:** การจัดการ Complex Many-to-Many Relationships
+
+---
+
+## Decision Drivers
+
+- **Data Integrity:** ป้องกัน Data Corruption และ Inconsistencies
+- **Performance:** Query Response Times < 200ms (p90)
+- **Scalability:** รองรับ 100+ concurrent users
+- **Maintainability:** ง่ายต่อการ Add/Modify Columns
+- **Auditability:** Complete audit trail สำหรับ Compliance
+- **Migration Safety:** ง่ายต่อการ Schema Evolution
+
+---
+
+## Considered Options
+
+### Option 1: Highly Normalized (3NF+)
+
+**แนวทาง:** Strict normalization ทุกตาราง
+
+**Pros:**
+
+- ✅ Data integrity สูงสุด
+- ✅ Minimal data duplication
+- ✅ Theoretical correctness
+
+**Cons:**
+
+- ❌ Complex queries มากขึ้น
+- ❌ Performance impact จาก JOINs
+- ❌ ยากต่อการ maintain ในระยะยาว
+
+### Option 2: Denormalized for Performance
+
+**แนวทาง:** Duplicate data สำหรับ performance
+
+**Pros:**
+
+- ✅ Fast queries (fewer JOINs)
+- ✅ Simple read operations
+- ✅ Good for reporting
+
+**Cons:**
+
+- ❌ Data synchronization complexity
+- ❌ Higher storage requirements
+- ❌ Risk of inconsistencies
+
+### Option 3: **Selective Normalization with Strategic Patterns** ⭐ (Selected)
+
+**แนวทาง:** Normalize ที่สำคัญ แต่ denormalize ที่จำเป็น พร้อม Standard Patterns
+
+**Pros:**
+
+- ✅ **Balance Performance & Integrity:** Optimize สำหรับ use case จริง
+- ✅ **Consistent Patterns:** Standard conventions ทั่วทั้ง schema
+- ✅ **Audit Trail Built-in:** Soft delete + tracking tables
+- ✅ **Migration Ready:** ง่ายต่อการ evolve schema
+- ✅ **Workflow Support:** Native state management
+
+**Cons:**
+
+- ❌ Requires architectural discipline
+- ❌ More complex initial design
+
+---
+
+## Decision Outcome
+
+**Chosen Option:** Option 3 - Selective Normalization with Strategic Patterns
+
+### Rationale
+
+เลือก Selective Normalization เนื่องจาก:
+
+1. **Business Reality:** DMS มี both transactional และ reporting needs
+2. **Performance Requirements:** ต้องการ fast reads สำหรับ list views แต่ maintain integrity สำหรับ transactions
+3. **Maintainability:** Standard patterns ลดความซับซ้อนในระยะยาว
+4. **Audit Requirements:** Built-in audit trail จำเป็นสำหรับ document management
+
+---
+
+## 🔍 Impact Analysis
+
+### Affected Components (ส่วนประกอบที่ได้รับผลกระทบ)
+
+| Component | Level | Impact Description | Required Action |
+|-----------|-------|-------------------|-----------------|
+| **Database Schema** | 🔴 High | ทุกตารางต้องใช้ standard patterns | Refactor all tables |
+| **TypeORM Entities** | 🔴 High | Entity classes ต้อง映射 schema patterns | Update entity definitions |
+| **Migration Scripts** | 🔴 High | ต้องมี migration สำหรับ pattern changes | Create migration strategy |
+| **Queries & Services** | 🟡 Medium | ต้อง optimize queries สำหรับ new patterns | Update service queries |
+| **Performance Testing** | 🟡 Medium | ต้อง validate performance ของ patterns | Load testing |
+
+### Required Changes (การเปลี่ยนแปลงที่ต้องดำเนินการ)
+
+#### 🔴 Critical Changes (ต้องทำทันที)
+- [ ] **Define Schema Standards** - สร้างมาตรฐานการออกแบบตาราง
+- [ ] **Implement Base Entity Pattern** - สำหรับ common fields
+- [ ] **Update Core Tables** - ใช้ standard patterns
+- [ ] **Create Audit Trail Tables** - สำหรับ tracking
+
+#### 🟡 Important Changes (ควรทำภายใน 1 สัปดาห์)
+- [ ] **Optimize Indexes** - สำหรับ performance
+- [ ] **Create Migration Scripts** - สำหรับ evolution
+- [ ] **Update TypeORM Entities** - reflect new patterns
+- [ ] **Performance Testing** - validate improvements
+
+#### 🟢 Nice-to-Have (ทำถ้ามีเวลา)
+- [ ] **Database Documentation** - auto-generate from schema
+- [ ] **Performance Monitoring** - query analysis tools
+- [ ] **Schema Validation** - automated checks
+
+---
+
+## Implementation Details
+
+### Schema Design Patterns
+
+#### 1. Base Table Pattern
+
+ทุกตารางต้องมี base columns ต่อไปนี้:
+
+```sql
+CREATE TABLE example_table (
+  -- Primary Keys (ADR-019)
+  id INT PRIMARY KEY AUTO_INCREMENT COMMENT 'Internal PK - never exposed',
+  uuid UUID NOT NULL DEFAULT UUID() COMMENT 'Public UUID (ADR-019)',
+
+  -- Business Columns
+  name VARCHAR(255) NOT NULL,
+  -- ... other business columns
+
+  -- Standard Metadata
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT 'Record creation time',
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT 'Last update time',
+  created_by INT NULL COMMENT 'User who created record',
+  updated_by INT NULL COMMENT 'User who last updated record',
+  deleted_at DATETIME NULL COMMENT 'Soft delete timestamp',
+
+  -- Indexes
+  UNIQUE INDEX idx_example_uuid (uuid),
+  INDEX idx_example_created_at (created_at),
+  INDEX idx_example_deleted_at (deleted_at)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
+```
+
+#### 2. Naming Conventions
+
+**Table Names:**
+
+- **Plural snake_case:** `organizations`, `correspondences`, `workflow_instances`
+- **Join Tables:** `table1_table2` (e.g., `correspondence_recipients`)
+- **Lookup Tables:** Prefix with type: `correspondence_types`, `organization_roles`
+
+**Column Names:**
+
+- **Primary Keys:** `id` (INT), `uuid` (UUID)
+- **Foreign Keys:** `{table}_id` (e.g., `organization_id`, `project_id`)
+- **Boolean Columns:** `is_` prefix: `is_active`, `is_deleted`
+- **Timestamp Columns:** `_at` suffix: `created_at`, `updated_at`, `deleted_at`
+- **User References:** `_by` suffix: `created_by`, `updated_by`
+
+#### 3. Relationship Patterns
+
+**One-to-Many:**
+
+```sql
+-- Projects have many Contracts
+CREATE TABLE contracts (
+  id INT PRIMARY KEY AUTO_INCREMENT,
+  uuid UUID NOT NULL DEFAULT UUID(),
+  project_id INT NOT NULL,
+  -- ... other columns
+  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE
+);
+```
+
+**Many-to-Many:**
+
+```sql
+-- Correspondences have many Recipients
+CREATE TABLE correspondence_recipients (
+  id INT PRIMARY KEY AUTO_INCREMENT,
+  correspondence_id INT NOT NULL,
+  user_id INT NOT NULL,
+  recipient_type ENUM('TO', 'CC', 'BCC') NOT NULL,
+  received_at TIMESTAMP NULL,
+  -- Metadata
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  FOREIGN KEY (correspondence_id) REFERENCES correspondences(id) ON DELETE CASCADE,
+  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
+  UNIQUE KEY unique_correspondence_recipient (correspondence_id, user_id)
+);
+```
+
+#### 4. Workflow State Pattern
+
+```sql
+-- Workflow States
+CREATE TABLE workflow_states (
+  id INT PRIMARY KEY AUTO_INCREMENT,
+  workflow_code VARCHAR(50) NOT NULL,
+  state_name VARCHAR(50) NOT NULL,
+  is_initial BOOLEAN DEFAULT FALSE,
+  is_terminal BOOLEAN DEFAULT FALSE,
+  allowed_transitions JSON NULL, -- Array of next states
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE KEY unique_workflow_state (workflow_code, state_name)
+);
+
+-- Workflow Instances
+CREATE TABLE workflow_instances (
+  id INT PRIMARY KEY AUTO_INCREMENT,
+  uuid UUID NOT NULL DEFAULT UUID(),
+  workflow_code VARCHAR(50) NOT NULL,
+  entity_type VARCHAR(50) NOT NULL, -- 'correspondence', 'rfa', etc.
+  entity_id INT NOT NULL,
+  current_state VARCHAR(50) NOT NULL,
+  status ENUM('ACTIVE', 'COMPLETED', 'CANCELLED') DEFAULT 'ACTIVE',
+  context JSON NULL,
+  -- Metadata
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  FOREIGN KEY (workflow_code, current_state) REFERENCES workflow_states(workflow_code, state_name)
+);
+```
+
+#### 5. Audit Trail Pattern
+
+```sql
+-- Generic Audit Trail
+CREATE TABLE audit_logs (
+  id BIGINT PRIMARY KEY AUTO_INCREMENT,
+  table_name VARCHAR(50) NOT NULL,
+  record_id INT NOT NULL,
+  record_uuid UUID NULL,
+  action ENUM('CREATE', 'UPDATE', 'DELETE', 'SOFT_DELETE') NOT NULL,
+  old_values JSON NULL,
+  new_values JSON NULL,
+  changed_fields JSON NULL, -- Array of changed field names
+  user_id INT NULL,
+  ip_address VARCHAR(45) NULL,
+  user_agent TEXT NULL,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+
+  INDEX idx_audit_table_record (table_name, record_id),
+  INDEX idx_audit_user (user_id, created_at),
+  INDEX idx_audit_created (created_at)
+);
+
+-- Document-specific History (for critical tables)
+CREATE TABLE correspondence_histories (
+  id BIGINT PRIMARY KEY AUTO_INCREMENT,
+  correspondence_id INT NOT NULL,
+  revision_number INT NOT NULL,
+  changes JSON NOT NULL, -- Full snapshot or delta
+  changed_by INT NULL,
+  change_reason VARCHAR(255) NULL,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+
+  FOREIGN KEY (correspondence_id) REFERENCES correspondences(id) ON DELETE CASCADE,
+  UNIQUE KEY unique_correspondence_revision (correspondence_id, revision_number)
+);
+```
+
+#### 6. Master Data Pattern
+
+```sql
+-- Reference Data Tables
+CREATE TABLE correspondence_types (
+  id INT PRIMARY KEY AUTO_INCREMENT,
+  type_code VARCHAR(20) NOT NULL UNIQUE, -- LETTER, RFI, MEMO
+  type_name VARCHAR(100) NOT NULL,
+  description TEXT NULL,
+  display_order INT DEFAULT 0,
+  is_active BOOLEAN DEFAULT TRUE,
+  -- Metadata
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
+) COMMENT='Master data: Correspondence types';
+```
+
+### TypeORM Entity Patterns
+
+#### Base Entity
+
+```typescript
+import { CreateDateColumn, UpdateDateColumn, DeleteDateColumn } from 'typeorm';
+import { UuidBaseEntity } from './uuid-base.entity';
+
+export abstract class BaseEntity extends UuidBaseEntity {
+  @CreateDateColumn({ type: 'timestamp' })
+  createdAt: Date;
+
+  @UpdateDateColumn({ type: 'timestamp' })
+  updatedAt: Date;
+
+  @DeleteDateColumn({ type: 'datetime', nullable: true })
+  deletedAt?: Date;
+
+  @Column({ type: 'int', nullable: true })
+  createdBy?: number;
+
+  @Column({ type: 'int', nullable: true })
+  updatedBy?: number;
+}
+```
+
+#### Entity Example
+
+```typescript
+@Entity('correspondences')
+export class Correspondence extends BaseEntity {
+  @Column({ type: 'varchar', length: 50 })
+  documentNumber: string;
+
+  @Column({ type: 'varchar', length: 255 })
+  subject: string;
+
+  @Column({ type: 'text', nullable: true })
+  content?: string;
+
+  @ManyToOne(() => CorrespondenceType)
+  @JoinColumn({ name: 'correspondence_type_id' })
+  type: CorrespondenceType;
+
+  @ManyToOne(() => Organization)
+  @JoinColumn({ name: 'originator_id' })
+  originator: Organization;
+
+  @OneToMany(() => CorrespondenceRecipient, recipient => recipient.correspondence)
+  recipients: CorrespondenceRecipient[];
+}
+```
+
+### Indexing Strategy
+
+#### Primary Indexes
+
+```sql
+-- UUID for public access
+CREATE UNIQUE INDEX idx_table_uuid ON table_name (uuid);
+
+-- Performance indexes
+CREATE INDEX idx_table_created_at ON table_name (created_at);
+CREATE INDEX idx_table_updated_at ON table_name (updated_at);
+CREATE INDEX idx_table_deleted_at ON table_name (deleted_at);
+```
+
+#### Foreign Key Indexes
+
+```sql
+-- All foreign keys should be indexed
+CREATE INDEX idx_correspondence_project_id ON correspondences (project_id);
+CREATE INDEX idx_correspondence_originator_id ON correspondences (originator_id);
+CREATE INDEX idx_correspondence_type_id ON correspondences (correspondence_type_id);
+```
+
+#### Query-Specific Indexes
+
+```sql
+-- Composite indexes for common queries
+CREATE INDEX idx_correspondences_project_status ON correspondences (project_id, status, deleted_at);
+CREATE INDEX idx_correspondences_date_range ON correspondences (created_at, deleted_at) WHERE deleted_at IS NULL;
+```
+
+---
+
+## Consequences
+
+### Positive
+
+1. ✅ **Consistency:** Standard patterns ทั่วทั้ง database
+2. ✅ **Performance:** Strategic indexing และ selective denormalization
+3. ✅ **Audit Trail:** Complete tracking สำหรับ compliance
+4. ✅ **Maintainability:** Clear naming conventions และ patterns
+5. ✅ **Migration Safety:** Evolution-friendly schema design
+6. ✅ **Type Safety:** TypeORM entities ที่สอดคล้องกับ schema
+
+### Negative
+
+1. ❌ **Initial Complexity:** ต้องเรียนรู้ patterns และ conventions
+2. ❌ **Storage Overhead:** Audit tables ใช้พื้นที่เพิ่ม
+3. ❌ **Development Overhead:** ต้อง maintain patterns อย่างสม่ำเสมอ
+
+### Mitigation Strategies
+
+- **Complexity:** Comprehensive documentation และ examples
+- **Storage:** Partition audit tables และ implement retention policies
+- **Development:** Code generation สำหรับ boilerplate entities
+
+---
+
+## 🔄 Review Cycle & Maintenance
+
+### Review Schedule
+- **Next Review:** 2026-10-04 (6 months from creation)
+- **Review Type:** Scheduled (Schema Strategy Review)
+- **Reviewers:** System Architect, DBA, Backend Team Lead
+
+### Review Checklist
+- [ ] ยังคงตอบโจทย์ Performance Requirements หรือไม่?
+- [ ] มี schema patterns ใหม่ที่ควรพิจารณาหรือไม่?
+- [ ] มีปัญหา Storage หรือ Performance หรือไม่?
+- [ ] ต้องการ Update หรือ Deprecate patterns ใดหรือไม่?
+
+### Version History
+| Version | Date | Changes | Status |
+|---------|------|---------|--------|
+| 1.0 | 2026-04-04 | Initial version - Selective Normalization Strategy | ✅ Accepted |
+
+---
+
+## Compliance
+
+เป็นไปตาม:
+
+- [Database Schema Tables](../03-Data-and-Storage/lcbp3-v1.8.0-schema-02-tables.sql)
+- [Data Dictionary](../03-Data-and-Storage/03-01-data-dictionary.md)
+- [ADR-009: Database Migration Strategy](./ADR-009-database-migration-strategy.md)
+- [ADR-019: Hybrid Identifier Strategy](./ADR-019-hybrid-identifier-strategy.md)
+
+---
+
+## Related ADRs
+
+- [ADR-009: Database Migration Strategy](./ADR-009-database-migration-strategy.md) - Schema evolution
+- [ADR-019: Hybrid Identifier Strategy](./ADR-019-hybrid-identifier-strategy.md) - UUID usage
+- [ADR-001: Unified Workflow Engine](./ADR-001-unified-workflow-engine.md) - Workflow state management
+
+---
+
+## References
+
+- [MariaDB Documentation](https://mariadb.com/kb/en/)
+- [TypeORM Documentation](https://typeorm.io/)
+- [Database Design Best Practices](https://www.databasestar.com/)

specs/06-Decision-Records/ADR-005-technology-stack.md

@@ -1,15 +1,29 @@
 # ADR-005: Technology Stack Selection
 
-**Status:** Accept
+**Status:** Accepted
 **Date:** 2026-02-24
 **Decision Makers:** Development Team, CTO
 **Related Documents:**
 
-- [System Architecture](../02-architecture/02-01-system-architecture.md)
+- [System Architecture](../02-Architecture/02-01-system-architecture.md)
 - [FullStack JS Guidelines](../03-implementation/03-01-fullftack-js-v1.7.0.md)
 
 ---
 
+## Gap Analysis & Purpose
+
+### ปิด Gap จากเอกสาร:
+- **System Architecture** - Section 4.1: "ระบบต้องพัฒนาด้วย Technology Stack ที่ทีมมีความเชี่ยวชาญ"
+  - เหตุผล: ทีมมีประสบการณ์ TypeScript/JavaScript จึงเลือก Stack ที่ใช้ภาษาเดียวกัน
+- **Infrastructure Constraints** - Section 5.2: "ระบบต้อง Deploy บน QNAP Container Station"
+  - เหตุผล: ต้องเลือก Technology ที่เข้ากับ QNAP และ Resource จำกัด
+
+### แก้ไขความขัดแย้ง:
+- **Development Speed** vs **Enterprise Requirements**: ต้องการพัฒนาเร็วแต่ต้องเป็น Enterprise-grade
+  - การตัดสินใจนี้ช่วยแก้ไขโดย: เลือก TypeScript ecosystem ที่ Modern แต่ก็ Enterprise-ready
+
+---
+
 ## Context and Problem Statement
 
 LCBP3-DMS ต้องเลือก Technology Stack สำหรับพัฒนา Document Management System ที่:
@@ -130,6 +144,77 @@ LCBP3-DMS ต้องเลือก Technology Stack สำหรับพั
 
 ---
 
+## 🔍 Impact Analysis
+
+### Affected Components (ส่วนประกอบที่ได้รับผลกระทบ)
+
+| Component | Level | Impact Description | Required Action |
+|-----------|-------|-------------------|-----------------|
+| **Development Environment** | 🔴 High | ต้องติดตั้ง Node.js, TypeScript, Docker | Setup dev environment |
+| **CI/CD Pipeline** | 🔴 High | ต้องสร้าง Pipeline สำหรับ TypeScript, Docker | Build/deploy automation |
+| **Team Skills** | 🟡 Medium | ทีมต้องเรียนรู้ NestJS, Next.js | Training sessions |
+| **Infrastructure** | 🟡 Medium | ต้องติดตั้ง Docker, Redis, MariaDB | Server setup |
+| **Documentation** | 🟡 Medium | ต้องเขียน Docs สำหรับ TypeScript ecosystem | Update documentation |
+
+### Required Changes (การเปลี่ยนแปลงที่ต้องดำเนินการ)
+
+#### 🔴 Critical Changes (ต้องทำทันที)
+- [ ] **Setup Development Environment** - All developers: Node.js, Docker, IDE setup
+- [ ] **Create Project Structure** - backend/, frontend/, docker-compose.yml: Initial scaffolding
+- [ ] **Configure TypeScript** - tsconfig.json, package.json: Build configuration
+- [ ] **Setup CI/CD** - .github/workflows/: Build and deploy automation
+- [ ] **Install Database** - MariaDB, Redis: Infrastructure setup
+
+#### 🟡 Important Changes (ควรทำภายใน 1 สัปดาห์)
+- [ ] **Create Code Standards** - .eslintrc, .prettierrc: Linting and formatting
+- [ ] **Setup Testing Framework** - Jest, Vitest, Playwright: Test infrastructure
+- [ ] **Documentation Setup** - README.md, CONTRIBUTING.md: Project docs
+- [ ] **Team Training** - NestJS, Next.js workshops: Knowledge transfer
+
+#### 🟢 Nice-to-Have (ทำถ้ามีเวลา)
+- [ ] **Create Component Library** - shadcn/ui customization: UI consistency
+- [ ] **Setup Monitoring** - Logging, metrics: Observability
+- [ ] **Performance Benchmarking** - Load testing scripts: Performance validation
+
+### Cross-Module Dependencies
+
+```mermaid
+graph TB
+    ADR[ADR-005 Tech Stack] --> Backend[NestJS Backend]
+    ADR --> Frontend[Next.js Frontend]
+    ADR --> DB[(MariaDB)]
+    ADR --> Redis[(Redis)]
+    ADR --> Docker[Docker]
+
+    Backend --> ADR001[ADR-001 Workflow Engine]
+    Backend --> ADR002[ADR-002 Numbering]
+    Frontend --> ADR011[ADR-011 App Router]
+    Frontend --> ADR012[ADR-012 UI Components]
+
+    Redis --> ADR006[ADR-006 Redis Strategy]
+    DB --> ADR009[ADR-009 Migration]
+```
+
+---
+
+## 📋 Version Dependency Matrix
+
+| ADR | Version | Dependency Type | Affected Version(s) | Implementation Status |
+|-----|---------|-----------------|---------------------|----------------------|
+| **ADR-005** | 1.0 | Foundation | v1.8.0+ | ✅ Implemented |
+| **ADR-001** | 1.0 | Depends On | v1.8.0+ | ✅ Implemented |
+| **ADR-002** | 1.0 | Depends On | v1.8.0+ | ✅ Implemented |
+| **ADR-006** | 1.0 | Required | v1.8.0+ | ✅ Implemented |
+| **ADR-009** | 1.0 | Database | v1.8.0+ | ✅ Implemented |
+
+### Version Compatibility Rules
+
+- **Minimum Version:** v1.8.0 (ADR มีผลบังคับใช้)
+- **Breaking Changes:** ไม่มี (Foundation stack)
+- **Deprecation Timeline:** ไม่มี (Core technology choices)
+
+---
+
 ## Architecture Decisions
 
 ### Backend Architecture: Modular Monolith
@@ -268,6 +353,26 @@ lcbp3-dms/
 
 ---
 
+## 🔄 Review Cycle & Maintenance
+
+### Review Schedule
+- **Next Review:** 2026-08-24 (6 months from last review)
+- **Review Type:** Scheduled (Foundation Review)
+- **Reviewers:** CTO, System Architect, Development Team Lead
+
+### Review Checklist
+- [ ] ยังคงเป็น Core Principle หรือไม่? (Technology Stack เป็นรากฐานของระบบ)
+- [ ] มีการเปลี่ยนแปลง Technology ที่กระทบหรือไม่? (New frameworks, EOL versions)
+- [ ] มี Issue หรือ Bug ที่เกิดจาก ADR นี้หรือไม่? (Performance issues, Compatibility problems)
+- [ ] ต้องการ Update หรือ Deprecate หรือไม่? (Version upgrades, New alternatives)
+
+### Version History
+| Version | Date | Changes | Status |
+|---------|------|---------|--------|
+| 1.0 | 2026-02-24 | Initial version - Full Stack TypeScript | ✅ Active |
+
+---
+
 ## Compliance
 
 เป็นไปตาม:

specs/06-Decision-Records/ADR-006-redis-caching-strategy.md

@@ -10,6 +10,20 @@
 
 ---
 
+## 🎯 Gap Analysis & Purpose
+
+### ปิด Gap จากเอกสาร:
+- **Non-Functional Rules** - Section 4.2: "ระบบต้องตอบสนอง Performance ได้ < 200ms (p90)"
+  - เหตุผล: Database queries ช้า ต้องใช้ Cache ในการเพิ่ม Performance
+- **Software Architecture** - Section 5.3: "ระบบต้องรองรับ Concurrent Access พร้อม Locking Mechanism"
+  - เหตุผล: ต้องการ Distributed Lock สำหรับ Document Numbering และ Race Conditions
+
+### แก้ไขความขัดแย้ง:
+- **Performance Requirements** vs **Data Consistency**: ต้องการความเร็วสูงแต่ต้องรักษาความสม่ำเสมอของข้อมูล
+  - การตัดสินใจนี้ช่วยแก้ไขโดย: ใช้ Redis พร้อม Cache Invalidation Strategy ที่ชัดเจน
+
+---
+
 ## Context and Problem Statement
 
 LCBP3-DMS ต้องการ High Performance ในการ:
@@ -90,6 +104,75 @@ LCBP3-DMS ต้องการ High Performance ในการ:
 
 ---
 
+## 🔍 Impact Analysis
+
+### Affected Components (ส่วนประกอบที่ได้รับผลกระทบ)
+
+| Component | Level | Impact Description | Required Action |
+|-----------|-------|-------------------|-----------------|
+| **Backend Services** | 🔴 High | ทุก Service ต้องใช้ Redis สำหรับ Cache และ Locking | Implement Redis clients |
+| **Authentication** | 🔴 High | Session Management และ Permission Caching | Update Auth service |
+| **Document Numbering** | 🔴 High | Distributed Locking สำหรับ Race Condition | Integrate Redlock |
+| **Infrastructure** | 🔴 High | ต้องติดตั้ง Redis Server และ Monitoring | Redis setup |
+| **API Performance** | 🟡 Medium | Response time ลดลง < 200ms | Performance optimization |
+
+### Required Changes (การเปลี่ยนแปลงที่ต้องดำเนินการ)
+
+#### 🔴 Critical Changes (ต้องทำทันที)
+- [ ] **Install Redis Server** - docker-compose.yml: Redis 7 configuration
+- [ ] **Create Redis Service** - backend/src/common/redis/: Redis connection management
+- [ ] **Update Auth Service** - backend/src/modules/auth/: Session caching
+- [ ] **Update Numbering Service** - backend/src/modules/document-numbering/: Distributed locks
+- [ ] **Add Permission Caching** - backend/src/modules/permissions/: Cache user abilities
+
+#### 🟡 Important Changes (ควรทำภายใน 1 สัปดาห์)
+- [ ] **Create Cache Invalidation Service** - backend/src/common/cache/: Cache management
+- [ ] **Add Rate Limiting** - backend/src/common/guards/: Redis-based rate limiter
+- [ ] **Setup BullMQ Queues** - backend/src/common/queues/: Background job processing
+- [ ] **Add Redis Monitoring** - backend/src/common/monitoring/: Metrics and alerts
+
+#### 🟢 Nice-to-Have (ทำถ้ามีเวลา)
+- [ ] **Create Redis Admin UI** - frontend/app/(admin)/admin/redis/: Cache management UI
+- [ ] **Add Performance Dashboard** - Grafana dashboards: Redis metrics visualization
+- [ ] **Implement Cache Warming** - Scripts: Pre-populate cache
+
+### Cross-Module Dependencies
+
+```mermaid
+graph TB
+    ADR[ADR-006 Redis Strategy] --> Auth[Auth Service]
+    ADR --> Numbering[Numbering Service]
+    ADR --> Permissions[Permission Service]
+    ADR --> API[All APIs]
+    ADR --> Redis[(Redis Server)]
+
+    Numbering --> ADR002[ADR-002 Numbering]
+    Auth --> ADR016[ADR-016 Security]
+    API --> ADR001[ADR-001 Workflow]
+
+    Redis --> ADR005[ADR-005 Tech Stack]
+    Redis --> ADR015[ADR-015 Deployment]
+```
+
+---
+
+## 📋 Version Dependency Matrix
+
+| ADR | Version | Dependency Type | Affected Version(s) | Implementation Status |
+|-----|---------|-----------------|---------------------|----------------------|
+| **ADR-006** | 1.0 | Infrastructure | v1.8.0+ | ✅ Implemented |
+| **ADR-002** | 1.0 | Required By | v1.8.0+ | ✅ Implemented |
+| **ADR-016** | 1.0 | Used By | v1.8.0+ | ✅ Implemented |
+| **ADR-005** | 1.0 | Component | v1.8.0+ | ✅ Implemented |
+
+### Version Compatibility Rules
+
+- **Minimum Version:** v1.8.0 (ADR มีผลบังคับใช้)
+- **Breaking Changes:** ไม่มี (Infrastructure component)
+- **Deprecation Timeline:** ไม่มี (Core infrastructure)
+
+---
+
 ## Redis Usage Patterns
 
 ### 1. Distributed Locking (Redlock)
@@ -409,6 +492,26 @@ export class RedisMonitoringService {
 
 ---
 
+## 🔄 Review Cycle & Maintenance
+
+### Review Schedule
+- **Next Review:** 2026-08-24 (6 months from last review)
+- **Review Type:** Scheduled (Infrastructure Review)
+- **Reviewers:** System Architect, DevOps Engineer, Development Team Lead
+
+### Review Checklist
+- [ ] ยังคงเป็น Core Principle หรือไม่? (Redis เป็น Infrastructure หลัก)
+- [ ] มีการเปลี่ยนแปลง Technology ที่กระทบหรือไม่? (New caching solutions, Redis alternatives)
+- [ ] มี Issue หรือ Bug ที่เกิดจาก ADR นี้หรือไม่? (Cache invalidation issues, Performance problems)
+- [ ] ต้องการ Update หรือ Deprecate หรือไม่? (Redis version upgrades, New patterns)
+
+### Version History
+| Version | Date | Changes | Status |
+|---------|------|---------|--------|
+| 1.0 | 2026-02-24 | Initial version - Redis Distributed Cache + Lock | ✅ Active |
+
+---
+
 ## Compliance
 
 เป็นไปตาม:

specs/06-Decision-Records/ADR-007-error-handling-strategy.md

@@ -0,0 +1,650 @@
+# ADR-007: Error Handling & Recovery Strategy
+
+**Status:** ✅ Accepted (Implementation Ready)
+**Date:** 2026-04-04
+**Decision Makers:** Development Team, System Architect
+**Related Documents:**
+
+- [API Design & Error Handling](../02-Architecture/02-04-api-design.md)
+- [ADR-010: Logging & Monitoring Strategy](./ADR-010-logging-monitoring-strategy.md)
+- [Backend Guidelines](../05-Engineering-Guidelines/05-02-backend-guidelines.md)
+
+---
+
+## 🎯 Gap Analysis & Purpose
+
+### ปิด Gap จากเอกสาร:
+- **API Design & Error Handling** - Section 6: "ระบบต้องมี Global Exception Filter และ Custom Business Exceptions"
+  - เหตุผล: ต้องการบันทึกการตัดสินใจเกี่ยวกับ Error Handling Patterns ที่ใช้จริง
+- **Backend Guidelines** - Section 4: "การจัดการ Errors ต้องสอดคล้องกันและมีความหมายต่อ User"
+  - เหตุผล: ต้องการทำให้ Error Messages และ Recovery Patterns เป็นมาตรฐาน
+
+### แก้ไขความขัดแย้ง:
+- **Technical Details** vs **User Experience**: ต้องการ log technical errors แต่แสดง user-friendly messages
+  - การตัดสินใจนี้ช่วยแก้ไขโดย: แยก technical logging และ user-facing error messages
+
+---
+
+## Context and Problem Statement
+
+LCBP3-DMS ต้องการ Error Handling Strategy ที่:
+
+1. **Consistent:** ทุก Error ใช้ Formats และ Patterns เดียวกัน
+2. **User-Friendly:** Error messages เข้าใจง่ายสำหรับ non-technical users
+3. **Debuggable:** Technical details สำหรับ developers และ ops
+4. **Recoverable:** 用户提供 recovery options เมื่อเป็นไปได้
+5. **Secure:** ไม่เปิดเผย sensitive information ใน error responses
+
+### Key Challenges
+
+1. **Error Classification:** การจำแนกประเภท errors (validation, business, system)
+2. **Message Localization:** รองรับภาษาไทยและอังกฤษ
+3. **Recovery Guidance:** แนะนำ users ว่าควรทำอย่างไรต่อ
+4. **Cross-Module Consistency:** Errors จาก modules ต่างกันต้องสอดคล้อง
+5. **Performance Impact:** Error handling ไม่ควส่งผลกระทบ performance
+
+---
+
+## Decision Drivers
+
+- **User Experience:** Errors ไม่ควสร้างความสับสนหรือความกลัว
+- **Debuggability:** Developers สามารถหา root cause ได้เร็ว
+- **Security:** ไม่เปิดเผย internal details สู่ users
+- **Maintainability:** ง่ายต่อการ add new error types
+- **Compliance:** Audit trail สำหรับ errors และ recovery actions
+- **Performance:** Error handling ไม่ควส่งผลกระทบ response times
+
+---
+
+## Considered Options
+
+### Option 1: HTTP Status Codes Only
+
+**แนวทาง:** ใช้เพียง HTTP status codes และ generic messages
+
+**Pros:**
+
+- ✅ Simple implementation
+- ✅ Standard HTTP semantics
+- ✅ Low overhead
+
+**Cons:**
+
+- ❌ Limited error information
+- ❌ Poor user experience
+- ❌ Difficult debugging
+- ❌ No recovery guidance
+
+### Option 2: Custom Error Objects with Details
+
+**แนวทาง:** สร้าง custom error objects พร้อม detailed information
+
+**Pros:**
+
+- ✅ Rich error information
+- ✅ Better debugging
+- ✅ Recovery guidance possible
+
+**Cons:**
+
+- ❌ More complex implementation
+- ❌ Risk of information leakage
+- ❌ Larger response sizes
+
+### Option 3: **Layered Error Handling with Classification** ⭐ (Selected)
+
+**แนวทาง:** Classify errors และ provide appropriate detail levels
+
+**Pros:**
+
+- ✅ **Balanced Approach:** User-friendly + technical details
+- ✅ **Security:** Control information exposure by error type
+- ✅ **Recovery Focus:** Actionable error messages
+- ✅ **Consistency:** Standard patterns across modules
+- ✅ **Localization Ready:** Support for multiple languages
+
+**Cons:**
+
+- ❌ Requires error classification discipline
+- ❌ More initial setup
+
+---
+
+## Decision Outcome
+
+**Chosen Option:** Option 3 - Layered Error Handling with Classification
+
+### Rationale
+
+เลือก Layered Approach เนื่องจาก:
+
+1. **User-Centric:** Error messages ที่เข้าใจง่ายและมีประโยชน์
+2. **Developer-Friendly:** Technical details สำหรับ debugging
+3. **Security:** Controlled information exposure
+4. **Scalability:** ง่ายต่อการ add new error types
+5. **Compliance:** Audit trail สำหรับ error tracking
+
+---
+
+## 🔍 Impact Analysis
+
+### Affected Components (ส่วนประกอบที่ได้รับผลกระทบ)
+
+| Component | Level | Impact Description | Required Action |
+|-----------|-------|-------------------|-----------------|
+| **Global Exception Filter** | 🔴 High | Centralized error processing | Implement layered filter |
+| **Custom Exceptions** | 🔴 High | Business-specific error types | Create exception hierarchy |
+| **Error DTOs** | 🔴 High | Standardized error responses | Define response schemas |
+| **Frontend Error Handling** | 🟡 Medium | Parse and display errors appropriately | Update error UI components |
+| **Logging Strategy** | 🟡 Medium | Log appropriate detail levels | Integrate with ADR-010 |
+| **Documentation** | 🟡 Medium | Error catalog and handling guide | Create error reference |
+
+### Required Changes (การเปลี่ยนแปลงที่ต้องดำเนินการ)
+
+#### 🔴 Critical Changes (ต้องทำทันที)
+- [ ] **Create Exception Hierarchy** - base classes และ specific types
+- [ ] **Implement Global Filter** - layered error processing
+- [ ] **Define Error DTOs** - standardized response format
+- [ ] **Update All Controllers** - use new exception types
+
+#### 🟡 Important Changes (ควรทำภายใน 1 สัปดาห์)
+- [ ] **Create Error Catalog** - all possible errors และ recovery actions
+- [ ] **Update Frontend Error Handling** - parse and display appropriately
+- [ ] **Add Error Logging** - integrate with logging strategy
+- [ ] **Create Error Tests** - unit and integration tests
+
+#### 🟢 Nice-to-Have (ทำถ้ามีเวลา)
+- [ ] **Error Analytics** - track error rates and patterns
+- [ ] **Error Recovery UI** - guided recovery flows
+- [ ] **Error Localization** - Thai/English message support
+
+---
+
+## Implementation Details
+
+### Error Classification System
+
+#### Error Types
+
+```typescript
+export enum ErrorType {
+  // User Errors (400 range)
+  VALIDATION = 'VALIDATION',
+  BUSINESS_RULE = 'BUSINESS_RULE',
+  PERMISSION_DENIED = 'PERMISSION_DENIED',
+  NOT_FOUND = 'NOT_FOUND',
+  CONFLICT = 'CONFLICT',
+
+  // System Errors (500 range)
+  INTERNAL_ERROR = 'INTERNAL_ERROR',
+  DATABASE_ERROR = 'DATABASE_ERROR',
+  EXTERNAL_SERVICE = 'EXTERNAL_SERVICE',
+  INFRASTRUCTURE = 'INFRASTRUCTURE'
+}
+
+export enum ErrorSeverity {
+  LOW = 'LOW',       // User mistake, easy recovery
+  MEDIUM = 'MEDIUM', // Business rule violation, needs action
+  HIGH = 'HIGH',     // System issue, may need support
+  CRITICAL = 'CRITICAL' // System failure, immediate attention
+}
+```
+
+#### Exception Hierarchy
+
+```typescript
+// Base Exception
+export abstract class BaseException extends HttpException {
+  constructor(
+    public readonly type: ErrorType,
+    public readonly code: string,
+    public readonly message: string,
+    public readonly userMessage?: string,
+    public readonly severity: ErrorSeverity = ErrorSeverity.MEDIUM,
+    public readonly details?: any,
+    public readonly recoveryActions?: string[]
+  ) {
+    super(
+      {
+        error: {
+          type,
+          code,
+          message: userMessage || message,
+          severity,
+          timestamp: new Date().toISOString(),
+          ...(recoveryActions && { recoveryActions }),
+          ...(process.env.NODE_ENV === 'development' && {
+            technicalMessage: message,
+            details
+          })
+        }
+      },
+      getStatusCode(type)
+    );
+  }
+}
+
+// Validation Errors
+export class ValidationException extends BaseException {
+  constructor(message: string, details?: ValidationErrorDetail[]) {
+    super(
+      ErrorType.VALIDATION,
+      'VALIDATION_ERROR',
+      message,
+      'ข้อมูลที่กรอกไม่ถูกต้อง กรุณาตรวจสอบและลองใหม่',
+      ErrorSeverity.LOW,
+      details,
+      ['ตรวจสอบข้อมูลที่กรอก', 'แก้ไขข้อมูลที่ผิดพลาด', 'ลองใหม่อีกครั้ง']
+    );
+  }
+}
+
+// Business Rule Errors
+export class BusinessException extends BaseException {
+  constructor(code: string, message: string, userMessage?: string, recoveryActions?: string[]) {
+    super(
+      ErrorType.BUSINESS_RULE,
+      code,
+      message,
+      userMessage || 'ไม่สามารถดำเนินการได้เนื่องจากเงื่อนไขทางธุรกิจ',
+      ErrorSeverity.MEDIUM,
+      undefined,
+      recoveryActions || ['ติดต่อผู้ดูแลระบบ', 'ตรวจสอบเงื่อนไขการดำเนินการ']
+    );
+  }
+}
+
+// Permission Errors
+export class PermissionException extends BaseException {
+  constructor(resource: string, action: string) {
+    super(
+      ErrorType.PERMISSION_DENIED,
+      'PERMISSION_DENIED',
+      `User lacks permission for ${action} on ${resource}`,
+      `คุณไม่มีสิทธิ์${action} ${resource}`,
+      ErrorSeverity.MEDIUM,
+      { resource, action },
+      ['ติดต่อผู้ดูแลระบบเพื่อขอสิทธิ์', 'ลองใช้บัญชีที่มีสิทธิ์']
+    );
+  }
+}
+
+// System Errors
+export class SystemException extends BaseException {
+  constructor(message: string, details?: any) {
+    super(
+      ErrorType.INTERNAL_ERROR,
+      'INTERNAL_ERROR',
+      message,
+      'เกิดข้อผิดพลาดในระบบ กรุณาลองใหม่ภายหลัง',
+      ErrorSeverity.HIGH,
+      details,
+      ['ลองใหม่อีกครั้ง', 'ติดต่อผู้ดูแลระบบหากยังไม่ได้']
+    );
+  }
+}
+```
+
+### Global Exception Filter
+
+```typescript
+@Injectable()
+export class GlobalExceptionFilter implements ExceptionFilter {
+  private readonly logger = new Logger(GlobalExceptionFilter.name);
+
+  catch(exception: unknown, host: ArgumentsHost) {
+    const ctx = host.switchToHttp();
+    const response = ctx.getResponse();
+    const request = ctx.getRequest();
+
+    let errorResponse: any;
+
+    if (exception instanceof BaseException) {
+      // Handle our custom exceptions
+      errorResponse = exception.getResponse();
+      this.logError(exception, request, false);
+    } else if (exception instanceof HttpException) {
+      // Handle NestJS HTTP exceptions
+      const status = exception.getStatus();
+      const exceptionResponse = exception.getResponse();
+
+      errorResponse = {
+        error: {
+          type: this.getErrorType(status),
+          code: 'HTTP_ERROR',
+          message: this.getUserMessage(status),
+          severity: ErrorSeverity.MEDIUM,
+          timestamp: new Date().toISOString(),
+          ...(process.env.NODE_ENV === 'development' && {
+            technicalMessage: exception.message,
+            details: exceptionResponse
+          })
+        }
+      };
+      this.logError(exception, request, false);
+    } else {
+      // Handle unexpected errors
+      errorResponse = {
+        error: {
+          type: ErrorType.INTERNAL_ERROR,
+          code: 'UNEXPECTED_ERROR',
+          message: 'เกิดข้อผิดพลาดที่ไม่คาดคิด กรุณาลองใหม่ภายหลัง',
+          severity: ErrorSeverity.CRITICAL,
+          timestamp: new Date().toISOString()
+        }
+      };
+      this.logError(exception, request, true);
+    }
+
+    response.status(errorResponse.error.statusCode || 500).json(errorResponse);
+  }
+
+  private logError(exception: any, request: Request, isCritical: boolean) {
+    const logData = {
+      path: request.url,
+      method: request.method,
+      userId: request.user?.id,
+      ip: request.ip,
+      userAgent: request.headers['user-agent'],
+      body: request.body,
+      exception: {
+        name: exception.name,
+        message: exception.message,
+        stack: exception.stack,
+        details: exception.details
+      }
+    };
+
+    if (isCritical || exception.severity === ErrorSeverity.CRITICAL) {
+      this.logger.error('Critical error occurred', logData);
+    } else {
+      this.logger.warn('Error occurred', logData);
+    }
+  }
+
+  private getErrorType(status: number): ErrorType {
+    if (status === 400) return ErrorType.VALIDATION;
+    if (status === 401) return ErrorType.PERMISSION_DENIED;
+    if (status === 403) return ErrorType.PERMISSION_DENIED;
+    if (status === 404) return ErrorType.NOT_FOUND;
+    if (status === 409) return ErrorType.CONFLICT;
+    return ErrorType.INTERNAL_ERROR;
+  }
+
+  private getUserMessage(status: number): string {
+    switch (status) {
+      case 400: return 'ข้อมูลที่ส่งมาไม่ถูกต้อง';
+      case 401: return 'กรุณาเข้าสู่ระบบก่อนใช้งาน';
+      case 403: return 'คุณไม่มีสิทธิ์ในการดำเนินการนี้';
+      case 404: return 'ไม่พบข้อมูลที่ร้องขอ';
+      case 409: return 'ข้อมูลซ้ำกันหรือมีความขัดแย้ง';
+      default: return 'เกิดข้อผิดพลาดในระบบ';
+    }
+  }
+}
+```
+
+### Service Layer Error Handling
+
+```typescript
+@Injectable()
+export class CorrespondenceService {
+  constructor(
+    @InjectRepository(Correspondence)
+    private correspondenceRepo: Repository<Correspondence>,
+    private logger: Logger
+  ) {}
+
+  async create(createDto: CreateCorrespondenceDto, userId: number): Promise<Correspondence> {
+    try {
+      // Business validation
+      if (createDto.originatorId && !await this.canUserCreateForOrganization(userId, createDto.originatorId)) {
+        throw new PermissionException('correspondence', 'create for organization');
+      }
+
+      // Check for duplicate document number
+      if (await this.isDuplicateDocumentNumber(createDto.documentNumber)) {
+        throw new BusinessException(
+          'DUPLICATE_DOCUMENT_NUMBER',
+          `Document number ${createDto.documentNumber} already exists`,
+          'เลขที่เอกสารนี้มีอยู่แล้ว กรุณาใช้เลขที่อื่น',
+          ['ตรวจสอบเลขที่เอกสารล่าสุด', 'ขอเลขที่เอกสารใหม่']
+        );
+      }
+
+      // Create correspondence
+      const correspondence = this.correspondenceRepo.create({
+        ...createDto,
+        createdBy: userId,
+        createdAt: new Date()
+      });
+
+      const saved = await this.correspondenceRepo.save(correspondence);
+
+      this.logger.log(`Correspondence created: ${saved.id}`);
+      return saved;
+
+    } catch (error) {
+      if (error instanceof BaseException) {
+        throw error; // Re-throw our custom exceptions
+      }
+
+      // Handle database errors
+      if (error.code === 'ER_DUP_ENTRY') {
+        throw new BusinessException(
+          'DUPLICATE_ENTRY',
+          'Database constraint violation',
+          'ข้อมูลซ้ำกันในระบบ กรุณาตรวจสอบ'
+        );
+      }
+
+      // Handle unexpected errors
+      this.logger.error('Unexpected error in CorrespondenceService.create', error);
+      throw new SystemException('Failed to create correspondence', error);
+    }
+  }
+
+  async findOne(uuid: string, userId: number): Promise<Correspondence> {
+    const correspondence = await this.correspondenceRepo.findOne({
+      where: { uuid, deletedAt: IsNull() },
+      relations: ['type', 'originator', 'recipients']
+    });
+
+    if (!correspondence) {
+      throw new BusinessException(
+        'CORRESPONDENCE_NOT_FOUND',
+        `Correspondence with UUID ${uuid} not found`,
+        'ไม่พบเอกสารที่ค้นหา',
+        ['ตรวจสอบ UUID ที่ระบุ', 'ค้นหาเอกสารจากรายการ']
+      );
+    }
+
+    // Check permission
+    if (!await this.canUserView(correspondence, userId)) {
+      throw new PermissionException('correspondence', 'view');
+    }
+
+    return correspondence;
+  }
+}
+```
+
+### Frontend Error Handling
+
+```typescript
+// Error response type
+interface ErrorResponse {
+  error: {
+    type: string;
+    code: string;
+    message: string;
+    severity: string;
+    timestamp: string;
+    recoveryActions?: string[];
+    technicalMessage?: string;
+    details?: any;
+  };
+}
+
+// Error handler component
+export function ErrorDisplay({ error, onRetry }: { error: ErrorResponse; onRetry?: () => void }) {
+  const getSeverityColor = (severity: string) => {
+    switch (severity) {
+      case 'LOW': return 'text-yellow-600';
+      case 'MEDIUM': return 'text-orange-600';
+      case 'HIGH': return 'text-red-600';
+      case 'CRITICAL': return 'text-red-800';
+      default: return 'text-gray-600';
+    }
+  };
+
+  return (
+    <div className="rounded-lg border border-red-200 bg-red-50 p-4">
+      <div className="flex items-center">
+        <div className="flex-shrink-0">
+          <ExclamationTriangleIcon className="h-5 w-5 text-red-400" />
+        </div>
+        <div className="ml-3">
+          <h3 className={`text-sm font-medium ${getSeverityColor(error.error.severity)}`}>
+            {error.error.message}
+          </h3>
+
+          {error.error.recoveryActions && (
+            <div className="mt-2 text-sm text-gray-600">
+              <p className="font-medium">วิธีแก้ไข:</p>
+              <ul className="list-disc list-inside space-y-1">
+                {error.error.recoveryActions.map((action, index) => (
+                  <li key={index}>{action}</li>
+                ))}
+              </ul>
+            </div>
+          )}
+
+          <div className="mt-3 flex space-x-3">
+            {onRetry && (
+              <button
+                onClick={onRetry}
+                className="rounded bg-blue-600 px-3 py-1 text-sm text-white hover:bg-blue-700"
+              >
+                ลองใหม่
+              </button>
+            )}
+            <button className="rounded bg-gray-600 px-3 py-1 text-sm text-white hover:bg-gray-700">
+              ติดต่อผู้ดูแลระบบ
+            </button>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+// API service error handling
+export class ApiService {
+  async request<T>(config: AxiosRequestConfig): Promise<T> {
+    try {
+      const response = await axios.request<T>(config);
+      return response.data;
+    } catch (error) {
+      if (axios.isAxiosError(error) && error.response) {
+        const errorData = error.response.data as ErrorResponse;
+        throw errorData; // Re-throw structured error
+      }
+      throw {
+        error: {
+          type: 'INTERNAL_ERROR',
+          code: 'NETWORK_ERROR',
+          message: 'ไม่สามารถเชื่อมต่อกับเซิร์ฟเวอร์ได้',
+          severity: 'HIGH',
+          timestamp: new Date().toISOString(),
+          recoveryActions: ['ตรวจสอบการเชื่อมต่ออินเทอร์เน็ต', 'ลองใหม่ภายหลัง']
+        }
+      };
+    }
+  }
+}
+```
+
+### Error Catalog
+
+| Error Code | Type | User Message | Recovery Actions | Severity |
+|------------|------|--------------|------------------|----------|
+| `VALIDATION_ERROR` | Validation | ข้อมูลที่กรอกไม่ถูกต้อง | ตรวจสอบข้อมูล, แก้ไข, ลองใหม่ | LOW |
+| `DUPLICATE_DOCUMENT_NUMBER` | Business | เลขที่เอกสารซ้ำกัน | ตรวจสอบเลขล่าสุด, ขอเลขใหม่ | MEDIUM |
+| `CORRESPONDENCE_NOT_FOUND` | Business | ไม่พบเอกสาร | ตรวจสอบ UUID, ค้นหาใหม่ | MEDIUM |
+| `PERMISSION_DENIED` | Permission | ไม่มีสิทธิ์ดำเนินการ | ติดต่อ admin, ใช้บัญชีอื่น | MEDIUM |
+| `WORKFLOW_INVALID_TRANSITION` | Business | ไม่สามารถดำเนินการได้ในสถานะปัจจุบัน | ตรวจสอบ workflow, ดำเนินการอื่น | MEDIUM |
+| `INTERNAL_ERROR` | System | เกิดข้อผิดพลาดในระบบ | ลองใหม่, ติดต่อ admin | HIGH |
+| `DATABASE_ERROR` | System | ฐานข้อมูลมีปัญหา | ลองใหม่ภายหลัง, แจ้ง admin | HIGH |
+| `EXTERNAL_SERVICE` | System | บริการภายนอกมีปัญหา | ลองใหม่ภายหลัง | MEDIUM |
+
+---
+
+## Consequences
+
+### Positive
+
+1. ✅ **User Experience:** Clear, actionable error messages
+2. ✅ **Debuggability:** Technical details available when needed
+3. ✅ **Consistency:** Standard error handling across all modules
+4. ✅ **Security:** Controlled information exposure
+5. ✅ **Recovery:** Users know what to do when errors occur
+6. ✅ **Maintainability:** Easy to add new error types
+
+### Negative
+
+1. ❌ **Initial Complexity:** ต้อง setup exception hierarchy
+2. ❌ **Development Overhead:** ต้องคิด error messages และ recovery actions
+3. ❌ **Response Size:** Error responses ใหญ่ขึ้นเล็กน้อย
+
+### Mitigation Strategies
+
+- **Complexity:** Provide comprehensive templates and examples
+- **Development Overhead:** Create error catalog and guidelines
+- **Response Size:** Optimize and compress where needed
+
+---
+
+## 🔄 Review Cycle & Maintenance
+
+### Review Schedule
+- **Next Review:** 2026-10-04 (6 months from creation)
+- **Review Type:** Scheduled (Error Strategy Review)
+- **Reviewers:** System Architect, Backend Team Lead, Frontend Team Lead
+
+### Review Checklist
+- [ ] Error messages ยังเข้าใจง่ายสำหรับ users หรือไม่?
+- [ ] Recovery actions ยังมีประสิทธิภาพหรือไม่?
+- [ ] มี error patterns ใหม่ที่ควรเพิ่มหรือไม่?
+- [ ] ต้องการ update หรือ deprecate error types ใดหรือไม่?
+
+### Version History
+| Version | Date | Changes | Status |
+|---------|------|---------|--------|
+| 1.0 | 2026-04-04 | Initial version - Layered Error Handling Strategy | ✅ Accepted |
+
+---
+
+## Compliance
+
+เป็นไปตาม:
+
+- [API Design & Error Handling](../02-Architecture/02-04-api-design.md)
+- [ADR-010: Logging & Monitoring Strategy](./ADR-010-logging-monitoring-strategy.md)
+- [Backend Guidelines](../05-Engineering-Guidelines/05-02-backend-guidelines.md)
+
+---
+
+## Related ADRs
+
+- [ADR-010: Logging & Monitoring Strategy](./ADR-010-logging-monitoring-strategy.md) - Error logging
+- [ADR-003: API Design Strategy](./ADR-003-api-design-strategy.md) - Error response format
+- [ADR-016: Security Authentication](./ADR-016-security-authentication.md) - Permission errors
+
+---
+
+## References
+
+- [NestJS Exception Filters](https://docs.nestjs.com/exception-filters)
+- [HTTP Status Codes](https://httpstatuses.com/)
+- [Error Handling Best Practices](https://martinfowler.com/articles/error-handling-patterns.html)

specs/06-Decision-Records/ADR-008-email-notification-strategy.md

@@ -4,6 +4,63 @@
 **Date:** 2026-02-24
 **Decision Makers:** Backend Team, System Architect
 **Related Documents:** [Backend Guidelines](../03-implementation/03-02-backend-guidelines.md), [TASK-BE-011](../06-tasks/README.md)
+**Version Applicability:** v1.8.0+
+**Next Review:** 2026-08-01 (6-month cycle)
+
+---
+
+## Gap Analysis & Requirement Linking
+
+### ปิด Gap จาก Requirements:
+
+| Gap/Requirement | แหล่งที่มา | วิธีการแก้ไขใน ADR นี้ |
+|----------------|-------------|-------------------|
+| **Multi-Channel Notifications** | [Product Vision](../00-overview/00-03-product-vision.md) - Communication Requirements | BullMQ + Redis for Email, LINE, In-app |
+| **Performance Optimization** | [Acceptance Criteria](../01-Requirements/01-05-acceptance-criteria.md) - AC-PERF-001 | Async queue prevents API blocking |
+| **Reliability & Retry** | [Business Rules](../01-Requirements/01-02-business-rules/01-02-03-ui-ux-rules.md) - User Experience | BullMQ retry mechanism with exponential backoff |
+| **Template Management** | [Engineering Guidelines](../05-Engineering-Guidelines/05-02-backend-guidelines.md) - Maintainability | Handlebars templates with Git versioning |
+| **User Preferences** | [Edge Cases](../01-Requirements/01-06-edge-cases-and-rules.md) - User settings | Configurable notification channels |
+
+### แก้ไขความขัดแย้ง:
+
+- **Conflict:** Sync vs Async sending (Performance vs. Simplicity)
+- **Resolution:** Chose BullMQ for reliability and performance
+- **Trade-off:** Redis dependency vs. Robust notification system
+
+---
+
+## Impact Analysis
+
+### Affected Components (ส่วนประกอบที่ได้รับผลกระทบ):
+
+| Component | ผลกระทบ | ความสำคัญ |
+|-----------|----------|-----------|
+| **Notification Service** | Core notification logic | 🔴 Critical |
+| **Email Queue** | BullMQ queue setup | 🔴 Critical |
+| **Email Processor** | Queue worker implementation | 🔴 Critical |
+| **LINE Notify Queue** | LINE notification handling | 🟡 Important |
+| **Email Templates** | Handlebars template files | 🟡 Important |
+| **Workflow Integration** | Event → notification triggers | 🟡 Important |
+| **Redis Infrastructure** | Queue storage and management | 🔴 Critical |
+| **User Preferences** | Notification settings UI | 🟢 Guidelines |
+| **Monitoring Dashboard** | Bull Board for job monitoring | 🟢 Guidelines |
+
+### Required Changes (การเปลี่ยนแปลงที่ต้องดำเนินการ):
+
+#### Backend (NestJS)
+- [x] Setup BullMQ module with Redis connection
+- [x] Create NotificationService with queue management
+- [x] Implement EmailProcessor with Handlebars templates
+- [x] Add LINE Notify processor
+- [x] Integrate with workflow events
+- [x] Add retry logic and error handling
+- [x] Setup job monitoring (Bull Board)
+
+#### Infrastructure
+- [x] Configure Redis for queue persistence
+- [x] Setup SMTP credentials
+- [x] Create email template directory structure
+- [x] Configure LINE Notify API access
 
 ---
 
@@ -387,6 +444,35 @@ async notifyWorkflowTransition(
 
 ---
 
+## ADR Review Cycle
+
+### Core Principle Review Schedule
+- **Review Frequency:** ทุก 6 เดือน (กุมภาพันธ์ และ สิงหาคม)
+- **Trigger Events:**
+  - Major version upgrade (v1.9.0, v2.0.0)
+  - Notification channel requirements changes
+  - Queue performance issues
+  - New notification providers (LINE Notify v2, etc.)
+
+### Review Checklist
+- [ ] Queue performance metrics acceptable
+- [ ] Email delivery rates within SLA
+- [ ] Template system still meets requirements
+- [ ] Redis capacity and performance adequate
+- [ ] Cross-document dependencies still valid
+- [ ] New notification channels to consider
+- [ ] Security of notification data maintained
+
+### Version Dependency Matrix
+
+| System Version | ADR Version | Required Changes | Status |
+|----------------|-------------|------------------|---------|
+| v1.8.0 - v1.8.5 | ADR-008 v1.0 | Base BullMQ + Redis setup | ✅ Complete |
+| v1.9.0+ | ADR-008 v1.1 | Review queue performance and channels | 📋 Planned |
+| v2.0.0+ | ADR-008 v2.0 | Consider new notification patterns | 📋 Future |
+
+---
+
 ## Related ADRs
 
 - [ADR-006: Redis Caching Strategy](./ADR-006-redis-caching-strategy.md) - ใช้ Redis สำหรับ Queue
@@ -402,5 +488,16 @@ async notifyWorkflowTransition(
 
 ---
 
-**Last Updated:** 2025-12-01
-**Next Review:** 2025-06-01
+**Document Version:** v1.0
+**Last Updated:** 2026-02-24
+**Next Review:** 2026-08-01 (6-month cycle)
+**Version Applicability:** LCBP3 v1.8.0+
+
+---
+
+## Change History
+
+| Version | Date | Changes | Author |
+|---------|------|---------|---------|
+| v1.0 | 2026-02-24 | Initial ADR creation with notification strategy | Backend Team |
+| v1.1 | 2026-04-04 | Added structured templates: Impact Analysis, Gap Linking, Version Dependency, Review Cycle | System Architect |

specs/06-Decision-Records/ADR-009-database-migration-strategy.md

@@ -4,6 +4,65 @@
 **Date:** 2026-02-24
 **Decision Makers:** Backend Team, DevOps Team, System Architect
 **Related Documents:** [TASK-BE-001](../06-tasks/TASK-BE-015-schema-v160-migration.md), [ADR-005: Technology Stack](./ADR-005-technology-stack.md)
+**Version Applicability:** v1.8.0+
+**Next Review:** 2026-08-01 (6-month cycle)
+
+---
+
+## Gap Analysis & Requirement Linking
+
+### ปิด Gap จาก Requirements:
+
+| Gap/Requirement | แหล่งที่มา | วิธีการแก้ไขใน ADR นี้ |
+|----------------|-------------|-------------------|
+| **Schema Evolution** | [Product Vision](../00-overview/00-03-product-vision.md) - Data Integrity | TypeORM migrations with version control |
+| **Zero-Downtime Deployment** | [Acceptance Criteria](../01-Requirements/01-05-acceptance-criteria.md) - AC-DEPLOY-001 | Blue-Green deployment strategy |
+| **Data Safety** | [Business Rules](../01-Requirements/01-02-business-rules/01-02-02-doc-numbering-rules.md) - Document numbering | Rollback mechanism with backups |
+| **Team Collaboration** | [Engineering Guidelines](../05-Engineering-Guidelines/05-02-backend-guidelines.md) - Team workflows | Git-based migration collaboration |
+| **Auditability** | [Infrastructure OPS](../04-Infrastructure-OPS/04-04-deployment-guide.md) - Deployment tracking | Migration tracking table and CI/CD integration |
+
+### แก้ไขความขัดแย้ง:
+
+- **Conflict:** Simplicity vs. Safety (Synchronize vs. TypeORM Migrations)
+- **Resolution:** Chose TypeORM Migrations for production safety
+- **Trade-off:** Additional discipline required vs. Data protection
+
+---
+
+## Impact Analysis
+
+### Affected Components (ส่วนประกอบที่ได้รับผลกระทบ):
+
+| Component | ผลกระทบ | ความสำคัญ |
+|-----------|----------|-----------|
+| **Database Config** | TypeORM configuration with migrations | 🔴 Critical |
+| **Migration Files** | Version-controlled schema changes | 🔴 Critical |
+| **CI/CD Pipeline** | Automated migration execution | 🔴 Critical |
+| **Deployment Scripts** | Blue-Green deployment logic | 🔴 Critical |
+| **Database Backup** | Pre-migration backup strategy | 🔴 Critical |
+| **Migration Testing** | Test suite for migrations | 🟡 Important |
+| **Documentation** | Migration best practices guide | 🟢 Guidelines |
+| **Monitoring** | Migration execution monitoring | 🟢 Guidelines |
+
+### Required Changes (การเปลี่ยนแปลงที่ต้องดำเนินการ):
+
+#### Backend (NestJS)
+- [x] Configure TypeORM with migrations disabled
+- [x] Create migration workflow scripts
+- [x] Setup migration testing framework
+- [x] Implement migration rollback procedures
+- [x] Add migration health checks
+
+#### DevOps/Infrastructure
+- [x] Create database backup automation
+- [x] Setup Blue-Green deployment pipeline
+- [x] Configure migration execution in CI/CD
+- [x] Add migration monitoring and alerts
+
+#### Team Processes
+- [x] Define migration review checklist
+- [x] Document migration conflict resolution
+- [x] Create migration approval workflow
 
 ---
 
@@ -349,6 +408,35 @@ describe('Migrations', () => {
 
 ---
 
+## ADR Review Cycle
+
+### Core Principle Review Schedule
+- **Review Frequency:** ทุก 6 เดือน (กุมภาพันธ์ และ สิงหาคม)
+- **Trigger Events:**
+  - Major version upgrade (v1.9.0, v2.0.0)
+  - Complex schema changes requiring breaking migrations
+  - Database performance issues
+  - New TypeORM version compatibility
+
+### Review Checklist
+- [ ] Migration process still meeting safety requirements
+- [ ] Zero-downtime strategy effective
+- [ ] Rollback procedures tested and working
+- [ ] Team collaboration workflow smooth
+- [ ] Cross-document dependencies still valid
+- [ ] New database technologies or patterns to consider
+- [ ] Migration execution time within acceptable limits
+
+### Version Dependency Matrix
+
+| System Version | ADR Version | Required Changes | Status |
+|----------------|-------------|------------------|---------|
+| v1.8.0 - v1.8.5 | ADR-009 v1.0 | Base TypeORM migration setup | ✅ Complete |
+| v1.9.0+ | ADR-009 v1.1 | Review migration performance and tools | 📋 Planned |
+| v2.0.0+ | ADR-009 v2.0 | Consider new database patterns | 📋 Future |
+
+---
+
 ## Related ADRs
 
 - [ADR-005: Technology Stack](./ADR-005-technology-stack.md) - เลือกใช้ TypeORM
@@ -364,5 +452,16 @@ describe('Migrations', () => {
 
 ---
 
-**Last Updated:** 2025-12-01
-**Next Review:** 2025-06-01
+**Document Version:** v1.0
+**Last Updated:** 2026-02-24
+**Next Review:** 2026-08-01 (6-month cycle)
+**Version Applicability:** LCBP3 v1.8.0+
+
+---
+
+## Change History
+
+| Version | Date | Changes | Author |
+|---------|------|---------|---------|
+| v1.0 | 2026-02-24 | Initial ADR creation with migration strategy | Backend Team |
+| v1.1 | 2026-04-04 | Added structured templates: Impact Analysis, Gap Linking, Version Dependency, Review Cycle | System Architect |

specs/06-Decision-Records/ADR-010-logging-monitoring-strategy.md

@@ -4,6 +4,68 @@
 **Date:** 2026-02-24
 **Decision Makers:** Backend Team, DevOps Team
 **Related Documents:** [Backend Guidelines](../03-implementation/03-02-backend-guidelines.md)
+**Version Applicability:** v1.8.0+
+**Next Review:** 2026-08-01 (6-month cycle)
+
+---
+
+## Gap Analysis & Requirement Linking
+
+### ปิด Gap จาก Requirements:
+
+| Gap/Requirement | แหล่งที่มา | วิธีการแก้ไขใน ADR นี้ |
+|----------------|-------------|-------------------|
+| **Structured Logging** | [Product Vision](../00-overview/00-03-product-vision.md) - Operations Requirements | Winston with JSON format for searchability |
+| **Performance Monitoring** | [Acceptance Criteria](../01-Requirements/01-05-acceptance-criteria.md) - AC-PERF-002 | Request logging and performance interceptors |
+| **Error Tracking** | [Business Rules](../01-Requirements/01-02-business-rules/01-02-03-ui-ux-rules.md) - User Experience | Global exception filter with context |
+| **Audit Trail** | [Security ADR-016](./ADR-016-security-authentication.md) - Security events | Structured audit logging for compliance |
+| **Scalability** | [Architecture](../02-architecture/02-02-software-architecture.md) - Performance | Phase 2 ELK Stack for centralized logging |
+
+### แก้ไขความขัดแย้ง:
+
+- **Conflict:** Cost vs. Features (Winston vs. Full ELK Stack)
+- **Resolution:** Phased approach - Winston now, ELK later
+- **Trade-off:** Manual log search initially vs. Future centralized dashboard
+
+---
+
+## Impact Analysis
+
+### Affected Components (ส่วนประกอบที่ได้รับผลกระทบ):
+
+| Component | ผลกระทบ | ความสำคัำ |
+|-----------|----------|-----------|
+| **Logger Configuration** | Winston setup with transports | 🔴 Critical |
+| **NestJS Integration** | Custom logger service | 🔴 Critical |
+| **Request Middleware** | HTTP request logging | 🟡 Important |
+| **Exception Filter** | Global error logging | 🔴 Critical |
+| **Performance Interceptor** | Slow request detection | 🟡 Important |
+| **Database Logging** | Query performance tracking | 🟡 Important |
+| **Log Rotation** | File management strategy | 🟡 Important |
+| **Docker Logging** | Container log configuration | 🟢 Guidelines |
+| **Future ELK Stack** | Phase 2 centralized logging | 🟢 Guidelines |
+
+### Required Changes (การเปลี่ยนแปลงที่ต้องดำเนินการ):
+
+#### Backend (NestJS)
+- [x] Configure Winston with multiple transports
+- [x] Create custom NestJS logger service
+- [x] Implement request logging middleware
+- [x] Add global exception filter
+- [x] Create performance interceptor
+- [x] Configure database query logging
+- [x] Setup log rotation policies
+
+#### Infrastructure
+- [x] Configure Docker logging driver
+- [x] Setup log volume persistence
+- [x] Create log monitoring alerts
+- [x] Plan ELK Stack architecture (Phase 2)
+
+#### Development Process
+- [x] Define logging standards and best practices
+- [x] Create logging guidelines documentation
+- [x] Setup log analysis procedures
 
 ---
 
@@ -435,6 +497,35 @@ logger.add(
 
 ---
 
+## ADR Review Cycle
+
+### Core Principle Review Schedule
+- **Review Frequency:** ทุก 6 เดือน (กุมภาพันธ์ และ สิงหาคม)
+- **Trigger Events:**
+  - Major version upgrade (v1.9.0, v2.0.0)
+  - Log volume exceeds capacity
+  - Performance issues requiring deeper monitoring
+  - ELK Stack implementation (Phase 2)
+
+### Review Checklist
+- [ ] Logging strategy still meeting observability needs
+- [ ] Log storage and rotation policies effective
+- [ ] Performance monitoring providing adequate insights
+- [ ] Error tracking and alerting working properly
+- [ ] Cross-document dependencies still valid
+- [ ] New logging technologies or patterns to consider
+- [ ] ELK Stack implementation timeline and requirements
+
+### Version Dependency Matrix
+
+| System Version | ADR Version | Required Changes | Status |
+|----------------|-------------|------------------|---------|
+| v1.8.0 - v1.8.5 | ADR-010 v1.0 | Base Winston logging setup | ✅ Complete |
+| v1.9.0+ | ADR-010 v1.1 | Review logging performance and ELK readiness | 📋 Planned |
+| v2.0.0+ | ADR-010 v2.0 | Implement ELK Stack (Phase 2) | 📋 Future |
+
+---
+
 ## Related ADRs
 
 - [ADR-007: API Design & Error Handling](./ADR-007-api-design-error-handling.md)
@@ -450,5 +541,16 @@ logger.add(
 
 ---
 
-**Last Updated:** 2025-12-01
-**Next Review:** 2025-06-01
+**Document Version:** v1.0
+**Last Updated:** 2026-02-24
+**Next Review:** 2026-08-01 (6-month cycle)
+**Version Applicability:** LCBP3 v1.8.0+
+
+---
+
+## Change History
+
+| Version | Date | Changes | Author |
+|---------|------|---------|---------|
+| v1.0 | 2026-02-24 | Initial ADR creation with logging strategy | Backend Team |
+| v1.1 | 2026-04-04 | Added structured templates: Impact Analysis, Gap Linking, Version Dependency, Review Cycle | System Architect |

specs/06-Decision-Records/ADR-011-nextjs-app-router.md

@@ -4,6 +4,68 @@
 **Date:** 2025-12-01
 **Decision Makers:** Frontend Team, System Architect
 **Related Documents:** [Frontend Guidelines](../05-Engineering-Guidelines/05-03-frontend-guidelines.md), [ADR-005: Technology Stack](./ADR-005-technology-stack.md)
+**Version Applicability:** v1.8.0+
+**Next Review:** 2026-08-01 (6-month cycle)
+
+---
+
+## Gap Analysis & Requirement Linking
+
+### ปิด Gap จาก Requirements:
+
+| Gap/Requirement | แหล่งที่มา | วิธีการแก้ไขใน ADR นี้ |
+|----------------|-------------|-------------------|
+| **Modern Architecture** | [Product Vision](../00-overview/00-03-product-vision.md) - Technology Requirements | App Router with Server Components |
+| **Performance Optimization** | [Acceptance Criteria](../01-Requirements/01-05-acceptance-criteria.md) - AC-PERF-003 | Server Components reduce bundle size |
+| **Layout Management** | [Frontend Guidelines](../05-Engineering-Guidelines/05-03-frontend-guidelines.md) - Architecture | Built-in nested layout system |
+| **Future-Proofing** | [Engineering Guidelines](../05-Engineering-Guidelines/05-01-fullstack-js-guidelines.md) - Technology choices | Next.js recommended approach |
+| **Code Organization** | [Architecture](../02-architecture/02-02-software-architecture.md) - Frontend structure | Route groups and file-based routing |
+
+### แก้ไขความขัดแย้ง:
+
+- **Conflict:** Familiarity vs. Modern approach (Pages Router vs. App Router)
+- **Resolution:** Chose App Router for future-proofing and performance
+- **Trade-off:** Learning curve vs. Better performance and DX
+
+---
+
+## Impact Analysis
+
+### Affected Components (ส่วนประกอบที่ได้รับผลกระทบ):
+
+| Component | ผลกระทบ | ความสำคัญ |
+|-----------|----------|-----------|
+| **App Structure** | Complete folder reorganization | 🔴 Critical |
+| **Routing Logic** | File-based routing with groups | 🔴 Critical |
+| **Layout System** | Nested layouts with auth | 🔴 Critical |
+| **Data Fetching** | Server vs Client components | 🔴 Critical |
+| **State Management** | Integration with App Router | 🟡 Important |
+| **Form Handling** | Server Actions integration | 🟡 Important |
+| **Authentication** | Server-side auth checks | 🟡 Important |
+| **Component Library** | Server Component compatibility | 🟡 Important |
+| **Development Workflow** | New patterns and conventions | 🟢 Guidelines |
+
+### Required Changes (การเปลี่ยนแปลงที่ต้องดำเนินการ):
+
+#### Frontend (Next.js)
+- [x] Restructure app/ directory with route groups
+- [x] Implement root and nested layouts
+- [x] Convert pages to Server Components where appropriate
+- [x] Add 'use client' directives to interactive components
+- [x] Implement Server Actions for form handling
+- [x] Add loading and error boundary components
+- [x] Update authentication to server-side checks
+
+#### Development Process
+- [x] Train team on Server Components
+- [x] Document App Router patterns
+- [x] Update code review guidelines
+- [x] Create migration guide from Pages Router
+
+#### Integration
+- [x] Update state management for App Router
+- [x] Ensure UI library compatibility
+- [x] Test form handling with Server Actions
 
 ---
 
@@ -381,6 +443,35 @@ export default function Error({
 
 ---
 
+## ADR Review Cycle
+
+### Core Principle Review Schedule
+- **Review Frequency:** ทุก 6 เดือน (กุมภาพันธ์ และ สิงหาคม)
+- **Trigger Events:**
+  - Major Next.js version upgrade
+  - Performance issues with current implementation
+  - New App Router features or patterns
+  - Server Components ecosystem maturity
+
+### Review Checklist
+- [ ] App Router implementation meeting performance goals
+- [ ] Server/Client component separation effective
+- [ ] Layout system working as expected
+- [ ] Team adoption and productivity satisfactory
+- [ ] Cross-document dependencies still valid
+- [ ] New Next.js features to adopt
+- [ ] Bundle size and performance metrics acceptable
+
+### Version Dependency Matrix
+
+| System Version | ADR Version | Required Changes | Status |
+|----------------|-------------|------------------|---------|
+| v1.8.0 - v1.8.5 | ADR-011 v1.0 | Base App Router implementation | ✅ Complete |
+| v1.9.0+ | ADR-011 v1.1 | Review performance and adoption | 📋 Planned |
+| v2.0.0+ | ADR-011 v2.0 | Consider new Next.js patterns | 📋 Future |
+
+---
+
 ## Related ADRs
 
 - [ADR-005: Technology Stack](./ADR-005-technology-stack.md) - เลือกใช้ Next.js
@@ -395,5 +486,16 @@ export default function Error({
 
 ---
 
-**Last Updated:** 2025-12-01
-**Next Review:** 2026-06-01
+**Document Version:** v1.0
+**Last Updated:** 2026-02-24
+**Next Review:** 2026-08-01 (6-month cycle)
+**Version Applicability:** LCBP3 v1.8.0+
+
+---
+
+## Change History
+
+| Version | Date | Changes | Author |
+|---------|------|---------|---------|
+| v1.0 | 2025-12-01 | Initial ADR creation with App Router strategy | Frontend Team |
+| v1.1 | 2026-04-04 | Added structured templates: Impact Analysis, Gap Linking, Version Dependency, Review Cycle | System Architect |

specs/06-Decision-Records/ADR-012-ui-component-library.md

@@ -4,6 +4,63 @@
 **Date:** 2026-02-24
 **Decision Makers:** Frontend Team, UX Designer
 **Related Documents:** [Frontend Guidelines](../05-Engineering-Guidelines/05-03-frontend-guidelines.md), [ADR-005: Technology Stack](./ADR-005-technology-stack.md)
+**Version Applicability:** v1.8.0+
+**Next Review:** 2026-08-01 (6-month cycle)
+
+---
+
+## Gap Analysis & Requirement Linking
+
+### ปิด Gap จาก Requirements:
+
+| Gap/Requirement | แหล่งที่มา | วิธีการแก้ไขใน ADR นี้ |
+|----------------|-------------|-------------------|
+| **Design Consistency** | [Product Vision](../00-overview/00-03-product-vision.md) - UI/UX Requirements | Shadcn/UI for consistent design system |
+| **Accessibility Support** | [Acceptance Criteria](../01-Requirements/01-05-acceptance-criteria.md) - AC-UI-003 | Radix UI primitives for WCAG 2.1 AA |
+| **Performance Optimization** | [Frontend Guidelines](../05-Engineering-Guidelines/05-03-frontend-guidelines.md) - Performance | Tree-shakeable components, minimal bundle |
+| **Customization Flexibility** | [Engineering Guidelines](../05-Engineering-Guidelines/05-01-fullstack-js-guidelines.md) - DX | Full ownership of component code |
+| **Bundle Size Constraints** | [Architecture](../02-architecture/02-02-software-architecture.md) - Performance | Copy-only-what-you-use approach |
+
+### แก้ไขความขัดแย้ง:
+
+- **Conflict:** Library vs. Custom (MUI/Ant Design vs. Shadcn/UI)
+- **Resolution:** Chose Shadcn/UI for full control and minimal bundle
+- **Trade-off:** Manual updates vs. Complete customization freedom
+
+---
+
+## Impact Analysis
+
+### Affected Components (ส่วนประกอบที่ได้รับผลกระทบ):
+
+| Component | ผลกระทบ | ความสำคัญ |
+|-----------|----------|-----------|
+| **UI Components** | All UI components use Shadcn/UI | 🔴 Critical |
+| **Tailwind Config** | CSS variables and theming | 🔴 Critical |
+| **Component Library** | Custom component compositions | 🔴 Critical |
+| **Form Components** | Integration with React Hook Form | 🟡 Important |
+| **Layout Components** | Page layouts and navigation | 🟡 Important |
+| **Theme System** | Dark/light mode support | 🟡 Important |
+| **Component Testing** | Unit tests for custom components | 🟡 Important |
+| **Documentation** | Component usage guidelines | 🟢 Guidelines |
+| **Update Process** | Manual component update workflow | 🟢 Guidelines |
+
+### Required Changes (การเปลี่ยนแปลงที่ต้องดำเนินการ):
+
+#### Frontend (Next.js)
+- [x] Initialize Shadcn/UI project
+- [x] Add core components (Button, Input, Card, etc.)
+- [x] Setup Tailwind CSS with CSS variables
+- [x] Create custom component compositions
+- [x] Implement theme switching
+- [x] Update all pages to use new components
+- [x] Add component testing
+
+#### Design System
+- [x] Define design tokens and colors
+- [x] Create component usage guidelines
+- [x] Document customization patterns
+- [x] Setup component update workflow
 
 ---
 
@@ -409,6 +466,35 @@ export function CorrespondenceCard({ correspondence }) {
 
 ---
 
+## ADR Review Cycle
+
+### Core Principle Review Schedule
+- **Review Frequency:** ทุก 6 เดือน (กุมภาพันธ์ และ สิงหาคม)
+- **Trigger Events:**
+  - Major version upgrade (v1.9.0, v2.0.0)
+  - Shadcn/UI major updates
+  - New component requirements
+  - Accessibility standard updates
+
+### Review Checklist
+- [ ] Component library still meets design requirements
+- [ ] Bundle size within acceptable limits
+- [ ] Accessibility compliance maintained
+- [ ] Custom components properly documented
+- [ ] Cross-document dependencies still valid
+- [ ] New component libraries to consider
+- [ ] Component update workflow effective
+
+### Version Dependency Matrix
+
+| System Version | ADR Version | Required Changes | Status |
+|----------------|-------------|------------------|---------|
+| v1.8.0 - v1.8.5 | ADR-012 v1.0 | Base Shadcn/UI implementation | ✅ Complete |
+| v1.9.0+ | ADR-012 v1.1 | Review component updates and performance | 📋 Planned |
+| v2.0.0+ | ADR-012 v2.0 | Consider new UI patterns or libraries | 📋 Future |
+
+---
+
 ## Related ADRs
 
 - [ADR-005: Technology Stack](./ADR-005-technology-stack.md) - เลือกใช้ Tailwind CSS
@@ -424,5 +510,16 @@ export function CorrespondenceCard({ correspondence }) {
 
 ---
 
-**Last Updated:** 2025-12-01
-**Next Review:** 2026-06-01
+**Document Version:** v1.0
+**Last Updated:** 2026-02-24
+**Next Review:** 2026-08-01 (6-month cycle)
+**Version Applicability:** LCBP3 v1.8.0+
+
+---
+
+## Change History
+
+| Version | Date | Changes | Author |
+|---------|------|---------|---------|
+| v1.0 | 2026-02-24 | Initial ADR creation with UI component strategy | Frontend Team |
+| v1.1 | 2026-04-04 | Added structured templates: Impact Analysis, Gap Linking, Version Dependency, Review Cycle | System Architect |

specs/06-Decision-Records/ADR-013-form-handling-validation.md

@@ -4,6 +4,67 @@
 **Date:** 2026-02-24
 **Decision Makers:** Frontend Team
 **Related Documents:** [Frontend Guidelines](../05-Engineering-Guidelines/05-03-frontend-guidelines.md)
+**Version Applicability:** v1.8.0+
+**Next Review:** 2026-08-01 (6-month cycle)
+
+---
+
+## Gap Analysis & Requirement Linking
+
+### ปิด Gap จาก Requirements:
+
+| Gap/Requirement | แหล่งที่มา | วิธีการแก้ไขใน ADR นี้ |
+|----------------|-------------|-------------------|
+| **Form Validation** | [Product Vision](../00-overview/00-03-product-vision.md) - Data Integrity | React Hook Form + Zod validation |
+| **Performance Optimization** | [Acceptance Criteria](../01-Requirements/01-05-acceptance-criteria.md) - AC-UI-002 | Uncontrolled components for minimal re-renders |
+| **Type Safety** | [Engineering Guidelines](../05-Engineering-Guidelines/05-01-fullstack-js-guidelines.md) - TypeScript | Zod schema to TypeScript types |
+| **Developer Experience** | [Frontend Guidelines](../05-Engineering-Guidelines/05-03-frontend-guidelines.md) - DX | Clean API with minimal boilerplate |
+| **Bundle Size Constraints** | [Architecture](../02-architecture/02-02-software-architecture.md) - Performance | Lightweight solution (8.5kb) |
+
+### แก้ไขความขัดแย้ง:
+
+- **Conflict:** Performance vs. Developer Experience (Formik vs. RHF)
+- **Resolution:** Chose React Hook Form for performance and type safety
+- **Trade-off:** Learning curve for uncontrolled components vs. Better performance
+
+---
+
+## Impact Analysis
+
+### Affected Components (ส่วนประกอบที่ได้รับผลกระทบ):
+
+| Component | ผลกระทบ | ความสำคัญ |
+|-----------|----------|-----------|
+| **Form Components** | All forms use RHF + Zod | 🔴 Critical |
+| **Validation Schemas** | Zod schemas for all forms | 🔴 Critical |
+| **API Routes** | Server-side validation | 🔴 Critical |
+| **UI Components** | FormField wrapper components | 🟡 Important |
+| **File Upload** | RHF integration for file handling | 🟡 Important |
+| **Dynamic Forms** | useFieldArray for complex forms | 🟡 Important |
+| **Type Definitions** | Form types from Zod schemas | 🟡 Important |
+| **Testing Setup** | Form testing utilities | 🟢 Guidelines |
+| **Documentation** | Form patterns and examples | 🟢 Guidelines |
+
+### Required Changes (การเปลี่ยนแปลงที่ต้องดำเนินการ):
+
+#### Frontend (Next.js)
+- [x] Install React Hook Form + Zod
+- [x] Create validation schemas for all forms
+- [x] Update all form components to use RHF
+- [x] Create reusable FormField components
+- [x] Implement file upload with RHF
+- [x] Add dynamic form patterns (useFieldArray)
+- [x] Setup form testing utilities
+
+#### Backend (NestJS)
+- [x] Sync validation logic with frontend schemas
+- [x] Update DTOs to match Zod schemas
+- [x] Add proper error responses for validation failures
+
+#### Architecture
+- [x] Document form patterns
+- [x] Create form component templates
+- [x] Define validation strategy across stack
 
 ---
 
@@ -471,6 +532,35 @@ import { Controller } from 'react-hook-form';
 
 ---
 
+## ADR Review Cycle
+
+### Core Principle Review Schedule
+- **Review Frequency:** ทุก 6 เดือน (กุมภาพันธ์ และ สิงหาคม)
+- **Trigger Events:**
+  - Major version upgrade (v1.9.0, v2.0.0)
+  - Performance issues requiring form optimization
+  - New form patterns or requirements
+  - React Hook Form/Zod major updates
+
+### Review Checklist
+- [ ] Form performance metrics acceptable
+- [ ] Validation schemas still meet requirements
+- [ ] Type safety maintained across forms
+- [ ] Bundle size within limits
+- [ ] Cross-document dependencies still valid
+- [ ] New form libraries or patterns to consider
+- [ ] Backend validation sync maintained
+
+### Version Dependency Matrix
+
+| System Version | ADR Version | Required Changes | Status |
+|----------------|-------------|------------------|---------|
+| v1.8.0 - v1.8.5 | ADR-013 v1.0 | Base RHF + Zod implementation | ✅ Complete |
+| v1.9.0+ | ADR-013 v1.1 | Review form performance and patterns | 📋 Planned |
+| v2.0.0+ | ADR-013 v2.0 | Consider new form technologies | 📋 Future |
+
+---
+
 ## Related ADRs
 
 - [ADR-007: API Design & Error Handling](./ADR-007-api-design-error-handling.md)
@@ -485,5 +575,16 @@ import { Controller } from 'react-hook-form';
 
 ---
 
+**Document Version:** v1.0
 **Last Updated:** 2026-02-24
-**Next Review:** 2026-06-01
+**Next Review:** 2026-08-01 (6-month cycle)
+**Version Applicability:** LCBP3 v1.8.0+
+
+---
+
+## Change History
+
+| Version | Date | Changes | Author |
+|---------|------|---------|---------|
+| v1.0 | 2026-02-24 | Initial ADR creation with form handling strategy | Frontend Team |
+| v1.1 | 2026-04-04 | Added structured templates: Impact Analysis, Gap Linking, Version Dependency, Review Cycle | System Architect |

specs/06-Decision-Records/ADR-014-state-management.md

@@ -4,6 +4,64 @@
 **Date:** 2026-02-24
 **Decision Makers:** Frontend Team
 **Related Documents:** [Frontend Guidelines](../05-Engineering-Guidelines/05-03-frontend-guidelines.md), [ADR-011: App Router](./ADR-011-nextjs-app-router.md)
+**Version Applicability:** v1.8.0+
+**Next Review:** 2026-08-01 (6-month cycle)
+
+---
+
+## Gap Analysis & Requirement Linking
+
+### ปิด Gap จาก Requirements:
+
+| Gap/Requirement | แหล่งที่มา | วิธีการแก้ไขใน ADR นี้ |
+|----------------|-------------|-------------------|
+| **Global State Management** | [Product Vision](../00-overview/00-03-product-vision.md) - UI/UX Requirements | Zustand for client state |
+| **Server State Synchronization** | [Acceptance Criteria](../01-Requirements/01-05-acceptance-criteria.md) - AC-UI-001 | TanStack Query for API data |
+| **Performance Optimization** | [Frontend Guidelines](../05-Engineering-Guidelines/05-03-frontend-guidelines.md) - Performance | Selective re-renders with Zustand |
+| **Type Safety** | [Engineering Guidelines](../05-Engineering-Guidelines/05-01-fullstack-js-guidelines.md) - TypeScript | Full TypeScript support |
+| **Bundle Size Constraints** | [Architecture](../02-architecture/02-02-software-architecture.md) - Performance | Lightweight solutions (Zustand 1.2kb) |
+
+### แก้ไขความขัดแย้ง:
+
+- **Conflict:** Complexity vs. Features (Redux vs. Zustand)
+- **Resolution:** Chose Zustand + TanStack Query for simplicity and specialization
+- **Trade-off:** Smaller ecosystem vs. Better developer experience
+
+---
+
+## Impact Analysis
+
+### Affected Components (ส่วนประกอบที่ได้รับผลกระทบ):
+
+| Component | ผลกระทบ | ความสำคัญ |
+|-----------|----------|-----------|
+| **Auth Store** | User session management | 🔴 Critical |
+| **Notification Store** | Global notifications | 🔴 Critical |
+| **UI Store** | Theme and preferences | 🟡 Important |
+| **API Client** | TanStack Query integration | 🔴 Critical |
+| **Form Components** | React Hook Form + Zod | 🟡 Important |
+| **Server Components** | Data fetching patterns | 🟡 Important |
+| **Component Structure** | 'use client' directives | 🟡 Important |
+| **Testing Setup** | Store testing patterns | 🟢 Guidelines |
+| **Documentation** | State management patterns | 🟢 Guidelines |
+
+### Required Changes (การเปลี่ยนแปลงที่ต้องดำเนินการ):
+
+#### Frontend (Next.js)
+- [x] Install Zustand and TanStack Query
+- [x] Create auth store with persistence
+- [x] Create notification store
+- [x] Create UI preferences store
+- [x] Setup Query Provider
+- [x] Update components to use stores
+- [x] Add 'use client' directives where needed
+- [x] Implement form validation with RHF + Zod
+
+#### Architecture
+- [x] Define state management patterns
+- [x] Document when to use each solution
+- [x] Create store templates
+- [x] Setup testing utilities for stores
 
 ---
 
@@ -381,6 +439,35 @@ export const useUIStore = create<UIState>()(
 
 ---
 
+## ADR Review Cycle
+
+### Core Principle Review Schedule
+- **Review Frequency:** ทุก 6 เดือน (กุมภาพันธ์ และ สิงหาคม)
+- **Trigger Events:**
+  - Major version upgrade (v1.9.0, v2.0.0)
+  - Performance issues requiring state management changes
+  - New React/Next.js features affecting state
+  - Bundle size optimization requirements
+
+### Review Checklist
+- [ ] State management patterns still meet requirements
+- [ ] Bundle size within acceptable limits
+- [ ] Performance metrics acceptable (re-render counts)
+- [ ] Type safety maintained across stores
+- [ ] Cross-document dependencies still valid
+- [ ] New state management libraries to consider
+- [ ] Testing coverage for stores adequate
+
+### Version Dependency Matrix
+
+| System Version | ADR Version | Required Changes | Status |
+|----------------|-------------|------------------|---------|
+| v1.8.0 - v1.8.5 | ADR-014 v1.0 | Base Zustand + TanStack Query setup | ✅ Complete |
+| v1.9.0+ | ADR-014 v1.1 | Review bundle size and performance | 📋 Planned |
+| v2.0.0+ | ADR-014 v2.0 | Consider new React state patterns | 📋 Future |
+
+---
+
 ## Related ADRs
 
 - [ADR-011: Next.js App Router](./ADR-011-nextjs-app-router.md) - Server Components
@@ -396,5 +483,16 @@ export const useUIStore = create<UIState>()(
 
 ---
 
+**Document Version:** v1.0
 **Last Updated:** 2026-02-24
-**Next Review:** 2026-06-01
+**Next Review:** 2026-08-01 (6-month cycle)
+**Version Applicability:** LCBP3 v1.8.0+
+
+---
+
+## Change History
+
+| Version | Date | Changes | Author |
+|---------|------|---------|---------|
+| v1.0 | 2026-02-24 | Initial ADR creation with state management strategy | Frontend Team |
+| v1.1 | 2026-04-04 | Added structured templates: Impact Analysis, Gap Linking, Version Dependency, Review Cycle | System Architect |

specs/06-Decision-Records/ADR-015-deployment-infrastructure.md

@@ -4,6 +4,67 @@
 **Date:** 2026-02-24
 **Decision Makers:** DevOps Team, System Architect
 **Related Documents:** [ADR-005: Technology Stack](./ADR-005-technology-stack.md), [Operations Guide](../04-Infrastructure-OPS/04-04-deployment-guide.md), [Docker Compose Setup](../04-Infrastructure-OPS/04-01-docker-compose.md)
+**Version Applicability:** v1.8.0+
+**Next Review:** 2026-08-01 (6-month cycle)
+
+---
+
+## Gap Analysis & Requirement Linking
+
+### ปิด Gap จาก Requirements:
+
+| Gap/Requirement | แหล่งที่มา | วิธีการแก้ไขใน ADR นี้ |
+|----------------|-------------|-------------------|
+| **Deployment Strategy** | [Product Vision](../00-overview/00-03-product-vision.md) - Infrastructure Requirements | Docker Compose + Blue-Green on QNAP |
+| **Zero Downtime** | [Acceptance Criteria](../01-Requirements/01-05-acceptance-criteria.md) - AC-DEPLOY-001 | Blue-Green deployment with NGINX proxy |
+| **Resource Constraints** | [Infrastructure OPS](../04-Infrastructure-OPS/04-01-docker-compose.md) - QNAP limitations | Single-server Docker Compose (not K8s) |
+| **Rollback Capability** | [Edge Cases](../01-Requirements/01-06-edge-cases-and-rules.md) - Deployment failures | Tagged images + NGINX switchback |
+| **Environment Management** | [Security ADR-016](./ADR-016-security-authentication.md) - Secrets management | .env files on QNAP only |
+
+### แก้ไขความขัดแย้ง:
+
+- **Conflict:** Complexity vs. Reliability (Docker Compose vs Kubernetes)
+- **Resolution:** Chose Docker Compose for QNAP compatibility, added Blue-Green for reliability
+- **Trade-off:** Manual scaling vs. Resource efficiency
+
+---
+
+## Impact Analysis
+
+### Affected Components (ส่วนประกอบที่ได้รับผลกระทบ):
+
+| Component | ผลกระทบ | ความสำคัญ |
+|-----------|----------|-----------|
+| **Docker Compose Files** | Blue/Green structure + NGINX proxy | 🔴 Critical |
+| **Deployment Scripts** | deploy.sh with health checks | 🔴 Critical |
+| **Environment Config** | .env management strategy | 🔴 Critical |
+| **QNAP Storage** | Volume mounting strategy | 🔴 Critical |
+| **NGINX Configuration** | Reverse proxy setup | 🟡 Important |
+| **CI/CD Pipeline** | Gitea Actions integration | 🟡 Important |
+| **Monitoring Setup** | Health check endpoints | 🟡 Important |
+| **Backup Strategy** | Database backup automation | 🟡 Important |
+| **Documentation** | Deployment runbooks | 🟢 Guidelines |
+
+### Required Changes (การเปลี่ยนแปลงที่ต้องดำเนินการ):
+
+#### Infrastructure (QNAP)
+- [x] Create blue/green directory structure
+- [x] Setup shared volumes for uploads/logs
+- [x] Configure NGINX reverse proxy
+- [x] Implement deployment scripts
+- [x] Setup environment variables management
+
+#### Application (Backend/Frontend)
+- [x] Add health check endpoints
+- [x] Implement graceful shutdown
+- [x] Add startup validation for required env vars
+- [x] Configure logging to shared volume
+
+#### Operations
+- [x] Create deployment checklist
+- [x] Setup backup automation
+- [x] Document rollback procedures
+- [x] Configure monitoring alerts
 
 ---
 
@@ -440,6 +501,35 @@ server {
 
 ---
 
+## ADR Review Cycle
+
+### Core Principle Review Schedule
+- **Review Frequency:** ทุก 6 เดือน (กุมภาพันธ์ และ สิงหาคม)
+- **Trigger Events:**
+  - Major version upgrade (v1.9.0, v2.0.0)
+  - QNAP Container Station updates
+  - Performance issues requiring scaling changes
+  - Security updates affecting deployment
+
+### Review Checklist
+- [ ] Blue-Green deployment still meets zero-downtime requirements
+- [ ] Resource allocation matches current load
+- [ ] Security best practices still current
+- [ ] QNAP compatibility maintained
+- [ ] Cross-document dependencies still valid
+- [ ] New deployment tools/practices to consider
+- [ ] Backup and recovery procedures tested
+
+### Version Dependency Matrix
+
+| System Version | ADR Version | Required Changes | Status |
+|----------------|-------------|------------------|---------|
+| v1.8.0 - v1.8.5 | ADR-015 v1.0 | Base Docker Compose setup | ✅ Complete |
+| v1.9.0+ | ADR-015 v1.1 | Review resource allocation | 📋 Planned |
+| v2.0.0+ | ADR-015 v2.0 | Consider horizontal scaling | 📋 Future |
+
+---
+
 ## Related ADRs
 
 - [ADR-005: Technology Stack](./ADR-005-technology-stack.md)
@@ -455,5 +545,16 @@ server {
 
 ---
 
+**Document Version:** v1.0
 **Last Updated:** 2026-02-24
-**Next Review:** 2026-06-01
+**Next Review:** 2026-08-01 (6-month cycle)
+**Version Applicability:** LCBP3 v1.8.0+
+
+---
+
+## Change History
+
+| Version | Date | Changes | Author |
+|---------|------|---------|---------|
+| v1.0 | 2026-02-24 | Initial ADR creation with deployment strategy | DevOps Team |
+| v1.1 | 2026-04-04 | Added structured templates: Impact Analysis, Gap Linking, Version Dependency, Review Cycle | System Architect |

specs/06-Decision-Records/ADR-016-security-authentication.md

@@ -4,6 +4,67 @@
 **Date:** 2026-02-24
 **Decision Makers:** Security Team, System Architect
 **Related Documents:** [ADR-004: RBAC Implementation](./ADR-004-rbac-implementation.md), [ADR-007: API Design](./ADR-007-api-design-error-handling.md)
+**Version Applicability:** v1.8.0+
+**Next Review:** 2026-08-01 (6-month cycle)
+
+---
+
+## Gap Analysis & Requirement Linking
+
+### ปิด Gap จาก Requirements:
+
+| Gap/Requirement | แหล่งที่มา | วิธีการแก้ไขใน ADR นี้ |
+|----------------|-------------|-------------------|
+| **Authentication & Authorization** | [Product Vision](../00-overview/00-03-product-vision.md) - Security Requirements | JWT + RBAC 4-level implementation |
+| **Data Protection** | [Acceptance Criteria](../01-Requirements/01-05-acceptance-criteria.md) - AC-SEC-001 | AES-256 encryption at rest + HTTPS in transit |
+| **Audit Trail** | [Business Rules](../01-Requirements/01-02-business-rules/01-02-01-rbac-matrix.md) | Comprehensive security event logging |
+| **Session Management** | [Edge Cases](../01-Requirements/01-06-edge-cases-and-rules.md) - Session timeout | Stateless JWT + 15min access token expiry |
+| **Input Validation** | [API Design](../02-architecture/02-04-api-design.md) - Validation layer | Class-validator + Zod + Sanitization |
+
+### แก้ไขความขัดแย้ง:
+
+- **Conflict:** Cross-domain authentication complexity vs. User Experience
+- **Resolution:** Chose Bearer tokens over HTTP-only cookies for Next.js ↔ NestJS communication
+- **Trade-off:** Slightly reduced XSS protection for improved developer experience
+
+---
+
+## Impact Analysis
+
+### Affected Components (ส่วนประกอบที่ได้รับผลกระทบ):
+
+| Component | ผลกระทบ | ความสำคัญ |
+|-----------|----------|-----------|
+| **Backend Auth Module** | JWT implementation + Guards | 🔴 Critical |
+| **Frontend Auth Store** | Zustand token management | 🔴 Critical |
+| **Database Schema** | refresh_tokens table | 🔴 Critical |
+| **API Controllers** | @UseGuards(JwtAuthGuard) | 🟡 Important |
+| **Middleware** | Helmet + CORS configuration | 🟡 Important |
+| **User Service** | Password hashing with bcrypt | 🟡 Important |
+| **Audit Log Service** | Security event tracking | 🟡 Important |
+| **Frontend Login Page** | Token storage logic | 🟢 Guidelines |
+| **Environment Config** | JWT secrets + Encryption keys | 🔴 Critical |
+
+### Required Changes (การเปลี่ยนแปลงที่ต้องดำเนินการ):
+
+#### Backend (NestJS)
+- [x] Implement AuthService with JWT
+- [x] Create JwtAuthGuard
+- [x] Add refresh_tokens entity
+- [x] Configure Helmet + CORS
+- [x] Add rate limiting (Throttler)
+- [x] Implement audit logging
+
+#### Frontend (Next.js)
+- [x] Create auth store (Zustand)
+- [x] Update API client with Bearer token
+- [x] Add token refresh logic
+- [x] Update login/logout flows
+
+#### Infrastructure
+- [x] Environment variables for secrets
+- [x] HTTPS/TLS configuration
+- [x] Database encryption setup
 
 ---
 
@@ -427,6 +488,35 @@ await this.auditLogService.create({
 
 ---
 
+## ADR Review Cycle
+
+### Core Principle Review Schedule
+- **Review Frequency:** ทุก 6 เดือน (กุมภาพันธ์ และ สิงหาคม)
+- **Trigger Events:**
+  - Major version upgrade (v1.9.0, v2.0.0)
+  - Security vulnerability discovery
+  - New compliance requirements
+  - Architecture changes affecting auth
+
+### Review Checklist
+- [ ] JWT configuration still meets security standards
+- [ ] Password policy alignment with current threats
+- [ ] Rate limiting effectiveness
+- [ ] Audit log completeness
+- [ ] Cross-document dependencies still valid
+- [ ] Implementation matches documented decisions
+- [ ] New security best practices to consider
+
+### Version Dependency Matrix
+
+| System Version | ADR Version | Required Changes | Status |
+|----------------|-------------|------------------|---------|
+| v1.8.0 - v1.8.5 | ADR-016 v1.0 | Base implementation | ✅ Complete |
+| v1.9.0+ | ADR-016 v1.1 | Review JWT expiry times | 📋 Planned |
+| v2.0.0+ | ADR-016 v2.0 | Consider session management changes | 📋 Future |
+
+---
+
 ## Related ADRs
 
 - [ADR-004: RBAC Implementation](./ADR-004-rbac-implementation.md)
@@ -443,5 +533,16 @@ await this.auditLogService.create({
 
 ---
 
+**Document Version:** v1.0
 **Last Updated:** 2026-02-24
-**Next Review:** 2026-06-01 (Quarterly review)
+**Next Review:** 2026-08-01 (6-month cycle)
+**Version Applicability:** LCBP3 v1.8.0+
+
+---
+
+## Change History
+
+| Version | Date | Changes | Author |
+|---------|------|---------|---------|
+| v1.0 | 2026-02-24 | Initial ADR creation with security strategy | Security Team |
+| v1.1 | 2026-04-04 | Added structured templates: Impact Analysis, Gap Linking, Version Dependency, Review Cycle | System Architect |

specs/06-Decision-Records/ADR-017-ollama-data-migration.md

@@ -3,7 +3,15 @@
 **Status:** Accepted
 **Date:** 2026-02-26
 **Version:** 1.8.3 (Aligned with ADR-020)
+**Review Cycle:** Core ADR (Review every 6 months or Major Version upgrade)
 **Decision Makers:** Development Team, DevOps Engineer, AI Integration Lead
+**Gap Resolution:** Addresses legacy document migration challenges (20,000+ PDFs) and data integrity validation requirements (Product Vision v1.8.5, Section 3.1) and migration acceptance criteria (UAT Criteria, Section 4.6)
+**Version Dependency:**
+- **Effective From:** v1.8.3
+- **Applies To:** v1.8.3+ (Migration execution)
+- **Backward Compatible:** v1.8.0+ (Migration planning)
+- **Required For:** v1.9.0+ (Legacy data completion)
+
 **Related Documents:**
 
 - [ADR-020: AI Intelligence Integration Architecture](./ADR-020-ai-intelligence-integration.md) — Overall AI Architecture & RFA-First Strategy
@@ -85,7 +93,51 @@
 
 **Chosen Option:** Option 3 — Local AI Model (Ollama) + n8n
 
-**Rationale:** ประยุกต์ใช้ Hardware ที่มีอยู่ โดยไม่ขัดหลัก Privacy และ Security ของโครงการ n8n ช่วยลด Risk ที่จะกระทบ Core Backend และรองรับ Checkpoint/Resume ได้ดีกว่าการเขียน Script เอง
+**Rationale:**
+
+ประยุกต์ใช้ Hardware ที่มีอยู่ โดยไม่ขัดหลัก Privacy และ Security ของโครงการ n8n ช่วยลด Risk ที่จะกระทบ Core Backend และรองรับ Checkpoint/Resume ได้ดีกว่าการเขียน Script เอง
+
+---
+
+## Impact Analysis
+
+### Affected Components
+
+| Component | Impact Level | Description |
+|-----------|--------------|-------------|
+| **Migration Infrastructure** | **High** | n8n workflows, Ollama AI services, Admin Desktop setup |
+| **Database Schema** | **High** | Migration tables, audit logs, staging areas |
+| **Backend Services** | **High** | Migration APIs, validation services, storage integration |
+| **Storage Systems** | **Medium** | Two-phase storage, file management, cleanup processes |
+| **Security Model** | **Medium** | Migration tokens, IP whitelisting, audit trails |
+| **Frontend Interface** | **Medium** | Migration dashboard, review queues, approval workflows |
+| **Monitoring & Logging** | **Medium** | Migration progress tracking, error handling, performance metrics |
+| **Documentation** | **Low** | Migration procedures, troubleshooting guides |
+
+### Required Changes
+
+| Change Category | Specific Changes | Priority |
+|----------------|------------------|----------|
+| **Infrastructure** | <ul><li>Setup n8n on QNAP NAS with Docker</li><li>Install Ollama with Gemma 4 on Admin Desktop</li><li>Configure PaddleOCR service for Thai text extraction</li><li>Setup network segmentation and AI isolation per ADR-018</li><li>Configure GPU monitoring and temperature controls</li></ul> | **Critical** |
+| **Database** | <ul><li>Create migration_logs table with UUIDv7 primary keys</li><li>Create migration_review_queue staging table</li><li>Create import_transactions audit table</li><li>Create migration_progress tracking table</li><li>Setup migration_fallback_state table</li></ul> | **Critical** |
+| **Backend** | <ul><li>Implement MigrationService with business logic</li><li>Create AI validation layer with confidence thresholds</li><li>Add migration-specific API endpoints with CASL guards</li><li>Implement idempotency handling for migration requests</li><li>Create storage service integration for two-phase file handling</li></ul> | **Critical** |
+| **Security** | <ul><li>Implement migration token system with 7-day expiry</li><li>Setup IP whitelisting for migration services</li><li>Configure rate limiting for migration endpoints</li><li>Create comprehensive audit logging for migration operations</li><li>Implement Nginx security rules for migration access</li></ul> | **High** |
+| **Storage** | <ul><li>Implement two-phase storage (temp → permanent)</li><li>Create migration-specific storage paths</li><li>Setup file cleanup and archival processes</li><li>Implement storage service integration</li><li>Create file validation and virus scanning workflows</li></ul> | **High** |
+| **Frontend** | <ul><li>Build migration dashboard with queue management</li><li>Create review interface for AI suggestions</li><li>Implement bulk approval/rejection workflows</li><li>Add progress tracking and monitoring displays</li><li>Create error handling and retry interfaces</li></ul> | **Medium** |
+| **Monitoring** | <ul><li>Setup migration progress tracking and metrics</li><li>Implement AI service health monitoring</li><li>Create error logging and alerting systems</li><li>Setup performance monitoring for migration workflows</li><li>Create GPU temperature and resource monitoring</li></ul> | **Medium** |
+| **Documentation** | <ul><li>Create migration operation procedures</li><li>Document troubleshooting and recovery processes</li><li>Create admin training materials</li><li>Update API documentation with migration endpoints</li><li>Create rollback and recovery guides</li></ul> | **Medium** |
+
+### Cross-Component Dependencies
+
+| Dependency | Source | Target | Impact |
+|------------|--------|--------|--------|
+| **n8n → Backend API** | Migration workflows | Validation endpoints | Data processing |
+| **AI Services → Backend** | Ollama processing | AI validation layer | Quality control |
+| **Migration Service → Storage** | Data processing | Two-phase storage | File management |
+| **Frontend → Migration API** | Dashboard interface | Migration endpoints | User interaction |
+| **Audit → Migration** | Logging service | Migration audit trail | Compliance tracking |
+| **Monitoring → Infrastructure** | Health checks | AI and n8n services | Operational stability |
+| **Security → Migration** | Token validation | Migration access control | Access management |
 
 ---
 
@@ -392,9 +444,112 @@ _สำหรับขั้นตอนปฏิบัติงานแบบ
 
 ---
 
+## ADR Review Cycle
+
+### Review Classification
+
+**Core ADR Status:** This ADR is classified as a **Core Migration Architecture** due to its fundamental impact on data migration strategy and AI integration patterns.
+
+### Review Schedule
+
+| Review Type | Frequency | Trigger | Scope |
+|-------------|-----------|---------|-------|
+| **Regular Review** | Every 6 months | Calendar-based | Migration effectiveness, AI accuracy |
+| **Major Version Review** | Every major version (v2.0.0, v3.0.0) | Version planning | Architecture relevance, new migration requirements |
+| **Migration Review** | During migration execution | Migration progress | Performance, accuracy, operational issues |
+| **Post-Migration Review** | After migration completion | Migration completion | Lessons learned, improvements, retirement planning |
+
+### Review Process
+
+#### Phase 1: Preparation (1 week before review)
+1. **Migration Metrics Collection**
+   - Migration progress and completion rates
+   - AI validation accuracy and confidence scores
+   - Error rates and failure patterns
+   - Processing performance benchmarks
+   - Storage and resource utilization metrics
+
+2. **Stakeholder Notification**
+   - Development Team
+   - DevOps Engineer
+   - AI Integration Lead
+   - Database Administrator
+   - Project Management
+
+#### Phase 2: Review Meeting (2-hour session)
+1. **Migration Performance Assessment**
+   - Review migration progress against targets
+   - Analyze AI validation accuracy and effectiveness
+   - Evaluate processing speed and resource utilization
+   - Assess error handling and recovery procedures
+
+2. **Data Quality Evaluation**
+   - Review AI validation accuracy against human verification
+   - Analyze data integrity and consistency metrics
+   - Evaluate duplicate detection and handling
+   - Assess revision drift protection effectiveness
+
+3. **Operational Assessment**
+   - Review system stability and reliability
+   - Evaluate monitoring and alerting effectiveness
+   - Assess rollback and recovery procedures
+   - Review security compliance and audit trails
+
+#### Phase 3: Decision & Documentation (1 week after review)
+1. **Review Outcomes**
+   - **No Change:** Migration architecture remains effective
+   - **Update Required:** Adjust AI parameters or migration procedures
+   - **Enhancement:** Add new migration capabilities or optimizations
+   - **Retire:** Migration complete, ADR no longer needed
+
+2. **Documentation Updates**
+   - Update migration procedures and guidelines
+   - Revise performance benchmarks and targets
+   - Document lessons learned and best practices
+   - Update operational procedures and troubleshooting guides
+
+### Review Criteria
+
+| Criterion | Question | Pass/Fail Threshold |
+|-----------|----------|---------------------|
+| **Migration Progress** | Is migration meeting completion targets? | Pass: ≥90% of target, Fail: <90% |
+| **AI Validation Accuracy** | Is AI validation meeting accuracy targets? | Pass: ≥85% accuracy, Fail: <85% |
+| **Processing Performance** | Are processing times within acceptable limits? | Pass: <3s per record, Fail: >3s |
+| **Data Integrity** | Are data integrity issues within acceptable limits? | Pass: <2% errors, Fail: ≥2% |
+| **System Stability** | Is migration system stable and reliable? | Pass: >99% uptime, Fail: <99% |
+| **Security Compliance** | Are all security controls functioning properly? | Pass: 100% compliant, Fail: Any violations |
+
+### Review History Template
+
+```
+## Review Cycle [YYYY-MM-DD]
+
+**Review Type:** [Regular/Major Version/Migration/Post-Migration]
+**Reviewers:** [Names and roles]
+**Duration:** [Meeting date]
+
+### Findings
+- [Key findings from migration performance and data quality assessment]
+
+### Issues Identified
+- [Performance bottlenecks, accuracy problems, or operational issues]
+
+### Recommendations
+- [Migration optimizations, AI improvements, or procedural changes]
+
+### Outcome
+- [No Change/Update Required/Enhancement/Retire]
+
+### Next Review Date
+- [YYYY-MM-DD]
+```
+
+---
+
 ## Document History
 
 | Version | Date       | Author      | Changes                                                              |
 | ------- | ---------- | ----------- | -------------------------------------------------------------------- |
 | 1.8.0   | 2026-02-26 | DevOps Team | Initial ADR — Ollama + n8n Migration Architecture                    |
 | 1.8.2   | 2026-04-03 | Tech Lead   | **Updated** — Aligned with ADR-019 (UUID Strategy), changed AI Model to `gemma4:9b` (9.6 GB) |
+| 1.8.4   | 2026-04-04 | System Architect | **Enhanced** — Added Impact Analysis template, ADR Review Cycle process, Gap Linking to requirements, and Version Dependency tracking |

specs/06-Decision-Records/ADR-017B-ai-document-classification.md

@@ -1,9 +1,17 @@
-# ADR-017B: Smart Legacy Document Digitization (AI-Powered Use Case Extension)
+# ADR-017B: AI Document Classification
 
 **Status:** Accepted
 **Date:** 2026-03-27
 **Version:** 1.8.2 (Aligned with ADR-020)
+**Review Cycle:** Core ADR (Review every 6 months or Major Version upgrade)
 **Decision Makers:** Development Team, AI Integration Lead
+**Gap Resolution:** Addresses manual document classification inefficiency and inconsistency problems (Product Vision v1.8.5, Section 3.3) and AI-assisted workflow requirements (UAT Criteria, Section 4.8)
+**Version Dependency:**
+- **Effective From:** v1.8.2
+- **Applies To:** v1.8.2+ (AI classification features)
+- **Backward Compatible:** v1.8.0+ (Manual classification still available)
+- **Required For:** v1.9.0+ (Enhanced document management)
+
 **Related Documents:**
 
 - [ADR-020: AI Intelligence Integration Architecture](./ADR-020-ai-intelligence-integration.md) — Overall AI Architecture & RFA-First Strategy
@@ -14,7 +22,7 @@
 - [Migration Business Scope](../03-Data-and-Storage/03-06-migration-business-scope.md)
 - [Glossary](../00-Overview/00-02-glossary.md)
 
-> **Note:** ADR-017B เป็น Use Case Extension ของ ADR-017 ที่ขยายขอบเขตการใช้งาน Ollama จาก Migration Batch สู่ระบบจัดหมวดหมู่เอกสารอัจฉริยะ (Smart Categorization) พร้อมควบคุมตาม ADR-018 (AI Isolation Policy) และเป็นส่วนหนึ่งของ ADR-020 (Unified AI Architecture).
+> **Note:** ADR-017B extends ADR-017's scope from batch migration to AI-powered document classification, enabling automatic categorization and metadata extraction. Complies with ADR-018 (AI Isolation Policy) and is part of ADR-020 (Unified AI Architecture).
 
 ---
 
@@ -22,11 +30,11 @@
 
 ### ปัญหาที่ต้องการแก้ไข
 
-โครงการ LCBP3 มีเอกสารเก่าจำนวนมาก (กว่า 20,000 ฉบับ) ที่ต้องนำเข้าสู่ระบบ DMS ใหม่ การจัดหมวดหมู่และสกัด Metadata ด้วยมือมีปัญหาหลัก 3 ประการ:
+โครงการ LCBP3 มีเอกสารจำนวนมาก (ทั้งเก่าและใหม่) ที่ต้องจัดหมวดหมู่และสกัด Metadata อัตโนมัติ การจัดหมวดหมู่ด้วยมือมีปัญหาหลัก 3 ประการ:
 
-1. **Manual Labor สูง:** ต้องใช้เวลานานในการอ่านและพิมพ์ข้อมูล Metadata (Data Entry)
-2. **Human Error:** ความผิดพลาดจากการพิมพ์ (Typo) โดยเฉพาะเลขที่สัญญาและชื่อเฉพาะ
-3. **Searchability:** ไฟล์ PDF ที่เป็นแค่ภาพสแกน (Scanned) ไม่สามารถค้นหาเนื้อหาได้
+1. **Manual Labor สูง:** ต้องใช้เวลานานในการอ่านและจัดหมวดหมู่เอกสารด้วยมือ
+2. **Human Error:** ความผิดพลาดจากการจัดหมวดหมู่ (ผิดประเภท, ผิด Tag) โดยเฉพาะเอกสารที่ซับซ้อน
+3. **Inconsistency:** การจัดหมวดหมู่ไม่สม่ำเสมอกันระหว่างผู้จัดการคนละคน
 
 ### ข้อจำกัดที่สำคัญ
 
@@ -100,7 +108,47 @@
 
 **Rationale:**
 
-ประยุกต์ใช้ Hardware ที่มีอยู่ (i7-9700K + RTX 2060 Super) โดยไม่ขัดหลัก Privacy และ Security ของโครงการ n8n ช่วยลด Risk ที่จะกระทบ Core Backend และรองรับ Checkpoint/Resume ได้ดีกว่าการเขียน Script เอง นอกจากนี้ยังสอดคล้องกับ **ADR-018 (AI Boundary)** ที่กำหนดให้ AI ต้องรันบน Admin Desktop แยกต่างหาก และไม่สามารถเข้าถึง Database/Storage โดยตรงได้
+การใช้ AI จัดหมวดหมู่เอกสารอัตโนมัติด้วย Ollama ช่วยลดภาระงานจากการจัดหมวดหมู่ด้วยมือ พร้อมรักษาความปลอดภัยตามนโยบาย ADR-018 ที่กำหนดให้ AI ต้องรันบน Admin Desktop แยกต่างหาก และไม่สามารถเข้าถึง Database/Storage โดยตรง ทำให้ได้ประสิทธิภาพที่ดีขึ้นในการจัดการเอกสารขนาดใหญ่
+
+---
+
+## Impact Analysis
+
+### Affected Components
+
+| Component | Impact Level | Description |
+|-----------|--------------|-------------|
+| **Frontend Components** | **High** | AI classification UI, suggestion displays, user confirmation flows |
+| **Backend Services** | **High** | AI integration endpoints, validation services, classification logic |
+| **AI Infrastructure** | **Medium** | Ollama model usage, prompt engineering, confidence scoring |
+| **Database Schema** | **Medium** | AI suggestion storage, classification history, confidence tracking |
+| **User Experience** | **Medium** | Workflow changes, AI-assisted classification interfaces |
+| **API Design** | **Medium** | AI classification endpoints, response formats, error handling |
+| **Testing Framework** | **Low** | AI accuracy tests, classification validation, user acceptance tests |
+| **Documentation** | **Low** | User guides, AI classification procedures, troubleshooting |
+
+### Required Changes
+
+| Change Category | Specific Changes | Priority |
+|----------------|------------------|----------|
+| **Frontend** | <ul><li>Create AI classification suggestion components</li><li>Build confidence score indicators</li><li>Implement user confirmation dialogs</li><li>Add classification history displays</li><li>Create AI-assisted tagging interface</li></ul> | **Critical** |
+| **Backend** | <ul><li>Implement AI classification service endpoints</li><li>Create validation layer for AI suggestions</li><li>Add confidence threshold processing</li><li>Implement classification audit logging</li><li>Create AI model communication interfaces</li></ul> | **Critical** |
+| **Database** | <ul><li>Create AI classification suggestions table</li><li>Add confidence score tracking fields</li><li>Implement classification history logging</li><li>Create user feedback storage for AI improvement</li><li>Update data dictionary with AI fields</li></ul> | **High** |
+| **AI Integration** | <ul><li>Setup Ollama model communication protocols</li><li>Implement prompt engineering for document classification</li><li>Create confidence scoring algorithms</li><li>Setup fallback model switching logic</li><li>Implement AI response validation</li></ul> | **High** |
+| **API** | <ul><li>Create /api/ai/classify endpoint</li><li>Implement AI suggestion confirmation endpoints</li><li>Add AI service health check endpoints</li><li>Create classification feedback endpoints</li><li>Implement rate limiting for AI services</li></ul> | **High** |
+| **Testing** | <ul><li>Create AI accuracy validation tests</li><li>Implement classification consistency tests</li><li>Add user acceptance testing for AI features</li><li>Create performance tests for AI endpoints</li><li>Implement security tests for AI boundaries</li></ul> | **Medium** |
+| **Documentation** | <ul><li>Create user guide for AI classification features</li><li>Document AI model limitations and best practices</li><li>Create troubleshooting guide for AI issues</li><li>Update API documentation with AI endpoints</li></ul> | **Medium** |
+
+### Cross-Component Dependencies
+
+| Dependency | Source | Target | Impact |
+|------------|--------|--------|--------|
+| **Frontend → AI API** | Classification UI components | /api/ai/classify endpoint | User experience |
+| **Backend → AI Services** | AI classification service | Ollama model API | Classification accuracy |
+| **Database → Classification** | Classification results | AI suggestions table | Data persistence |
+| **Validation → AI Output** | Validation layer | AI response processing | Quality control |
+| **Audit → AI Interactions** | Logging service | Classification audit trail | Compliance |
+| **Testing → AI Accuracy** | Test suites | Classification validation | Quality assurance |
 
 ---
 
@@ -269,19 +317,19 @@ Phase 2: Final Commit (โดย Admin ผ่าน Frontend)
 
 ### Positive Consequences
 
-1. ✅ **Privacy Guaranteed** — ไม่มีข้อมูลออกนอกเครือข่ายองค์กร
-2. ✅ **Zero AI Cost** — ไม่มีค่าใช้จ่าย Pay-per-use
-3. ✅ **Security Compliant (ADR-018)** — AI Isolation ชัดเจน
-4. ✅ **Human-in-the-Loop** — ความถูกต้อง 100% ก่อน Commit
-5. ✅ **Recoverability** — รองรับ Checkpoint/Resume และ Rollback
-6. ✅ **Searchable Legacy** — Scanned PDF กลายเป็น Searchable Metadata
+1. ✅ **Automated Classification:** ลดเวลาการจัดหมวดหมู่เอกสารด้วยมืออย่างมีนัยสำคัญ
+2. ✅ **Consistent Categorization:** AI จัดหมวดหมู่อย่างสม่ำเสมอตามเกณฑ์เดียวกัน
+3. ✅ **Security Compliant (ADR-018):** AI Isolation ชัดเจน ปลอดภัย
+4. ✅ **Human-in-the-Loop:** ความถูกต้อง 100% ก่อนยืนยันการจัดหมวดหมู่
+5. ✅ **Scalable:** รองรับการจัดหมวดหมู่เอกสารจำนวนมาก
+6. ✅ **Cost Effective:** ไม่มีค่าใช้จ่ายต่อเอกสาร (On-premise AI)
 
 ### Negative Consequences
 
-1. ❌ **Operational Overhead** — ต้องดูแล GPU Temperature และ Desktop Uptime
-2. ❌ **Accuracy Trade-off** — Model ขนาดเล็กอาจแม่นยำน้อยกว่า Cloud AI
-3. ❌ **Time Investment** — ต้องใช้เวลา ~3–4 คืนในการ Migration
-4. ❌ **Hardware Dependency** — ต้องพึ่งพา Desktop Desk-5439
+1. ❌ **Operational Overhead:** ต้องดูแล GPU Temperature และ Desktop Uptime
+2. ❌ **Accuracy Trade-off:** Model ขนาดเล็กอาจแม่นยำน้อยกว่า Cloud AI
+3. ❌ **Hardware Dependency:** ต้องพึ่งพา Desktop Desk-5439
+4. ❌ **Processing Time:** ต้องรอ AI processing สำหรับเอกสารแต่ละฉบับ
 
 ### Mitigation Strategies
 
@@ -292,6 +340,108 @@ Phase 2: Final Commit (โดย Admin ผ่าน Frontend)
 
 ---
 
+## ADR Review Cycle
+
+### Review Classification
+
+**Core ADR Status:** This ADR is classified as a **Core AI Feature** due to its fundamental impact on document management workflows and AI integration patterns.
+
+### Review Schedule
+
+| Review Type | Frequency | Trigger | Scope |
+|-------------|-----------|---------|-------|
+| **Regular Review** | Every 6 months | Calendar-based | AI accuracy, user adoption, performance |
+| **Major Version Review** | Every major version (v2.0.0, v3.0.0) | Version planning | Architecture relevance, new AI capabilities |
+| **Performance Review** | Quarterly | Performance monitoring | AI processing times, accuracy metrics |
+| **User Feedback Review** | Quarterly | User feedback analysis | User satisfaction, workflow improvements |
+
+### Review Process
+
+#### Phase 1: Preparation (1 week before review)
+1. **Metrics Collection**
+   - AI classification accuracy rates and trends
+   - User adoption and satisfaction metrics
+   - Processing performance benchmarks
+   - Error rates and failure patterns
+   - User feedback and improvement suggestions
+
+2. **Stakeholder Notification**
+   - Development Team
+   - AI Integration Lead
+   - Product Management
+   - User Experience Team
+   - Quality Assurance Team
+
+#### Phase 2: Review Meeting (2-hour session)
+1. **Performance Assessment**
+   - Review AI accuracy metrics against targets
+   - Analyze processing time performance
+   - Evaluate error rates and failure patterns
+   - Assess system resource utilization
+
+2. **User Experience Evaluation**
+   - Review user adoption and satisfaction rates
+   - Analyze user feedback and improvement requests
+   - Evaluate workflow integration effectiveness
+   - Assess user interface and experience quality
+
+3. **Technology Assessment**
+   - Review AI model performance and accuracy
+   - Evaluate new AI technologies and improvements
+   - Assess integration with other system components
+   - Review security and compliance status
+
+#### Phase 3: Decision & Documentation (1 week after review)
+1. **Review Outcomes**
+   - **No Change:** AI classification remains effective and accurate
+   - **Update Required:** Adjust AI parameters or user interface
+   - **Enhancement:** Add new classification capabilities or features
+   - **Retire:** AI classification no longer needed (unlikely)
+
+2. **Documentation Updates**
+   - Update AI classification procedures and guidelines
+   - Revise user documentation and training materials
+   - Update performance metrics and targets
+   - Modify integration documentation
+
+### Review Criteria
+
+| Criterion | Question | Pass/Fail Threshold |
+|-----------|----------|---------------------|
+| **Classification Accuracy** | Is AI meeting target accuracy rates? | Pass: ≥85%, Fail: <85% |
+| **User Adoption** | Are users actively using AI classification? | Pass: >70% adoption, Fail: ≤70% |
+| **Processing Performance** | Are processing times within acceptable limits? | Pass: <10s per document, Fail: >10s |
+| **User Satisfaction** | Are users satisfied with AI suggestions? | Pass: ≥4.0/5.0, Fail: <4.0/5.0 |
+| **Error Rates** | Are AI errors within acceptable thresholds? | Pass: <5% error rate, Fail: ≥5% |
+| **Integration Stability** | Is AI integration stable and reliable? | Pass: >99% uptime, Fail: <99% |
+
+### Review History Template
+
+```
+## Review Cycle [YYYY-MM-DD]
+
+**Review Type:** [Regular/Major Version/Performance/User Feedback]
+**Reviewers:** [Names and roles]
+**Duration:** [Meeting date]
+
+### Findings
+- [Key findings from accuracy, performance, and user experience assessment]
+
+### Issues Identified
+- [Accuracy problems, performance bottlenecks, or user experience issues]
+
+### Recommendations
+- [AI model improvements, user interface enhancements, or workflow changes]
+
+### Outcome
+- [No Change/Update Required/Enhancement/Retire]
+
+### Next Review Date
+- [YYYY-MM-DD]
+```
+
+---
+
 ## Related Documents
 
 - [ADR-017: Ollama Data Migration Architecture](./ADR-017-ollama-data-migration.md) — Architecture หลักสำหรับ Migration
@@ -309,9 +459,12 @@ Phase 2: Final Commit (โดย Admin ผ่าน Frontend)
 |---------|------------|------------|---------|
 | 1.0.0   | 2026-02-26 | Nattanin   | Initial Use Case Specification |
 | 1.8.1   | 2026-03-27 | Tech Lead  | **Refactored to ADR format** — Aligned with ADR-017, ADR-018, and Project Specs |
+| 1.8.3   | 2026-04-04 | System Architect | **Renamed** — Changed from "Smart Legacy Document Digitization" to "AI Document Classification" for clarity and simplicity |
+| 1.8.4   | 2026-04-04 | System Architect | **Enhanced** — Added Impact Analysis template, ADR Review Cycle process, Gap Linking to requirements, and Version Dependency tracking |
 
 ---
 
-**Last Updated:** 2026-03-27
+**Last Updated:** 2026-04-04
 **Status:** Accepted
 **Next Review:** 2026-06-01 (Quarterly review)
+**Next 6-Month Review:** 2026-10-04 (regular review cycle)

specs/06-Decision-Records/ADR-018-ai-boundary.md

@@ -3,12 +3,20 @@
 **Status:** Accepted
 **Date:** 2026-03-27
 **Version:** 1.8.2 (Aligned with ADR-020)
+**Review Cycle:** Core ADR (Review every 6 months or Major Version upgrade)
 **Decision Makers:** Security Team, System Architect, AI Integration Lead
+**Gap Resolution:** Addresses AI security risks (data exposure, unauthorized modification, privilege escalation) and compliance requirements (ISO 27001, PDPA) from Security Requirements (Section 3.1) and Risk Assessment (Section 4.2)
+**Version Dependency:**
+- **Effective From:** v1.8.2
+- **Applies To:** v1.8.2+ (All AI implementations)
+- **Backward Compatible:** v1.8.0+ (Security policy enforcement)
+- **Required For:** v1.9.0+ (Mandatory for all AI features)
+
 **Related Documents:**
 
 - [ADR-020: AI Intelligence Integration Architecture](./ADR-020-ai-intelligence-integration.md) — Overall AI Architecture & RFA-First Strategy
 - [ADR-017: Ollama Data Migration Architecture](./ADR-017-ollama-data-migration.md)
-- [ADR-017B: Smart Legacy Document Digitization](./ADR-017B-ollama.md)
+- [ADR-017B: AI Document Classification](./ADR-017B-ai-document-classification.md)
 - [ADR-016: Security & Authentication](./ADR-016-security-authentication.md)
 - [ADR-019: Hybrid Identifier Strategy](./ADR-019-hybrid-identifier-strategy.md)
 - [n8n Migration Setup Guide](../03-Data-and-Storage/03-05-n8n-migration-setup-guide.md)
@@ -104,6 +112,45 @@
 
 ---
 
+## Impact Analysis
+
+### Affected Components
+
+| Component | Impact Level | Description |
+|-----------|--------------|-------------|
+| **AI Infrastructure** | **High** | Physical isolation on Admin Desktop, network segmentation |
+| **Security Architecture** | **High** | New AI authentication, audit logging, validation layers |
+| **API Design** | **Medium** | AI-specific endpoints, authentication scopes, rate limiting |
+| **Network Configuration** | **Medium** | IP whitelisting, firewall rules, zone segmentation |
+| **Monitoring & Logging** | **Medium** | AI service health checks, audit trail expansion |
+| **Development Workflow** | **Low** | AI development guidelines, compliance checks |
+| **Documentation** | **Low** | Security policies, AI integration guides |
+
+### Required Changes
+
+| Change Category | Specific Changes | Priority |
+|----------------|------------------|----------|
+| **Infrastructure** | <ul><li>Setup AI Zone on Admin Desktop (Desk-5439)</li><li>Configure network segmentation and IP whitelisting</li><li>Install Ollama and AI services on isolated host</li><li>Setup firewall rules for AI communication</li></ul> | **Critical** |
+| **Security** | <ul><li>Create AI service authentication tokens</li><li>Implement AI-specific API scopes and permissions</li><li>Setup comprehensive audit logging for AI interactions</li><li>Configure rate limiting for AI endpoints</li></ul> | **Critical** |
+| **API Layer** | <ul><li>Create AI validation service with confidence thresholds</li><li>Add AI-specific authentication middleware</li><li>Implement AI request/response logging</li><li>Create AI health check endpoints</li></ul> | **Critical** |
+| **Network** | <ul><li>Configure LAN-only access for AI services</li><li>Setup IP whitelist for AI host communication</li><li>Implement network monitoring for AI traffic</li><li>Create firewall rules for AI zone isolation</li></ul> | **High** |
+| **Monitoring** | <ul><li>Setup AI service health monitoring</li><li>Create audit log analysis for AI interactions</li><li>Implement GPU temperature and resource monitoring</li><li>Create alerting for AI service failures</li></ul> | **High** |
+| **Documentation** | <ul><li>Create AI integration security guidelines</li><li>Update development workflows with AI security requirements</li><li>Create AI compliance documentation</li><li>Update API documentation with AI security requirements</li></ul> | **Medium** |
+| **Testing** | <ul><li>Create AI security penetration tests</li><li>Implement AI boundary validation tests</li><li>Create AI authentication and authorization tests</li><li>Setup AI compliance verification tests</li></ul> | **Medium** |
+
+### Cross-Component Dependencies
+
+| Dependency | Source | Target | Impact |
+|------------|--------|--------|--------|
+| **AI Services → Backend API** | Ollama/OpenRAG requests | DMS Backend validation layer | Security enforcement |
+| **Authentication → AI Services** | JWT token validation | AI service access control | Access management |
+| **Network → AI Infrastructure** | Firewall rules | Admin Desktop isolation | Network security |
+| **Audit → AI Interactions** | Logging service | AI request/response tracking | Compliance monitoring |
+| **Monitoring → AI Health** | Health checks | AI service availability | Operational stability |
+| **Documentation → Development** | Security guidelines | AI integration patterns | Developer compliance |
+
+---
+
 ## AI Isolation Architecture
 
 ### Infrastructure Layout
@@ -384,7 +431,7 @@ Response:
 ## Related Documents
 
 - [ADR-017: Ollama Data Migration Architecture](./ADR-017-ollama-data-migration.md) — Migration implementation following ADR-018
-- [ADR-017B: Smart Legacy Document Digitization](./ADR-017B-ollama.md) — Smart categorization use case
+- [ADR-017B: AI Document Classification](./ADR-017B-ai-document-classification.md) — AI document classification use case
 - [ADR-016: Security & Authentication](./ADR-016-security-authentication.md) — General security strategy
 - [ADR-019: Hybrid Identifier Strategy](./ADR-019-hybrid-identifier-strategy.md) — UUID strategy for API security
 - [03-07-OpenRAG.md](../03-Data-and-Storage/03-07-OpenRAG.md) — RAG architecture under ADR-018
@@ -392,15 +439,119 @@ Response:
 
 ---
 
+## ADR Review Cycle
+
+### Review Classification
+
+**Core ADR Status:** This ADR is classified as a **Core Security Policy** due to its fundamental impact on system security, compliance, and AI governance.
+
+### Review Schedule
+
+| Review Type | Frequency | Trigger | Scope |
+|-------------|-----------|---------|-------|
+| **Regular Review** | Every 6 months | Calendar-based | Security effectiveness, compliance status |
+| **Major Version Review** | Every major version (v2.0.0, v3.0.0) | Version planning | Architecture relevance, new AI technologies |
+| **Security Review** | Quarterly | Security audit | Threat model updates, vulnerability assessment |
+| **Compliance Review** | Annually | Compliance audit | ISO 27001, PDPA requirements verification |
+
+### Review Process
+
+#### Phase 1: Preparation (1 week before review)
+1. **Security Metrics Collection**
+   - AI service access logs and anomaly detection
+   - Authentication and authorization audit results
+   - Network segmentation and firewall rule effectiveness
+   - Audit log completeness and integrity verification
+   - Compliance framework updates (ISO 27001, PDPA)
+
+2. **Stakeholder Notification**
+   - Security Team
+   - System Architect
+   - AI Integration Lead
+   - Compliance Officer
+   - DevOps Team
+
+#### Phase 2: Review Meeting (2-hour session)
+1. **Security Assessment**
+   - Review AI isolation effectiveness and any breach attempts
+   - Assess authentication and authorization mechanisms
+   - Evaluate audit logging completeness and accuracy
+   - Review network segmentation and firewall configurations
+
+2. **Compliance Evaluation**
+   - Verify ISO 27001 and PDPA compliance status
+   - Review regulatory changes and impact requirements
+   - Assess audit trail completeness for compliance reporting
+   - Evaluate data privacy and retention policies
+
+3. **Technology Assessment**
+   - Review AI technology stack currency and security patches
+   - Assess new AI security threats and mitigation strategies
+   - Evaluate monitoring and alerting effectiveness
+   - Review incident response procedures for AI security events
+
+#### Phase 3: Decision & Documentation (1 week after review)
+1. **Review Outcomes**
+   - **No Change:** Security policy remains effective and compliant
+   - **Update Required:** Adjust security controls or procedures
+   - **Enhancement:** Add new security measures for emerging threats
+   - **Urgent:** Immediate security updates required
+
+2. **Documentation Updates**
+   - Update security controls and procedures
+   - Revise compliance documentation
+   - Update incident response playbooks
+   - Modify security guidelines and training materials
+
+### Review Criteria
+
+| Criterion | Question | Pass/Fail Threshold |
+|-----------|----------|---------------------|
+| **Security Effectiveness** | Are AI isolation controls preventing unauthorized access? | Pass: 0 incidents, Fail: Any breach |
+| **Compliance Status** | Are all ISO 27001 and PDPA requirements met? | Pass: 100% compliant, Fail: Any gaps |
+| **Audit Trail Completeness** | Are all AI interactions logged and traceable? | Pass: 100% coverage, Fail: <100% |
+| **Authentication Integrity** | Are AI service authentication mechanisms robust? | Pass: No unauthorized access, Fail: Any incidents |
+| **Network Isolation** | Are AI services properly segmented from production? | Pass: No lateral movement, Fail: Any cross-zone access |
+| **Monitoring Effectiveness** | Are AI security events detected and alerted promptly? | Pass: <5min detection, Fail: >5min |
+
+### Review History Template
+
+```
+## Review Cycle [YYYY-MM-DD]
+
+**Review Type:** [Regular/Major Version/Security/Compliance]
+**Reviewers:** [Names and roles]
+**Duration:** [Meeting date]
+
+### Findings
+- [Key findings from security and compliance assessment]
+
+### Issues Identified
+- [Security gaps, compliance issues, or vulnerabilities discovered]
+
+### Recommendations
+- [Security enhancements, compliance improvements, or procedural changes]
+
+### Outcome
+- [No Change/Update Required/Enhancement/Urgent]
+
+### Next Review Date
+- [YYYY-MM-DD]
+```
+
+---
+
 ## Document History
 
 | Version | Date       | Author       | Changes                                                  |
 | ------- | ---------- | ------------ | -------------------------------------------------------- |
 | 1.8.1   | 2026-03-27 | Security Lead| Initial ADR — AI Boundary Policy (Physical Isolation)    |
 | 1.8.2   | 2026-04-03 | Tech Lead    | Updated — Aligned AI Model spec with ADR-017/017B        |
+| 1.8.3   | 2026-04-04 | System Architect | Enhanced — Added Impact Analysis template, ADR Review Cycle process, Gap Linking to requirements, and Version Dependency tracking |
 
 ---
 
-**Last Updated:** 2026-04-03
+**Last Updated:** 2026-04-04
 **Status:** Accepted
 **Next Review:** 2026-06-01 (Quarterly security review)
+**Next 6-Month Review:** 2026-10-04 (regular review cycle)

specs/06-Decision-Records/ADR-019-hybrid-identifier-strategy.md

@@ -3,7 +3,15 @@
 **Status:** Accepted
 **Date:** 2026-03-12
 **Version:** 1.8.2
+**Review Cycle:** Core ADR (Review every 6 months or Major Version upgrade)
 **Decision Makers:** Development Team, Database Architect
+**Gap Resolution:** Addresses security vulnerability from sequential INT IDs (OWASP BOLA) and scalability requirements for cross-system integration (Product Vision v1.8.5, Section 2.4) and API security requirements (Security Requirements, Section 3.1)
+**Version Dependency:**
+- **Effective From:** v1.8.2
+- **Applies To:** v1.8.2+ (Progressive implementation)
+- **Backward Compatible:** v1.8.0+ (Dual-mode transition)
+- **Required For:** v1.9.0+ (All public APIs must use UUID)
+
 **Related Documents:**
 
 - [Data Dictionary](../03-Data-and-Storage/03-01-data-dictionary.md)
@@ -92,6 +100,48 @@
 
 ---
 
+## Impact Analysis
+
+### Affected Components
+
+| Component | Impact Level | Description |
+|-----------|--------------|-------------|
+| **Database Schema** | **High** | Add UUID columns to 14 core tables with UNIQUE indexes |
+| **Backend Entities** | **High** | Add BaseUuidEntity, update all public-facing entities |
+| **API Layer** | **High** | Update controllers, services, DTOs to use UUID parameters |
+| **Frontend Types** | **Medium** | Update TypeScript interfaces to use publicId consistently |
+| **URL Routing** | **Medium** | Change route patterns from INT to UUID parameters |
+| **Security Model** | **Medium** | Enhanced OWASP BOLA protection, API authentication |
+| **Caching Strategy** | **Medium** | Redis cache keys transition from INT to UUID |
+| **API Documentation** | **Low** | Update endpoint documentation and examples |
+| **Testing Framework** | **Low** | Update test fixtures and mock data |
+
+### Required Changes
+
+| Change Category | Specific Changes | Priority |
+|----------------|------------------|----------|
+| **Database** | <ul><li>ADD UUID column to 14 core tables (SQL First)</li><li>CREATE UNIQUE INDEX on each UUID column</li><li>Update data dictionary with new fields</li></ul> | **Critical** |
+| **Backend** | <ul><li>Create BaseUuidEntity with publicId property</li><li>Update 14+ entities to extend BaseUuidEntity</li><li>Modify controllers to accept UUID parameters</li><li>Update services to resolve UUID → INT for queries</li><li>Modify DTOs to expose publicId, exclude INT id</li></ul> | **Critical** |
+| **API Layer** | <ul><li>Update route patterns to use :uuid parameters</li><li>Add ParseUUIDPipe for validation</li><li>Implement FindByIdOrUuid methods during transition</li><li>Update API responses to return publicId</li></ul> | **Critical** |
+| **Frontend** | <ul><li>Update all TypeScript interfaces to use publicId</li><li>Remove fallback uuid/id fields from types</li><li>Update URL construction to use publicId</li><li>Modify API calls to pass UUID strings</li></ul> | **High** |
+| **Security** | <ul><li>Update CASL policies to work with UUID identifiers</li><li>Enhance API authentication for UUID-based routes</li><li>Update audit logging to use UUID references</li></ul> | **High** |
+| **Caching** | <ul><li>Update Redis cache key strategy to use UUID</li><li>Implement cache invalidation for UUID-based keys</li><li>Migrate existing cache entries during transition</li></ul> | **Medium** |
+| **Testing** | <ul><li>Update unit tests with UUID fixtures</li><li>Modify integration tests for UUID routes</li><li>Add performance tests for UUID vs INT lookups</li></ul> | **Medium** |
+| **Documentation** | <ul><li>Update API documentation with UUID examples</li><li>Create migration guide for developers</li><li>Update frontend development guidelines</li></ul> | **Medium** |
+
+### Cross-Component Dependencies
+
+| Dependency | Source | Target | Impact |
+|------------|--------|--------|--------|
+| **Entity → Database** | BaseUuidEntity publicId property | Database uuid column | Data persistence |
+| **Controller → Service** | UUID route parameters | Service UUID resolution | Request handling |
+| **Frontend → API** | publicId in TypeScript | UUID API endpoints | Data binding |
+| **Cache → Database** | Redis UUID keys | Database UUID lookups | Performance |
+| **Security → API** | CASL UUID policies | UUID-based route protection | Authorization |
+| **Documentation → Code** | UUID examples | Implementation patterns | Developer guidance |
+
+---
+
 ## Technical Specification
 
 ### 1. UUID Format
@@ -510,12 +560,119 @@ type ProjectOption = {
 
 ---
 
+## ADR Review Cycle
+
+### Review Classification
+
+**Core ADR Status:** This ADR is classified as a **Core Architecture Decision** due to its fundamental impact on system security, data architecture, and API design patterns.
+
+### Review Schedule
+
+| Review Type | Frequency | Trigger | Scope |
+|-------------|-----------|---------|-------|
+| **Regular Review** | Every 6 months | Calendar-based | Security effectiveness, performance impact |
+| **Major Version Review** | Every major version (v2.0.0, v3.0.0) | Version planning | Architecture relevance, new requirements |
+| **Security Review** | Annually or after security incident | Security audit | OWASP compliance, threat model updates |
+| **Performance Review** | Quarterly | Performance monitoring | Database performance, query optimization |
+
+### Review Process
+
+#### Phase 1: Preparation (1 week before review)
+1. **Metrics Collection**
+   - UUID vs INT query performance benchmarks
+   - Security incident reports related to ID enumeration
+   - Storage usage and growth patterns
+   - Developer adoption and compliance rates
+   - Cross-system integration success metrics
+
+2. **Stakeholder Notification**
+   - Development Team
+   - Database Architect
+   - Security Team
+   - API Team
+   - Frontend Team
+
+#### Phase 2: Review Meeting (2-hour session)
+1. **Security Assessment**
+   - Review any ID enumeration attempts
+   - Assess OWASP BOLA protection effectiveness
+   - Evaluate UUID randomness and collision resistance
+
+2. **Performance Evaluation**
+   - Analyze UUID lookup performance vs INT
+   - Review index fragmentation and maintenance
+   - Assess storage impact and growth projections
+
+3. **Implementation Compliance**
+   - Check frontend publicId usage consistency
+   - Verify API endpoint UUID adoption
+   - Review cache key migration progress
+
+#### Phase 3: Decision & Documentation (1 week after review)
+1. **Review Outcomes**
+   - **No Change:** ADR remains valid and effective
+   - **Update Required:** Adjust naming conventions or patterns
+   - **Supersede:** New ADR created for different identifier strategy
+   - **Retire:** ADR no longer relevant (unlikely given core nature)
+
+2. **Documentation Updates**
+   - Update review date and findings
+   - Add new version notes
+   - Update implementation guidelines
+   - Modify transition timeline if needed
+
+### Review Criteria
+
+| Criterion | Question | Pass/Fail Threshold |
+|-----------|----------|---------------------|
+| **Security Effectiveness** | Are ID enumeration attacks prevented? | Pass: 0 incidents, Fail: Any successful enumeration |
+| **Performance Impact** | Are UUID lookups within acceptable limits? | Pass: <50ms avg, Fail: >50ms avg |
+| **Developer Compliance** | Is publicId used consistently across codebase? | Pass: >95% compliance, Fail: <95% |
+| **Storage Efficiency** | Is storage impact within projections? | Pass: <5% deviation, Fail: >5% |
+| **API Coverage** | Are all public APIs using UUID? | Pass: 100% coverage, Fail: Any INT-based endpoints |
+| **Frontend Consistency** | Are all TypeScript types using publicId? | Pass: 100% compliance, Fail: Any fallback fields |
+
+### Review History Template
+
+```
+## Review Cycle [YYYY-MM-DD]
+
+**Review Type:** [Regular/Major Version/Security/Performance]
+**Reviewers:** [Names and roles]
+**Duration:** [Meeting date]
+
+### Findings
+- [Key findings from security and performance assessment]
+
+### Issues Identified
+- [Problems or concerns discovered]
+
+### Recommendations
+- [Action items and decisions]
+
+### Outcome
+- [No Change/Update Required/Supersede/Retire]
+
+### Next Review Date
+- [YYYY-MM-DD]
+```
+
+---
+
 ## 🔄 Change Log
 
 | Version | Date       | Changes                                                             | Updated By  |
 | ------- | ---------- | ------------------------------------------------------------------- | ----------- |
+| 1.8.3   | 2026-04-04 | Enhanced — Added Impact Analysis template, ADR Review Cycle process, Gap Linking to requirements, and Version Dependency tracking | System Architect |
 | 1.8.2   | 2026-04-01 | Removed Waiver: Session Identity to enforce strict `publicId` usage | Antigravity |
 | 1.8.1   | 2026-03-21 | Added Naming Convention Summary & Transition Strategy               | Claude      |
 | 1.8.0   | 2026-03-12 | Initial Decision Outcome & Technical Spec                           | Human Dev   |
 
+---
+
+**Last Updated:** 2026-04-04
+**Status:** Accepted
+**Implementation Target:** v1.9.0+ (Progressive)
+**Next Review Date:** 2026-10-04 (6-month regular review)
+
 _สำหรับรายละเอียดการ Implement ดูที่ Implementation Plan ใน `05-07-hybrid-uuid-implementation-plan.md`_

specs/06-Decision-Records/ADR-020-ai-intelligence-integration.md

@@ -3,11 +3,19 @@
 **Status:** Proposed
 **Date:** 2026-04-03
 **Version:** 1.8.5
+**Review Cycle:** Core ADR (Review every 6 months or Major Version upgrade)
 **Decision Makers:** Development Team, AI Integration Lead, System Architect
+**Gap Resolution:** Addresses requirement for automated document processing efficiency (Product Vision v1.8.5, Section 3.2) and acceptance criteria for AI-assisted metadata extraction (UAT Criteria, Section 4.7)
+**Version Dependency:**
+- **Effective From:** v1.9.0
+- **Applies To:** v1.9.0+ (Full implementation)
+- **Backward Compatible:** v1.8.5 (API endpoints only)
+- **Required For:** v2.0.0 (Core AI features)
+
 **Related Documents:**
 
 - [ADR-017: Ollama Data Migration Architecture](./ADR-017-ollama-data-migration.md)
-- [ADR-017B: Smart Legacy Document Digitization](./ADR-017B-ollama.md)
+- [ADR-017B: AI Document Classification](./ADR-017B-ai-document-classification.md)
 - [ADR-018: AI Boundary Policy](./ADR-018-ai-boundary.md) — AI Physical Isolation
 - [ADR-019: Hybrid Identifier Strategy](./ADR-019-hybrid-identifier-strategy.md) — UUID Strategy
 - [n8n Migration Setup Guide](../03-Data-and-Storage/03-05-n8n-migration-setup-guide.md)
@@ -83,6 +91,45 @@
 
 ---
 
+## Impact Analysis
+
+### Affected Components
+
+| Component | Impact Level | Description |
+|-----------|--------------|-------------|
+| **Backend Architecture** | **High** | New AiModule, MigrationService, database schema changes |
+| **Frontend Components** | **Medium** | DocumentReviewForm, Migration Dashboard enhancements |
+| **Infrastructure** | **High** | Admin Desktop AI services, n8n workflows, Docker setup |
+| **Security Model** | **Medium** | ADR-018 boundary enforcement, new API endpoints |
+| **Database Schema** | **Medium** | migration_logs table, ai_audit_logs table |
+| **API Layer** | **Medium** | New AI endpoints, authentication scopes |
+| **Testing Framework** | **Medium** | AI accuracy tests, integration tests |
+| **Documentation** | **Low** | User guides, admin procedures |
+
+### Required Changes
+
+| Change Category | Specific Changes | Priority |
+|----------------|------------------|----------|
+| **Database** | <ul><li>Create `migration_logs` table (SQL First)</li><li>Create `ai_audit_logs` table</li><li>Update data dictionary</li></ul> | **Critical** |
+| **Backend** | <ul><li>Implement AiModule with n8n integration</li><li>Create MigrationService with business logic</li><li>Add AI endpoints with CASL guards</li><li>Update validation layer for AI responses</li></ul> | **Critical** |
+| **Frontend** | <ul><li>Build DocumentReviewForm reusable component</li><li>Create Admin Migration Dashboard</li><li>Integrate AI suggestions in RFA form</li><li>Add confidence score indicators</li></ul> | **High** |
+| **Infrastructure** | <ul><li>Setup n8n on Admin Desktop (Desk-5439)</li><li>Deploy Ollama with Gemma 4</li><li>Configure PaddleOCR service</li><li>Setup Docker containers</li></ul> | **Critical** |
+| **Security** | <ul><li>Implement ADR-018 AI boundaries</li><li>Add AI-specific authentication scopes</li><li>Create audit logging for AI interactions</li><li>Setup rate limiting for AI endpoints</li></ul> | **Critical** |
+| **Testing** | <ul><li>AI accuracy validation tests</li><li>End-to-end pipeline tests</li><li>Security boundary verification</li><li>Performance benchmarking</li></ul> | **High** |
+| **Documentation** | <ul><li>Admin workflow procedures</li><li>User AI assistance guide</li><li>Troubleshooting procedures</li><li>API documentation updates</li></ul> | **Medium** |
+
+### Cross-Component Dependencies
+
+| Dependency | Source | Target | Impact |
+|------------|--------|--------|--------|
+| **AI Service → Database** | AiService extraction calls | migration_logs table | Data persistence |
+| **Frontend → AI Gateway** | DocumentReviewForm | /api/ai/extract endpoint | Real-time suggestions |
+| **n8n → Backend API** | AI workflows | Validation endpoints | Human-in-the-loop |
+| **Admin Desktop → QNAP NAS** | AI services | DMS backend API | Security boundary |
+| **Migration Service → Storage** | Batch processing | File storage system | Document handling |
+
+---
+
 ## Architecture Overview
 
 ### Core Technology Stack
@@ -479,7 +526,7 @@ OUTPUT FORMAT:
 
 ### Architecture Decision Records
 - **[ADR-017: Ollama Data Migration](./ADR-017-ollama-data-migration.md)** — Foundation migration architecture
-- **[ADR-017B: Smart Categorization](./ADR-017B-ollama.md)** — AI categorization use cases
+- **[ADR-017B: AI Document Classification](./ADR-017B-ai-document-classification.md)** — AI classification use cases
 - **[ADR-018: AI Boundary Policy](./ADR-018-ai-boundary.md)** — Security isolation requirements (CRITICAL)
 - **[ADR-019: Hybrid Identifier Strategy](./ADR-019-hybrid-identifier-strategy.md)** — UUID usage patterns (CRITICAL)
 
@@ -500,16 +547,118 @@ OUTPUT FORMAT:
 
 ---
 
+## ADR Review Cycle
+
+### Review Classification
+
+**Core ADR Status:** This ADR is classified as a **Core Architecture Decision** due to its fundamental impact on system architecture and security boundaries.
+
+### Review Schedule
+
+| Review Type | Frequency | Trigger | Scope |
+|-------------|-----------|---------|-------|
+| **Regular Review** | Every 6 months | Calendar-based | Validity assessment, performance metrics |
+| **Major Version Review** | Every major version (v2.0.0, v3.0.0) | Version planning | Architecture relevance, compatibility |
+| **Security Review** | Annually or after security incident | Security audit | ADR-018 compliance, threat model |
+| **Technology Review** | As needed | Tech stack changes | AI model updates, infrastructure changes |
+
+### Review Process
+
+#### Phase 1: Preparation (1 week before review)
+1. **Metrics Collection**
+   - AI accuracy rates and trends
+   - Performance benchmarks vs targets
+   - Security incident reports
+   - User feedback and satisfaction scores
+   - Technology stack currency assessment
+
+2. **Stakeholder Notification**
+   - Development Team
+   - AI Integration Lead
+   - System Architect
+   - Security Team
+   - Product Management
+
+#### Phase 2: Review Meeting (2-hour session)
+1. **Current State Assessment**
+   - Review success metrics achievement
+   - Identify gaps or deviations from original decision
+   - Assess technology relevance and currency
+
+2. **Impact Evaluation**
+   - Measure actual vs expected business impact
+   - Evaluate implementation challenges
+   - Identify unintended consequences
+
+3. **Future Considerations**
+   - Emerging AI technologies
+   - Changing business requirements
+   - Scalability concerns
+   - Security landscape changes
+
+#### Phase 3: Decision & Documentation (1 week after review)
+1. **Review Outcomes**
+   - **No Change:** ADR remains valid and effective
+   - **Update Required:** Minor adjustments to implementation
+   - **Supersede:** New ADR created to replace this one
+   - **Retire:** ADR no longer relevant
+
+2. **Documentation Updates**
+   - Update review date and findings
+   - Add new version notes
+   - Link to related ADRs if created
+   - Update implementation roadmap
+
+### Review Criteria
+
+| Criterion | Question | Pass/Fail Threshold |
+|-----------|----------|---------------------|
+| **Effectiveness** | Is AI achieving target accuracy (>85%)? | Pass: ≥85%, Fail: <85% |
+| **Performance** | Are processing times within targets (<15s)? | Pass: ≤15s, Fail: >15s |
+| **Security** | Is ADR-018 compliance maintained? | Pass: 100% compliant, Fail: Any violation |
+| **Adoption** | Are users utilizing AI features? | Pass: >70% adoption, Fail: ≤70% |
+| **Maintainability** | Is system supportable with current resources? | Pass: Yes, Fail: Requires additional resources |
+| **Technology Currency** | Are AI models and infrastructure up-to-date? | Pass: Current version, Fail: >1 version behind |
+
+### Review History Template
+
+```
+## Review Cycle [YYYY-MM-DD]
+
+**Review Type:** [Regular/Major Version/Security/Technology]
+**Reviewers:** [Names and roles]
+**Duration:** [Meeting date]
+
+### Findings
+- [Key findings from metrics and assessment]
+
+### Issues Identified
+- [Problems or concerns discovered]
+
+### Recommendations
+- [Action items and decisions]
+
+### Outcome
+- [No Change/Update Required/Supersede/Retire]
+
+### Next Review Date
+- [YYYY-MM-DD]
+```
+
+---
+
 ## Document History
 
 | Version | Date | Author | Changes |
 |---------|------|--------|---------|
 | 1.8.5 | 2026-04-03 | AI Integration Lead | Initial ADR — AI Intelligence Integration Architecture |
 | 1.8.6 | 2026-04-03 | Tech Lead | Updated — Aligned with detailed task specifications and implementation requirements |
+| 1.8.7 | 2026-04-04 | System Architect | Enhanced — Added Impact Analysis template, ADR Review Cycle process, Gap Linking to requirements, and Version Dependency tracking |
 
 ---
 
-**Last Updated:** 2026-04-03
+**Last Updated:** 2026-04-04
 **Status:** Proposed
 **Review Date:** 2026-04-10
 **Implementation Target:** v1.9.0
+**Next Review Date:** 2026-10-04 (6-month regular review)

specs/06-Decision-Records/ADR-REVIEW-PROCESS.md

@@ -0,0 +1,245 @@
+# ADR Review Process & Version Dependency Policy
+
+**Version:** 1.0
+**Date:** 2026-04-04
+**Owner:** System Architect
+
+---
+
+## 📋 วัตถุประสงค์
+
+เอกสารนี้กำหนดกระบวนการทบทวน ADRs (Architecture Decision Records) และการจัดการ Version Dependencies เพื่อให้มั่นใจว่า:
+
+1. **คุณภาพ ADRs**: การบันทึกการตัดสินใจมีคุณภาพสม่ำเสมอ
+2. **Gap Linking**: ทุก ADR เชื่อมโยงกับ Requirements และ Acceptance Criteria
+3. **Impact Analysis**: การประเมินผลกระทบเป็นระบบ
+4. **Version Management**: การจัดการ Dependencies ระหว่าง ADRs
+5. **Review Cycle**: การทบทวน ADRs ที่สำคัญเป็นระยะ
+
+---
+
+## 🔄 ADR Review Process
+
+### Review Types
+
+#### 1. Initial Review (สำหรับ ADR ใหม่)
+- **Trigger**: สร้าง ADR ใหม่
+- **Timeline**: ภายใน 7 วันทำการ
+- **Reviewers**: System Architect + 2 Senior Developers + Product Owner
+- **Goal**: ตรวจสอบความสมบูรณ์และความถูกต้อง
+
+#### 2. Scheduled Review (ทบทวนตามกำหนด)
+- **Trigger**: ทุก 6 เดือน สำหรับ Core ADRs
+- **Timeline**: 1-2 วันทำการ
+- **Reviewers**: System Architect + Development Team Lead
+- **Goal**: ตรวจสอบความยังคงเป็นปัจจุบัน
+
+#### 3. Triggered Review (ทบทวนตามเหตุการณ์)
+- **Trigger**: Major version upgrade, Critical issue, Technology change
+- **Timeline**: ภายใน 3 วันทำการ
+- **Reviewers**: System Architect + Technical Lead + DevOps
+- **Goal**: ประเมินผลกระทบจากการเปลี่ยนแปลง
+
+### Review Checklist
+
+#### ✅ Initial Review Checklist
+
+**Structure & Content:**
+- [ ] มี Gap Analysis และเชื่อมโยงกับ Requirements หรือไม่?
+- [ ] มี Impact Analysis ครบถ้วนหรือไม่?
+- [ ] มี Version Dependency Matrix หรือไม่?
+- [ ] Context ชัดเจนและเข้าใจง่ายหรือไม่?
+- [ ] มี Options อย่างน้อย 2-3 ทางเลือกพร้อม Pros/Cons หรือไม่?
+
+**Technical Quality:**
+- [ ] Decision Rationale มีเหตุผลรองรับที่ดีหรือไม่?
+- [ ] Consequences ระบุทั้งดีและไม่ดีอย่างสมจริงหรือไม่?
+- [ ] Implementation Details มีรายละเอียดเพียงพอหรือไม่?
+- [ ] Cross-Module Dependencies ถูกต้องหรือไม่?
+
+**Compliance:**
+- [ ] เป็นไปตาม ADR Template ล่าสุดหรือไม่?
+- [ ] Link ไปยัง Related Documents ถูกต้องหรือไม่?
+- [ ] ไม่ขัดแย้งกับ ADRs ที่มีอยู่หรือไม่?
+
+#### ✅ Scheduled Review Checklist
+
+**Relevance:**
+- [ ] ADR นี้ยังคงเป็น Core Principle หรือไม่?
+- [ ] มีการเปลี่ยนแปลง Technology ที่กระทบหรือไม่?
+- [ ] มี Alternative ที่ดีกว่าที่เกิดขึ้นหรือไม่?
+
+**Issues & Performance:**
+- [ ] มี Issue หรือ Bug ที่เกิดจาก ADR นี้หรือไม่?
+- [ ] Performance ยังเป็นไปตามที่คาดหวังหรือไม่?
+- [ ] มีปัญหา Maintainability หรือไม่?
+
+**Updates Needed:**
+- [ ] ต้องการ Update หรือ Deprecate หรือไม่?
+- [ ] ต้องการ Version increment หรือไม่?
+- [ ] ต้องการสร้าง ADR ใหม่ที่แทนที่หรือไม่?
+
+### Review Workflow
+
+```mermaid
+stateDiagram-v2
+    [*] --> Proposed: Create ADR
+    Proposed --> UnderReview: Initial Review Started
+    UnderReview --> Accepted: Review Passed
+    UnderReview --> Rejected: Review Failed
+    UnderReview --> Revision: Request Changes
+    
+    Revision --> UnderReview: Resubmit
+    
+    Accepted --> ScheduledReview: 6 Months Later
+    ScheduledReview --> Accepted: No Changes Needed
+    ScheduledReview --> UpdateRequired: Changes Needed
+    ScheduledReview --> Deprecated: No Longer Relevant
+    
+    UpdateRequired --> Accepted: Updates Complete
+    
+    Accepted --> TriggeredReview: Major Event
+    TriggeredReview --> Accepted: No Impact
+    TriggeredReview --> UpdateRequired: Impact Found
+    
+    Rejected --> [*]
+    Deprecated --> [*]
+```
+
+---
+
+## 📊 Version Dependency Management
+
+### Version Matrix Template
+
+| ADR | Version | Dependency Type | Affected Version(s) | Implementation Status | Review Date |
+|-----|---------|-----------------|---------------------|----------------------|-------------|
+| **ADR-XXX** | 1.0 | Core | v1.8.0+ | ✅ Implemented | 2026-08-24 |
+| **ADR-YYY** | 2.1 | Required By | v1.8.1+ | 🔄 In Progress | 2026-08-24 |
+| **ADR-ZZZ** | 1.5 | Conflicts With | v1.7.x | ⚠️ Must Resolve | 2026-08-24 |
+
+### Dependency Types
+
+| Type | Description | Example |
+|------|-------------|---------|
+| **Core** | ADR พื้นฐานของระบบ | ADR-005 Technology Stack |
+| **Required** | ADR ที่จำเป็นต้องมี | ADR-006 Redis for ADR-002 |
+| **Used By** | ADR ที่ใช้ ADR อื่น | ADR-002 uses ADR-006 |
+| **Conflicts** | ADR ที่ขัดแย้งกัน | Legacy vs New approach |
+| **Supersedes** | ADR ที่แทนที่ ADR เก่า | New numbering strategy |
+
+### Version Compatibility Rules
+
+#### Minimum Version Policy
+- **Core ADRs**: มีผลบังคับใช้ตั้งแต่ v1.8.0 เป็นต้นไป
+- **Feature ADRs**: ระบุ version ที่เริ่มมีผลบังคับใช้
+- **Breaking Changes**: ต้อง increment Major version และ Update ทุก ADR ที่เกี่ยวข้อง
+
+#### Breaking Change Classification
+- **🔴 Critical**: ต้อง Update ทันที (Security, Data loss risk)
+- **🟡 Important**: ควร Update ภายใน 1 เดือน (Performance, Compatibility)
+- **🟢 Minor**: สามารถ Update ตาม schedule ได้ (Documentation, Nice-to-have)
+
+#### Deprecation Timeline
+- **Announcement**: ประกาศล่วงหน้า 3 เดือน
+- **Warning**: Log warning ในระบบ 1 เดือนก่อน deprecate
+- **Removal**: ลบหรือ deprecate หลังจาก timeline ครบ
+
+---
+
+## 🎯 Core ADRs Definition
+
+### Core ADRs List (ต้องทบทวนทุก 6 เดือน)
+
+| ADR | Title | Category | Review Priority |
+|-----|-------|----------|-----------------|
+| **ADR-001** | Unified Workflow Engine | Core Architecture | 🔴 High |
+| **ADR-002** | Document Numbering Strategy | Core Business Logic | 🔴 High |
+| **ADR-005** | Technology Stack Selection | Foundation | 🔴 High |
+| **ADR-006** | Redis Usage & Caching Strategy | Infrastructure | 🔴 High |
+| **ADR-016** | Security & Authentication Strategy | Security | 🔴 High |
+| **ADR-019** | Hybrid Identifier Strategy | Data Architecture | 🔴 High |
+
+### Feature ADRs (ทบทวนตามความจำเป็น)
+
+- Frontend Architecture ADRs (ADR-011, 012, 013, 014)
+- API & Integration ADRs (ADR-008, 010)
+- AI & Data Integration ADRs (ADR-017, 018, 020)
+
+---
+
+## 📝 Review Documentation
+
+### Review Meeting Template
+
+**Date:** [Date]
+**Attendees:** [Names]
+**ADR(s) Reviewed:** [List]
+
+#### Discussion Points
+1. **Gap Analysis Validation**: [Notes]
+2. **Impact Analysis Review**: [Notes]
+3. **Version Dependencies**: [Notes]
+4. **Issues Identified**: [List]
+5. **Action Items**: [List with owners]
+
+#### Decisions Made
+- [ ] ADR-XXX: Approved as is
+- [ ] ADR-YYY: Approved with changes
+- [ ] ADR-ZZZ: Requires revision
+- [ ] ADR-ABC: Deprecated
+
+#### Next Steps
+1. [Action item 1] - [Owner] - [Due date]
+2. [Action item 2] - [Owner] - [Due date]
+
+### Review Report Template
+
+```markdown
+# ADR Review Report - [Date]
+
+## Summary
+- Total ADRs Reviewed: [X]
+- Approved: [Y]
+- Requires Changes: [Z]
+- Deprecated: [W]
+
+## Key Findings
+1. [Finding 1]
+2. [Finding 2]
+
+## Action Items
+[List of action items]
+
+## Next Review Date
+[Date]
+```
+
+---
+
+## 🔧 Tools & Automation
+
+### Automated Checks
+- **Template Validation**: ตรวจสอบว่า ADR ใช้ template ล่าสุด
+- **Link Validation**: ตรวจสอบลิงก์ภายในเอกสาร
+- **Dependency Matrix**: สร้าง automatic dependency graph
+- **Version Consistency**: ตรวจสอบ version numbers ใน matrix
+
+### Monitoring & Alerts
+- **ADR Age Alert**: ADR ที่ไม่ได้ทบทวน > 6 เดือน
+- **Broken Dependencies**: ADR ที่อ้างอิงถึง ADR ที่ deprecated
+- **Review Due**: แจ้งเตือนก่อน review date 1 สัปดาห์
+
+---
+
+## 📚 References
+
+- [Enhanced ADR Template](./ADR-TEMPLATE-enhanced.md)
+- [ADR Index](./README.md)
+- [Version Management Best Practices](../05-Engineering-Guidelines/05-05-git-conventions.md)
+
+---
+
+**Document Version:** 1.0  
+**Last Updated:** 2026-04-04  
+**Next Review:** 2026-10-04

specs/06-Decision-Records/ADR-TEMPLATE-enhanced.md

@@ -0,0 +1,168 @@
+# ADR-XXX: [Title]
+
+**Status:** Proposed
+**Date:** YYYY-MM-DD
+**Decision Makers:** [Names]
+**Related Documents:**
+- [Link to relevant specs]
+
+---
+
+## 🎯 Gap Analysis & Purpose
+
+### ปิด Gap จากเอกสาร:
+- **[Document Name]** - [Section/Requirement]: [บรรทัดที่เกี่ยวข้อง]
+  - เหตุผล: [อธิบายว่า Gap นี้คืออะไร และทำไมต้องแก้ไข]
+
+### แก้ไขความขัดแย้ง:
+- **[Document Name]** vs **[Another Document]**: [อธิบายความขัดแย้ง]
+  - การตัดสินใจนี้ช่วยแก้ไขโดย: [วิธีการแก้ไข]
+
+---
+
+## Context and Problem Statement
+
+[Describe the problem...]
+
+---
+
+## Decision Drivers
+
+- [Driver 1]
+- [Driver 2]
+
+---
+
+## Considered Options
+
+### Option 1: [Name]
+
+**Pros:**
+
+- ✅ [Pro 1]
+
+**Cons:**
+
+- ❌ [Con 1]
+
+---
+
+## Decision Outcome
+
+**Chosen Option:** [Option X]
+
+### Rationale
+
+[Why this option...]
+
+---
+
+## 🔍 Impact Analysis
+
+### Affected Components (ส่วนประกอบที่ได้รับผลกระทบ)
+
+| Component | Level | Impact Description | Required Action |
+|-----------|-------|-------------------|-----------------|
+| **Backend** | 🔴 High | [รายละเอียดผลกระทบ] | [Action Required] |
+| **Frontend** | 🟡 Medium | [รายละเอียดผลกระทบ] | [Action Required] |
+| **Database** | 🔴 High | [รายละเอียดผลกระทบ] | [Action Required] |
+| **Infrastructure** | 🟢 Low | [รายละเอียดผลกระทบ] | [Action Required] |
+
+### Required Changes (การเปลี่ยนแปลงที่ต้องดำเนินการ)
+
+#### 🔴 Critical Changes (ต้องทำทันที)
+- [ ] **[Change 1]** - [File/Module]: [Description]
+- [ ] **[Change 2]** - [File/Module]: [Description]
+
+#### 🟡 Important Changes (ควรทำภายใน X วัน)
+- [ ] **[Change 3]** - [File/Module]: [Description]
+- [ ] **[Change 4]** - [File/Module]: [Description]
+
+#### 🟢 Nice-to-Have (ทำถ้ามีเวลา)
+- [ ] **[Change 5]** - [File/Module]: [Description]
+
+### Cross-Module Dependencies
+
+```mermaid
+graph TB
+    ADR[ADR-XXX] --> Module1[Module 1]
+    ADR --> Module2[Module 2]
+    ADR --> Module3[Module 3]
+    
+    Module1 --> Dependency1[Dependency A]
+    Module2 --> Dependency2[Dependency B]
+    Module3 --> Dependency3[Dependency C]
+```
+
+---
+
+## 📋 Version Dependency Matrix
+
+| ADR | Version | Dependency Type | Affected Version(s) | Implementation Status |
+|-----|---------|-----------------|---------------------|----------------------|
+| **ADR-XXX** | 1.0 | Core | v1.8.0+ | ✅ Implemented |
+| **ADR-YYY** | 2.1 | Required By | v1.8.1+ | 🔄 In Progress |
+| **ADR-ZZZ** | 1.5 | Conflicts With | v1.7.x | ⚠️ Must Resolve |
+
+### Version Compatibility Rules
+
+- **Minimum Version:** v1.8.0 (ADR มีผลบังคับใช้)
+- **Breaking Changes:** ไม่มี (หรือระบุถ้ามี)
+- **Deprecation Timeline:** [ระบุถ้ามีการ deprecate]
+
+---
+
+## Implementation Details
+
+[รายละเอียดการ Implement...]
+
+---
+
+## Consequences
+
+### Positive
+
+1. ✅ [Impact 1]
+
+### Negative
+
+1. ❌ [Risk 1]
+
+### Mitigation Strategies
+
+- [Strategy 1]: [Description]
+
+---
+
+## 🔄 Review Cycle & Maintenance
+
+### Review Schedule
+- **Next Review:** [Date] (6 months from last review)
+- **Review Type:** [Scheduled/Triggered/Major Version]
+- **Reviewers:** [Names/Roles]
+
+### Review Checklist
+- [ ] ยังคงเป็น Core Principle หรือไม่?
+- [ ] มีการเปลี่ยนแปลง Technology ที่กระทบหรือไม่?
+- [ ] มี Issue หรือ Bug ที่เกิดจาก ADR นี้หรือไม่?
+- [ ] ต้องการ Update หรือ Deprecate หรือไม่?
+
+### Version History
+| Version | Date | Changes | Status |
+|---------|------|---------|--------|
+| 1.0 | YYYY-MM-DD | Initial version | ✅ Active |
+| 1.1 | YYYY-MM-DD | [Changes] | ✅ Active |
+
+---
+
+## Related ADRs
+
+- [ADR-XXX: Title](./ADR-XXX.md) - [Relationship]
+- [ADR-YYY: Title](./ADR-YYY.md) - [Relationship]
+
+---
+
+## References
+
+- [Reference 1]
+- [Reference 2]

specs/06-Decision-Records/README.md

@@ -1,19 +1,23 @@
 # Architecture Decision Records (ADRs)
 
-**Version:** 1.8.1
-**Last Updated:** 2026-03-16
+**Version:** 1.8.2
+**Last Updated:** 2026-04-04
 **Project:** LCBP3-DMS (Laem Chabang Port Phase 3 - Document Management System)
 
 ---
 
 ## 📋 What are ADRs?
 
-Architecture Decision Records (ADRs) เป็นเอกสารที่บันทึก **ประวัติการตัดสินใจทางสถาปัตยกรรมที่สำคัญ** ของโปรเจกต์ โดยร ะบุ:
+Architecture Decision Records (ADRs) เป็นเอกสารที่บันทึก **ประวัติการตัดสินใจทางสถาปัตยกรรมที่สำคัญ** ของโปรเจกต์ โดยระบุ:
 
 - **Context**: เหตุผลที่ต้องตัดสินใจ
-- **Options Considered**: ทางเลือกที่พิจารณา
+- **Gap Analysis**: ปิด Gap จาก Requirements และแก้ไขความขัดแย้ง
+- **Impact Analysis**: ผลกระทบต่อ Components และการเปลี่ยนแปลงที่ต้องทำ
+- **Options Considered**: ทางเลือกที่พิจารณา (พร้อม Pros/Cons)
 - **Decision**: สิ่งที่เลือก และเหตุผล
+- **Version Dependencies**: ความสัมพันธ์ระหว่าง ADRs
 - **Consequences**: ผลที่ตามมา (ดีและไม่ดี)
+- **Review Cycle**: การทบทวน ADRs เป็นระยะ
 
 **วัตถุประสงค์:**
 
@@ -21,6 +25,9 @@ Architecture Decision Records (ADRs) เป็นเอกสารที่บ
 2. ป้องกันการสงสัยว่า "ทำไมถึงออกแบบแบบนี้" ในอนาคต
 3. ช่วยในการ Onboard สมาชิกใหม่
 4. บันทึกประวัติศาสตร์การพัฒนาโปรเจกต์
+5. **ใหม่!** เชื่อมโยงการตัดสินใจกับ Requirements และ Acceptance Criteria
+6. **ใหม่!** วิเคราะห์ผลกระทบอย่างเป็นระบบ
+7. **ใหม่!** จัดการ Version Dependencies ระหว่าง ADRs
 
 ---
 
@@ -80,7 +87,7 @@ Architecture Decision Records (ADRs) เป็นเอกสารที่บ
 | ADR                                             | Title                              | Status        | Date       | Summary                                                                      |
 | ----------------------------------------------- | ---------------------------------- | ------------- | ---------- | ---------------------------------------------------------------------------- |
 | [ADR-017](./ADR-017-ollama-data-migration.md)  | Ollama Data Migration Architecture | ✅ Accepted   | 2026-02-26 | On-premise AI (Ollama) สำหรับ Migration 20,000+ PDFs พร้อม Validation Layer |
-| [ADR-017B](./ADR-017B-ollama.md)               | Smart Legacy Document Digitization | ✅ Accepted   | 2026-03-27 | AI-powered categorization สำหรับเอกสารเก่า ตาม ADR-018 (AI Isolation)   |
+| [ADR-017B](./ADR-017B-ai-document-classification.md) | AI Document Classification | ✅ Accepted | 2026-03-27 | AI-powered document classification ตาม ADR-018 (AI Isolation) |
 | [ADR-018](./ADR-018-ai-boundary.md)            | AI Boundary Policy                 | ✅ Accepted   | 2026-03-27 | Physical Isolation + API-only communication (Zero Trust for AI)              |
 | [ADR-020](./ADR-020-ai-intelligence-integration.md) | AI Intelligence Integration Architecture | 🔄 Proposed | 2026-04-03 | Unified AI Pipeline สำหรับ RFA-First (Legacy Migration + New Ingestion)    |
 
@@ -142,16 +149,19 @@ Architecture Decision Records (ADRs) เป็นเอกสารที่บ
 
 ### ADR Structure
 
-แต่ละ ADR มีโครงสร้างดังนี้:
+แต่ละ ADR มีโครงสร้างดังนี้ (Enhanced Template v1.2):
 
-1. **Status**: Accepted, Proposed, Deprecated, Superseded
+1. **Gap Analysis & Purpose**: เชื่อมโยงกับ Requirements และแก้ไขความขัดแย้ง
 2. **Context**: ปัญหาหรือสถานการณ์ที่ต้องตัดสินใจ
 3. **Decision Drivers**: ปัจจัยที่มีผลต่อการตัดสินใจ
 4. **Considered Options**: ทางเลือกที่พิจารณา (พร้อม Pros/Cons)
 5. **Decision Outcome**: สิ่งที่เลือก และเหตุผล
-6. **Consequences**: ผลที่ตามมา (Positive/Negative/Mitigation)
-7. **Implementation Details**: รายละเอียดการ Implement (Code examples)
-8. **Related ADRs**: ADR อื่นที่เกี่ยวข้อง
+6. **🔍 Impact Analysis**: ผลกระทบต่อ Components และ Required Changes
+7. **📋 Version Dependency Matrix**: ความสัมพันธ์ระหว่าง ADRs และ Version Compatibility
+8. **Consequences**: ผลที่ตามมา (Positive/Negative/Mitigation)
+9. **🔄 Review Cycle & Maintenance**: กำหนดการทบทวนและ Version History
+10. **Implementation Details**: รายละเอียดการ Implement (Code examples)
+11. **Related ADRs**: ADR อื่นที่เกี่ยวข้อง
 
 ### Reading Tips
 
@@ -162,6 +172,39 @@ Architecture Decision Records (ADRs) เป็นเอกสารที่บ
 
 ---
 
+## 🆕 Enhanced Template & Review Process (v1.8.2)
+
+### New Features
+
+#### 🎯 Gap Analysis & Purpose
+- **ปิด Gap จากเอกสาร**: ระบุว่า ADR นี้แก้ไข Requirement ใด
+- **แก้ไขความขัดแย้ง**: ระบุว่า ADR นี้แก้ไขความขัดแย้งระหว่าง Requirements ใด
+
+#### 🔍 Impact Analysis
+- **Affected Components**: ระดับผลกระทบ (🔴 High, 🟡 Medium, 🟢 Low)
+- **Required Changes**: แบ่งเป็น Critical/Important/Nice-to-Have
+- **Cross-Module Dependencies**: Mermaid diagram แสดงความสัมพันธ์
+
+#### 📋 Version Dependency Matrix
+- **Dependency Types**: Core, Required, Used By, Conflicts, Supersedes
+- **Version Compatibility**: ระบุ version ที่ ADR มีผลบังคับใช้
+- **Implementation Status**: ✅ Implemented, 🔄 In Progress, ⚠️ Must Resolve
+
+#### 🔄 Review Cycle & Maintenance
+- **Review Schedule**: ทบทวนทุก 6 เดือนสำหรับ Core ADRs
+- **Review Checklist**: ตรวจสอบความเป็นปัจจุบัน
+- **Version History**: Tracking การเปลี่ยนแปลงของ ADR
+
+### Review Process
+
+- **Initial Review**: 7 วันทำการสำหรับ ADR ใหม่
+- **Scheduled Review**: ทุก 6 เดือนสำหรับ Core ADRs
+- **Triggered Review**: เมื่อมี Major version upgrade หรือ Critical issue
+
+📖 **ดูรายละเอียด**: [ADR Review Process](./ADR-REVIEW-PROCESS.md)
+
+---
+
 ## 🆕 Creating New ADRs
 
 ### When to Create an ADR?
@@ -182,68 +225,22 @@ Architecture Decision Records (ADRs) เป็นเอกสารที่บ
 
 ### ADR Template
 
-```markdown
-# ADR-XXX: [Title]
+ใช้ **Enhanced ADR Template v1.2** สำหรับ ADR ใหม่ทั้งหมด:
 
-**Status:** Proposed
-**Date:** YYYY-MM-DD
-**Decision Makers:** [Names]
-**Related Documents:** [Links]
+📋 **Template**: [ADR-TEMPLATE-enhanced.md](./ADR-TEMPLATE-enhanced.md)
 
----
+**Key Sections (ต้องรวมทุกอย่าง):**
+- ✅ Gap Analysis & Purpose
+- ✅ Impact Analysis (Components + Required Changes + Dependencies)
+- ✅ Version Dependency Matrix
+- ✅ Review Cycle & Maintenance
+- ✅ Cross-Module Dependencies (Mermaid diagram)
 
-## Context and Problem Statement
-
-[Describe the problem...]
-
----
-
-## Decision Drivers
-
-- [Driver 1]
-- [Driver 2]
-
----
-
-## Considered Options
-
-### Option 1: [Name]
-
-**Pros:**
-
-- ✅ [Pro 1]
-
-**Cons:**
-
-- ❌ [Con 1]
-
----
-
-## Decision Outcome
-
-**Chosen Option:** [Option X]
-
-### Rationale
-
-[Why this option...]
-
----
-
-## Consequences
-
-### Positive
-
-1. ✅ [Impact 1]
-
-### Negative
-
-1. ❌ [Risk 1]
-
----
-
-## Related ADRs
-
-- [ADR-XXX: Title](./ADR-XXX.md)
+**Quick Start:**
+```bash
+# Copy template
+cp ADR-TEMPLATE-enhanced.md ADR-XXX-title.md
+# Edit with your specific content
 ```
 
 ---
@@ -372,5 +369,14 @@ graph TB
 
 ---
 
-**Version:** 1.8.0
-**Last Review:** 2026-02-24
+**Version:** 1.8.2 (Enhanced Template + Review Process)
+**Last Review:** 2026-04-04
+**Next Review:** 2026-10-04
+
+---
+
+## 📚 Enhanced Documentation
+
+- **[Enhanced ADR Template](./ADR-TEMPLATE-enhanced.md)** - Template ใหม่พร้อม Impact Analysis
+- **[ADR Review Process](./ADR-REVIEW-PROCESS.md)** - กระบวนการทบทวนและ Version Management
+- **[Version Dependency Matrix](./VERSION-DEPENDENCIES.md)** - ความสัมพันธ์ระหว่าง ADRs (สร้างในอนาคต)

specs/08-Tasks/Task BE-AI-01.md

@@ -20,34 +20,16 @@
   - Webhook endpoint: `/webhook/ai-processing`
   - Environment variables: `N8N_BASIC_AUTH_USER`, `N8N_BASIC_AUTH_PASSWORD`
 - [ ] **Ollama Service:**
-  - Pull model: `gemma:9b` (GPU optimized, higher accuracy)
+  - Pull model: `gemma4:e4b` (GPU optimized, higher accuracy)
   - API endpoint: `http://localhost:11434`
   - Health check: `GET /api/tags`
   - Memory requirement: Minimum 8GB VRAM for 9B model
-  - ollama run gemma4:9b-q5_K_M / gemma4:9b-q4_K_M
-  - สร้างไฟล์ %USERPROFILE%\.ollama\config
-```config
-# ใช้ GPU เป็นหลัก
-gpu: true
-num_gpu: 1
-
-# เปิด KV cache เพื่อให้ตอบเร็วขึ้น
-kv_cache: true
-
-# จำกัด batch size ให้เหมาะกับ VRAM 8GB
-gpu_batch_size: 512
-
-# ปรับ num_thread ให้เหมาะกับ CPU 6–8 คอร์
-num_thread: 6
-
-# เปิด mmap เพื่อโหลดโมเดลเร็วขึ้น
-mmap: true
-
-# ปรับ max_seq_len ให้เหมาะกับงาน DMS
-max_seq_len: 4096
-
-# ปรับ temp ต่ำเพื่อให้ผลลัพธ์เสถียร
-temperature: 0.2
+  - ollama run gemma4
+  - ตั้ง Windows System Environment Variables หรือใน PowerShell:
+    - [System.Environment]::SetEnvironmentVariable('OLLAMA_HOST', '0.0.0.0', 'User')
+    - [System.Environment]::SetEnvironmentVariable('OLLAMA_KEEP_ALIVE', '30m', 'User')
+    - [System.Environment]::SetEnvironmentVariable("OLLAMA_NUM_GPU", "1", "User")
+    - [System.Environment]::SetEnvironmentVariable("OLLAMA_NUM_THREAD", "8", "User")
 ```
 
 - [ ] **PaddleOCR Service:**

specs/08-Tasks/Task BE-API-01.md

@@ -0,0 +1,274 @@
+# Task BE-API-01: API Design Strategy Implementation
+
+**Phase:** Backend API Standardization
+**ADR Compliance:** ADR-003 (API Design Strategy), ADR-019 (UUID Strategy)
+**Priority:** 🟡 Important - API Consistency & Developer Experience
+
+> **Context:** การ implement Hybrid REST + Action Endpoints ตาม ADR-003 เพื่อให้ API สอดคล้องกันทั่วทั้งระบบ
+
+---
+
+## 📋 Implementation Tasks
+
+### **API-1.1: Base Controller & Patterns**
+- [ ] **Create Base Controller Class:**
+  - File: `backend/src/common/controllers/base.controller.ts`
+  - Features: Standard CRUD operations, pagination, filtering
+  - Methods: `findAll()`, `findOne(uuid)`, `create()`, `update(uuid)`, `remove(uuid)`
+- [ ] **Create Standard Response DTOs:**
+  - File: `backend/src/common/dto/response.dto.ts`
+  - Types: `ApiResponse<T>`, `PaginatedResponse<T>`, `ActionResponse`
+  - Include meta information: timestamp, pagination, version
+- [ ] **Create Action Endpoint Decorator:**
+  - File: `backend/src/common/decorators/action-endpoint.decorator.ts`
+  - Purpose: Mark business action endpoints for Swagger documentation
+  - Usage: `@ActionEndpoint('submit', 'Submit correspondence for routing')`
+
+### **API-1.2: Correspondence API Refactor**
+- [ ] **Update Correspondence Controller:**
+  - File: `backend/src/modules/correspondence/correspondence.controller.ts`
+  - REST endpoints: GET, POST, PUT, PATCH, DELETE `/correspondences`
+  - Action endpoints: 
+    - POST `/correspondences/:uuid/submit`
+    - POST `/correspondences/:uuid/approve`
+    - POST `/correspondences/:uuid/reject`
+    - POST `/correspondences/:uuid/forward`
+- [ ] **Create Action DTOs:**
+  - File: `backend/src/modules/correspondence/dto/correspondence-actions.dto.ts`
+  - DTOs: `SubmitDto`, `ApproveDto`, `RejectDto`, `ForwardDto`
+  - Validation: Business rules for each action
+- [ ] **Update Correspondence Service:**
+  - Methods: `submit()`, `approve()`, `reject()`, `forward()`
+  - Integration: Workflow engine transitions
+  - Error handling: Business exceptions for invalid states
+
+### **API-1.3: RFA API Implementation**
+- [ ] **Create RFA Controller:**
+  - File: `backend/src/modules/rfa/rfa.controller.ts`
+  - REST endpoints: Standard CRUD for RFAs
+  - Action endpoints:
+    - POST `/rfa/:uuid/submit-for-review`
+    - POST `/rfa/:uuid/approve`
+    - POST `/rfa/:uuid/request-changes`
+    - POST `/rfa/:uuid/final-approve`
+- [ ] **Create RFA Action DTOs:**
+  - File: `backend/src/modules/rfa/dto/rfa-actions.dto.ts`
+  - DTOs: `SubmitForReviewDto`, `ApproveDto`, `RequestChangesDto`
+  - Include: Comments, attachments, change requests
+- [ ] **Update RFA Service:**
+  - Workflow integration: Document numbering, state transitions
+  - Business logic: Review cycles, approval chains
+  - Notifications: Trigger email/LINE notifications
+
+### **API-1.4: API Documentation & Testing**
+- [ ] **Update Swagger Configuration:**
+  - File: `backend/src/main.ts`
+  - Group endpoints by module and type (REST vs Actions)
+  - Add examples for all DTOs and responses
+  - Configure security: JWT Bearer authentication
+- [ ] **Create API Client Library:**
+  - File: `frontend/lib/api/client.ts`
+  - Methods: Typed API calls for all endpoints
+  - Error handling: Parse structured error responses
+  - Type safety: TypeScript interfaces for all DTOs
+- [ ] **Add Integration Tests:**
+  - Directory: `backend/test/api/`
+  - Coverage: All REST and action endpoints
+  - Scenarios: Success cases, error cases, permission tests
+  - Tools: Jest, Supertest
+
+### **API-1.5: Performance & Optimization**
+- [ ] **Implement Response Caching:**
+  - Master data endpoints: Organizations, projects, types
+  - Cache keys: `master:${entity}:${projectId}`
+  - TTL: 1 hour for master data, 15 minutes for dynamic data
+- [ ] **Add Request Validation:**
+  - DTO validation: class-validator decorators
+  - Business rule validation: Custom validators
+  - Rate limiting: By user role and endpoint type
+- [ ] **Database Query Optimization:**
+  - Pagination: Limit/offset with total count
+  - Filtering: Dynamic where clauses
+  - Relations: Eager loading for common queries
+
+---
+
+## 🔧 Technical Implementation Details
+
+### Base Controller Structure
+
+```typescript
+// File: backend/src/common/controllers/base.controller.ts
+export abstract class BaseController<T extends BaseEntity> {
+  constructor(
+    protected readonly service: BaseService<T>,
+    protected readonly entityName: string
+  ) {}
+
+  @Get()
+  @ApiResponse({ status: 200, description: `List ${entityName}` })
+  async findAll(@Query() query: PaginationDto): Promise<PaginatedResponse<T>> {
+    return this.service.findAll(query);
+  }
+
+  @Get(':uuid')
+  @ApiResponse({ status: 200, description: `Get ${entityName} by UUID` })
+  async findOne(@Param('uuid') uuid: string): Promise<ApiResponse<T>> {
+    return this.service.findOne(uuid);
+  }
+
+  @Post()
+  @ApiResponse({ status: 201, description: `Create ${entityName}` })
+  async create(@Body() dto: CreateDto): Promise<ApiResponse<T>> {
+    return this.service.create(dto);
+  }
+
+  // ... other standard methods
+}
+```
+
+### Action Endpoint Pattern
+
+```typescript
+// File: backend/src/modules/correspondence/correspondence.controller.ts
+@Controller('correspondences')
+@ApiTags('Correspondences')
+export class CorrespondenceController extends BaseController<Correspondence> {
+  
+  @Post(':uuid/submit')
+  @ActionEndpoint('submit', 'Submit correspondence for routing')
+  @ApiResponse({ status: 200, description: 'Correspondence submitted successfully' })
+  async submit(
+    @Param('uuid') uuid: string,
+    @Body() dto: SubmitCorrespondenceDto,
+    @CurrentUser() user: User
+  ): Promise<ActionResponse> {
+    return this.correspondenceService.submit(uuid, dto, user.id);
+  }
+
+  @Post(':uuid/approve')
+  @ActionEndpoint('approve', 'Approve correspondence')
+  async approve(
+    @Param('uuid') uuid: string,
+    @Body() dto: ApproveCorrespondenceDto,
+    @CurrentUser() user: User
+  ): Promise<ActionResponse> {
+    return this.correspondenceService.approve(uuid, dto, user.id);
+  }
+}
+```
+
+### Frontend API Client
+
+```typescript
+// File: frontend/lib/api/correspondence.ts
+export class CorrespondenceApi {
+  private client = new ApiClient('/correspondences');
+
+  // REST operations
+  async findAll(query?: CorrespondenceListQuery): Promise<PaginatedCorrespondences> {
+    return this.client.get('', { params: query });
+  }
+
+  async findOne(uuid: string): Promise<Correspondence> {
+    return this.client.get(`/${uuid}`);
+  }
+
+  async create(dto: CreateCorrespondenceDto): Promise<Correspondence> {
+    return this.client.post('', dto);
+  }
+
+  // Action operations
+  async submit(uuid: string, dto: SubmitCorrespondenceDto): Promise<ActionResponse> {
+    return this.client.post(`/${uuid}/submit`, dto);
+  }
+
+  async approve(uuid: string, dto: ApproveCorrespondenceDto): Promise<ActionResponse> {
+    return this.client.post(`/${uuid}/approve`, dto);
+  }
+}
+```
+
+---
+
+## 📊 Success Criteria
+
+### Functional Requirements
+- [ ] All correspondence endpoints follow hybrid pattern
+- [ ] RFA endpoints implemented with actions
+- [ ] Swagger documentation complete with examples
+- [ ] Frontend API client typed and tested
+- [ ] Integration tests cover all scenarios
+
+### Non-Functional Requirements
+- [ ] API response times < 200ms (p90)
+- [ ] Error responses consistent and user-friendly
+- [ ] Documentation auto-generated and up-to-date
+- [ ] Type safety across frontend and backend
+- [ ] Rate limiting and security implemented
+
+### Compliance Requirements
+- [ ] ADR-003 patterns followed consistently
+- [ ] ADR-019 UUID strategy implemented
+- [ ] ADR-007 error handling integrated
+- [ ] ADR-010 logging for all API calls
+
+---
+
+## 🚀 Deployment & Rollout
+
+### Phase 1: Backend Implementation (Week 1-2)
+- Implement base controller and patterns
+- Refactor correspondence API
+- Create comprehensive tests
+
+### Phase 2: Frontend Integration (Week 3)
+- Update API client library
+- Implement error handling UI
+- Add integration tests
+
+### Phase 3: Documentation & Monitoring (Week 4)
+- Complete Swagger documentation
+- Add API monitoring
+- Performance testing and optimization
+
+---
+
+## 📋 Dependencies & Prerequisites
+
+### Must Have
+- ✅ ADR-003 Approved
+- ✅ ADR-007 Error Handling Strategy
+- ✅ Base infrastructure (NestJS, TypeORM, Redis)
+- ✅ Authentication system (JWT, CASL)
+
+### Nice to Have
+- API analytics dashboard
+- Automated API testing pipeline
+- Client code generation
+
+---
+
+## 🔄 Review & Acceptance
+
+### Code Review Checklist
+- [ ] All endpoints follow hybrid pattern
+- [ ] DTOs properly validated
+- [ ] Error handling consistent
+- [ ] Documentation complete
+- [ ] Tests comprehensive
+- [ ] Performance optimized
+
+### Acceptance Criteria
+- [ ] API documentation available at `/api/docs`
+- [ ] All tests passing (>90% coverage)
+- [ ] Performance benchmarks met
+- [ ] Security scan passed
+- [ ] Frontend integration verified
+
+---
+
+**Owner:** Backend Team Lead  
+**Estimated Effort:** 3-4 weeks (1 developer)  
+**Risk Level:** Medium (API breaking changes)  
+**Rollback Plan:** Version previous API endpoints alongside new ones

specs/08-Tasks/Task BE-DB-01.md

@@ -0,0 +1,406 @@
+# Task BE-DB-01: Database Schema Strategy Implementation
+
+**Phase:** Database Standardization & Optimization
+**ADR Compliance:** ADR-004 (Database Schema Design), ADR-009 (Migration Strategy), ADR-019 (UUID Strategy)
+**Priority:** 🟡 Important - Data Integrity & Performance
+
+> **Context:** การ implement Selective Normalization Patterns ตาม ADR-004 เพื่อให้ database schema สอดคล้องกันและมีประสิทธิภาพ
+
+---
+
+## 📋 Implementation Tasks
+
+### **DB-1.1: Base Entity Pattern Implementation**
+- [ ] **Create Base Entity Classes:**
+  - File: `backend/src/common/entities/base.entity.ts`
+  - Features: UUID, timestamps, soft delete, audit fields
+  - Inheritance: All entities extend from base
+- [ ] **Create UuidBaseEntity (ADR-019):**
+  - File: `backend/src/common/entities/uuid-base.entity.ts`
+  - Properties: `id` (INT PK), `uuid` (UUID public), `createdAt`, `updatedAt`
+  - Decorators: `@Exclude()` for internal ID, `@Expose()` for UUID
+- [ ] **Update All Entity Classes:**
+  - Directory: `backend/src/modules/*/entities/`
+  - Extend from base entities
+  - Add proper decorators and relationships
+  - Ensure UUID handling compliance
+
+### **DB-1.2: Audit Trail Implementation**
+- [ ] **Create Audit Log Entity:**
+  - File: `backend/src/common/entities/audit-log.entity.ts`
+  - Table: `audit_logs`
+  - Fields: `tableName`, `recordId`, `action`, `oldValues`, `newValues`, `userId`
+  - Indexes: Performance optimization for queries
+- [ ] **Create Audit Trail Service:**
+  - File: `backend/src/common/services/audit-trail.service.ts`
+  - Methods: `logCreate()`, `logUpdate()`, `logDelete()`, `logSoftDelete()`
+  - Features: Automatic change detection, JSON diff, user tracking
+- [ ] **Implement Audit Interceptor:**
+  - File: `backend/src/common/interceptors/audit.interceptor.ts`
+  - Trigger: Before/After database operations
+  - Scope: All entity operations (CRUD)
+  - Performance: Async logging to avoid blocking
+
+### **DB-1.3: Workflow State Management**
+- [ ] **Create Workflow State Entities:**
+  - File: `backend/src/modules/workflow/entities/`
+  - Entities: `WorkflowState`, `WorkflowInstance`, `WorkflowHistory`
+  - Relationships: State machine definitions and instances
+- [ ] **Implement State Transition Logic:**
+  - File: `backend/src/modules/workflow/services/workflow-state.service.ts`
+  - Methods: `validateTransition()`, `executeTransition()`, `getCurrentState()`
+  - Features: Business rule validation, history tracking
+- [ ] **Create Workflow History Tables:**
+  - Tables: `workflow_histories`, `correspondence_histories`, `rfa_histories`
+  - Purpose: Track all state changes with context
+  - Features: JSON snapshots, user attribution, timestamps
+
+### **DB-1.4: Schema Optimization & Indexing**
+- [ ] **Analyze Current Query Patterns:**
+  - Tools: MySQL slow query log, EXPLAIN plans
+  - Focus: Correspondence list, RFA workflows, user permissions
+  - Document: Current performance bottlenecks
+- [ ] **Implement Strategic Indexes:**
+  - Foreign key indexes: All FK columns indexed
+  - Composite indexes: Common query patterns
+  - Partial indexes: Active records only (WHERE deleted_at IS NULL)
+- [ ] **Optimize Table Structures:**
+  - Review: Data types, column sizes, NULL constraints
+  - Normalize: Where beneficial for integrity
+  - Denormalize: Where beneficial for performance
+
+### **DB-1.5: Migration & Evolution Strategy**
+- [ ] **Create Migration Scripts:**
+  - Directory: `backend/src/database/migrations/`
+  - Format: SQL scripts (following ADR-009)
+  - Features: Rollback capability, dependency tracking
+- [ ] **Implement Schema Validation:**
+  - File: `backend/src/common/validators/schema.validator.ts`
+  - Checks: Naming conventions, required fields, relationships
+  - Automation: Pre-commit hooks, CI validation
+- [ ] **Create Database Documentation:**
+  - Auto-generation: From TypeORM entities
+  - Format: Markdown with ER diagrams
+  - Include: Field descriptions, relationships, indexes
+
+---
+
+## 🔧 Technical Implementation Details
+
+### Base Entity Implementation
+
+```typescript
+// File: backend/src/common/entities/base.entity.ts
+import { CreateDateColumn, UpdateDateColumn, DeleteDateColumn, Column } from 'typeorm';
+import { UuidBaseEntity } from './uuid-base.entity';
+
+export abstract class BaseEntity extends UuidBaseEntity {
+  @CreateDateColumn({ 
+    type: 'timestamp',
+    name: 'created_at',
+    comment: 'Record creation time'
+  })
+  createdAt: Date;
+
+  @UpdateDateColumn({ 
+    type: 'timestamp',
+    name: 'updated_at',
+    comment: 'Last update time'
+  })
+  updatedAt: Date;
+
+  @DeleteDateColumn({ 
+    type: 'datetime',
+    name: 'deleted_at',
+    nullable: true,
+    comment: 'Soft delete timestamp'
+  })
+  deletedAt?: Date;
+
+  @Column({ 
+    type: 'int',
+    name: 'created_by',
+    nullable: true,
+    comment: 'User who created record'
+  })
+  createdBy?: number;
+
+  @Column({ 
+    type: 'int',
+    name: 'updated_by',
+    nullable: true,
+    comment: 'User who last updated record'
+  })
+  updatedBy?: number;
+}
+```
+
+### UuidBaseEntity (ADR-019)
+
+```typescript
+// File: backend/src/common/entities/uuid-base.entity.ts
+import { PrimaryGeneratedColumn, Column, Exclude, Expose } from 'typeorm';
+
+export abstract class UuidBaseEntity {
+  @PrimaryGeneratedColumn()
+  @Exclude()
+  id: number;
+
+  @Column({ 
+    type: 'uuid',
+    unique: true,
+    name: 'uuid',
+    comment: 'Public UUID identifier (ADR-019)'
+  })
+  @Expose({ name: 'id' }) // Expose UUID as 'id' in API
+  uuid: string;
+}
+```
+
+### Audit Trail Service
+
+```typescript
+// File: backend/src/common/services/audit-trail.service.ts
+@Injectable()
+export class AuditTrailService {
+  constructor(
+    @InjectRepository(AuditLog)
+    private auditLogRepo: Repository<AuditLog>
+  ) {}
+
+  async logCreate(entity: BaseEntity, userId: number): Promise<void> {
+    const auditLog = this.auditLogRepo.create({
+      tableName: entity.constructor.name,
+      recordId: entity.id,
+      recordUuid: entity.uuid,
+      action: 'CREATE',
+      newValues: entity,
+      userId
+    });
+    await this.auditLogRepo.save(auditLog);
+  }
+
+  async logUpdate(
+    entity: BaseEntity, 
+    oldValues: any, 
+    newValues: any, 
+    userId: number
+  ): Promise<void> {
+    const changedFields = this.getChangedFields(oldValues, newValues);
+    
+    const auditLog = this.auditLogRepo.create({
+      tableName: entity.constructor.name,
+      recordId: entity.id,
+      recordUuid: entity.uuid,
+      action: 'UPDATE',
+      oldValues,
+      newValues,
+      changedFields,
+      userId
+    });
+    await this.auditLogRepo.save(auditLog);
+  }
+
+  private getChangedFields(old: any, new: any): string[] {
+    const changes: string[] = [];
+    for (const key in new) {
+      if (old[key] !== new[key]) {
+        changes.push(key);
+      }
+    }
+    return changes;
+  }
+}
+```
+
+### Audit Interceptor
+
+```typescript
+// File: backend/src/common/interceptors/audit.interceptor.ts
+@Injectable()
+export class AuditInterceptor implements NestInterceptor {
+  constructor(private auditService: AuditTrailService) {}
+
+  async intercept(context: ExecutionContext, next: CallHandler): Promise<Observable<any>> {
+    const request = context.switchToHttp().getRequest();
+    const userId = request.user?.id;
+    
+    return next.handle().pipe(
+      tap(async (result) => {
+        // Log successful operations
+        if (result && typeof result === 'object') {
+          await this.auditService.logCreate(result, userId);
+        }
+      }),
+      catchError(async (error) => {
+        // Log failed operations
+        console.error('Operation failed:', error);
+        throw error;
+      })
+    );
+  }
+}
+```
+
+### Workflow State Management
+
+```typescript
+// File: backend/src/modules/workflow/entities/workflow-instance.entity.ts
+@Entity('workflow_instances')
+export class WorkflowInstance extends BaseEntity {
+  @Column({ type: 'varchar', length: 50 })
+  workflowCode: string;
+
+  @Column({ type: 'varchar', length: 50 })
+  entityType: string; // 'correspondence', 'rfa', etc.
+
+  @Column({ type: 'int' })
+  entityId: number;
+
+  @Column({ type: 'varchar', length: 50 })
+  currentState: string;
+
+  @Column({ 
+    type: 'enum', 
+    enum: ['ACTIVE', 'COMPLETED', 'CANCELLED'],
+    default: 'ACTIVE'
+  })
+  status: string;
+
+  @Column({ type: 'json', nullable: true })
+  context: any; // Workflow-specific context
+
+  // Relationships
+  @ManyToOne(() => WorkflowState)
+  @JoinColumn({ 
+    name: 'workflow_code', 
+    referencedColumnName: 'workflow_code',
+    referencedColumnName: 'state_name'
+  })
+  currentStateDefinition: WorkflowState;
+
+  @OneToMany(() => WorkflowHistory, history => history.instance)
+  histories: WorkflowHistory[];
+}
+```
+
+### Schema Migration Example
+
+```sql
+-- File: backend/src/database/migrations/001_add_audit_trail.sql
+
+-- Create audit log table
+CREATE TABLE audit_logs (
+  id BIGINT PRIMARY KEY AUTO_INCREMENT,
+  table_name VARCHAR(50) NOT NULL,
+  record_id INT NOT NULL,
+  record_uuid UUID NULL,
+  action ENUM('CREATE', 'UPDATE', 'DELETE', 'SOFT_DELETE') NOT NULL,
+  old_values JSON NULL,
+  new_values JSON NULL,
+  changed_fields JSON NULL,
+  user_id INT NULL,
+  ip_address VARCHAR(45) NULL,
+  user_agent TEXT NULL,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  
+  INDEX idx_audit_table_record (table_name, record_id),
+  INDEX idx_audit_user (user_id, created_at),
+  INDEX idx_audit_created (created_at),
+  INDEX idx_audit_record_uuid (record_uuid)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci
+COMMENT='Audit trail for all data changes';
+
+-- Add base columns to existing tables (example)
+ALTER TABLE correspondences 
+ADD COLUMN created_by INT NULL COMMENT 'User who created record',
+ADD COLUMN updated_by INT NULL COMMENT 'User who last updated record',
+ADD INDEX idx_correspondences_created_by (created_by),
+ADD INDEX idx_correspondences_updated_by (updated_by);
+```
+
+---
+
+## 📊 Success Criteria
+
+### Functional Requirements
+- [ ] All entities extend from base classes
+- [ ] Audit trail captures all data changes
+- [ ] Workflow state management implemented
+- [ ] Database performance optimized
+- [ ] Migration strategy in place
+
+### Non-Functional Requirements
+- [ ] Query response times < 200ms (p90)
+- [ ] Audit logging doesn't impact performance
+- [ ] Schema validation automated
+- [ ] Documentation auto-generated
+- [ ] Zero data loss during migrations
+
+### Compliance Requirements
+- [ ] ADR-004 patterns followed consistently
+- [ ] ADR-009 migration strategy implemented
+- [ ] ADR-019 UUID strategy enforced
+- [ ] Audit trail meets compliance requirements
+
+---
+
+## 🚀 Deployment & Rollout
+
+### Phase 1: Base Pattern Implementation (Week 1)
+- Create base entity classes
+- Update core entities (users, organizations, projects)
+- Implement audit trail foundation
+
+### Phase 2: Workflow & Audit Implementation (Week 2-3)
+- Implement workflow state management
+- Add audit logging to all modules
+- Create migration scripts
+
+### Phase 3: Optimization & Documentation (Week 4)
+- Performance optimization and indexing
+- Schema validation automation
+- Documentation generation
+
+---
+
+## 📋 Dependencies & Prerequisites
+
+### Must Have
+- ✅ ADR-004 Approved
+- ✅ ADR-009 Migration Strategy
+- ✅ ADR-019 UUID Strategy
+- ✅ TypeORM configuration
+- ✅ Database backup strategy
+
+### Nice to Have
+- Database performance monitoring
+- Automated schema testing
+- Visual ER diagram generation
+
+---
+
+## 🔄 Review & Acceptance
+
+### Code Review Checklist
+- [ ] All entities follow base pattern
+- [ ] Audit logging comprehensive
+- [ ] Workflow state correct
+- [ ] Indexes optimized
+- [ ] Migration scripts safe
+- [ ] Documentation complete
+
+### Acceptance Criteria
+- [ ] All entities extend base classes
+- [ ] Audit trail captures 100% of changes
+- [ ] Performance benchmarks met
+- [ ] Migration scripts tested
+- [ ] Schema validation passes
+- [ ] Documentation generated
+
+---
+
+**Owner:** Backend Team Lead + DBA  
+**Estimated Effort:** 4 weeks (1-2 developers)  
+**Risk Level:** High (Database schema changes)  
+**Rollback Plan:** Full database backups, migration rollback scripts

specs/08-Tasks/Task BE-ERR-01.md

@@ -0,0 +1,466 @@
+# Task BE-ERR-01: Error Handling & Recovery Strategy Implementation
+
+**Phase:** Error Handling Standardization
+**ADR Compliance:** ADR-007 (Error Handling & Recovery), ADR-010 (Logging & Monitoring)
+**Priority:** 🟡 Important - User Experience & Debuggability
+
+> **Context:** การ implement Layered Error Handling ตาม ADR-007 เพื่อให้ error messages สอดคล้องกันและมีประโยชน์ต่อ users
+
+---
+
+## 📋 Implementation Tasks
+
+### **ERR-1.1: Exception Hierarchy Implementation**
+- [ ] **Create Base Exception Classes:**
+  - File: `backend/src/common/exceptions/base.exception.ts`
+  - Classes: `BaseException`, `ValidationException`, `BusinessException`
+  - Features: Error classification, user messages, recovery actions
+- [ ] **Create Specific Exception Types:**
+  - File: `backend/src/common/exceptions/`
+  - Types: `PermissionException`, `SystemException`, `WorkflowException`
+  - Properties: Error codes, severity levels, recovery guidance
+- [ ] **Implement Error Severity System:**
+  - Enum: `ErrorSeverity` (LOW, MEDIUM, HIGH, CRITICAL)
+  - Logic: Different handling based on severity
+  - Integration: Logging levels and alerting
+
+### **ERR-1.2: Global Exception Filter**
+- [ ] **Create Global Exception Filter:**
+  - File: `backend/src/common/filters/global-exception.filter.ts`
+  - Features: Layered error processing, information control
+  - Integration: NestJS exception handling pipeline
+- [ ] **Implement Error Classification:**
+  - Logic: Categorize errors by type and severity
+  - Response format: Standardized error responses
+  - Development vs Production: Different detail levels
+- [ ] **Add Error Logging Integration:**
+  - Integration: ADR-010 logging strategy
+  - Context: Request information, user details, stack traces
+  - Performance: Async logging to avoid blocking
+
+### **ERR-1.3: Service Layer Error Handling**
+- [ ] **Update Correspondence Service:**
+  - File: `backend/src/modules/correspondence/correspondence.service.ts`
+  - Methods: Use custom exceptions instead of generic errors
+  - Validation: Business rule validation with proper errors
+  - Recovery: Provide actionable error messages
+- [ ] **Update RFA Service:**
+  - File: `backend/src/modules/rfa/rfa.service.ts`
+  - Workflow errors: Invalid transitions, permission issues
+  - Document numbering: Duplicate numbers, format errors
+  - Integration: Workflow engine error handling
+- [ ] **Update All Other Services:**
+  - Directory: `backend/src/modules/*/services/`
+  - Pattern: Consistent error handling across all modules
+  - Validation: Input validation with detailed errors
+
+### **ERR-1.4: Frontend Error Handling**
+- [ ] **Create Error Display Component:**
+  - File: `frontend/components/common/error-display.tsx`
+  - Features: User-friendly error messages, recovery actions
+  - Styling: Consistent with design system
+  - Localization: Support for Thai/English messages
+- [ ] **Update API Client Error Handling:**
+  - File: `frontend/lib/api/client.ts`
+  - Logic: Parse structured error responses
+  - Actions: Display appropriate recovery options
+  - Integration: Global error state management
+- [ ] **Implement Error Recovery UI:**
+  - Features: Retry buttons, alternative actions, help links
+  - Context: Different recovery flows per error type
+  - User Experience: Clear guidance and next steps
+
+### **ERR-1.5: Error Catalog & Documentation**
+- [ ] **Create Error Catalog:**
+  - File: `docs/error-catalog.md`
+  - Content: All error codes, messages, recovery actions
+  - Format: Structured table with examples
+  - Maintenance: Process for adding new errors
+- [ ] **Implement Error Analytics:**
+  - Tracking: Error rates, patterns, user impact
+  - Dashboard: Error monitoring and alerting
+  - Integration: ADR-010 monitoring strategy
+- [ ] **Create Error Handling Guidelines:**
+  - Document: Developer guidelines for error handling
+  - Examples: Common patterns and best practices
+  - Review: Code review checklist for errors
+
+---
+
+## 🔧 Technical Implementation Details
+
+### Exception Hierarchy
+
+```typescript
+// File: backend/src/common/exceptions/base.exception.ts
+export enum ErrorType {
+  VALIDATION = 'VALIDATION',
+  BUSINESS_RULE = 'BUSINESS_RULE',
+  PERMISSION_DENIED = 'PERMISSION_DENIED',
+  NOT_FOUND = 'NOT_FOUND',
+  CONFLICT = 'CONFLICT',
+  INTERNAL_ERROR = 'INTERNAL_ERROR',
+  DATABASE_ERROR = 'DATABASE_ERROR',
+  EXTERNAL_SERVICE = 'EXTERNAL_SERVICE',
+  INFRASTRUCTURE = 'INFRASTRUCTURE'
+}
+
+export enum ErrorSeverity {
+  LOW = 'LOW',       // User mistake, easy recovery
+  MEDIUM = 'MEDIUM', // Business rule violation, needs action
+  HIGH = 'HIGH',     // System issue, may need support
+  CRITICAL = 'CRITICAL' // System failure, immediate attention
+}
+
+export abstract class BaseException extends HttpException {
+  constructor(
+    public readonly type: ErrorType,
+    public readonly code: string,
+    public readonly message: string,
+    public readonly userMessage?: string,
+    public readonly severity: ErrorSeverity = ErrorSeverity.MEDIUM,
+    public readonly details?: any,
+    public readonly recoveryActions?: string[]
+  ) {
+    super(
+      {
+        error: {
+          type,
+          code,
+          message: userMessage || message,
+          severity,
+          timestamp: new Date().toISOString(),
+          ...(recoveryActions && { recoveryActions }),
+          ...(process.env.NODE_ENV === 'development' && { 
+            technicalMessage: message,
+            details 
+          })
+        }
+      },
+      getStatusCode(type)
+    );
+  }
+}
+
+export class ValidationException extends BaseException {
+  constructor(message: string, details?: ValidationErrorDetail[]) {
+    super(
+      ErrorType.VALIDATION,
+      'VALIDATION_ERROR',
+      message,
+      'ข้อมูลที่กรอกไม่ถูกต้อง กรุณาตรวจสอบและลองใหม่',
+      ErrorSeverity.LOW,
+      details,
+      ['ตรวจสอบข้อมูลที่กรอก', 'แก้ไขข้อมูลที่ผิดพลาด', 'ลองใหม่อีกครั้ง']
+    );
+  }
+}
+```
+
+### Global Exception Filter
+
+```typescript
+// File: backend/src/common/filters/global-exception.filter.ts
+@Injectable()
+export class GlobalExceptionFilter implements ExceptionFilter {
+  private readonly logger = new Logger(GlobalExceptionFilter.name);
+
+  catch(exception: unknown, host: ArgumentsHost) {
+    const ctx = host.switchToHttp();
+    const response = ctx.getResponse();
+    const request = ctx.getRequest();
+
+    let errorResponse: any;
+
+    if (exception instanceof BaseException) {
+      // Handle our custom exceptions
+      errorResponse = exception.getResponse();
+      this.logError(exception, request, false);
+    } else if (exception instanceof HttpException) {
+      // Handle NestJS HTTP exceptions
+      const status = exception.getStatus();
+      const exceptionResponse = exception.getResponse();
+      
+      errorResponse = {
+        error: {
+          type: this.getErrorType(status),
+          code: 'HTTP_ERROR',
+          message: this.getUserMessage(status),
+          severity: ErrorSeverity.MEDIUM,
+          timestamp: new Date().toISOString(),
+          ...(process.env.NODE_ENV === 'development' && { 
+            technicalMessage: exception.message,
+            details: exceptionResponse 
+          })
+        }
+      };
+      this.logError(exception, request, false);
+    } else {
+      // Handle unexpected errors
+      errorResponse = {
+        error: {
+          type: ErrorType.INTERNAL_ERROR,
+          code: 'UNEXPECTED_ERROR',
+          message: 'เกิดข้อผิดพลาดที่ไม่คาดคิด กรุณาลองใหม่ภายหลัง',
+          severity: ErrorSeverity.CRITICAL,
+          timestamp: new Date().toISOString()
+        }
+      };
+      this.logError(exception, request, true);
+    }
+
+    response.status(errorResponse.error.statusCode || 500).json(errorResponse);
+  }
+
+  private logError(exception: any, request: Request, isCritical: boolean) {
+    const logData = {
+      path: request.url,
+      method: request.method,
+      userId: request.user?.id,
+      ip: request.ip,
+      userAgent: request.headers['user-agent'],
+      exception: {
+        name: exception.name,
+        message: exception.message,
+        stack: exception.stack,
+        details: exception.details
+      }
+    };
+
+    if (isCritical || exception.severity === ErrorSeverity.CRITICAL) {
+      this.logger.error('Critical error occurred', logData);
+    } else {
+      this.logger.warn('Error occurred', logData);
+    }
+  }
+}
+```
+
+### Service Layer Example
+
+```typescript
+// File: backend/src/modules/correspondence/correspondence.service.ts
+@Injectable()
+export class CorrespondenceService {
+  async create(createDto: CreateCorrespondenceDto, userId: number): Promise<Correspondence> {
+    try {
+      // Business validation
+      if (createDto.originatorId && !await this.canUserCreateForOrganization(userId, createDto.originatorId)) {
+        throw new PermissionException('correspondence', 'create for organization');
+      }
+
+      // Check for duplicate document number
+      if (await this.isDuplicateDocumentNumber(createDto.documentNumber)) {
+        throw new BusinessException(
+          'DUPLICATE_DOCUMENT_NUMBER',
+          `Document number ${createDto.documentNumber} already exists`,
+          'เลขที่เอกสารนี้มีอยู่แล้ว กรุณาใช้เลขที่อื่น',
+          ['ตรวจสอบเลขที่เอกสารล่าสุด', 'ขอเลขที่เอกสารใหม่']
+        );
+      }
+
+      // Create correspondence
+      const correspondence = this.correspondenceRepo.create({
+        ...createDto,
+        createdBy: userId,
+        createdAt: new Date()
+      });
+
+      const saved = await this.correspondenceRepo.save(correspondence);
+      
+      this.logger.log(`Correspondence created: ${saved.id}`);
+      return saved;
+
+    } catch (error) {
+      if (error instanceof BaseException) {
+        throw error; // Re-throw our custom exceptions
+      }
+
+      // Handle database errors
+      if (error.code === 'ER_DUP_ENTRY') {
+        throw new BusinessException(
+          'DUPLICATE_ENTRY',
+          'Database constraint violation',
+          'ข้อมูลซ้ำกันในระบบ กรุณาตรวจสอบ'
+        );
+      }
+
+      // Handle unexpected errors
+      this.logger.error('Unexpected error in CorrespondenceService.create', error);
+      throw new SystemException('Failed to create correspondence', error);
+    }
+  }
+}
+```
+
+### Frontend Error Display Component
+
+```typescript
+// File: frontend/components/common/error-display.tsx
+interface ErrorResponse {
+  error: {
+    type: string;
+    code: string;
+    message: string;
+    severity: string;
+    timestamp: string;
+    recoveryActions?: string[];
+    technicalMessage?: string;
+    details?: any;
+  };
+}
+
+export function ErrorDisplay({ error, onRetry }: { error: ErrorResponse; onRetry?: () => void }) {
+  const getSeverityColor = (severity: string) => {
+    switch (severity) {
+      case 'LOW': return 'text-yellow-600';
+      case 'MEDIUM': return 'text-orange-600';
+      case 'HIGH': return 'text-red-600';
+      case 'CRITICAL': return 'text-red-800';
+      default: return 'text-gray-600';
+    }
+  };
+
+  return (
+    <div className="rounded-lg border border-red-200 bg-red-50 p-4">
+      <div className="flex items-center">
+        <div className="flex-shrink-0">
+          <ExclamationTriangleIcon className="h-5 w-5 text-red-400" />
+        </div>
+        <div className="ml-3">
+          <h3 className={`text-sm font-medium ${getSeverityColor(error.error.severity)}`}>
+            {error.error.message}
+          </h3>
+          
+          {error.error.recoveryActions && (
+            <div className="mt-2 text-sm text-gray-600">
+              <p className="font-medium">วิธีแก้ไข:</p>
+              <ul className="list-disc list-inside space-y-1">
+                {error.error.recoveryActions.map((action, index) => (
+                  <li key={index}>{action}</li>
+                ))}
+              </ul>
+            </div>
+          )}
+
+          <div className="mt-3 flex space-x-3">
+            {onRetry && (
+              <button
+                onClick={onRetry}
+                className="rounded bg-blue-600 px-3 py-1 text-sm text-white hover:bg-blue-700"
+              >
+                ลองใหม่
+              </button>
+            )}
+            <button className="rounded bg-gray-600 px-3 py-1 text-sm text-white hover:bg-gray-700">
+              ติดต่อผู้ดูแลระบบ
+            </button>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+### Error Catalog Structure
+
+```markdown
+# Error Catalog
+
+| Error Code | Type | User Message | Recovery Actions | Severity | Module |
+|------------|------|--------------|------------------|----------|--------|
+| VALIDATION_ERROR | Validation | ข้อมูลที่กรอกไม่ถูกต้อง | ตรวจสอบข้อมูล, แก้ไข, ลองใหม่ | LOW | All |
+| DUPLICATE_DOCUMENT_NUMBER | Business | เลขที่เอกสารซ้ำกัน | ตรวจสอบเลขล่าสุด, ขอเลขใหม่ | MEDIUM | Correspondence |
+| CORRESPONDENCE_NOT_FOUND | Business | ไม่พบเอกสาร | ตรวจสอบ UUID, ค้นหาใหม่ | MEDIUM | Correspondence |
+| PERMISSION_DENIED | Permission | ไม่มีสิทธิ์ดำเนินการ | ติดต่อ admin, ใช้บัญชีอื่น | MEDIUM | All |
+| WORKFLOW_INVALID_TRANSITION | Business | ไม่สามารถดำเนินการได้ในสถานะปัจจุบัน | ตรวจสอบ workflow, ดำเนินการอื่น | MEDIUM | Workflow |
+| INTERNAL_ERROR | System | เกิดข้อผิดพลาดในระบบ | ลองใหม่, ติดต่อ admin | HIGH | All |
+| DATABASE_ERROR | System | ฐานข้อมูลมีปัญหา | ลองใหม่ภายหลัง, แจ้ง admin | HIGH | All |
+| EXTERNAL_SERVICE | System | บริการภายนอกมีปัญหา | ลองใหม่ภายหลัง | MEDIUM | Notification |
+```
+
+---
+
+## 📊 Success Criteria
+
+### Functional Requirements
+- [ ] Exception hierarchy implemented
+- [ ] Global exception filter working
+- [ ] All services use custom exceptions
+- [ ] Frontend displays user-friendly errors
+- [ ] Error catalog complete
+
+### Non-Functional Requirements
+- [ ] Error responses consistent across all endpoints
+- [ ] Error logging integrated with ADR-010
+- [ ] User recovery guidance actionable
+- [ ] Technical details controlled in production
+- [ ] Error analytics and monitoring
+
+### Compliance Requirements
+- [ ] ADR-007 patterns followed consistently
+- [ ] ADR-010 logging integrated
+- [ ] Security: No information leakage
+- [ ] Accessibility: Error messages understandable
+
+---
+
+## 🚀 Deployment & Rollout
+
+### Phase 1: Backend Implementation (Week 1)
+- Create exception hierarchy
+- Implement global filter
+- Update core services
+
+### Phase 2: Service Updates (Week 2)
+- Update all service methods
+- Add comprehensive error handling
+- Create error catalog
+
+### Phase 3: Frontend Integration (Week 3)
+- Update error display components
+- Implement recovery UI
+- Add error analytics
+
+---
+
+## 📋 Dependencies & Prerequisites
+
+### Must Have
+- ✅ ADR-007 Approved
+- ✅ ADR-010 Logging Strategy
+- ✅ NestJS framework setup
+- ✅ Frontend error state management
+
+### Nice to Have
+- Error monitoring dashboard
+- Automated error testing
+- Error localization framework
+
+---
+
+## 🔄 Review & Acceptance
+
+### Code Review Checklist
+- [ ] Exception hierarchy comprehensive
+- [ ] Global filter handles all cases
+- [ ] Services use proper exceptions
+- [ ] Frontend error handling user-friendly
+- [ ] Error catalog complete
+- [ ] No information leakage
+
+### Acceptance Criteria
+- [ ] All errors use custom exceptions
+- [ ] Error responses standardized
+- [ ] User recovery guidance clear
+- [ ] Technical details controlled
+- [ ] Error logging comprehensive
+- [ ] Frontend error handling tested
+
+---
+
+**Owner:** Backend Team Lead + Frontend Team Lead  
+**Estimated Effort:** 3 weeks (1-2 developers)  
+**Risk Level:** Low (Improvement, no breaking changes)  
+**Rollback Plan:** Revert to previous error handling