690523:2327 ADR-028-228-migration #01
This commit is contained in:
@@ -1,56 +1,164 @@
|
||||
# NAP-DMS Project Context & Core Rules
|
||||
# NAP-DMS Project Context & Rules
|
||||
|
||||
- Version: 1.9.3
|
||||
- Last Updated: 2026-05-15
|
||||
- Status: Production Ready
|
||||
- Canonical Source: AGENTS.md
|
||||
- For: Windsurf Cascade (and compatible: Codex CLI, opencode, Amp, Antigravity, AGENTS.md tools)
|
||||
- Version: 1.9.6 | Last synced from repo: 2026-05-22
|
||||
- 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)
|
||||
|
||||
## 🎭 Role & Persona
|
||||
## 🧠 Role & Persona
|
||||
|
||||
Act as a **Senior Full Stack Developer** specialized in NestJS, Next.js, and TypeScript.
|
||||
Focus on **Data Integrity, Security, Maintainability, and Performance**.
|
||||
You are a **Document Intelligence Engine** — every response must be precise, spec-compliant, and production-ready.
|
||||
Act as **Senior Full Stack Developer** specialized in NestJS, Next.js, TypeScript, 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**.
|
||||
|
||||
---
|
||||
|
||||
## 🔴 Tier 1 — CRITICAL (CI BLOCKER)
|
||||
## 🧩 Thought & Planning Protocol (Powered by Everything-Claude-Code)
|
||||
|
||||
1. **Identifier Strategy (ADR-019)**
|
||||
- ห้ามใช้ `parseInt()` บน UUID
|
||||
- ใช้ `publicId` (string) สำหรับการติดต่อภายนอก (API/URL) เท่านั้น
|
||||
2. **Database Management (ADR-009)**
|
||||
- ห้ามใช้ TypeORM Migrations หรือ `synchronize: true`
|
||||
- การแก้ Schema ต้องแก้ที่ SQL files ใน `specs/03-Data-and-Storage/` เท่านั้น
|
||||
3. **Security (ADR-016)**
|
||||
- ทุก API ต้องมี `CASL Guard` และตรวจสอบสิทธิ์ผ่าน RBAC Matrix
|
||||
- การอัปโหลดไฟล์ต้องเป็น Two-Phase (Temp → Commit) และต้องสแกน ClamAV
|
||||
4. **AI Boundary (ADR-018)**
|
||||
- AI Agent ต้องทำงานผ่าน DMS API เท่านั้น ห้ามเขียนลง Database หรือ Storage โดยตรง
|
||||
Before writing any code or taking any action in Tier 1 and Tier 2, the AI must demonstrate the following thinking process:
|
||||
|
||||
### 1. Analysis Phase (Explore & Analyze)
|
||||
|
||||
Problem Understanding: Restate what the user wants in clear, unambiguous terms.
|
||||
Context Search: Identify the relevant Spec files or ADRs from the "Key Spec Files" table that must be read before starting.
|
||||
Constraints Identification: Identify key constraints (e.g. Security rules, UUID patterns, or Domain terminology).
|
||||
|
||||
### 2. Planning Phase (Plan)
|
||||
|
||||
Alternative Exploration: Present at least 2 solution approaches (where possible) with pros/cons analysis.
|
||||
Step-by-Step Roadmap: Write a file-by-file plan of changes before executing.
|
||||
Verification Plan: Specify how to verify the work is complete (e.g. "which unit tests to write" or "which file to check the schema in").
|
||||
|
||||
### 3. Execution & Refinement (Execute & Refine)
|
||||
|
||||
Follow the plan step by step, and pause to ask if any uncertainty arises.
|
||||
If significant logic changes are made, summarize what was done for the user after completion.
|
||||
|
||||
---
|
||||
|
||||
## 📐 TypeScript Rules & Coding Standards (v1.9.0)
|
||||
## ⚙️ DMS Workflow Engine Protocol
|
||||
|
||||
- **File Header:** ทุกไฟล์ต้องขึ้นต้นด้วย `// File: path/filename`
|
||||
- **Change Log:** ต้องมีส่วน `// Change Log` ที่หัวไฟล์
|
||||
- **Language:** ตัวแปร/Logic เป็น English, Comment/JSDoc เป็น **Thai**
|
||||
- **Explicit Typing:** กำหนด Type ให้ชัดเจนเสมอ ห้ามใช้ `any`
|
||||
- **Cleanliness:** ห้ามมีบรรทัดว่างในฟังก์ชัน, Export ได้เพียง 1 symbol หลักต่อไฟล์
|
||||
กฎนี้ใช้คุม Logic การไหลของเอกสาร (RFA, Transmittal, Correspondence) เพื่อป้องกัน Race Condition และรักษาความถูกต้องของสถานะ:
|
||||
|
||||
- **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 ที่ครอบคลุมทุกประเภท)
|
||||
|
||||
---
|
||||
|
||||
## 📁 Specs Folder Organization (Hybrid Model)
|
||||
## 🛡️ Security & Integrity Audit Protocol
|
||||
|
||||
- **Core (00-06):** ข้อมูลอ้างอิงถาวร (Permanent Source of Truth)
|
||||
- **Feature (100-300):** สำหรับงาน Implementation ใหม่
|
||||
- `100-Infrastructures/`
|
||||
- `200-fullstacks/`
|
||||
- `300-others/`
|
||||
กฎนี้ให้ AI เป็น Gatekeeper ก่อน Commit โดยเน้น **Tier 1 — CRITICAL**:
|
||||
|
||||
- **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)
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Workflow Engine (ADR-001/021)
|
||||
## 🧭 Rule Enforcement Tiers
|
||||
|
||||
- ใช้ DSL-based state machine
|
||||
- การเปลี่ยนสถานะต้องตรวจสอบสถานะปัจจุบันจาก DB ก่อนเสมอ
|
||||
- งานที่ใช้เวลานานต้องส่งไปที่ **BullMQ** เท่านั้น
|
||||
### 🔴 Tier 1 — CRITICAL (CI BLOCKER)
|
||||
|
||||
Build fails หากละเมิด:
|
||||
|
||||
- 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-023)
|
||||
- Error handling strategy (ADR-007)
|
||||
- Forbidden patterns: `any`, `console.log`, UUID misuse, `id ?? ''` fallback
|
||||
|
||||
### 🟡 Tier 2 — IMPORTANT (CODE REVIEW)
|
||||
|
||||
Must fix ก่อน merge:
|
||||
|
||||
- Architecture patterns (thin controller, business logic in service)
|
||||
- Test coverage (80%+ business logic, 70%+ backend overall)
|
||||
- Cache invalidation
|
||||
- Naming conventions
|
||||
- **TypeScript Standards:** Missing JSDoc, explicit types, or file headers
|
||||
|
||||
### 🟢 Tier 3 — SPECIALIZED WORK
|
||||
|
||||
Requires domain-specific knowledge:
|
||||
|
||||
- **ADR-021 Integration:** Workflow Engine & Context implementation
|
||||
- **AI Infrastructure:** ADR-023/023A boundary enforcement and pipeline usage
|
||||
- **AI Runtime Layer:** ADR-024 Intent Classification, ADR-025 Tool Layer, ADR-026 Chat UI, ADR-027 Admin Console
|
||||
- **Migration Pipeline:** ADR-028 Staging Queue & post-migration cleanup
|
||||
- **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:
|
||||
|
||||
- Code style / formatting (Prettier handles)
|
||||
- Comment completeness
|
||||
- Minor optimizations
|
||||
|
||||
---
|
||||
|
||||
## 📐 TypeScript Rules & Coding Standards
|
||||
|
||||
### 📝 Core Standards
|
||||
|
||||
- **Strict Mode** — all strict checks enforced.
|
||||
- **ZERO `any` types** — use proper types or `unknown` + narrowing.
|
||||
- **ZERO `console.log`** — use NestJS `Logger` (backend) or remove (frontend).
|
||||
- **English for Code** — use English for all code identifiers, variables, and logic.
|
||||
- **Thai for Comments** — use Thai for comments, documentation, and JSDoc.
|
||||
- **Explicit Typing** — explicitly define types for all variables, parameters, and return values.
|
||||
- **JSDoc** — use JSDoc for all public classes and methods.
|
||||
|
||||
### 🏗️ File & Function Structure
|
||||
|
||||
- **File Headers** — every file MUST start with `// File: path/filename` on the first line.
|
||||
- **Change Log** — include `// Change Log` at the top of the file to track modifications.
|
||||
- **Single Export** — export **only one main symbol** per file.
|
||||
- **Function Style** — avoid unnecessary blank lines inside functions.
|
||||
|
||||
---
|
||||
|
||||
## 🚫 Forbidden Actions
|
||||
|
||||
| ❌ 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 `lcbp3-v1.9.0-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-023) |
|
||||
| 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-023) |
|
||||
| AI outputs without human validation | Human-in-the-loop validation required (ADR-023) |
|
||||
| n8n calling Ollama/Qdrant directly | n8n → DMS API → BullMQ → Ollama/Qdrant (ADR-023A) |
|
||||
| Qdrant query without `projectPublicId` filter | `QdrantService.search(projectPublicId, ...)` (ADR-023A) |
|
||||
|
||||
---
|
||||
|
||||
## 🚧 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 |
|
||||
|
||||
Reference in New Issue
Block a user