690417:1707 Refactor Work flow ADR-021

.windsurf/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.6
+- **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

.windsurf/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`

.windsurf/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

.windsurf/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
+```

.windsurf/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                  |

.windsurf/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

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

@@ -0,0 +1,63 @@
+---
+trigger: glob
+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`

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

@@ -0,0 +1,54 @@
+---
+trigger: glob
+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`

.windsurf/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                      |

.windsurf/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`

.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`