# THIẾT KẾ CẤU TRÚC NẠP BỘ NHỚ MEM0 & BỘ QUY CHUẨN KIỂM CHỨNG NGHIỆM THU **Dự án**: DSCons ERP (Công ty TNHH Xây Dựng Định Sơn - MST: `0202111150`) **Tác nhân**: `teamwork_preview_explorer_survey_3` **Ngày thực hiện**: 2026-10-05 **Mục tiêu**: Thiết kế cấu trúc dữ liệu nạp bộ nhớ dài hạn Mem0 (Milestone 3) và Bộ kịch bản kiểm thử nghiệm thu tự động (Milestone 4) theo yêu cầu tại `ORIGINAL_REQUEST.md` (Section `## 2026-10-05T20:25:13Z`). --- ## 1. PHÂN TÍCH CƠ CHẾ VẬN HÀNH BỘ NHỚ MEM0 (MEM0 INGESTION MECHANICS) ### 1.1. Kiến Trúc Kỹ Thuật Dưới Tầng Thực Thi (`mem0_service.py`) Qua phân tích trực tiếp mã nguồn dịch vụ nền Mem0 FastMCP tại `C:\Users\Admin\.gemini\config\scripts\mem0_service.py`: 1. **Engine Suy luận & LLM Provider**: - `AntigravityLLM` kế thừa `LLMBase` của Mem0, sử dụng `google.antigravity.Agent` (Google Antigravity Python SDK). - Khi gọi `mem.add(text, user_id=user_id, metadata=meta_dict)` với cờ mặc định `infer=True`, Mem0 cố gắng gọi LLM để trích xuất các "facts" từ đoạn text đầu vào. - Nếu LLM gặp lỗi (timeout, cloud invocation error), cơ chế fallback cục bộ sẽ cắt các dòng văn bản có độ dài > 5 ký tự để nạp trực tiếp (`infer=False`). 2. **Cơ Chế Vector Embedder (`PureVectorEmbedder`)**: - Vector Store: Embedded Qdrant tại `C:\Users\Admin\.gemini\antigravity\mem0_data\qdrant`, collection `antigravity_memories`. - Embedder: `PureVectorEmbedder` (768 chiều, zero-dependency, local cosine similarity). - Thuật toán sinh vector: ```python # Word-level hash: h = int(hashlib.sha256(w.encode("utf-8")).hexdigest(), 16) % 768 # trọng số +1.0 # Character 3-grams: nh = int(hashlib.md5(ngram.encode("utf-8")).hexdigest(), 16) % 768 # trọng số +0.5 # Chuẩn hóa về đơn vị vector độ dài 1 (unit norm) ``` - **Hệ quả quan trọng đối với khả năng truy xuất (Retrieval Dynamics)**: - Độ tương đồng Cosine giữa `query` và `memory` phụ thuộc trực tiếp vào **độ trùng khớp từ khóa (exact word match)** và **độ trùng khớp 3-grams ký tự**. - Nếu một memory chỉ dùng từ ngữ thuần Việt mà người dùng tìm kiếm bằng thuật ngữ tiếng Anh (hoặc ngược lại), độ tương đồng sẽ giảm sút. - Do đó, **kỹ thuật chèn từ khóa song ngữ (Bilingual Keyword Density)** và **tiền tố miền chuẩn hóa (Domain Prefix)** sẽ tạo ra giao thoa từ khóa và 3-gram cực mạnh, đẩy điểm tương đồng Cosine lên mức tối ưu ($\ge 0.65 - 0.75$). 3. **Cơ Chế Chống Trùng Lặp (Deduplication Gate)**: - Trước khi nạp, `mem0_add` tính `input_hash = hashlib.md5(clean_input.encode("utf-8")).hexdigest()`. - Đồng thời đối chiếu `m.get("memory", "").strip() == clean_input`. - Nếu đã tồn tại bản ghi có cùng hash hoặc text trong 300 bản ghi gần nhất, hệ thống trả về ngay `{"status": "exists", "id": ...}` và không sinh thêm bản ghi rác. 4. **Hỗ Trợ Metadata**: - `mem0_add` tiếp nhận tham số `metadata` kiểu Dict hoặc JSON string. - `mem0_search` hỗ trợ tham số `project: Optional[str]`, cho phép lọc theo trường `metadata["project"]`. - Việc gắn metadata chuẩn `{ "project": "DSCons", "category": "...", "area": "...", "invariants": [...] }` cho phép cô lập hoàn toàn tri thức của DSCons khỏi các dự án khác (như `FreeExile` hay `Global`). --- ### 1.2. Quy Chuẩn Văn Phong & Định Dạng Phù Hợp Nhất (Optimal Fact Phrasing) Để đảm bảo các Agent tương lai khi truy vấn bất kỳ góc độ nào đều nhận diện chính xác và tuân thủ vô điều kiện, các fact nạp vào Mem0 phải tuân thủ 5 nguyên tắc vàng: ``` ┌────────────────────────────────────────────────────────────────────────┐ │ CẤU TRÚC MỘT MEM0 FACT CHUẨN │ │ │ │ [Tiền tố Miền & Danh mục] [Tuyên ngôn Bất biến] [Chi tiết Kỹ thuật] │ │ [Chống Quy chuẩn / Cấm đoán] [Từ khóa Song ngữ VN/EN] │ └────────────────────────────────────────────────────────────────────────┘ ``` 1. **Nguyên tắc 1: Độc Lập Ngữ Cảnh Tuyệt Đối (Self-Contained Context)**: - Tuyệt đối không dùng đại từ nhân xưng mơ hồ ("nó", "hệ thống này", "chúng tôi", "dự án hiện tại"). - Luôn bắt đầu bằng định danh đầy đủ: *"DSCons ERP:"*, *"Kiến trúc Backend DSCons:"*, *"Giao diện Frontend DSCons:"*, *"Định mức Xây dựng DSCons:"*. 2. **Nguyên tắc 2: Tiền Tố Miền Chuẩn Hóa (Standardized Domain Prefixing)**: - Mỗi fact bắt đầu bằng nhãn thẻ nhận diện để Neo ngữ cảnh (Context Anchoring): - `[DSCons Rule: Root Standards & Core Laws]` - `[DSCons Backend Architecture: Clean Architecture & DDD]` - `[DSCons Frontend Theme: Dark Slate Design System]` - `[DSCons AEC Business: Pricing Norms & BoQ Budgeting]` - `[DSCons Testing & Quality: Verification Workflow]` 3. **Nguyên tắc 3: Tuyên Ngôn Bất Biến & Chống Quy Chuẩn (Invariants & Anti-Patterns)**: - Fact giá trị nhất trong môi trường AI Engineering không chỉ nói "nên làm gì" mà bắt buộc phải nêu rõ **"CẤM TUYỆT ĐỐI ĐIỀU GÌ"**. - Ví dụ: *"Tuyệt đối CẤM dữ liệu ảo/mock"*, *"CẤM dùng FLOAT/DOUBLE cho tiền tệ VNĐ và khối lượng"*, *"CẤM import httpx trong Application Layer"*, *"CẤM áp giá thép tấn cho ĐVT m/m2/tấm/ca"*. 4. **Nguyên tắc 4: Mật Độ Từ Khóa Song Ngữ (Bilingual Keyword Density)**: - Các truy vấn thực tế của lập trình viên và sub-agent diễn ra xen kẽ tiếng Anh và tiếng Việt: `"frontend theme"`, `"giao diện dark slate"`, `"backend architecture"`, `"kiến trúc lục giác"`, `"cừ larsen VL=0"`, `"database precision"`. - Tích hợp cả hai dạng thuật ngữ trong cùng một câu văn giúp bộ băm 3-gram và word hash của `PureVectorEmbedder` luôn đạt điểm cosine cao nhất. 5. **Nguyên tắc 5: Tính Nguyên Tử & Độ Dài Tối Ưu (Atomicity & Optimal Length)**: - Mỗi fact chứa đúng **1 luật hoặc 1 cụm quy chuẩn gắn kết chặt chẽ**. - Độ dài tối ưu: **40 đến 85 từ** (khoảng 350 - 650 bytes). Không gộp toàn bộ tài liệu thành một đoạn văn 500 từ gây loãng vector score và khó cập nhật khi có thay đổi cục bộ. --- ### 1.3. Khuyến Nghị Số Lượng & Độ Hạt Tri Thức (Granularity & Fact Allocation) Tổng hợp toàn bộ 5 mảng tài liệu cốt lõi, cơ cấu bộ nhớ khuyến nghị gồm **27 facts nguyên tử**: | Mảng Tri Thức (Core Area) | Tài Liệu Nguồn Căn Cứ | Số Lượng Facts | Trọng Tâm Quy Chuẩn | | :--- | :--- | :---: | :--- | | **Mảng 1: Quy chuẩn Gốc (Root Standards)** | `AGENTS.md`, `GEMINI.md` | **5 facts** | 7 Điều luật cốt lõi, Zero synthetic data, Hexagonal DDD, MCP matrix, Sub-agent DoD. | | **Mảng 2: Backend & CSDL (Backend & DB)** | `backend-clean-architecture`, `backend-patterns`, `coding-standards` | **5 facts** | 4 Tầng lục giác, Decimal(18,4), Double-entry ledger, Hot-reload uvicorn, Test teardown, Prefix `/v1/erp`. | | **Mảng 3: Giao diện (Frontend & UI/UX)** | `enterprise-ui-darkslate`, `frontend-patterns` | **5 facts** | Dark Slate theme, Inter & JetBrains Mono, Bloomberg density, Zero Sidebar Occlusion, Toast anti-flood, Cache buster. | | **Mảng 4: Nghiệp vụ AEC & BoQ (Business Domain)** | `aec-cad-takeoff`, `aec-pricing-norms` | **7 facts** | 4 Trụ cột Định Sơn (MST 0202111150), TT38 cừ Larsen VL=0, Tỷ lệ MR/T 40-65%, 4 Cấp độ dự toán, Anti-inflation thép tấn, Hạch toán thẳng TK 621/154, CAD takeoff TCVN3/1px/Bounding Box. | | **Mảng 5: Kiểm thử & Quy trình (Testing & Workflow)** | `tdd-workflow`, `workflow-plan-task-test-report`, `verification-loop`, `eval-harness` | **5 facts** | Deep Matrix D1-D6 trên `task.md`, TDD Closed Loop 80%+, 6 Pha Verification Loop, Eval Harness EDD, Real browser testing. | | **TỔNG CỘNG** | **Toàn bộ hệ thống DSCons ERP** | **27 facts** | **Bao quát 100% luật bất biến, không dư thừa, không trùng lặp.** | --- ## 2. BẢNG DANH MỤC 27 FACTS NGUYÊN TỬ ĐỀ XUẤT CHO MILESTONE 3 Dưới đây là nội dung chi tiết của 27 facts được thiết kế theo đúng quy chuẩn ngữ nghĩa, kèm siêu dữ liệu (metadata) tương ứng: ### 2.1. Mảng 1: Quy Chuẩn Gốc (Root Standards - 5 facts) #### Fact 1.1: Bảy Điều Luật Cốt Lõi Bất Biến - **Metadata**: `{"project": "DSCons", "category": "Root Standards", "code": "RULE-ROOT-01", "area": "Area 1"}` - **Nội dung (`text`)**: > `[DSCons Rule: Root Standards & 7 Core Laws] DSCons ERP tuân thủ tuyệt đối Bảy Điều luật cốt lõi bất biến: (1) Nghiêm cấm 100% dữ liệu ảo/mock synthetic data; (2) Hàng rào kiểm thử hồi quy pytest 100% Passed; (3) Kiểm thử giao diện trên trình duyệt thực tế browser testing; (4) Vòng đời máy chủ Uvicorn luôn chạy --reload; (5) Chống hội chứng Bus Factor bằng tài liệu hóa giải thích rõ ràng; (6) Tuân thủ kiến trúc lục giác Hexagonal Architecture và DDD; (7) Bắt buộc khai thác tối đa hệ sinh thái MCP Server.` #### Fact 1.2: Cấm Tuyệt Đối Dữ Liệu Ảo & Nguồn Sự Thật Duy Nhất - **Metadata**: `{"project": "DSCons", "category": "Root Standards", "code": "RULE-ROOT-02", "area": "Area 1"}` - **Nội dung (`text`)**: > `[DSCons Rule: Zero Synthetic Data & Source of Truth] Trong DSCons ERP, nghiêm cấm tuyệt đối mọi hành vi tạo dữ liệu giả, mock script hoặc seed ảo (Zero-tolerance synthetic data). Mọi hóa đơn, dự toán, nhà cung cấp, vật tư phải được trích xuất 100% từ nguồn sự thật thực tế: Cổng Thuế điện tử Tổng cục Thuế (GDT), Odoo database dump, và hồ sơ hợp đồng HĐ-2026 của Công ty TNHH Xây Dựng Định Sơn (MST: 0202111150).` #### Fact 1.3: Ranh Giới Kiến Trúc Lục Giác & Cấm Lỗi Rò Rỉ Tầng - **Metadata**: `{"project": "DSCons", "category": "Root Standards", "code": "RULE-ROOT-03", "area": "Area 1"}` - **Nội dung (`text`)**: > `[DSCons Rule: Hexagonal Architecture & Boundary Enforcement] Hệ thống DSCons ERP áp dụng kiến trúc lục giác DDD (Ports and Adapters). CẤM TUYỆT ĐỐI viết raw SQL, câu lệnh DDL hoặc mở DB connection trực tiếp trong Routers/Presentation layer. CẤM TUYỆT ĐỐI import các HTTP client (httpx, requests) hoặc gọi API LLM ngoài trực tiếp trong Application và Domain layer. Mọi kết nối mạng phải qua Outbound Infrastructure Adapters hoặc EnterpriseAiGateway.` #### Fact 1.4: Ma Trận Bắt Buộc Khai Thác MCP Server - **Metadata**: `{"project": "DSCons", "category": "Root Standards", "code": "RULE-ROOT-04", "area": "Area 1"}` - **Nội dung (`text`)**: > `[DSCons Rule: Mandatory MCP Tools Protocol] Agent làm việc tại DSCons ERP bắt buộc ưu tiên sử dụng MCP tools thay thế script tạm: lsp-mcp (lsp_definition, lsp_references, lsp_diagnostics) cho duyệt code và refactor symbol; chrome-devtools-mcp cho nghiệm thu trình duyệt thực tế và bắt lỗi console/network; markitdown cho đọc bóc tách tài liệu dự toán PDF/Excel; memory cho Knowledge Graph kiến trúc; StitchMCP cho thiết kế UI; gemini-api-docs cho tra cứu SDK.` #### Fact 1.5: Điều Phối Sub-Agents & Tiêu Chuẩn Nghiệm Thu DoD - **Metadata**: `{"project": "DSCons", "category": "Root Standards", "code": "RULE-ROOT-05", "area": "Area 1"}` - **Nội dung (`text`)**: > `[DSCons Rule: Sub-Agent Coordination & Definition of Done] Giám đốc Kỹ thuật điều phối các Sub-Agents chuyên trách: Architect-DB, Dev-Backend, Dev-Frontend, Domain-AEC-Auditor, QA-SecOps. Mọi tác vụ nghiệm thu (Definition of Done - DoD) bắt buộc phải có đầy đủ: Bối cảnh, Ràng buộc kỹ thuật, Input/Output Schema rõ ràng, không vi phạm ranh giới kiến trúc, đạt 100% pytest passed và dọn dẹp sạch sẽ dữ liệu kiểm thử test teardown.` --- ### 2.2. Mảng 2: Quy Chuẩn Backend & CSDL (Backend & DB - 5 facts) #### Fact 2.1: Bốn Tầng Kiến Trúc Backend Clean Architecture - **Metadata**: `{"project": "DSCons", "category": "Backend & DB", "code": "RULE-BACKEND-01", "area": "Area 2"}` - **Nội dung (`text`)**: > `[DSCons Backend Architecture: 4-Layer Clean Architecture & DDD] Backend DSCons cấu trúc 4 tầng nghiêm ngặt: (1) Presentation (FastAPI Routers chỉ validate Pydantic schema và ủy quyền); (2) Application (Use Cases, Command/Query Handlers giao tiếp qua Domain Ports); (3) Domain Core (Entities, Value Objects, Protocols hoàn toàn độc lập 0% phụ thuộc framework/DB); (4) Infrastructure (Repositories, Adapters đóng gói SQL và external HTTP clients). Code phải vượt qua pytest test_architecture_boundary_enforcement.py.` #### Fact 2.2: Độ Chính Xác Số Học Tài Chính & Sổ Kép Bất Biến - **Metadata**: `{"project": "DSCons", "category": "Backend & DB", "code": "RULE-BACKEND-02", "area": "Area 2"}` - **Nội dung (`text`)**: > `[DSCons Backend Architecture: Database Precision & Double-Entry Ledger] Trong CSDL PostgreSQL và mã nguồn Python của DSCons ERP, TUYỆT ĐỐI CẤM sử dụng kiểu FLOAT hoặc DOUBLE cho tiền tệ VNĐ và khối lượng bóc tách BoQ. Bắt buộc sử dụng kiểu NUMERIC(18, 4) hoặc BIGINT trong PostgreSQL và kiểu Decimal trong Python. Mọi biến động tài chính, hạn mức ngân sách và kho vật tư áp dụng cơ chế Sổ kép (Double-entry ledger) bất biến kèm khóa Optimistic/Pessimistic Locking.` #### Fact 2.3: Vòng Đời Máy Chủ FastAPI Uvicorn & Hot-Reload - **Metadata**: `{"project": "DSCons", "category": "Backend & DB", "code": "RULE-BACKEND-03", "area": "Area 2"}` - **Nội dung (`text`)**: > `[DSCons Backend Architecture: FastAPI Server Lifecycle & Hot-Reload] Máy chủ backend Uvicorn của DSCons ERP luôn được vận hành với cờ --reload (python -m uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload). Trước khi nghiệm thu bất kỳ API endpoint hoặc module mới nào, Agent bắt buộc phải xác nhận tiến trình máy chủ đang chạy đã nạp nóng (hot-reloaded) mã nguồn mới nhất, tránh tình trạng kiểm thử trên phiên bản code cũ.` #### Fact 2.4: Chính Sách Thu Dọn Dữ Liệu Kiểm Thử Tự Động (Test Teardown) - **Metadata**: `{"project": "DSCons", "category": "Backend & DB", "code": "RULE-BACKEND-04", "area": "Area 2"}` - **Nội dung (`text`)**: > `[DSCons Backend Architecture: Strict Automated Test Teardown] Toàn bộ các kiểm thử tự động trong pytest tests/ khi chèn dữ liệu vào CSDL PostgreSQL (users, dự án, takeoffs, chat messages, quy tắc) bắt buộc phải có cơ chế dọn dẹp sạch sẽ 100% (Teardown via pytest fixture yield hoặc khối finally). Tuyệt đối không để sót các bản ghi rác mang tiền tố TEST-%, API_CAD%, SAMPLE_CAD% trong database sau khi test hoàn thành.` #### Fact 2.5: Quy Định Tiền Tố Định Tuyến API Gateway Prefix `/v1/erp` - **Metadata**: `{"project": "DSCons", "category": "Backend & DB", "code": "RULE-BACKEND-05", "area": "Area 2"}` - **Nội dung (`text`)**: > `[DSCons Backend Architecture: API Gateway Routing Prefix /v1/erp] Mọi API Endpoints và UI Dashboards mới trong hệ thống DSCons ERP bắt buộc phải tuân thủ tiền tố định tuyến /v1/erp (Ví dụ: @router.get("/v1/erp/dashboard/..."), /v1/erp/takeoff/...). Tuyệt đối không mount routes ở root level (/) vì API Gateway (Nginx/Cloudflare Tunnel) sẽ chặn và trả về lỗi 404 (Lỗi quên V1 vào endpoint).` --- ### 2.3. Mảng 3: Quy Chuẩn Giao Diện (Frontend & UI/UX - 5 facts) #### Fact 3.1: Hệ Thống Thiết Kế Dark Slate & Màu Sắc Chuẩn - **Metadata**: `{"project": "DSCons", "category": "Frontend UI", "code": "RULE-FRONTEND-01", "area": "Area 3"}` - **Nội dung (`text`)**: > `[DSCons Frontend Theme: Dark Slate Design System & Palette] Giao diện DSCons ERP áp dụng chuẩn thiết kế Enterprise Dark Slate Theme: Màu nền chính #0b0f19 / #080d1a, thẻ/panel #111827, đường viền #1e293b. Mọi màn hình bắt buộc import stylesheet dùng chung /static/css/erp_enterprise.css và thanh điều hướng thống nhất
với logo DSCons, menu phân hệ và trạng thái tài khoản.` #### Fact 3.2: Typography Song Ngữ & Phân Cấp Hiển Thị - **Metadata**: `{"project": "DSCons", "category": "Frontend UI", "code": "RULE-FRONTEND-02", "area": "Area 3"}` - **Nội dung (`text`)**: > `[DSCons Frontend Theme: Typography Standards & Font Hierarchy] Giao diện DSCons chuẩn hóa kiểu chữ: Google Fonts Inter hỗ trợ đầy đủ tiếng Việt cho toàn bộ tiêu đề và nội dung; Font JetBrains Mono cho toàn bộ số liệu tài chính VNĐ, đơn giá ca máy, mã thiết bị, và tọa độ CAD. Phân cấp cỡ chữ chặt chẽ: Tiêu đề trang 15px-17px (bold), Thẻ 13px-14px, Nội dung 12px-13px, Nhãn phụ Meta 10.5px-11.5px uppercase tracking.` #### Fact 3.3: Mật Độ Thông Tin Cao Bloomberg & Chống Đè Sidebar - **Metadata**: `{"project": "DSCons", "category": "Frontend UI", "code": "RULE-FRONTEND-03", "area": "Area 3"}` - **Nội dung (`text`)**: > `[DSCons Frontend Theme: High-Density Bloomberg Layout & Zero Sidebar Occlusion] Frontend DSCons tối ưu mật độ thông tin cao (Bloomberg/Palantir density): Paddings/gaps gọn gàng 8px-14px cho cards và 6px-10px cho hàng dữ liệu, chia cột Multi-Column Split-View. Chống đè menu (Zero Occlusion): Toàn bộ bố cục chính .erp-main-layout bao bọc nội dung với margin-left: var(--sidebar-width) (260px desktop, 72px collapsed), cấm để sidebar cố định che khuất nội dung.` #### Fact 3.4: Luồng Dữ Liệu Đơn Chiều & Khóa Chống Trùng Bất Đồng Bộ - **Metadata**: `{"project": "DSCons", "category": "Frontend UI", "code": "RULE-FRONTEND-04", "area": "Area 3"}` - **Nội dung (`text`)**: > `[DSCons Frontend Theme: Unidirectional Data Flow & Idempotent Locks] Giao diện DSCons tuân thủ luồng dữ liệu đơn chiều: Các hàm chuyển tab switchTab hoặc switchBoqViewMode là Pure State Renderers, tuyệt đối không gọi ngược lại Action Creators gây đệ quy vô tận. Mọi thao tác submit biểu mẫu và gọi API phải có cờ khóa chống trùng bất đồng bộ (Idempotent locks: if (isSubmitting) return; hoặc debounce) để ngăn chặn gửi nhiều request trùng lặp.` #### Fact 3.5: Hàng Rào Chống Tràn Thông Báo (Toast Anti-Flood) & Cache Buster - **Metadata**: `{"project": "DSCons", "category": "Frontend UI", "code": "RULE-FRONTEND-05", "area": "Area 3"}` - **Nội dung (`text`)**: > `[DSCons Frontend Theme: Toast Anti-Flood & Static Asset Cache Buster] Hệ thống thông báo DSCons có hàng rào Toast Anti-Flood tự động chặn các thông báo trùng lặp đang hiển thị và giới hạn tối đa 3 Toast cùng lúc trên màn hình. Mọi lệnh gán img.src hình ảnh bản vẽ CAD phải gắn ?v=${Date.now()}. Khi cập nhật file JS/CSS cốt lõi, bắt buộc tăng phiên bản Cache Buster (?v=x.x.x) trên toàn bộ các file .html để trình duyệt người dùng hiển thị đúng UI mới.` --- ### 2.4. Mảng 4: Nghiệp Vụ AEC & BoQ (Business Domain - 7 facts) #### Fact 4.1: Bốn Trụ Cột Kinh Doanh Của Định Sơn (MST 0202111150) - **Metadata**: `{"project": "DSCons", "category": "AEC Business", "code": "RULE-AEC-01", "area": "Area 4"}` - **Nội dung (`text`)**: > `[DSCons AEC Business: 4 Business Pillars of Dinh Son MST 0202111150] Công ty TNHH Xây Dựng Định Sơn (MST: 0202111150) có 4 Trụ cột kinh doanh độc lập: (1) Thi công Xây lắp & Thủy lợi (Đa Độ, Cống Bến Kem, Kiến Minh...); (2) Dịch vụ Vận tải Xe Ben & Logistics Cơ Giới (Thoát Nước Hải Phòng 0200149705 vận chuyển bùn đất); (3) Cho thuê Máy móc Ca máy (Loan Khải 0201889988); (4) Mua bán Vật tư & San lấp (Trung Kiên 0201805660). Tuyệt đối KHÔNG gộp các trụ cột 2, 3, 4 thành Dự án Thi công Xây dựng.` #### Fact 4.2: Định Mức Cừ Larsen & Tôn Chống Lầy Thông Tư 38 (VL = 0) - **Metadata**: `{"project": "DSCons", "category": "AEC Business", "code": "RULE-AEC-02", "area": "Area 4"}` - **Nội dung (`text`)**: > `[DSCons AEC Business: Circular 38 Larsen Pile Norms & Material Cost VL=0] Căn cứ Luật Xây dựng 2025/2026 và Thông tư 38: Công tác Thuê, Ép, Nhổ cừ thép Larsen IV hoặc thuê tôn chống lầy cấu thành 100% từ Chi phí Nhân công (NC) và Chi phí Ca máy (M). Tuyệt đối KHÔNG sinh ra chi phí mua vật liệu thô mới (Bắt buộc VL = 0 VNĐ) trong Bảng Tổng Hợp Nhu Cầu Vật Tư (MR). Nghiêm cấm gán nhầm đơn giá mua cừ mới làm sai lệch dự toán thi công.` #### Fact 4.3: Hàng Rào Kiểm Toán Tỷ Trọng Ngân Sách Vật Tư ($MR / T$) - **Metadata**: `{"project": "DSCons", "category": "AEC Business", "code": "RULE-AEC-03", "area": "Area 4"}` - **Nội dung (`text`)**: > `[DSCons AEC Business: Material Budget Ratio Sanity Gate MR/T] Hệ thống kiểm toán dự toán DSCons áp dụng Hàng rào kiểm soát tỷ trọng vật tư (Sanity Check Gate): Tổng chi phí vật tư (MR) bắt buộc nằm trong khoảng 40% - 65% của Chi phí trực tiếp (T = VL + NC + M). Nếu tỷ lệ MR / T vượt quá 75%, hệ thống phải tự động kích hoạt Cảnh báo Bất thường (Anomaly Alert) nhằm chặn đứng lỗi nhân đôi khối lượng hoặc áp nhầm giá mua mới cho thiết bị thuê.` #### Fact 4.4: Bốn Cấp Độ Chi Phí Dự Toán & Ma Trận Hệ Số Tổng Hợp Kinh Phí - **Metadata**: `{"project": "DSCons", "category": "AEC Business", "code": "RULE-AEC-04", "area": "Area 4"}` - **Nội dung (`text`)**: > `[DSCons AEC Business: 4-Tier Budgeting & THKP Markup Matrix] Dự toán DSCons phân cấp 4 tầng chi phí: Cấp 1 Chi phí trực tiếp (T = VL + NC + M); Cấp 2 Dự toán XD sau thuế (G_XD = (T + GT + TL) * 1.08 VAT, dùng chào thầu BoQ); Cấp 3 Dự toán Gói thầu (G_GTXD = G_XD + Dự phòng); Cấp 4 Tổng mức đầu tư (G_TMĐT). Hệ số tổng hợp kinh phí (G_XD / T) phải tra cứu đúng loại công trình: Dân dụng ~1.2636; Nông nghiệp Thủy lợi cống đê ~1.2419-1.2543; Giao thông đường cầu ~1.2505; tuyệt đối không áp dụng đồng nhất một công thức.` #### Fact 4.5: Hàng Rào Chống Khống Giá Thép & Danh Mục Từ Khóa Loại Trừ - **Metadata**: `{"project": "DSCons", "category": "AEC Business", "code": "RULE-AEC-05", "area": "Area 4"}` - **Nội dung (`text`)**: > `[DSCons AEC Business: Anti-Inflation Steel Pricing & Strict Unit Guard] Đơn giá thép mua mới (16.15 - 16.45 tr/tấn) CHỈ ĐƯỢC PHÉP áp dụng cho cốt thép chịu lực kết cấu bê tông theo đúng ĐVT (tấn, 100kg, kg). CẤM TUYỆT ĐỐI áp giá thép tấn cho ĐVT m, m2, tấm, ca, chuyến. Tự động loại trừ 100% khi khớp giá thép với các từ khóa: cừ thép, thuê cừ, cừ larsen, thuê ván thép, ván khuôn thép, khung xương thép, bốc xếp vận chuyển thép, dây chống sét D10, dàn giáo.` #### Fact 4.6: Hạch Toán Vật Tư Xuất Thẳng Chân Công Trường & Phân Bổ BoQ - **Metadata**: `{"project": "DSCons", "category": "AEC Business", "code": "RULE-AEC-06", "area": "Area 4"}` - **Nội dung (`text`)**: > `[DSCons AEC Business: Direct-to-Site Accounting & BoQ-Driven Allocation] DSCons tuyệt đối không dùng TK 152 tạo Kho Ảo cho vật tư thi công. Vật tư (thép, xi măng, cát, đá, cọc) giao thẳng về chân công trình được hạch toán trực tiếp: Nợ TK 621_Chi_tiết_Dự_án (hoặc TK 154) / Nợ TK 1331 / Có TK 331. Hệ thống tự động đọc định mức dự toán BoQ của các dự án đang thi công và hạn mức vật tư còn lại (Remaining Quota) để tự động phân rã chi phí và gán đúng mã dự án matched_project_id.` #### Fact 4.7: Bóc Tách Bản Vẽ CAD: Giải Mã TCVN3 & Cắt Khung Bounding Box - **Metadata**: `{"project": "DSCons", "category": "AEC Business", "code": "RULE-AEC-07", "area": "Area 4"}` - **Nội dung (`text`)**: > `[DSCons AEC Business: CAD Takeoff Engine TCVN3 Decoding & Bounding Box] Engine bóc tách CAD DSCons giải mã chính xác byte font TCVN3/.VnTime/VNI, cố định stroke-width: 1px non-scaling-stroke trên vector graphics. Tự động quét Model Space thực tế để cắt Bounding Box sạch (Zero-Void), loại bỏ khoảng trống rác >100m. Phân định chặt chẽ Xây mới (NEW_BUILD_ENGINE) vs Cải tạo (RENOVATION_ENGINE áp dụng định mức Chương SA/AA, vật liệu VL = 0 VNĐ, cấm tự sinh khối lượng đúc mới kết cấu hiện trạng).` --- ### 2.5. Mảng 5: Kiểm Thử & Quy Trình (Testing & Workflow - 5 facts) #### Fact 5.1: Quy Trình Lập Kế Hoạch Đa Tầng Deep Matrix D1 Đến D6 - **Metadata**: `{"project": "DSCons", "category": "Testing & Workflow", "code": "RULE-WORKFLOW-01", "area": "Area 5"}` - **Nội dung (`text`)**: > `[DSCons Testing & Quality: Deep Matrix Workflow D1-D6 on task.md] Mọi đợt tái cấu trúc lớn (Mass Refactoring) hoặc tính năng trên 10 files tại DSCons bắt buộc áp dụng quy trình Deep Matrix Workflow trên task.md từ D1 đến D6: [D1] Module/Epic, [D2] Business Flow, [D3] Domain Logic, [D4] State & Transitions, [D5] Event Bus Dependencies, [D6] File-level Execution. Thực thi từng phần từ D6 ngược lên; nghiêm cấm tạo scaffolding rỗng hoặc TODO giả; cập nhật timestamp và checkbox sau mỗi khối logic.` #### Fact 5.2: Giao Thức TDD Closed-Loop Tự Hành & Hàng Rào Hồi Quy - **Metadata**: `{"project": "DSCons", "category": "Testing & Workflow", "code": "RULE-WORKFLOW-02", "area": "Area 5"}` - **Nội dung (`text`)**: > `[DSCons Testing & Quality: Autonomous Closed-Loop TDD & Regression Gate] Mọi phát triển phần mềm DSCons tuân thủ Test-Driven Development (TDD): Viết test trước khi sửa mã nguồn; xác nhận test FAIL (negative baseline); triển khai mã tối thiểu; tự hành sửa lỗi qua traceback tối đa 5 vòng lặp (zero human hand-holding) cho đến khi 100% test PASS; độ bao phủ coverage >= 80% (unit + integration + E2E). Hàng rào pytest tests -v đạt 100% Passed là điều kiện bắt buộc trước khi commit.` #### Fact 5.3: Chu Trình Nghiệm Thu Chất Lượng 6 Pha Verification Loop - **Metadata**: `{"project": "DSCons", "category": "Testing & Workflow", "code": "RULE-WORKFLOW-03", "area": "Area 5"}` - **Nội dung (`text`)**: > `[DSCons Testing & Quality: 6-Phase Verification Quality Gate] Trước khi tạo Pull Request hoặc bàn giao tính năng, Agent bắt buộc vượt qua chu trình kiểm chứng 6 pha Verification Loop: Pha 1 Build Verification (npm run build / uvicorn reload); Pha 2 Type Check (pyright / tsc); Pha 3 Lint Check (ruff / eslint); Pha 4 Test Suite (pytest --cov >= 80%); Pha 5 Security Scan (quét secret/SQLi); Pha 6 Diff Review (đối soát git diff không dư thừa).` #### Fact 5.4: Khung Đánh Giá Năng Lực & Hồi Quy Eval-Driven Development - **Metadata**: `{"project": "DSCons", "category": "Testing & Workflow", "code": "RULE-WORKFLOW-04", "area": "Area 5"}` - **Nội dung (`text`)**: > `[DSCons Testing & Quality: Eval-Driven Development EDD & Grader Harness] DSCons ERP áp dụng triết lý Eval-Driven Development (EDD) xem evals là unit tests của AI development: Thiết lập tiêu chí thành công trước khi triển khai; theo dõi hồi quy (Regression Evals) với độ tin cậy pass@k; sử dụng Code-Based Grader mang tính tất định (deterministic checks) kiểm tra file patterns, test pass, build success thay vì chấm điểm cảm tính.` #### Fact 5.5: Kiểm Thử Trình Duyệt Thực Tế & Ranh Giới Kiến Trúc Tự Động - **Metadata**: `{"project": "DSCons", "category": "Testing & Workflow", "code": "RULE-WORKFLOW-05", "area": "Area 5"}` - **Nội dung (`text`)**: > `[DSCons Testing & Quality: Real Browser Automation Gate & AST Boundary] Toàn bộ tính năng UI/UX và mô hình bản vẽ/BIM bắt buộc kiểm thử trực tiếp trên trình duyệt thực tế (Real Browser Gate qua Chrome DevTools MCP hoặc Playwright), xác nhận 0 lỗi console JavaScript, FPS > 30 và chụp ảnh nghiệm thu. Đồng thời mọi thay đổi backend bắt buộc vượt qua bộ kiểm tra ranh giới AST tự động: pytest tests/test_architecture_boundary_enforcement.py đạt 100% Passed.` --- ## 3. THIẾT KẾ BỘ KIỂM CHỨNG & NGHIỆM THU (VERIFICATION & ACCEPTANCE TEST SUITE) ### 3.1. Danh Mục Các Truy Vấn Kiểm Thử Nghiệm Thu (Test Query Catalog) Bộ kiểm chứng nghiệm thu được thiết kế gồm **8 truy vấn trọng tâm** (3 truy vấn bắt buộc theo `ORIGINAL_REQUEST.md` + 5 truy vấn chuyên sâu cho từng phân hệ): ``` ┌────────────────────────────────────────────────────────────────────────┐ │ DANH MỤC TRUY VẤN KIỂM CHỨNG NGHIỆM THU MEM0 │ ├────────────────────────────────────────────────────────────────────────┤ │ 1. [BẮT BUỘC] "DSCons rule" -> Trả về 7 Luật Cốt Lõi, Zero-Mock │ │ 2. [BẮT BUỘC] "frontend theme" -> Trả về Dark Slate, Bloomberg │ │ 3. [BẮT BUỘC] "backend architecture" -> Trả về Hexagonal DDD, Decimal │ │ 4. [CHUYÊN SÂU] "AEC pricing norms" -> Trả về TT38 cừ Larsen VL=0 │ │ 5. [CHUYÊN SÂU] "CAD takeoff geometry"-> Trả về TCVN3, 1px, BoundingBox │ │ 6. [CHUYÊN SÂU] "database precision" -> Trả về NUMERIC(18,4), Sổ kép │ │ 7. [CHUYÊN SÂU] "testing workflow" -> Trả về Deep Matrix D1-D6, TDD │ │ 8. [CHUYÊN SÂU] "MCP tools protocol" -> Trả về Ma trận lsp-mcp, chrome│ └────────────────────────────────────────────────────────────────────────┘ ``` --- ### 3.2. Tiêu Chí Đánh Giá Đạt / Không Đạt (Pass / Fail Criteria) #### A. Tiêu Chí Đạt (Pass Assertions): 1. **Relevance & Top-1 Precision**: - Đối với mỗi truy vấn trong số 8 truy vấn trên, kết quả Top-1 trả về từ `mem0_search(query, limit=5)` bắt buộc phải thuộc danh mục 27 facts mới của DSCons. - Điểm tương đồng Cosine (score) của Top-1 phải đạt **$\ge 0.55$** (mục tiêu lý tưởng: $\ge 0.65$). 2. **Top-3 Domain Dominance**: - Tối thiểu 2 trong 3 kết quả đầu tiên (hoặc 100% kết quả liên quan đến xây dựng/ERP) phải trích xuất từ 27 facts mới của DSCons. 3. **Phủ Đủ 5 Mảng Tri Thức (Coverage Gate)**: - Khi chạy `mem0_get_all(user_id="developer")`, hệ thống phải chứa đầy đủ 27 facts mới phân bố đủ 5 mảng: Root (5), Backend (5), Frontend (5), AEC (7), Testing (5). 4. **Metadata Integrity**: - 100% các facts mới nạp phải chứa metadata có trường `"project": "DSCons"`. #### B. Tiêu Chí Không Đạt / Loại Trừ Tuyệt Đối (Negative Assertions - Zero Obsolete Remnants): 1. **Tuyệt đối KHÔNG xuất hiện tàn dư DSCons cũ**: - Không xuất hiện 2 bản ghi log trùng lặp cũ: `user: DSCons logging (05/10/2026): app/core/logging_config.configure_logging()...` (ID: `bab3dbc0-2f3c-49ad-b416-a9f4f8077dbf`, `5dcc1be8-7216-47a3-8285-dc5b81ffe324`). - Không xuất hiện bản ghi chứa metadata méo mó: text nói về FreeExile nhưng metadata ghi `"project": "DSCons-ERP"` (ID: `8d9178bc-0f7c-429f-b7ee-1af803df4c15`). - Không xuất hiện các con số dự toán cũ sai lệch (như cache 71 hạng mục 4,49 tỷ hay số tiền phóng đại 4.753 tỷ). 2. **Tuyệt đối KHÔNG xuất hiện kết quả FreeExile trong Top-3 của truy vấn DSCons**: - Khi tìm kiếm `"DSCons rule"`: Kết quả Top-3 tuyệt đối không được chứa nội dung game FreeExile (như `Savage Infinite Atlas`, `FreeExile Combat UI`, `Path of Exile 2`). - Khi tìm kiếm `"frontend theme"`: Không được trả về `Feral NPC & Dialogue HUD` của FreeExile ở Top-1 (hiện tại đang bị lỗi này!). - Khi tìm kiếm `"backend architecture"`: Không được trả về `FreeExile Server-Authoritative Streaming` hay `Cocos Creator 3.x` ở Top-1/Top-2. 3. **Chính sách Zero-Wipe đối với các dự án khác**: - Dữ liệu của FreeExile và sở thích lập trình chung (Global) vẫn phải tồn tại nguyên vẹn trong CSDL Qdrant (chứng minh Selective Cleanup thực thi đúng). --- ### 3.3. Ma Trận Đối Soát Kỳ Vọng Từng Truy Vấn (Query Expectation Matrix) | # | Truy Vấn (Query) | Fact Kỳ Vọng Xuất Hiện (Expected Top Hit) | Từ Khóa Bắt Buộc Có (Must Contain) | Tàn Dư Cấm Xuất Hiện (Negative Check) | | :-: | :--- | :--- | :--- | :--- | | **Q1** | `"DSCons rule"` | Fact 1.1 hoặc Fact 1.2 (`RULE-ROOT-01`, `RULE-ROOT-02`) | `Bảy Điều luật`, `cốt lõi`, `synthetic data`, `Định Sơn` | `app/core/logging_config`, `FreeExile`, `Atlas` | | **Q2** | `"frontend theme"` | Fact 3.1 hoặc Fact 3.2 (`RULE-FRONTEND-01`, `RULE-FRONTEND-02`) | `Dark Slate`, `#0b0f19`, `Inter`, `JetBrains Mono` | `Feral NPC`, `Dialogue HUD`, `Combat UI` | | **Q3** | `"backend architecture"` | Fact 2.1 hoặc Fact 2.2 (`RULE-BACKEND-01`, `RULE-BACKEND-02`) | `Clean Architecture`, `DDD`, `NUMERIC(18, 4)`, `Decimal` | `Server-Authoritative Streaming`, `Cocos Creator` | | **Q4** | `"AEC pricing norms"` | Fact 4.2 hoặc Fact 4.4 (`RULE-AEC-02`, `RULE-AEC-04`) | `Thông tư 38`, `cừ Larsen`, `VL = 0`, `G_XD` | `4.753 tỷ`, `cache 71 hạng mục` | | **Q5** | `"CAD takeoff geometry"` | Fact 4.7 (`RULE-AEC-07`) | `TCVN3`, `stroke-width: 1px`, `Bounding Box`, `Chương SA` | `FreeExile`, game mechanics | | **Q6** | `"database precision"` | Fact 2.2 (`RULE-BACKEND-02`) | `NUMERIC(18, 4)`, `Decimal`, `Sổ kép`, `Double-entry` | `FLOAT`, `DOUBLE` được khuyến khích | | **Q7** | `"testing workflow"` | Fact 5.1 hoặc Fact 5.2 (`RULE-WORKFLOW-01`, `RULE-WORKFLOW-02`) | `Deep Matrix D1-D6`, `TDD`, `80%`, `task.md` | Scaffolding rỗng, TODO | | **Q8** | `"MCP tools protocol"` | Fact 1.4 (`RULE-ROOT-04`) | `lsp-mcp`, `chrome-devtools-mcp`, `markitdown`, `memory` | Script tạm, regex text grep | --- ## 4. KẾ HOẠCH HÀNH ĐỘNG CHI TIẾT (PROPOSALS FOR MILESTONE 3 & MILESTONE 4) ### 4.1. Kế Hoạch Milestone 3: Nạp Bộ Nhớ Tự Động (Ingestion Execution Protocol) - **Mục tiêu**: Nạp tuần tự và trọn vẹn 27 facts nguyên tử vào Mem0 sau khi Milestone 2 (Selective Cleanup) đã hoàn thành dọn dẹp các bản ghi cũ. - **Phương thức triển khai**: - Viết một script Python tự động thực thi hoặc thực hiện tuần tự qua MCP tool `mem0_add`. - Khuyến nghị sử dụng script chạy nền kết nối thẳng tới FastMCP hoặc gọi qua tool `call_mcp_tool(ServerName="mem0", ToolName="mem0_add", ...)`: ```python import json import time def ingest_facts(facts_catalog): for fact in facts_catalog: args = { "text": fact["text"], "user_id": "developer", "metadata": fact["metadata"] } # Gọi mem0_add # Nghỉ 150ms giữa các lệnh để tránh dồn ứ I/O trên Embedded Qdrant time.sleep(0.15) ``` - **Xử lý Biên & Phòng Vệ (Defensive Engineering)**: - Nếu `mem0_add` trả về `{"status": "exists"}`, script ghi nhận là đã nạp an toàn, không báo lỗi. - Sau khi nạp xong 27 facts, chạy `mem0_get_all` để kiểm đếm số lượng facts mang metadata `project: DSCons`. Nếu đủ 27 facts $\rightarrow$ Chốt Milestone 3 ĐẠT. --- ### 4.2. Kế Hoạch Milestone 4: Kiểm Chứng Tự Động (Verification Test Runner) - **Mục tiêu**: Chạy bộ 8 truy vấn kiểm thử, đối soát tự động theo ma trận tiêu chí Pass/Fail và xuất Bảng Báo Cáo Nghiệm Thu (Verification Scorecard). - **Mã nguồn kịch bản kiểm thử đề xuất (`test_mem0_verification.py`)**: ```python import json from typing import List, Dict TEST_SUITE = [ { "name": "Mandatory Q1 - DSCons Root Rules", "query": "DSCons rule", "expected_keywords": ["Bảy Điều luật", "Định Sơn", "synthetic data", "lục giác"], "forbidden_keywords": ["app/core/logging_config", "FreeExile", "Savage"] }, { "name": "Mandatory Q2 - Frontend Theme", "query": "frontend theme", "expected_keywords": ["Dark Slate", "0b0f19", "Inter", "JetBrains Mono"], "forbidden_keywords": ["Feral NPC", "Dialogue HUD", "Atlas"] }, { "name": "Mandatory Q3 - Backend Architecture", "query": "backend architecture", "expected_keywords": ["Clean Architecture", "NUMERIC(18, 4)", "Decimal", "Ports"], "forbidden_keywords": ["FreeExile", "Server-Authoritative", "Cocos"] }, { "name": "Domain Q4 - AEC Pricing Norms", "query": "AEC pricing norms", "expected_keywords": ["Thông tư 38", "cừ Larsen", "VL = 0", "MR / T"], "forbidden_keywords": ["4.753 tỷ", "cache 71"] }, { "name": "Domain Q5 - CAD Takeoff Geometry", "query": "CAD takeoff geometry", "expected_keywords": ["TCVN3", "stroke-width: 1px", "Bounding Box"], "forbidden_keywords": ["FreeExile"] }, { "name": "Domain Q6 - Database Precision", "query": "database precision", "expected_keywords": ["NUMERIC(18, 4)", "Decimal", "Double-entry"], "forbidden_keywords": ["FLOAT", "DOUBLE"] }, { "name": "Domain Q7 - Testing Workflow", "query": "testing workflow", "expected_keywords": ["Deep Matrix", "D1-D6", "TDD", "task.md"], "forbidden_keywords": ["scaffolding"] }, { "name": "Domain Q8 - MCP Tools Protocol", "query": "MCP tools protocol", "expected_keywords": ["lsp-mcp", "chrome-devtools-mcp", "markitdown"], "forbidden_keywords": ["grep_search"] } ] def run_verification(search_tool_fn): scorecard = [] all_passed = True for test in TEST_SUITE: res_json = search_tool_fn(query=test["query"], limit=5) res = json.loads(res_json) results = res.get("memories", {}).get("results", []) # Đánh giá Top-1 top_hit = results[0] if results else {} top_text = top_hit.get("memory", "") top_score = top_hit.get("score", 0.0) has_expected = any(k.lower() in top_text.lower() for k in test["expected_keywords"]) has_forbidden = any(k.lower() in top_text.lower() for k in test["forbidden_keywords"]) is_pass = has_expected and not has_forbidden and (top_score >= 0.55) scorecard.append({ "test": test["name"], "query": test["query"], "top_score": top_score, "is_pass": is_pass, "top_snippet": top_text[:120] + "..." if len(top_text) > 120 else top_text }) if not is_pass: all_passed = False return all_passed, scorecard ``` - **Bảng Biểu Xuất Ra (Scorecard Output)**: Tạo bảng nghiệm thu trực quan báo cáo Giám đốc Kỹ thuật với các cột: Truy vấn, Điểm tương đồng Top-1, Kết quả Kiểm tra Từ khóa Bắt buộc, Kết quả Kiểm tra Tàn dư Âm tính, Trạng thái (PASS/FAIL). --- ## 5. TỔNG KẾT & CHỈ DẪN CHUYỂN GIAO (SUMMARY & TRANSITION DIRECTIVE) Bản thiết kế này cung cấp đầy đủ: 1. **Bản đồ toán học & ngữ nghĩa** giải thích rõ cơ chế vector embedding của Mem0 và nguyên nhân cần dùng Domain Prefix song ngữ. 2. **Bộ danh mục 27 facts chuẩn hóa** đã sẵn sàng để nạp trực tiếp vào `mem0_add` mà không cần biên soạn lại. 3. **Bộ test suite 8 câu hỏi với tiêu chí định lượng chính xác** bảo đảm nghiệm thu sạch 100% không còn tàn dư cũ. 4. **Kế hoạch thực thi 2 bước cho Milestone 3 và Milestone 4** để các Sub-Agent tiếp theo triển khai trơn tru và tự hành.