690519:0819 Prepare refactor AI [skip ci]
This commit is contained in:
Nattanin
+256
-49
@@ -1,7 +1,7 @@
|
||||
# NAP-DMS Gemini Rules & Standards
|
||||
|
||||
- For: Gemini 1.5 Pro / Flash / 2.0 (Google AI Studio, Vertex AI, Antigravity)
|
||||
- Version: 1.9.3 | Last synced from AGENTS.md: 2026-05-16
|
||||
- For: Gemini (Google AI Studio, Vertex AI, Antigravity, Gemini CLI)
|
||||
- Version: 1.9.5 | Last synced from AGENTS.md: 2026-05-18
|
||||
- Repo: [https://git.np-dms.work/np-dms/lcbp3](https://git.np-dms.work/np-dms/lcbp3)
|
||||
- Skill pack: `.agents/skills/` (v1.9.0, 21 skills) — see [`skills/README.md`](../.agents/skills/README.md) + [`skills/_LCBP3-CONTEXT.md`](../.agents/skills/_LCBP3-CONTEXT.md)
|
||||
|
||||
@@ -9,20 +9,9 @@
|
||||
|
||||
## 🧠 Role & Persona
|
||||
|
||||
Act as a **Senior Full Stack Developer** specialized in:
|
||||
Act as **Senior Full Stack Developer** specialized in NestJS, Next.js, TypeScript, DMS. Focus: Data Integrity, Security, Maintainability, Performance.
|
||||
|
||||
- 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**.
|
||||
You are a **Document Intelligence Engine** — not a general chatbot. Every response must be **precise**, **spec-compliant**, and **production-ready**.
|
||||
|
||||
---
|
||||
|
||||
@@ -51,23 +40,23 @@ If significant logic changes are made, summarize what was done for the user afte
|
||||
|
||||
## ⚙️ DMS Workflow Engine Protocol
|
||||
|
||||
กฎนี้ใช้คุมการเขียน Logic ส่วนการไหลของเอกสาร (RFA, Transmittal, Correspondence) เพื่อป้องกันปัญหา Race Condition และรักษาความถูกต้องของสถานะเอกสาร:
|
||||
กฎนี้ใช้คุม Logic การไหลของเอกสาร (RFA, Transmittal, Correspondence) เพื่อป้องกัน Race Condition และรักษาความถูกต้องของสถานะ:
|
||||
|
||||
- **State Management:** ทุกการเปลี่ยนสถานะของ Workflow ต้องตรวจสอบสถานะปัจจุบันจากฐานข้อมูลก่อนเสมอ เพื่อป้องกันการอนุมัติซ้ำซ้อน
|
||||
- **Concurrency Control:** หากมีการเจนเลขที่เอกสาร (Document Numbering) ต้องใช้ **Redis Redlock** หรือ **TypeORM `@VersionColumn`** เท่านั้น ห้ามใช้ logic ฝั่งแอปพลิเคชันเพียงอย่างเดียว (ADR-002)
|
||||
- **Background Jobs:** งานที่ต้องใช้เวลานานหรือการแจ้งเตือน (Email/Notification) ต้องถูกส่งไปทำที่ **BullMQ** ห้ามเขียนแบบ Inline ใน Service (ADR-008)
|
||||
- **Term Consistency:** ห้ามใช้คำทั่วไปอย่าง "Approval Flow" ให้ใช้ **"Workflow Engine"** และห้ามใช้ "Letter" ให้ใช้ **"Correspondence"** ตามที่กำหนดใน Glossary
|
||||
- **State Management:** ตรวจสอบสถานะปัจจุบันจาก DB ก่อนเสมอ เพื่อป้องกันการอนุมัติซ้ำซ้อน (ดู `05-06-code-snippets.md` `[workflow-transition]`)
|
||||
- **Concurrency Control:** การจอนเลขที่เอกสารต้องใช้ **Redis Redlock** หรือ **TypeORM `@VersionColumn`** เท่านั้น (ADR-002)
|
||||
- **Background Jobs:** งานนานหรือการแจ้งเตือนต้องส่งไปทำที่ **BullMQ** ห้ามเขียนแบบ Inline (ADR-008)
|
||||
- **Term Consistency:** ห้ามใช้ "Approval Flow" ให้ใช้ **"Workflow Engine"** และห้ามใช้ "Letter" ให้ใช้ **"Correspondence"** (หมายเหตุ: "จดหมาย" ในคอมเมนต์ภาษาไทย = Correspondence ที่ครอบคลุมทุกประเภท)
|
||||
|
||||
---
|
||||
|
||||
## 🛡️ Security & Integrity Audit Protocol
|
||||
|
||||
กฎนี้จะช่วยให้ AI ทำหน้าที่เป็น Gatekeeper ก่อนที่คุณจะ Commit โค้ด โดยเน้นไปที่ **Tier 1 — CRITICAL**:
|
||||
กฎนี้ให้ AI เป็น Gatekeeper ก่อน Commit โดยเน้น **Tier 1 — CRITICAL**:
|
||||
|
||||
- **UUID Validation:** ทุกครั้งที่มีการรับค่า ID จาก API หรือ URL ต้องตรวจสอบว่าเป็น **UUIDv7** และห้ามใช้ `parseInt()` หรือตัวดำเนินการทางคณิตศาสตร์กับค่านี้เด็ดขาด (ADR-019)
|
||||
- **RBAC Check:** การสร้าง API ใหม่ต้องมี **CASL Guard** และตรวจสอบสิทธิ์แบบ 4-Level RBAC Matrix เสมอ (ADR-016)
|
||||
- **Data Isolation:** หากมีการใช้ฟีเจอร์ AI ต้องมั่นใจว่ารันผ่าน **Ollama บน Admin Desktop** เท่านั้น และห้ามให้ AI เข้าถึง Database หรือ Storage โดยตรง (ต้องผ่าน DMS API เท่านั้น) (ADR-023)
|
||||
- **Input Sanitization:** ไฟล์อัปโหลดต้องผ่านการตรวจสอบแบบ **Two-Phase** (Temp → Commit) และต้องสแกนด้วย **ClamAV** ก่อนย้ายเข้า Permanent Storage (ADR-016)
|
||||
- **UUID Validation:** ตรวจสอบว่าเป็น **UUIDv7** และห้ามใช้ `parseInt()` บน UUID (ADR-019)
|
||||
- **RBAC Check:** API ใหม่ต้องมี **CASL Guard** และตรวจสอบ 4-Level RBAC Matrix (ADR-016)
|
||||
- **Data Isolation:** AI ต้องรันผ่าน **Ollama บน Admin Desktop** เท่านั้น ห้ามเข้าถึง DB/storage โดยตรง (ADR-023)
|
||||
- **Input Sanitization:** ไฟล์อัปโหลดต้องผ่าน **Two-Phase** (Temp → Commit) และสแกนด้วย **ClamAV** (ADR-016)
|
||||
|
||||
---
|
||||
|
||||
@@ -95,7 +84,16 @@ Must fix before merge:
|
||||
- Naming conventions
|
||||
- **TypeScript Standards:** Missing JSDoc, explicit types, or file headers
|
||||
|
||||
### 🟢 Tier 3 — GUIDELINES
|
||||
### 🟢 Tier 3 — SPECIALIZED WORK
|
||||
|
||||
Requires domain-specific knowledge:
|
||||
|
||||
- **ADR-021 Integration:** Workflow Engine & Context implementation
|
||||
- **AI Integration:** ADR-023/023A boundary enforcement and pipeline usage
|
||||
- **Complex Business Logic:** Multi-step workflows with state management
|
||||
- **Performance Optimization:** Database queries, caching strategies, bulk operations
|
||||
|
||||
### 🔵 Tier 4 — GUIDELINES
|
||||
|
||||
Best practice — follow when possible:
|
||||
|
||||
@@ -122,9 +120,10 @@ Spec priority: **`06-Decision-Records`** > **`05-Engineering-Guidelines`** > oth
|
||||
| **ADR-008 Notifications** | `specs/06-Decision-Records/ADR-008-email-notification-strategy.md` | ✅ Active | BullMQ + multi-channel notification |
|
||||
| **ADR-009 DB Migration** | `specs/06-Decision-Records/ADR-009-database-migration-strategy.md` | ✅ Active | Schema changes — edit SQL directly |
|
||||
| **ADR-016 Security** | `specs/06-Decision-Records/ADR-016-security-authentication.md` | ✅ Active | Auth, RBAC, file upload security |
|
||||
| **ADR-015 Release Strategy** | `specs/06-Decision-Records/ADR-015-deployment-infrastructure.md` | ✅ Active | Blue-Green deployment + release gates |
|
||||
| **ADR-019 UUID** | `specs/06-Decision-Records/ADR-019-hybrid-identifier-strategy.md` | ✅ Active | UUID-related work |
|
||||
| **ADR-021 Workflow Context** | `specs/06-Decision-Records/ADR-021-workflow-context.md` | ✅ Active | Integrated workflow & step attachments |
|
||||
| **ADR-023 AI Architecture** | `specs/06-Decision-Records/ADR-023-unified-ai-architecture.md` | ✅ Active | Unified AI boundaries and pipeline (base architecture) |
|
||||
| **ADR-023 AI Architecture** | `specs/06-Decision-Records/ADR-023-unified-ai-architecture.md` | ✅ Active | Unified AI boundaries and pipeline (base architecture) |
|
||||
| **ADR-023A AI Model Rev.** | `specs/06-Decision-Records/ADR-023A-unified-ai-architecture.md` | ✅ Active | 2-Model stack (gemma4:e4b Q8_0), BullMQ 2-queue, RAG embed scope, OCR auto-detect |
|
||||
| **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 |
|
||||
@@ -164,6 +163,32 @@ Spec priority: **`06-Decision-Records`** > **`05-Engineering-Guidelines`** > oth
|
||||
- `200-fullstacks/` - งาน Fullstack Development (Backend + Frontend features, Workflow Engine, API)
|
||||
- `300-others/` - งานอื่นๆ (Documentation, Research, Non-code tasks)
|
||||
|
||||
### การตั้งชื่อโฟลเดอร์ Feature Work
|
||||
|
||||
ใช้รูปแบบ: `nXX-feature-name`
|
||||
|
||||
- **n** = หลักร้อยของหมวดหมู่ (1, 2, 3)
|
||||
- **XX** = เลขลำดับงาน (01, 02, 03, ...)
|
||||
- **feature-name** = ชื่องาน (kebab-case)
|
||||
|
||||
ตัวอย่าง:
|
||||
|
||||
- `100-Infrastructures/102-infra-ops` - Infrastructure Operations
|
||||
- `200-fullstacks/201-transmittals-circulation` - Transmittals + Circulation Integration
|
||||
- `200-fullstacks/203-unified-workflow-engine` - Unified Workflow Engine
|
||||
|
||||
### กฎสำคัญ
|
||||
|
||||
- **เมื่อสร้าง feature spec ใหม่** → วางไว้ในหมวดหมู่ที่เหมาะสม (100/200/300)
|
||||
- **ใช้เลขลำดับต่อจากงานล่าสุด** ในหมวดหมู่เดียวกัน
|
||||
- **อ่าน README.md** ในแต่ละหมวดหมู่ก่อนเริ่มงาน
|
||||
|
||||
ดูรายละเอียดเพิ่มเติมใน:
|
||||
|
||||
- `specs/100-Infrastructures/README.md`
|
||||
- `specs/200-fullstacks/README.md`
|
||||
- `specs/300-others/README.md`
|
||||
|
||||
---
|
||||
|
||||
## 🆔 Identifier Strategy (ADR-019) — CRITICAL
|
||||
@@ -194,6 +219,8 @@ const value = c.publicId ?? c.id ?? ''; // Wrong!
|
||||
const value = c.publicId; // "019505a1-7c3e-7000-8000-abc123def456"
|
||||
```
|
||||
|
||||
Read `specs/05-Engineering-Guidelines/05-07-hybrid-uuid-implementation-plan.md` before any UUID-related work.
|
||||
|
||||
---
|
||||
|
||||
## 🛡️ Security Rules (Non-Negotiable)
|
||||
@@ -209,6 +236,25 @@ const value = c.publicId; // "019505a1-7c3e-7000-8000-abc123def456"
|
||||
9. **Error Handling (ADR-007):** Use layered error classification with user-friendly messages
|
||||
10. **AI Integration (ADR-023/023A):** RFA-First approach; n8n orchestrates Migration Phase only via DMS API — never calls Ollama directly; `QdrantService.search()` requires `projectPublicId` as mandatory param
|
||||
|
||||
Full details: `specs/06-Decision-Records/ADR-016-security-authentication.md`
|
||||
|
||||
---
|
||||
|
||||
## 🚧 Out of Scope — Never Do Without Explicit Approval
|
||||
|
||||
| ❌ Never Do Autonomously | ⚠️ Why Approval Is Required |
|
||||
| --------------------------------------------------------------- | ---------------------------------------------------------------- |
|
||||
| `DROP` or `RENAME` a column / table | Irreversible data loss — requires DBA + PM sign-off |
|
||||
| Push directly to `main` / `master` branch | Bypasses CI, code review, and release gates |
|
||||
| Generate or insert seed data into production database | May corrupt live data or violate business state invariants |
|
||||
| Delete files from permanent storage | Files may be referenced in active documents or audit trails |
|
||||
| Modify RBAC permission matrix without security team approval | Defines access control for all users — security boundary change |
|
||||
| Upgrade major library versions (NestJS, Next.js, TypeORM, etc.) | Breaking changes require full regression test cycle |
|
||||
| Disable or modify authentication / authorization guards | Creates unguarded endpoints — immediate security risk |
|
||||
| Change Redis lock TTL or disable Redlock | Risk of document number race condition (ADR-002) |
|
||||
| Create or supersede an ADR unilaterally | Architecture decisions require team consensus and review process |
|
||||
| Add new columns to production tables without schema review | Must update Data Dictionary + downstream queries simultaneously |
|
||||
|
||||
---
|
||||
|
||||
## 📐 TypeScript Rules & Coding Standards
|
||||
@@ -304,36 +350,197 @@ const value = c.publicId; // "019505a1-7c3e-7000-8000-abc123def456"
|
||||
3. Add regression test if logic changed
|
||||
4. Verify no forbidden patterns introduced
|
||||
|
||||
### 🟣 Specialized Work — ADR-021, AI Integration, Complex Logic
|
||||
|
||||
**MUST complete:**
|
||||
|
||||
1. **Domain Knowledge Check** - Read relevant ADRs (ADR-021, ADR-023/023A)
|
||||
2. **Pattern Verification** - Check existing implementations in codebase
|
||||
3. **Specialized Requirements** - Follow domain-specific patterns
|
||||
4. **Complex Logic Testing** - Multi-scenario test coverage
|
||||
5. **Performance Validation** - Load testing if applicable
|
||||
|
||||
**For ADR-021 Integration:**
|
||||
|
||||
- Read ADR-021 - Integrated workflow & step attachments
|
||||
- Check ADR-001 - Unified workflow engine patterns
|
||||
- Verify WorkflowEngineService - Polymorphic instance handling
|
||||
- Add workflow fields - Expose workflowInstanceId, workflowState, availableActions
|
||||
- Include IntegratedBanner - Frontend workflow lifecycle display
|
||||
- Test workflow transitions - State changes and action validation
|
||||
|
||||
**For AI Integration (ADR-023/023A):**
|
||||
|
||||
- Verify AI boundary enforcement - No direct DB/storage access
|
||||
- Check BullMQ 2-queue setup - ai-realtime + ai-batch
|
||||
- Validate Qdrant multi-tenancy - projectPublicId filter required
|
||||
- Test human-in-the-loop validation workflows
|
||||
- Audit AI interaction logging
|
||||
|
||||
**Expected output:**
|
||||
|
||||
- Backend services expose specialized context fields
|
||||
- Frontend components use domain-specific patterns
|
||||
- Complex state management with proper validation
|
||||
- Performance metrics within acceptable thresholds
|
||||
- Comprehensive test coverage for edge cases
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Context-Aware Triggers
|
||||
|
||||
When user asks about... check these files:
|
||||
|
||||
| Request | Files to Check | Expected Response |
|
||||
| ----------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------- |
|
||||
| "สร้าง API ใหม่" | `05-02-backend-guidelines.md`, `lcbp3-v1.9.0-schema-02-tables.sql` | NestJS Controller + Service + DTO + CASL Guard |
|
||||
| "แก้ฟอร์ม frontend" | `05-03-frontend-guidelines.md`, `01-06-edge-cases-and-rules.md` | RHF+Zod + TanStack Query + Thai comments |
|
||||
| "เพิ่ม field ใหม่" | `ADR-009`, `03-01-data-dictionary.md`, `lcbp3-v1.9.0-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" | `lcbp3-v1.9.0-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-023`, `ADR-023A` | AI boundary + 2-model stack + BullMQ queue policy |
|
||||
| "Error handling" | `ADR-007` | Layered error classification + recovery |
|
||||
| "File upload" | `ADR-016`, `05-02-backend-guidelines.md`, `03-Data-and-Storage/03-03-file-storage.md` | Two-phase upload → temp → commit; ClamAV + whitelist |
|
||||
| "Notifications / Queue" | `ADR-008`, `05-02-backend-guidelines.md` | BullMQ job — never inline; check retry + dead-letter |
|
||||
| "Add i18n / translate" | `05-08-i18n-guidelines.md` | i18n keys only — no hardcoded text |
|
||||
| "Workflow / DSL" | `ADR-001`, `01-03-modules/01-03-06-unified-workflow.md` | DSL state machine + WorkflowEngineService |
|
||||
| "Document numbering" | `ADR-002`, `01-02-business-rules/01-02-02-doc-numbering-rules.md` | Redis Redlock + DB optimistic lock (double-lock) |
|
||||
| Request | Status | Files to Check | Expected Response |
|
||||
| --------------------------- | ------ | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
|
||||
| "สร้าง API ใหม่" | ✅ | `05-02-backend-guidelines.md`, `lcbp3-v1.9.0-schema-02-tables.sql` | NestJS Controller + Service + DTO + CASL Guard |
|
||||
| "แก้ฟอร์ม frontend" | ✅ | `05-03-frontend-guidelines.md`, `01-06-edge-cases-and-rules.md` | RHF+Zod + TanStack Query + Thai comments |
|
||||
| "เพิ่ม field ใหม่" | ✅ | `ADR-009`, `03-01-data-dictionary.md`, `lcbp3-v1.9.0-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" | ✅ | `lcbp3-v1.9.0-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-023`, `ADR-023A` | AI boundary + 2-model stack + BullMQ queue policy |
|
||||
| "Error handling" | ✅ | `ADR-007` | Layered error classification + recovery |
|
||||
| "File upload" | ✅ | `ADR-016`, `05-02-backend-guidelines.md`, `03-Data-and-Storage/03-03-file-storage.md` | Two-phase upload → temp → commit; ClamAV + whitelist |
|
||||
| "Notifications / Queue" | ✅ | `ADR-008`, `05-02-backend-guidelines.md` | BullMQ job — never inline; check retry + dead-letter |
|
||||
| "Add i18n / translate" | ✅ | `05-08-i18n-guidelines.md` | i18n keys only — no hardcoded text |
|
||||
| "Workflow / DSL" | ✅ | `ADR-001`, `01-03-modules/01-03-06-unified-workflow.md` | DSL state machine + WorkflowEngineService |
|
||||
| "Document numbering" | ✅ | `ADR-002`, `01-02-business-rules/01-02-02-doc-numbering-rules.md` | Redis Redlock + DB optimistic lock (double-lock) |
|
||||
| "ตรวจสอบ Workflow" | ✅ | `01-06-edge-cases-and-rules.md`, `05-02-backend-guidelines.md`, `ADR-001`, `ADR-002` | เช็คการเปลี่ยน State, คิว BullMQ และการล็อกเลขที่เอกสาร |
|
||||
| "Transmittal submit" | 📋 | `ADR-021`, `specs/200-fullstacks/201-transmittals-circulation/` | submit() with EC-RFA-004 validation |
|
||||
| "Circulation reassign" | 📋 | `ADR-021`, `specs/200-fullstacks/201-transmittals-circulation/` | reassignRouting() with EC-CIRC-001 |
|
||||
| "สร้าง workflow ใหม่" | 📋 | `ADR-001`, `ADR-021`, `specs/200-fullstacks/203-unified-workflow-engine/` | DSL workflow definition + WorkflowEngineService setup |
|
||||
| "ตรวจสอบ AI boundary" | ✅ | `ADR-023`, `ADR-023A` | Verify Ollama isolation + BullMQ queues + Qdrant projectPublicId filter |
|
||||
| "จัดการ document numbering" | ✅ | `ADR-002`, `specs/03-Data-and-Storage/03-04-document-numbering.md` | Redis Redlock + template system + preview/override workflows |
|
||||
| "Audit ความปลอดภัย" | ✅ | `ADR-016`, `ADR-019`, `ADR-023`, `ADR-023A` | ตรวจสอบ UUID pattern, CASL Guard, AI Boundary และ Qdrant multi-tenancy |
|
||||
| "แก้ bug / bugfix" | ✅ | `.agents/workflows/bugfix.md`, `error-catalog.md` | ใช้ bugfix workflow สำหรับเคสที่สาเหตุชัดเจน |
|
||||
| "ตรวจแอปจริง" | ✅ | `.windsurf/workflows/check-real-app.md` | ตรวจ endpoint/UI/console หลัง build pass — No Fake Evidence |
|
||||
| "งานค้าง / resume" | ✅ | `.windsurf/workflows/resume-pending-work.md` | อ่าน checkpoint เดิม → ตรวจ build → วางแผนต่อโดยไม่ทำงานซ้ำ |
|
||||
|
||||
**Status Legend:**
|
||||
|
||||
- ✅ Implemented and verified
|
||||
- 📋 Spec exists, implementation in progress
|
||||
- 🔄 In development
|
||||
- ❌ Not yet started
|
||||
|
||||
## 🛠️ Final Checklists
|
||||
|
||||
### 🔴 Tier 1 — CRITICAL (CI BLOCKER)
|
||||
|
||||
**Security & Data Integrity:**
|
||||
|
||||
- [ ] **UUID Strategy:** Use `publicId` only, no `parseInt()` on UUID values (ADR-019)
|
||||
- [ ] **RBAC Guards:** CASL guards on all endpoints, 4-level matrix checked (ADR-016)
|
||||
- [ ] **AI Boundary:** Ollama isolation, no direct DB/storage access (ADR-023/023A)
|
||||
- [ ] **Input Validation:** Zod (frontend) + class-validator (backend DTO)
|
||||
- [ ] **File Upload:** Two-phase (Temp → Commit), ClamAV scan, whitelist enforced
|
||||
- [ ] **Idempotency:** `Idempotency-Key` header validated on critical POST/PUT/PATCH
|
||||
- [ ] **Error Handling:** Layered classification (Validation, Business, System) with user-friendly messages (ADR-007)
|
||||
|
||||
**Code Quality:**
|
||||
|
||||
- [ ] No `any` types in TypeScript (use interfaces/types)
|
||||
- [ ] No `console.log` in committed code (use NestJS Logger)
|
||||
- [ ] Database schema verified before writing queries
|
||||
- [ ] SQL injection prevention checked
|
||||
|
||||
### 🟡 Tier 2 — IMPORTANT (CODE REVIEW)
|
||||
|
||||
**Architecture & Standards:**
|
||||
|
||||
- [ ] **File header `// File: path/filename` present**
|
||||
- [ ] **`// Change Log` section included at top**
|
||||
- [ ] **JSDoc present for public classes and methods**
|
||||
- [ ] **One main export per file**
|
||||
- [ ] Business logic in services, thin controllers pattern
|
||||
- [ ] Schema changes via SQL directly (ADR-009)
|
||||
- [ ] Test coverage meets targets (Backend 70%+, Business Logic 80%+)
|
||||
- [ ] Cache invalidation when data modified
|
||||
- [ ] Naming conventions followed
|
||||
|
||||
**Localization & Comments:**
|
||||
|
||||
- [ ] Business logic comments in Thai, technical comments in English
|
||||
- [ ] Code identifiers in English
|
||||
- [ ] i18n keys used instead of hardcode text
|
||||
|
||||
### 🟢 Tier 3 — SPECIALIZED WORK
|
||||
|
||||
**Workflow Integration (ADR-021):**
|
||||
|
||||
- [ ] WorkflowEngineService polymorphic handling verified
|
||||
- [ ] Workflow fields exposed (workflowInstanceId, workflowState, availableActions)
|
||||
- [ ] IntegratedBanner + WorkflowLifecycle components used
|
||||
- [ ] Workflow transitions tested with state validation
|
||||
- [ ] RBAC guards on workflow actions
|
||||
|
||||
**AI Integration (ADR-023/023A):**
|
||||
|
||||
- [ ] **BullMQ Usage:** Background jobs via BullMQ, no inline processing
|
||||
- [ ] **Qdrant Multi-tenancy:** `projectPublicId` filter enforced
|
||||
- [ ] **Human-in-the-loop:** AI outputs validated before use
|
||||
- [ ] **Audit Logging:** All AI interactions logged to `ai_audit_logs`
|
||||
- [ ] **2-Model Stack:** gemma4:e4b Q8_0 + nomic-embed-text verified
|
||||
|
||||
**Performance & Complex Logic:**
|
||||
|
||||
- [ ] Performance metrics within targets (P95 ≤ 5s for ≤10MB uploads)
|
||||
- [ ] Multi-scenario test coverage for edge cases
|
||||
- [ ] Load testing completed if applicable
|
||||
- [ ] Complex state management properly validated
|
||||
|
||||
### 🔵 Tier 4 — GUIDELINES
|
||||
|
||||
**Code Style:**
|
||||
|
||||
- [ ] Code formatting follows Prettier rules
|
||||
- [ ] Comment completeness where helpful
|
||||
- [ ] Minor optimizations considered but not required
|
||||
|
||||
---
|
||||
|
||||
## Agent skills
|
||||
|
||||
### Issue tracker
|
||||
|
||||
Issues live in the self-hosted Gitea repo at git.np-dms.work:2222. See `docs/agents/issue-tracker.md`.
|
||||
|
||||
### Triage labels
|
||||
|
||||
Default label vocabulary (no custom mapping). See `docs/agents/triage-labels.md`.
|
||||
|
||||
### Domain docs
|
||||
|
||||
Single-context repo with domain documentation in `specs/`. See `docs/agents/domain.md`.
|
||||
|
||||
---
|
||||
|
||||
## 📚 Full Documentation
|
||||
|
||||
This file is a **quick reference**. For detailed information:
|
||||
|
||||
- **Architecture:** `specs/02-architecture/`
|
||||
- **Requirements:** `specs/01-requirements/`
|
||||
- **Data & Storage:** `specs/03-Data-and-Storage/` (canonical schema + `deltas/` incremental SQL per ADR-009)
|
||||
- **Engineering Guidelines:** `specs/05-Engineering-Guidelines/`
|
||||
- **Decision Records:** `specs/06-Decision-Records/`
|
||||
- **Infrastructure:** `specs/04-Infrastructure-OPS/`
|
||||
- **Agent Skill Pack:** `.agents/skills/` (NestJS/Next.js rules + 21 Speckit & Utility skills)
|
||||
- **Helper Scripts:** `.agents/scripts/{bash,powershell}/` (audit, validate, prerequisites, setup-plan)
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Change Log
|
||||
|
||||
| Version | Date | Changes | Updated By |
|
||||
| ------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
|
||||
| 1.9.3 | 2026-05-16 | Sync with AGENTS.md v1.9.3 — ADR-023A updates, schema v1.9.0 path corrections, CaslModule import fix for DelegationModule, console.log → Logger migration | Windsurf AI |
|
||||
| 1.9.0 | 2026-05-13 | Sync with AGENTS.md v1.9.0 — TS Standards, Hybrid Specs organization | Windsurf AI |
|
||||
| 1.8.5 | 2026-04-22 | Legacy version | Human Dev |
|
||||
| Version | Date | Changes | Updated By |
|
||||
| ------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
|
||||
| 1.9.5 | 2026-05-18 | **Grill-with-Docs Session:** Domain terminology clarified (Correspondence = all doc types), Tier 3: SPECIALIZED WORK added, Context-Aware Triggers with Status column, Tier-specific Final Checklists | Windsurf AI |
|
||||
| 1.9.4 | 2026-05-16 | Added ADR-015 Release Strategy to Key Spec Files table (Blue-Green deployment + release gates) | Human Dev |
|
||||
| 1.9.3 | 2026-05-15 | ADR-023A: Model revision — gemma4:9b+Typhoon→gemma4:e4b Q8_0 (2-model stack), BullMQ 2-queue split, RAG full-doc embed, OCR auto-detect, n8n→DMS API boundary, QdrantService multi-tenancy contract | Windsurf AI |
|
||||
| 1.9.2 | 2026-05-14 | Consolidated legacy AI ADRs (017, 017B, 018, 020, 022) into master ADR-023: Unified AI Architecture | Antigravity AI |
|
||||
| 1.9.1 | 2026-05-13 | Added `bugfix` workflow and skill (migrated and improved from `docs/bugfix.md`) | Windsurf AI |
|
||||
| 1.9.0 | 2026-05-03 | Integrated Global TypeScript Coding Standards (Headers, JSDoc, Thai comments, Single Export, No blank lines) | Windsurf AI |
|
||||
| 1.8.5 | 2026-04-22 | Legacy version | Human Dev |
|
||||
|
||||
Reference in New Issue
Block a user