690608:0012 ADR-035-135 #08

2026-06-08 00:12:31 +07:00
parent a0f77ad121
commit 52b96d01de
48 changed files with 1590 additions and 1266 deletions
@@ -0,0 +1,33 @@
+# Memory Directory
+
+This directory contains project-specific memory and context that is NOT already covered in the specs/ directory.
+
+## Purpose
+
+The `memory/` directory is for:
+- MCP Tools documentation (MariaDB + Memory tools)
+- Project memory override rules (referencing AGENTS.md)
+- Context that doesn't fit into the specs/ structure
+
+## What's NOT Here
+
+The following content has been moved to `specs/88-logs/`:
+- Session history logs
+- Recent rollouts
+- Rules and decisions (now in specs/06-Decision-Records/ ADRs)
+- Domain terminology (now in specs/00-overview/00-02-glossary.md)
+- Known commands (now in specs/05-Engineering-Guidelines/)
+- Environment & Services (now in specs/04-Infrastructure-OPS/)
+
+## Files
+
+- `mcp-tools.md` — MCP MariaDB Tools and MCP Memory Tools documentation
+- `project-memory-override.md` — Project memory override rule referencing AGENTS.md
+
+## Single Source of Truth
+
+For project rules, decisions, and specifications, always refer to:
+- `AGENTS.md` — Project context and rules
+- `specs/06-Decision-Records/` — Architecture Decision Records (ADRs)
+- `specs/00-overview/00-02-glossary.md` — Domain terminology
+- `specs/05-Engineering-Guidelines/` — Backend, frontend, and testing guidelines
@@ -0,0 +1,95 @@
+# MCP Tools Documentation
+
+## MCP MariaDB Tools
+
+MCP MariaDB server provides tools for direct database inspection and management. Used for:
+
+- Verifying schema against spec file `specs/03-Data-and-Storage/lcbp3-v1.9.0-schema-02-tables.sql`
+- Debugging database issues without entering MySQL client
+- Checking data in production/staging
+- Validating schema changes before deploy
+
+### Available Tools
+
+| Tool | Purpose | Example Usage |
+|------|---------|----------------|
+| `mcp1_mysql_test_connection` | Test database connection | Verify MCP server connectivity |
+| `mcp1_mysql_show_databases` | List all databases | See available databases |
+| `mcp1_mysql_show_tables` | List all tables in database | See tables in `lcbp3` |
+| `mcp1_mysql_describe_table` | View table structure/columns | Check columns, types, keys of `correspondences` |
+| `mcp1_mysql_query` | Run SELECT query | View data in table or join query |
+| `mcp1_mysql_insert` | INSERT data | Add seed data or test data |
+| `mcp1_mysql_update` | UPDATE data | Modify data in table |
+| `mcp1_mysql_delete` | DELETE data | Delete data from table |
+
+### Usage with Development Flow
+
+**When writing new queries:**
+1. Use `mcp1_mysql_describe_table` to check columns and types
+2. Compare with `specs/03-Data-and-Storage/lcbp3-v1.9.0-schema-02-tables.sql`
+3. Use `mcp1_mysql_query` to test query before implement
+
+**When changing schema (ADR-009):**
+1. Use `mcp1_mysql_describe_table` to see current structure
+2. Create SQL delta in `specs/03-Data-and-Storage/deltas/`
+3. Use `mcp1_mysql_query` to verify result after apply delta
+
+**When debugging database issues:**
+1. Use `mcp1_mysql_query` to see actual data
+2. Compare with spec and data dictionary
+3. Check foreign keys and constraints
+
+### Warnings
+
+- **❌ NEVER use MCP MariaDB for DDL operations** (CREATE/ALTER/DROP) directly — must use SQL delta per ADR-009
+- **✅ Use for DQL/DML operations** (SELECT/INSERT/UPDATE/DELETE) for debug and test only
+- **⚠️ Be careful with DELETE operations** — may lose data in production
+- **✅ Always verify schema against spec file** before writing queries
+
+---
+
+## MCP Memory Tools
+
+MCP Memory server provides tools for managing Knowledge Graph and Long-term Memory. Used for:
+
+- Storing project knowledge and context in Graph format (Entities + Relations + Observations)
+- Searching and retrieving context from memory saved in previous sessions
+- Creating/editing/deleting entities, relations, and observations in knowledge graph
+
+### Available Tools
+
+| Tool | Purpose | Example Usage |
+|------|---------|----------------|
+| `mcp3_create_entities` | Create multiple new entities with observations | Create new entities like Project, User, Task |
+| `mcp3_create_relations` | Create relations between entities | Create relation: Project → has → User |
+| `mcp3_add_observations` | Add observations to existing entities | Add additional context to entity |
+| `mcp3_delete_entities` | Delete entities and related relations | Delete unused entities |
+| `mcp3_delete_relations` | Delete relations between entities | Delete incorrect or unused relations |
+| `mcp3_delete_observations` | Delete observations from entity | Delete incorrect or stale context |
+| `mcp3_open_nodes` | Retrieve entities by name | Get specific entity by name |
+| `mcp3_read_graph` | Read entire knowledge graph | See full graph structure |
+| `mcp3_search_nodes` | Search entities by query | Find entity by name, type, or observation |
+
+### Usage with Development Flow
+
+**When saving new context:**
+1. Use `mcp3_create_entities` to create new entities (if not exist)
+2. Use `mcp3_create_relations` to link entities
+3. Use `mcp3_add_observations` to add context/observations
+
+**When searching context:**
+1. Use `mcp3_search_nodes` to find relevant entities
+2. Use `mcp3_open_nodes` to get specific entity data
+3. Use `mcp3_read_graph` to see relations between entities
+
+**When editing context:**
+1. Use `mcp3_add_observations` to add new observations
+2. Use `mcp3_delete_observations` to delete incorrect observations
+3. Use `mcp3_create_relations` or `mcp3_delete_relations` to adjust relations
+
+### Warnings
+
+- **✅ Use for storing context that needs to be shared across multiple sessions** — e.g., important decisions, architecture decisions, rollout history
+- **⚠️ Be careful when deleting entities** — may lose context still in use
+- **✅ Check if entity exists before creating** — use `mcp3_search_nodes` or `mcp3_open_nodes` first
+- **✅ Use clear and unique entity names** — to prevent confusion
@@ -0,0 +1,87 @@
+# Project Memory Override
+
+> **Project:** NAP-DMS (LCBP3) — Laem Chabang Port Phase 3 Document Management System
+> **Version:** 1.9.9 (Last Synced: 2026-06-03)
+> **Stack:** NestJS 11 + Next.js 16 + TypeScript + MariaDB 11.8 + Redis + BullMQ + Elasticsearch + Ollama (on-prem AI)
+
+> [!IMPORTANT]
+> **Project memory นี้ต้องใช้งานภายใต้ `AGENTS.md` เสมอ**
+>
+> - ให้ใช้ `AGENTS.md` เป็นกฎหลักก่อน memory ทุกครั้ง
+> - ถ้า memory เก่าหรือ session note ขัดกับ `AGENTS.md` ให้ยึด `AGENTS.md`
+> - งาน schema ต้องทำตาม ADR-009 ผ่าน SQL/delta เท่านั้น
+> - งาน UUID/Public API ต้องทำตาม ADR-019 โดยใช้ `publicId` และห้าม `parseInt()` บน UUID
+> - งาน n8n / AI migration ต้องอยู่ในขอบเขต ADR-023A และ mutation ต้องมี `Idempotency-Key`
+
+## OS Rules & Sandbox Constraints
+
+> [!IMPORTANT]
+> **ระบบรันอยู่บน Windows OS**
+>
+> - ห้ามใช้คำสั่ง `bash` หรือคำสั่งของ Linux โดยเด็ดขาด
+> - คำสั่งทุกประเภทที่จะส่งให้ผู้ใช้รันหรือรันผ่าน Terminal ต้องเป็น **PowerShell** หรือ **CMD** เท่านั้น
+> - ห้ามใช้คำสั่ง `cd` ในการสลับ Directory ให้ระบุพารามิเตอร์ `Cwd` ใน Tool ตรง ๆ
+
+## 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: `typhoon2.5-np-dms:latest` (Main LLM) + `typhoon-np-dms-ocr:latest` (OCR, keep_alive:0) + `BGE-M3` (Dense 1024 + Sparse Embedding) + `BGE-Reranker-Large` (Reranker) on Admin Desktop — `nomic-embed-text` ถูกแทนที่แล้ว (ADR-034/035) | ADR-034/035 |
+| D11 | RAG Embedding trigger: `syncStatus()` → `enqueueRagPrepare()` เมื่อ status ≠ DRAFT; jobId = `rag-prepare:{documentPublicId}:{revisionNumber}` (BullMQ dedup); delete-before-upsert ทุกครั้ง | ADR-035 |
+| D12 | Qdrant collection `lcbp3_vectors` = Hybrid schema: `bge_dense` (1024 dims, Cosine) + `bge_sparse` (SPLADE); payload indexes: `project_public_id` (tenant), `doc_public_id`, `status_code`, `doc_type` | ADR-035 |
+
+## 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               |
+| **Ollama**        | `http://192.168.10.100:11434` | Admin Desktop (Desk-5439) | typhoon2.5-np-dms:latest (main) + typhoon-np-dms-ocr:latest (OCR, keep_alive:0) |
+| **Qdrant**        | `http://localhost:6333`       | Admin Desktop (Desk-5439) | Vector DB — requires projectPublicId |
+| **OCR Sidecar**   | `http://192.168.10.100:8765`  | Admin Desktop (Desk-5439) | Tesseract (fallback) / Typhoon OCR-3B (primary) + BGE-M3 `/embed` + BGE-Reranker `/rerank` |
+| **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
+
+```
+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
+```
+
+## Next Session Focus
+
+### N8N Migration & E2E Testing
+
+- [ ] **Import `n8n.workflow.v2.json`** เข้า n8n UI และทดสอบ End-to-End
+- [ ] **ทดสอบ End-to-End จริง** — รัน n8n กับ Excel ตัวอย่าง
+- [ ] **Frontend Editable Review Form** (Pipeline B) — pre-fill AI suggestions + tag suggestion UI
+- [ ] **Dry Run** กับ Excel จริงก่อน Production Migration
+
+### RAG Pipeline — Production Readiness
+
+- [X] **รัน SQL delta** `2026-06-05-add-rag-chunking-prompt.sql` ใน MariaDB production
+- [ ] **Deploy OCR Sidecar ใหม่** บน Desk-5439 หลัง rebuild image
+- [ ] **Drop + recreate Qdrant collection** `lcbp3_vectors` เป็น Hybrid schema
+- [ ] **SC-002 E2E accuracy test** — ทดสอบ Chat Q&A ≥ 80% accuracy
+
+### General Tasks
+
+- [ ] เพิ่ม unit test สำหรับ `upsertQueueRecord` ใน `ai-migration-checkpoint.service.spec.ts`
+- [ ] เพิ่ม unit test สำหรับ checksum dedup ใน `file-storage.service.spec.ts`