690524:1054 ADR-028-228-migration #02

2026-05-24 10:54:44 +07:00
parent 5a17f969b8
commit a63fe0fb5c
4 changed files with 820 additions and 93 deletions
@@ -2,6 +2,7 @@
 <!-- Change Log
 - 2026-05-23: Initialized long-term memory system with core project rules, Windows environment settings, and constraints.
 - 2026-05-23 (Session 2): N8N Workflow Refactor — QuizMe session, decisions locked, สร้าง CONTEXT-N8N-Refactor.md, สร้าง n8n.workflow.v2.json (ADR-023A compliant), อัพเดต 03-05 และ 03-06.
+- 2026-05-24: เพิ่ม sections: Known Commands, Current Decisions, Do/Don't Quick Reference, Environment & Services, Recent Rollouts.
 -->

 # 🧠 Agent Long-term Project Memory
@@ -74,7 +75,134 @@

 ---

-## 🔄 4. สถานะและประวัติการทำงาน (Latest Session Progress)
+## ⌨️ 4. Known Commands (PowerShell — Windows Only)
+
+> [!NOTE]
+> ห้ามใช้ bash/Linux commands ทุกอย่างต้องเป็น **PowerShell** หรือ **CMD** เท่านั้น
+
+### Dev Servers
+
+```powershell
+# Backend (NestJS) — port 3001
+npm run start:dev                        # รันจาก e:\np-dms\lcbp3\backend
+
+# Frontend (Next.js) — port 3000
+npm run dev                              # รันจาก e:\np-dms\lcbp3\frontend
+```
+
+### Build & Type Check
+
+```powershell
+# Backend
+npm run build                            # tsc compile
+npm run lint                             # ESLint
+
+# Frontend
+npm run build                            # Next.js build
+npx tsc --noEmit                         # Type check only
+```
+
+### Tests
+
+```powershell
+# Backend Unit Tests
+npm run test                             # Jest all
+npm run test -- --testPathPattern=<name> # เฉพาะ file
+npm run test:cov                         # Coverage report
+
+# Frontend Unit Tests
+npm run test                             # Vitest
+
+# E2E
+npx playwright test                      # รันจาก e:\np-dms\lcbp3\frontend
+```
+
+### Database & Services
+
+```powershell
+# Docker (รันจาก root หรือ backend)
+docker compose up -d                     # Start all services
+docker compose logs -f backend           # Tail backend logs
+docker compose ps                        # Check status
+```
+
+---
+
+## 🏛️ 5. Current Decisions (Locked)
+
+> การตัดสินใจเหล่านี้ **ไม่สามารถเปลี่ยนแปลงได้** โดยไม่ได้รับ Explicit Approval
+
+| ID  | Decision                                                                                    | ADR       |
+| --- | ------------------------------------------------------------------------------------------- | --------- |
+| D1  | n8n = Migration Phase orchestrator เท่านั้น — ห้ามทำ New Correspondence pipeline ผ่าน n8n   | ADR-023A  |
+| D2  | New Correspondence → BullMQ `ai-realtime` queue โดยตรง (ไม่ผ่าน n8n)                        | ADR-023A  |
+| D3  | n8n ต้อง call `POST /api/ai/jobs` (DMS Backend) เท่านั้น — ห้าม call Ollama/Qdrant โดยตรง   | ADR-023A  |
+| D4  | Excel metadata ส่งไปพร้อม AI job เป็น context (docNumber, title, sender ฯลฯ)                | Session 2 |
+| D5  | Tag suggestion ใช้ทาง C: แนะนำ existing tags + สร้างใหม่ได้ถ้าไม่มี (`isNew: true` flag)    | Session 2 |
+| D6  | Editable Review Form: AI pre-fill → user approve/edit → submit (human-in-the-loop ทุกครั้ง) | ADR-023   |
+| D7  | UUID Strategy: `publicId` (UUIDv7) เท่านั้นสำหรับ Public API — INT PK ต้อง `@Exclude()`     | ADR-019   |
+| D8  | Schema changes: แก้ SQL โดยตรง + เพิ่ม `deltas/*.sql` — ห้ามใช้ TypeORM migration files     | ADR-009   |
+| D9  | Qdrant search ต้องส่ง `projectPublicId` เป็น mandatory parameter ทุกครั้ง (compile-time)    | ADR-023A  |
+| D10 | AI model stack: `gemma4:e4b Q8_0` (LLM) + `nomic-embed-text` (Embeddings) on Admin Desktop  | ADR-023A  |
+
+---
+
+## ✅❌ 6. Do / Don't Quick Reference
+
+| ✅ Do                                                          | ❌ Don't                                            |
+| -------------------------------------------------------------- | --------------------------------------------------- |
+| ใช้ `publicId` (UUID string) ใน API/URL                        | `parseInt()` / `Number()` บน UUID                   |
+| ใช้ `RequestWithUser` ใน NestJS controller                     | `req: any` ใน controller                            |
+| ส่ง notification/email ผ่าน BullMQ                             | ส่ง email แบบ inline ใน service                     |
+| เขียน schema changes ใน `deltas/*.sql`                         | สร้าง TypeORM migration files                       |
+| ใช้ NestJS `Logger` แทน `console.log`                          | `console.log` ใน committed code                     |
+| ตรวจสอบ table/column ใน `schema-02-tables.sql` ก่อนเขียน query | คาดเดาชื่อ column โดยไม่ตรวจสอบ schema              |
+| ใช้ CASL Guard กับทุก mutation endpoint                        | สร้าง API ที่ไม่มี auth guard                       |
+| ผ่าน `StorageService` ทุกครั้งที่จัดการไฟล์                    | ทำ file operation โดยตรงโดยไม่ผ่าน `StorageService` |
+| ใช้คำสั่ง PowerShell/CMD บน Windows                            | ใช้ bash/Linux commands บน Windows                  |
+| Human-in-the-loop validate ก่อน apply AI output                | ใช้ AI output โดยตรงโดยไม่ผ่าน human review         |
+| เขียน comment ภาษาไทย, code identifier ภาษาอังกฤษ              | คำ comment ภาษาอังกฤษ หรือ identifier ภาษาไทย       |
+| ใส่ file header `// File: path/filename` ทุกไฟล์ TypeScript    | ไฟล์ที่ไม่มี file header                            |
+
+---
+
+## 🌐 7. Environment & Services
+
+| Service          | Local URL / Port            | Production                | Notes                                |
+| ---------------- | --------------------------- | ------------------------- | ------------------------------------ |
+| **Backend API**  | `http://localhost:3001`     | QNAP `192.168.10.8`       | NestJS — `/api` prefix               |
+| **Frontend**     | `http://localhost:3000`     | QNAP `192.168.10.8`       | Next.js                              |
+| **MariaDB**      | `localhost:3307`            | QNAP internal             | DB: `lcbp3`, root via docker         |
+| **Redis**        | `localhost:6379`            | QNAP internal             | BullMQ + session store               |
+| **n8n**          | `http://localhost:5678`     | QNAP `192.168.10.8:5678`  | Migration orchestrator only          |
+| **Ollama**       | `http://192.168.10.X:11434` | Admin Desktop (Desk-5439) | gemma4:e4b Q8_0 + nomic-embed-text   |
+| **Qdrant**       | `http://localhost:6333`     | Admin Desktop (Desk-5439) | Vector DB — requires projectPublicId |
+| **Gitea**        | `https://git.np-dms.work`   | QNAP `192.168.10.8`       | Source + CI/CD                       |
+| **Gitea Runner** | ASUSTOR `192.168.10.9`      | —                         | CI runner                            |
+
+### Key Environment Variables (ตรวจสอบใน `docker-compose.yml`)
+
+```
+DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_NAME
+REDIS_HOST, REDIS_PORT
+JWT_SECRET, JWT_EXPIRES_IN
+OLLAMA_BASE_URL (ชี้ไป Admin Desktop)
+QDRANT_URL
+```
+
+---
+
+## 🚀 8. Recent Rollouts
+
+| วันที่     | Version | รายการ                                                                          | สถานะ                       |
+| ---------- | ------- | ------------------------------------------------------------------------------- | --------------------------- |
+| 2026-05-23 | v1.9.6  | Specs reorganization (`100/200/300-*` folders), AGENTS.md v1.9.6 update         | ✅ Complete                 |
+| 2026-05-23 | v1.9.6  | N8N Workflow v2 (`n8n.workflow.v2.json`) — ADR-023A compliant, ลบ Ollama direct | ⏳ Pending import to n8n UI |
+| 2026-05-24 | v1.9.6  | AGENTS.md Project Memory Override rule (Windsurf / Antigravity / Codex)         | ✅ Complete                 |
+
+---
+
+## 🔄 9. สถานะและประวัติการทำงาน (Latest Session Progress)

 ### Session 1 — 2026-05-23 (Specs Reorganization)

@@ -130,7 +258,7 @@ Form Trigger → Set Config → Health/Token Check → Fetch Master Data

 ---

-## 🎯 5. แผนงานขั้นต่อไป (Next Session Focus)
+## 🎯 10. แผนงานขั้นต่อไป (Next Session Focus)

 ### N8N Migration (งานหลักที่เหลือ)