# DSCons ERP: BÁO CÁO KHẢO SÁT & TRÍCH XUẤT TOÀN DIỆN TRI THỨC DỰ ÁN
**Mã tiến trình**: `teamwork_preview_explorer_survey_2`  
**Ngày thực hiện**: 2026-10-05T20:30:00Z  
**Mục tiêu**: Khảo sát, phân tích chuyên sâu và trích xuất có hệ thống các quy chuẩn kiến trúc, luật bất biến (invariant laws), và tri thức nghiệp vụ cốt lõi từ 12 tài liệu quy chuẩn thuộc 5 mảng tài liệu trung tâm của hệ thống DSCons ERP.

---

## MỤC LỤC
1. [TỔNG QUAN HỆ THỐNG & TRIẾT LÝ VẬN HÀNH](#1-tổng-quan-hệ-thống--triết-lý-vận-hành)
2. [AREA 1: QUY CHUẨN GỐC & CƠ CHẾ ĐIỀU PHỐI (ROOT STANDARDS & MCP PROTOCOL)](#2-area-1-quy-chuẩn-gốc--cơ-chế-điều-phối-root-standards--mcp-protocol)
3. [AREA 2: QUY CHUẨN BACKEND & CƠ SỞ DỮ LIỆU (BACKEND CLEAN ARCHITECTURE & DB)](#3-area-2-quy-chuẩn-backend--cơ-sở-dữ-liệu-backend-clean-architecture--db)
4. [AREA 3: QUY CHUẨN FRONTEND & TRẢI NGHIỆM NGƯỜI DÙNG (DARK SLATE ENTERPRISE UI)](#4-area-3-quy-chuẩn-frontend--trải-nghiệm-người-dùng-dark-slate-enterprise-ui)
5. [AREA 4: NGHIỆP VỤ XÂY DỰNG AEC, CAD TAKEOFF & ĐỊNH MỨC ĐỊNH SƠN](#5-area-4-nghiệp-vụ-xây-dựng-aec-cad-takeoff--định-mức-định-sơn)
6. [AREA 5: QUY TRÌNH KIỂM THỬ, ĐÁNH GIÁ & QUẢN TRỊ TÁC VỤ (TESTING & WORKFLOW)](#6-area-5-quy-trình-kiểm-thử-đánh-giá--quản-trị-tác-vụ-testing--workflow)
7. [MA TRẬN QUAN HỆ CHÉO & LUẬT BẤT BIẾN TOÀN DỰ ÁN (CROSS-CUTTING INVARIANTS)](#7-ma-trận-quan-hệ-chéo--luật-bất-biến-toàn-dự-án-cross-cutting-invariants)
8. [DANH MỤC FACTS CHUẨN HÓA SẴN SÀNG NẠP VÀO MEM0](#8-danh-mục-facts-chuẩn-hóa-sẵn-sàng-nạp-vào-mem0)

---

## 1. TỔNG QUAN HỆ THỐNG & TRIẾT LÝ VẬN HÀNH

Hệ thống DSCons ERP là giải pháp điều hành doanh nghiệp chuyên ngành Xây dựng - Thủy lợi - Hạ tầng giao thông dành cho **Công ty TNHH Xây Dựng Định Sơn (Mã số thuế: `0202111150`)**. 

Toàn bộ triết lý thiết kế và vận hành của DSCons ERP được đặt trên 3 nguyên lý nền tảng:
1. **Nguồn sự thật tuyệt đối (Single Source of Truth - Zero Synthetic Data)**: Mọi dữ liệu tài chính, định mức, bản vẽ, vật tư và chi phí bắt buộc phải phản ánh đúng thực tế hồ sơ thầu, hóa đơn thuế điện tử (GDT) và dump cơ sở dữ liệu Odoo thực của Định Sơn.
2. **Kỹ thuật xác định & Ranh giới bất khả xâm phạm (Deterministic Engineering & Strict Boundaries)**: Kiến trúc lục giác (Hexagonal / Clean Architecture), độ chính xác số học tài chính `Decimal(18,4)`, sổ kép bất biến, và hàng rào kiểm thử ranh giới bằng AST bảo vệ hệ thống khỏi sự thoái hóa kiến trúc.
3. **Mật độ thông tin cao & Trải nghiệm chuyên nghiệp (High-Density Bloomberg/Palantir Standard)**: Giao diện tối ưu không gian hiển thị cho kỹ sư và ban giám đốc, không khoảng trống vô nghĩa, màu sắc Dark Slate chuyên sâu, luồng dữ liệu đơn chiều và bảo vệ tương tác người dùng.

---

## 2. AREA 1: QUY CHUẨN GỐC & CƠ CHẾ ĐIỀU PHỐI (ROOT STANDARDS & MCP PROTOCOL)

### 2.1. Định danh & Vai trò Cốt lõi
- **Vai trò**: Chuyên gia Kiến trúc Hệ thống Cấp cao kiêm Giám đốc Kỹ thuật (Technical Director).
- **Trách nhiệm**: Tổng chỉ huy thiết kế kiến trúc, điều phối mạng lưới Sub-Agents chuyên trách, kiểm soát chất lượng kỹ thuật nghiêm ngặt và trực tiếp nghiệm thu từng thành phẩm trước khi đưa vào sản xuất.

### 2.2. Bảy Điều Luật Cốt Lõi Bất Biến (Non-Negotiable Core Laws)
Theo `.agents/AGENTS.md` (Dòng 8 - 26):
1. **Tuyệt Đối Cấm Dữ Liệu Ảo / Mock (Strict Zero-Tolerance Synthetic Data)**:
   - Dữ liệu hóa đơn, dự án, định mức, nhà cung cấp bắt buộc 100% trích xuất từ: Cổng Thuế điện tử (GDT), Odoo dump thực tế và hồ sơ dự toán HĐ-2026 của Định Sơn (`0202111150`).
   - Cấm hoàn toàn mọi script seed ảo, mock dữ liệu không có căn cứ thực tế.
2. **Hàng Rào Kiểm Thử Hồi Quy (Automated Regression Gate)**:
   - Mọi sửa đổi mã nguồn backend, schema cơ sở dữ liệu hoặc API routes đều phải vượt qua bộ kiểm thử tự động `pytest tests -v` đạt **100% Passed**.
3. **Kiểm Thử Thực Tế Trên Trình Duyệt (Real Browser Automation Gate)**:
   - Mọi tính năng UI/UX và thao tác đồ họa bản vẽ bắt buộc phải được kiểm thử trực tiếp trên trình duyệt thực tế (ưu tiên qua `chrome-devtools-mcp` hoặc Playwright) trước khi báo hoàn thành.
4. **Vòng Đời Máy Chủ Hot-Reload**:
   - Máy chủ backend FastAPI/Uvicorn luôn chạy với cờ `--reload`. Phải xác nhận mã mới nhất đã nạp nóng vào tiến trình trước khi nghiệm thu.
5. **Chống Hội Chứng "Bus Factor" (Mandatory Documentation & Explainability)**:
   - Tuyệt đối không sinh code "hộp đen". Mọi quyết định thiết kế kiến trúc và logic phức tạp phải có inline comments và được tài liệu hóa rõ ràng để lập trình viên con người có thể kế thừa và duy trì.
6. **Tuân Thủ Tuyệt Đối DDD & Kiến Trúc Lục Giác (Strict Hexagonal Architecture & Ports/Adapters Boundary)**:
   - *Tầng Presentation*: Chỉ tiếp nhận request, validate schema, ủy quyền cho Application Services; CẤM raw SQL (`SELECT`, `INSERT`, `UPDATE`) hoặc DDL (`CREATE/ALTER/DROP TABLE`).
   - *Tầng Application*: Chỉ điều phối Use Cases; CẤM import HTTP clients cấp thấp (`httpx`, `requests`, `urllib.request`) hoặc gọi trực tiếp LLM endpoints bên ngoài (`openrouter.ai`, `generativelanguage.googleapis.com`). Mọi kết nối mạng phải qua Secondary Infrastructure Adapters hoặc `EnterpriseAiGateway` (Antigravity SDK native).
   - *Tầng Domain*: Hoàn toàn độc lập với Framework, ORM, CSDL và Network.
   - *Hàng rào AST*: Bắt buộc vượt qua `pytest tests/test_architecture_boundary_enforcement.py` đạt **100% Passed**.
7. **Bắt Buộc Khai Thác Hệ Sinh Thái MCP Server (Strict Mandatory MCP Server Utilization Gate)**:
   - Ưu tiên công cụ MCP chuyên biệt, cấm lạm dụng regex grep hoặc script tạm bợ.

### 2.3. Cơ chế Tuyển dụng Sub-Agents & Tiêu chuẩn Nghiệm thu (DoD)
- **Danh mục Sub-Agents phân nhiệm**:
  - `Architect-DB`: Chuyên trách schema PostgreSQL, index, migration, double-entry ledger.
  - `Dev-Backend`: Chuyên trách domain services, application handlers, infrastructure adapters, FastAPI routes.
  - `Dev-Frontend`: Chuyên trách layout Dark Slate, CAD viewer, Bloomberg density UI, component state.
  - `Domain-AEC-Auditor`: Chuyên trách thẩm tra định mức xây dựng 2026, đối soát BoQ, kiểm toán tỷ trọng $MR/T$.
  - `QA-SecOps`: Chuyên trách kiểm thử hồi quy, bảo mật API, rà soát lộ lọt secrets và test teardown.
- **Quy chuẩn Giao việc & Nghiệm thu (DoD)**: Mỗi công việc phải có Bối cảnh, Ràng buộc kỹ thuật, Schema vào/ra, và Definition of Done. Không chấp nhận code vi phạm ranh giới hoặc để sót rác dữ liệu test.

### 2.4. Ma Trận Điều Phối MCP Server Tại Workspace DSCons
Theo `.agents/AGENTS.md` (Dòng 48 - 58) & `GEMINI.md`:

| Nhiệm Vụ Kỹ Thuật | MCP Server Chỉ Định | Công Cụ Chính | Điều Kiện & Mục Đích Bắt Buộc |
| :--- | :--- | :--- | :--- |
| **Dò tìm tham chiếu, Symbol refactor, Phân tích Type** | `lsp-mcp` | `lsp_definition`, `lsp_references`, `lsp_diagnostics`, `lsp_document_symbols`, `lsp_rename` | Phải dùng khi đổi tên hàm/lớp, truy vết caller/callee, kiểm tra type integrity. Cấm dùng regex grep thay thế. |
| **Kiểm thử E2E, Chụp màn hình UI, Bắt lỗi giao diện** | `chrome-devtools-mcp` | `navigate_page`, `take_screenshot`, `click`, `list_console_messages`, `get_network_request` | Nghiệm thu trực quan giao diện, bắt 0 lỗi Console JS, 0 lỗi Network failure trên trình duyệt thực. |
| **Bóc tách tài liệu dự toán, BoQ, Hóa đơn** | `markitdown` | `convert_document` | Chuyển đổi file hồ sơ thầu, bảng dự toán (PDF, Word, Excel) sang định dạng Markdown chuẩn xác. |
| **Bộ nhớ đồ thị tri thức dài hạn** | `memory` | `create_entities`, `create_relations`, `add_observations`, `search_nodes` | Lưu trữ quyết định kiến trúc, schema database, luật định mức vào Knowledge Graph dài hạn. |
| **Thiết kế & Prototype Giao diện UI/UX** | `StitchMCP` | `generate_screen_from_text`, `apply_design_system`, `create_design_system` | Khởi tạo mockup và duy trì nhất quán design system chuẩn Dark Slate. |
| **Tra cứu tài liệu Gemini SDK & Interactions API** | `gemini-api_gemini-api-docs` | `gemini_search_docs`, `gemini_get_doc` | Tra cứu cú pháp SDK chính xác, loại trừ suy đoán ảo giác. |

---

## 3. AREA 2: QUY CHUẨN BACKEND & CƠ SỞ DỮ LIỆU (BACKEND CLEAN ARCHITECTURE & DB)

Căn cứ: `.agents/skills/backend-clean-architecture/SKILL.md`, `backend-patterns/SKILL.md`, `coding-standards/SKILL.md`.

### 3.1. Mô Hình 4 Tầng Kiến Trúc Lục Giác Chuẩn Mực
1. **Driving / Inbound Adapters (`presentation/`)**:
   - Thành phần: FastAPI Routers, Webhooks, CLI commands.
   - Trách nhiệm: Validate request body bằng Pydantic schemas, kiểm tra xác thực (JWT/Role), gọi Use Cases / Command Handlers trong Application Layer.
   - **Ràng buộc CẤM**: Tuyệt đối không mở kết nối DB trực tiếp (`db.get_connection()`), không viết câu lệnh SQL (`cur.execute()`), không chạy DDL (`CREATE TABLE`).
2. **Application Layer (`application/`)**:
   - Thành phần: Use Cases, Command/Query Handlers, Orchestrators, Service Facades.
   - Trách nhiệm: Thực thi luồng xử lý nghiệp vụ; chỉ phụ thuộc vào Domain Core; giao tiếp với hạ tầng thông qua **Domain Ports** (Interfaces).
   - **Ràng buộc CẤM**: Không import HTTP clients cấp thấp (`httpx`, `requests`, `urllib.request`). Không gọi trực tiếp endpoint LLM bên ngoài (`openrouter.ai`, `generativelanguage.googleapis.com`).
3. **Domain Core (`domain/`)**:
   - Thành phần: Business Entities, Value Objects, Domain Events, Domain Services, Port Interfaces (`@runtime_checkable Protocol`).
   - Trách nhiệm: Chứa đựng toàn bộ trái tim nghiệp vụ xây dựng (ví dụ: `EquipmentRepositoryPort`, `TakeoffService`, `BoqAuditService`).
   - **Độc lập tuyệt đối**: 0% phụ thuộc vào FastAPI, SQLAlchemy/PostgreSQL, ORM, mạng Internet hay bên thứ ba.
4. **Driven / Outbound Adapters (`infrastructure/`)**:
   - Concrete Repositories: `PostgresEquipmentRepository`, `PostgresTakeoffRepository`, quản lý connection và transaction an toàn.
   - External Adapters: `BrevoEmailAdapter`, `TelegramHttpAdapter`, `ZaloHttpAdapter` - đóng gói toàn bộ thư viện mạng (`httpx`, `aiohttp`).
   - AI Gateway: Tích hợp mô hình AI duy nhất qua `EnterpriseAiGateway` (Antigravity SDK native + auto-failover OpenRouter). CẤM hardcode endpoint LLM trong code nghiệp vụ.

### 3.2. Quy Tắc Routing & API Gateway Prefix
- **Bắt buộc tiền tố `/v1/erp`**: Mọi API Endpoints và UI Dashboards mới bắt buộc phải khai báo theo định dạng `@router.get("/v1/erp/...")`.
- **Lý do**: API Gateway (Nginx / Cloudflare Tunnel) cấu hình chuyển hướng theo prefix `/v1/erp`. Nếu gắn ở root level (`/dashboard`), hệ thống sẽ trả về 404 (Lỗi 'quên V1 vào end point').

### 3.3. Xử Lý Giao Dịch, Sổ Kép & Độ Chính Xác Số Học Tài Chính
- **Nguyên tắc Sổ Kép (Double-Entry Ledger)**:
  - Mọi biến động tài chính, dự toán công trình và kho vật tư bắt buộc lưu trữ dưới dạng Nhật ký biến động bất biến (Immutable Event Log).
  - Không sửa đè (no in-place overwrite) dữ liệu số dư; mọi điều chỉnh phải tạo bút toán đối ứng.
- **Khóa Giao Dịch**:
  - Áp dụng Optimistic Locking (dùng version column) hoặc Pessimistic Locking (`SELECT ... FOR UPDATE`) khi can thiệp vào hạn mức ngân sách dự toán hoặc xuất/nhập vật tư.
- **Độ Chính Xác Số Học Tuyệt Đối**:
  - **TUYỆT ĐỐI CẤM SỬ DỤNG `FLOAT` HOẶC `DOUBLE`** cho tiền tệ VNĐ và khối lượng BoQ bóc tách.
  - Cơ sở dữ liệu PostgreSQL: Bắt buộc dùng kiểu dữ liệu `NUMERIC(18, 4)` hoặc `BIGINT`.
  - Mã nguồn Python backend: Bắt buộc sử dụng thư viện `Decimal` từ module `decimal`.

### 3.4. Vòng Đời Máy Chủ & Dọn Dẹp Dữ Liệu Kiểm Thử (Strict Test Teardown)
- **Vòng đời Hot-Reload**: Uvicorn luôn chạy với lệnh:
  `python -m uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload`
- **Chính sách Test Teardown nghiêm ngặt**:
  - 100% test tự động (`pytest tests/`) chèn dữ liệu vào DB (users, takeoffs, chat, rules...) bắt buộc phải có cơ chế dọn dẹp sạch sẽ qua `finally`, `tearDown()`, hoặc `pytest fixture yield`.
  - Cấm để sót bản ghi mock/test (`TEST-%`, `API_CAD%`, `SAMPLE_CAD%`) trong cơ sở dữ liệu sau khi test kết thúc.

### 3.5. Backend Patterns & Best Practices
- **Repository & Service Layer Pattern**: Tách biệt rõ ràng tầng lưu trữ dữ liệu và tầng xử lý logic.
- **N+1 Query Prevention**: Luôn fetch dữ liệu theo lô (Batch fetch / eager loading / `IN (...)`), không lặp vòng query đơn lẻ.
- **Cache-Aside Pattern (Redis)**: Kiểm tra cache trước, nếu miss mới query DB và lưu cache có TTL (ví dụ 300s); chủ động invalidate khi update.
- **Xử lý lỗi tập trung (Centralized Error Handling)**: Chuẩn hóa phản hồi API lỗi (`{ success: false, error: message, details?: ... }`) với mã HTTP thích hợp (400, 401, 403, 404, 500).
- **Retry với Exponential Backoff**: Khi gọi dịch vụ mạng không ổn định, thử lại tối đa 3 lần với thời gian chờ cấp số nhân (1s, 2s, 4s).
- **Structured JSON Logging**: Ghi log có cấu trúc gồm `timestamp`, `level`, `message`, `requestId`, `method`, `path`.

### 3.6. Tiêu Chuẩn Viết Code Phổ Quát (Universal Coding Standards)
- **Readability First, KISS, DRY, YAGNI**: Đặt tên biến và hàm tường minh (Verb-Noun: `fetchMarketData`, `calculateSimilarity`).
- **Bất Biến (Immutability Pattern)**: Luôn dùng spread operator (`...`) hoặc object clone, không mutate trực tiếp state.
- **An Toàn Kiểu Dữ Liệu (Type Safety)**: Khai báo interface/type chặt chẽ; cấm dùng `any`.
- **Phát hiện Code Smell**: Cắt nhỏ các hàm > 50 dòng, hạn chế nesting sâu > 3 cấp bằng Early Returns (`if (!user) return;`), loại bỏ số ma thuật (Magic Numbers) bằng hằng số định danh.

---

## 4. AREA 3: QUY CHUẨN FRONTEND & TRẢI NGHIỆM NGƯỜI DÙNG (DARK SLATE ENTERPRISE UI)

Căn cứ: `.agents/skills/enterprise-ui-darkslate/SKILL.md`, `frontend-patterns/SKILL.md`.

### 4.1. Hệ Thống Thiết Kế Doanh Nghiệp (Dark Slate Theme)
- **Stylesheet chuẩn**: Bắt buộc import `/static/css/erp_enterprise.css`.
- **Thanh Điều Hướng Toàn Cục**: Dùng chung `<header class="erp-navbar">` chứa logo DSCons, menu phân hệ chức năng và tài khoản.
- **Bảng Màu Dark Slate**:
  - Nền chính (Main Background): `#0b0f19` / `#080d1a`.
  - Thẻ / Bảng điều khiển (Panel/Card): `#111827`.
  - Đường viền (Border): `#1e293b`.
- **Hệ Thống Typography Chuẩn**:
  - Phông chữ văn bản chung: Google Fonts `Inter` (hỗ trợ đầy đủ tiếng Việt có dấu) cho mọi nhãn, nút bấm và nội dung văn bản.
  - Phông chữ kỹ thuật / số liệu: `JetBrains Mono` dành riêng cho: Số tiền VNĐ, đơn giá ca máy, mã thiết bị, tọa độ hình học CAD, tỷ lệ phần trăm.
  - Thang kích cỡ chữ (Font Scale Hierarchy):
    - Tiêu đề trang (Page Titles): `15px - 17px` (font-weight: 700 bold).
    - Tiêu đề thẻ (Card/Panel Headers): `13px - 14px` (font-weight: 600).
    - Nội dung dữ liệu (Body/Cell Content): `12px - 13px`.
    - Nhãn phụ / Siêu dữ liệu (Meta/Badge/Label): `10.5px - 11.5px` (uppercase, letter-spacing tracking).

### 4.2. Mật Độ Thông Tin Cao (Bloomberg Density) & Chống Đè Sidebar (Zero Occlusion)
- **Chống đè Sidebar (Zero Occlusion)**:
  - Layout chính (`.erp-main-layout`) bao bọc toàn bộ nội dung với `margin-left: var(--sidebar-width)`.
  - Độ rộng sidebar chuẩn: `260px` khi mở rộng trên Desktop, `72px` khi thu gọn (collapsed).
  - Nghiêm cấm để Fixed Sidebar che khuất dữ liệu bên trái.
- **Mật độ thông tin cao (Bloomberg/Palantir Standard)**:
  - Loại bỏ các khoảng padding/margin khổng lồ (24px - 32px của các template web thông thường).
  - Padding & Gap chuẩn: `8px - 14px` cho Cards/Panels; `6px - 10px` cho các dòng dữ liệu bảng tính BoQ.
  - Bố cục chia cột thông minh (Multi-Column Split-View): Cột trái (Master List / Filters / CAD Canvas), Cột phải (Detail Panel / War Room / KPIs) thay vì cuộn dọc một trang dài vô tận.

### 4.3. Luồng Dữ Liệu Đơn Chiều & Bảo Vệ Tương Tác (Toast Anti-Flood & Locks)
- **Tách Biệt Render State và Action Creators**:
  - Các hàm chuyển đổi giao diện như `switchTab`, `switchBoqViewMode` là Pure State Renderers; cấm gọi ngược lại API Action Creators gây lặp vô tận (infinite recursion).
- **Khóa Chống Trùng Bất Đồng Bộ (Idempotent Action Locks)**:
  - Mọi nút bấm gửi dữ liệu phải có cờ kiểm soát `if (isSubmitting) return;` hoặc debounce/throttle để chống submit lặp.
- **Hàng Rào Chống Tràn Thông Báo (Toast Anti-Flood)**:
  - Tự động phát hiện và chặn thông báo trùng lặp đang hiển thị trên màn hình.
  - Giới hạn tối đa không quá 3 Toast thông báo xuất hiện cùng lúc.

### 4.4. Cơ Chế Cache Buster Bắt Buộc
- **Ảnh Bản Vẽ CAD**: Mọi lệnh gán nguồn ảnh `img.src` phải tự động đính kèm tham số thời gian thực: `?v=${Date.now()}` để tránh trình duyệt giữ cache ảnh cũ.
- **Tài Nguyên Tĩnh (JS/CSS Cốt Lõi)**:
  - Khi chỉnh sửa các file JavaScript hoặc CSS dùng chung (ví dụ `erp_mobile_dock.js`), BẮT BUỘC dùng PowerShell script để tìm và tăng (bump) phiên bản cache buster `?v=x.x.x` trên toàn bộ các file `.html` (ví dụ `?v=4.0.1`). Nếu thiếu, trình duyệt của người dùng sẽ không tải giao diện mới (gây lỗi 'chưa thấy menu').

### 4.5. Frontend Component & Performance Patterns
- **Component Composition & Compound Components**: Tách nhỏ `<Card>`, `<CardHeader>`, `<CardBody>`; sử dụng Context API cho `<Tabs>`, `<TabList>`, `<Tab>`.
- **Custom Hooks chuyên dụng**: `useToggle`, `useQuery`, `useDebounce` để quản lý logic tái sử dụng.
- **Ảo Hóa Danh Sách Dài (Virtualization)**: Sử dụng `@tanstack/react-virtual` khi render bảng tiên lượng BoQ hoặc danh sách hàng nghìn dòng.
- **Khả Năng Tiếp Cận (Accessibility & Keyboard Navigation)**: Hỗ trợ phím mũi tên, Enter, Escape, quản lý focus element khi mở/đóng modal dialog.

---

## 5. AREA 4: NGHIỆP VỤ XÂY DỰNG AEC, CAD TAKEOFF & ĐỊNH MỨC ĐỊNH SƠN

Căn cứ: `.agents/skills/aec-pricing-norms/SKILL.md`, `aec-cad-takeoff/SKILL.md`.

### 5.1. Bốn Trụ Cột Kinh Doanh Của Công Ty Định Sơn (MST: `0202111150`)
Hệ thống ERP DSCons quản lý tài chính dựa trên 4 phân hệ trụ cột kinh doanh độc lập:
1. **Trụ Cột 1: Thi công Xây lắp & Thủy lợi (Core Construction)**:
   - Các công trình trọng điểm: Kè Đa Độ, Cống Bến Kem & Chiếu sáng Kiến Minh, Rạng Đông, Bảo Long, Thiên Duyên, Bảo Lộc, Ngũ Phúc, Đại Đồng, Kiến Quốc, Kiến Hưng, Tân Trào...
2. **Trụ Cột 2: Dịch vụ Vận tải Xe Ben & Logistics Cơ Giới**:
   - Đối tác tiêu biểu: Công ty Thoát Nước Hải Phòng (MST `0200149705`) hợp đồng vận chuyển bùn đất.
   - **QUY TẮC CỐT LÕI**: Tuyệt đối **KHÔNG** gộp nghiệp vụ vận tải bùn đất này thành một Dự án Thi công Xây dựng.
3. **Trụ Cột 3: Cho thuê Máy móc & Ca máy Cơ giới**:
   - Đối tác tiêu biểu: Công ty Loan Khải (MST `0201889988`) hợp đồng cho thuê máy đào bánh xích.
   - **QUY TẮC CỐT LÕI**: Tuyệt đối **KHÔNG** gộp thành Dự án Thi công Xây dựng.
4. **Trụ Cột 4: Mua bán Vật tư & San lấp**:
   - Đối tác tiêu biểu: Công ty Trung Kiên (MST `0201805660`) là Nhà cung cấp Cát, Đá.
   - **QUY TẮC CỐT LÕI**: Tuyệt đối **KHÔNG** gộp thành Dự án Thi công Xây dựng.

### 5.2. Căn Cứ Pháp Lý & Định Mức Xây Dựng 2026
- **Khung Pháp Lý**: Luật Xây dựng 2025 (Luật số 135/2025/QH15 - có hiệu lực từ ngày 01/07/2026), các Nghị định số 206, 207, 210, 212/2026/NĐ-CP và Thông tư định mức giá ca máy 2026.
- **Quy Chuẩn Định Mức Cừ Larsen & Tôn Chống Lầy (Thông tư 38)**:
  - Công tác Thuê/Ép/Nhổ cừ Larsen IV hoặc thuê tôn chống lầy: **$100\%$ là Chi phí Nhân công ($NC$) và Chi phí Ca máy ($M$)**.
  - **TUYỆT ĐỐI KHÔNG sinh ra định mức mua mới vật liệu thô ($VL = 0\text{ VNĐ}$)** trong Bảng Nhu Cầu Vật Tư ($MR$).
- **Hàng Rào Kiểm Toán Tỷ Trọng Vật Tư (Sanity Check Gate)**:
  - Tổng chi phí vật tư ($MR$) **bắt buộc nằm trong dải an toàn $40\% - 65\%$ của Chi phí trực tiếp ($T$)**.
  - Nếu tỷ lệ $MR / T > 75\%$, hệ thống lập tức kích hoạt Cảnh báo Bất thường (Anomaly Alert) nhằm ngăn chặn việc nhân đôi định mức hoặc nhầm giá cừ thuê thành giá cừ mua mới.

### 5.3. Cấu Trúc 4 Cấp Độ Chi Phí Dự Toán Xây Dựng (4-Tier Budgeting Structure)
1. **Cấp 1 - Chi phí Trực tiếp ($T = VL + NC + M$)**:
   - Dùng cho lập Kế hoạch Nhu cầu Vật tư ($MR$), giao khoán tổ đội thợ và quản lý công trường.
   - Ví dụ chuẩn mẫu Nhà văn hóa Thôn Đại Thắng: $T = 1.283.665.229\text{ VNĐ}$.
2. **Cấp 2 - Dự toán Chi phí Xây dựng sau thuế ($G_{XD}$)**:
   - Dùng cho Chào thầu BoQ và Ký kết Hợp đồng thi công A-B.
   - Công thức: $G_{XD} = (T + GT + TL) \times (1 + \text{VAT})$.
   - Ví dụ mẫu NVH Đại Thắng: $G_{XD} = 1.622.032.453\text{ VNĐ} \approx 1,26359 \times T$.
   - Chi tiết cấu thành:
     - Chi phí Gián tiếp ($GT$): $C (7,3\%) + LT (1,1\%) + TT (2,5\%) = 10,9\% \times T = 139.919.510\text{ VNĐ}$.
     - Thu nhập chịu thuế tính trước ($TL$): $5,5\% \times (T + GT) = 78.297.161\text{ VNĐ}$.
     - Thuế GTGT ($VAT$): $8\% \times (T + GT + TL) = 120.150.565\text{ VNĐ}$.
3. **Cấp 3 - Dự toán Gói thầu Xây dựng ($G_{GTXD}$)**:
   - $G_{GTXD} = G_{XD} + GDP_{XD}$ (bao gồm chi phí dự phòng trượt giá gói thầu). Ví dụ NVH Đại Thắng: $1.875.559.000\text{ VNĐ}$.
4. **Cấp 4 - Tổng Mức Đầu Tư Toàn Bộ Dự Án ($G_{TMĐT}$)**:
   - $G_{TMĐT} = G_{XD} + G_{TB} + G_{QLDA} + G_{TV} + G_{K} + G_{DP} + G_{KT}$. Ví dụ NVH Đại Thắng: $2.380.885.000\text{ VNĐ}$.

### 5.4. Ma Trận Hệ Số Tổng Hợp Kinh Phí (THKP) Theo Từng Loại Hình Công Trình
Theo Thông tư 11/2021/TT-BXD, TT 14/2023/TT-BXD và Nghị định 206/2026/NĐ-CP:

| Loại Hình Công Trình | Chi phí Chung ($C$) | Nhà tạm ($LT$) | Không XĐ ($TT$) | Thu nhập chịu thuế ($TL$) | VAT | Hệ số Tổng hợp ($G_{XD} / T$) |
| :--- | :---: | :---: | :---: | :---: | :---: | :---: |
| **Dân dụng** (`civil_building` - NVH, Trường học, Trụ sở) | $7,3\% \times T$ | $1,1\%$ (Tuyến: $2,2\%$) | $2,5\% \times T$ | $5,5\% \times (T+GT)$ | $8,0\%$ | **$\approx 1,2636$** |
| **Nông nghiệp & PTNT / Thủy lợi** (`hydraulic_culvert`, `revetment`) | $5,5\% \times T$ | $2,2\%$ (Kè) / $1,1\%$ (Cống) | $2,0\% - 2,5\%$ | $5,5\% \times (T+GT)$ | $8,0\%$ | **$\approx 1,2419 - 1,2543$** |
| **Giao thông** (`transportation_road`, `bridge`) | $6,2\% \times T$ | $2,2\%$ (Theo tuyến) | $2,0\% \times T$ | $5,5\% \times (T+GT)$ | $8,0\%$ | **$\approx 1,2505$** |

### 5.5. Hàng Rào Chống Khống Giá & Kiểm Soát Đơn Vị Tính
- **Quy tắc Thép Cốt & Thép Tấn**: Đơn giá thép Sở Xây dựng công bố ($16,15\text{ tr} - 16,45\text{ 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** và bắt buộc khớp đúng đơn vị tính:
  - `tấn`: $16.450.000\text{ đ/tấn}$; `100kg`: $1.645.000\text{ đ/100kg}$; `kg`: $16.450\text{ đ/kg}$.
  - **CẤM TUYỆT ĐỐI áp giá thép tấn cho các ĐVT `m`, `m2`, `tấm`, `ca`, `chuyến`, `bộ`**.
- **Danh Mục Loại Trừ Khớp Giá Thép (Negative Keywords)**:
  - Loại trừ 100%: `cừ thép`, `thuê cừ`, `cừ larsen` (giá thuê $2.000\text{ đ/m/ngày}$ theo HĐ-2026), `thuê ván thép`, `ván chống lầy`, `ván khuôn thép`, `khung xương thép`, `bốc xếp thép`, `vận chuyển sắt thép`, `dây dẫn sét thép D10`, `dàn giáo thép`, `sơn sắt thép`.
- **Hồ Sơ Cống Hộp Kênh Ông Đèn Đến Nhà Bà Lanh (HĐ-2026 Thực Tế)**:
  - Giá trị Hợp đồng trọn gói (Phụ lục 01): $G_{HĐ} = \mathbf{6.482.295.000\text{ VNĐ}}$ ($6,482\text{ tỷ đồng}$).
  - Gồm 66 hạng mục xây lắp chính theo hồ sơ mời thầu e-GP.
  - CẤM dùng cache cũ 71 hạng mục (4,49 tỷ) vì chứa 5 hạng mục tự tạo trái quy định. Tuyệt đối cấm gán nhầm giá làm đội giá lên $4.753\text{ tỷ đồng}$.

### 5.6. Quy Chuẩn Xuất Thẳng Chân Công Trường (Direct-to-Site) & Hạch Toán BoQ
- **Cấm tạo Kho Ảo (TK 152)**: Vật tư giao thẳng công trường hạch toán trực tiếp vào chi phí sản xuất: `Nợ TK 621_Dự_án (hoặc TK 154) / Nợ TK 1331 / Có TK 331`.
- **Phân bổ BoQ-Driven tự động**: AI đối soát định mức BoQ của các dự án đang thi công để tự động gán mã dự án (`matched_project_id`), không ép công trường làm thủ tục hành chính thừa.
- **Tự động phân rã hóa đơn giao nhiều công trình**: Căn cứ hạn mức vật tư còn thiếu ($Remaining\_Quota$) để chia tỷ lệ chi phí vào từng tiểu khoản TK 621 tương ứng.

### 5.7. Động Cơ Bóc Tách Bản Vẽ CAD (AEC CAD Takeoff Engine)
- **Giải Mã Phông Chữ Tiếng Việt CAD (.VnTime / TCVN3 / VNI)**:
  - Bảng ánh xạ byte chuẩn xác triệt tiêu lỗi chính tả (ví dụ: `\xb5` = à, `\xb8` = á, `\xa8` = ă, `\xa9` = â, `\xaa` = ê, `\xae` = đ, `\xa7` = Đ...).
  - Kiểm tra ngữ nghĩa từ chuyên ngành xây dựng: *"ghi chú"* (không dùng *"ghi chó"*), *"sét/chống sét"* (không dùng *"sẹt"*), *"thép"* (không dùng *"thẹp"*), *"sàn"* (không dùng *"sán"*), *"đá"* (không dùng *"đà"*), *"bể phốt"* (không dùng *"bễ phốt"*).
  - Lọc bỏ mã AutoCAD: `%%u`, `%%U` (underline); chuyển `%%c` thành `Ø`, `%%d` thành `°`, `%%p` thành `±`.
- **Đồ Họa Vector CAD**:
  - `stroke-width: 1px !important;` kèm `vector-effect: non-scaling-stroke !important;`.
  - Cấm ép nét dày lên hatch/fill để tránh hiện tượng vón cục màu xanh (cyan blobs).
- **Bounding Box Không Gian Thực Tế & Zero-Void**:
  - Quét tọa độ Model Space thực tế chứa công trình (ví dụ $Y \in [440.000 .. 740.000]$), cắt bỏ chữ rác trôi nổi ở đỉnh ($Y \approx 0..50.000$), loại bỏ khoảng trống rỗng $>100\text{m}$.
  - Tách Bounding Box riêng biệt cho từng trang bản vẽ (Tổng mặt bằng, Mặt bằng kiến trúc, Chi tiết kết cấu, Điện nước...).
- **Phân Định Xây Mới vs Cải Tạo (New Build vs Renovation)**:
  - Khung tên/bìa chứa *"sửa chữa"*, *"cải tạo"*, *"hiện trạng"*, *"nâng cấp"*, *"phá dỡ"* $\rightarrow$ Kích hoạt `RENOVATION_ENGINE`.
  - Khung tên/bìa chứa *"xây mới"*, *"thi công mới"* $\rightarrow$ Kích hoạt `NEW_BUILD_ENGINE`.
  - *Quy tắc cải tạo*: CẤM tự ý sinh khối lượng đào móng, đúc mới dầm/sàn hàng loạt; bắt buộc áp dụng mã **Chương SA & AA** (đục tẩy `SA.11611`, `SA.11612`, cạo sơn `SA.11821`, phá dỡ gạch đá `AA.22221`, tháo dỡ cửa `AA.31312`, tháo dỡ mái tôn `AA.31221`) với $VL = 0\text{ VNĐ}$.
  - *Chính sách bóc tách nội bộ*: `run_takeoff_pipeline` chạy hoàn toàn bằng Rule-based Deterministic logic nội bộ, cấm gọi LLM ngoài để triệt tiêu Rate Limit HTTP 429.

---

## 6. AREA 5: QUY TRÌNH KIỂM THỬ, ĐÁNH GIÁ & QUẢN TRỊ TÁC VỤ (TESTING & WORKFLOW)

Căn cứ: `.agents/skills/tdd-workflow/SKILL.md`, `workflow-plan-task-test-report/SKILL.md`, `verification-loop/SKILL.md`, `eval-harness/SKILL.md`.

### 6.1. Quy Trình Test-Driven Development (TDD Workflow)
- **Nguyên Tắc Cốt Lõi**:
  1. *Tests BEFORE Code*: Viết test trước khi chạm vào mã nguồn nghiệp vụ.
  2. *Coverage Requirement*: Tối thiểu 80% coverage cho toàn bộ Unit, Integration và E2E tests. Bao phủ đầy đủ edge cases, lỗi phát sinh, ranh giới dữ liệu.
- **Vòng Lặp TDD 7 Bước**:
  1. *User Journey*: Mô tả luồng người dùng (`As a [role], I want to [action], so that [benefit]`).
  2. *Generate Test Cases*: Viết test cases chi tiết trước.
  3. *Run Tests (Must FAIL)*: Chạy test và xác nhận kết quả ban đầu là FAIL (negative baseline).
  4. *Implement Code*: Viết mã nguồn tối thiểu để test chuyển sang PASS.
  5. *Run Tests Again*: Xác nhận tests đã chuyển xanh (PASS).
  6. *Refactor*: Tối ưu hóa cấu trúc, khử duplicate, giữ test luôn xanh.
  7. *Verify Coverage*: Đo kiểm độ bao phủ đạt $\ge 80\%$.
- **Cấu Trúc AAA (Arrange - Act - Assert)**: Mọi unit test tuân thủ chuẩn AAA, chỉ kiểm tra hành vi quan sát được của người dùng, không kiểm tra chi tiết trạng thái nội bộ kín (implementation details).

### 6.2. Quy Trình Quản Trị Tác Vụ Lớn (Deep Matrix Plan - Task - Test - Report)
Bắt buộc áp dụng khi tái cấu trúc lớn (Mass Refactoring), phát triển tính năng phức tạp hoặc tác vụ can thiệp $> 10$ files:
- **PLAN (Phân rã Deep Matrix từ D1 đến D6 trong file `task.md`)**:
  - `[D1] Module / Epic`: Nhóm tính năng lớn (ví dụ: Module Bóc Tách Khối Lượng CAD Takeoff).
  - `[D2] Business Flow`: Luồng nghiệp vụ cốt lõi (ví dụ: Parse file DWG sang mô hình không gian).
  - `[D3] Domain Logic / Rules`: Quy tắc nghiệp vụ ngách (ví dụ: Giải mã TCVN3, Bounding Box).
  - `[D4] State & Data Transitions`: Trạng thái và chuyển dịch dữ liệu (ví dụ: DRAFT -> APPROVED).
  - `[D5] Cross-module Dependencies`: Giao tiếp Event Bus (ví dụ: TakeoffApproved -> Inventory Reserve).
  - `[D6] File-level Execution`: Xác định chính xác file bị can thiệp, hàm thêm mới, hàm xóa bỏ.
  - *Timestamp & Checkbox*: Mỗi task D1-D6 bắt buộc có checkbox `[ ]` và trạng thái `(Pending)`.
- **TASK (Thực thi từng phần - Incremental Execution)**:
  - Code từ tầng D6 ngược lên.
  - **CẤM TUYỆT ĐỐI SCAFFOLDING GIẢ**: Cấm tạo file rỗng hoặc chỉ để lại comment `// TODO: tự code tiếp`. Phải chuyển dịch toàn bộ logic thực sự.
  - Đánh dấu `[x]` và ghi nhận timestamp hoàn thành cụ thể.
- **TEST (Kiểm thử thực tế)**:
  - Tự động chạy `pytest` hoặc integration scripts; xác nhận Command Handler ghi được vào DB thật và Event Bus kích hoạt thành công. Đọc logs loại trừ `ImportError`.
- **REPORT (Báo cáo & Dừng chốt tiến độ)**:
  - Tóm tắt cho người dùng sau mỗi Wave/D1: Những lỗi logic cũ đã xử lý, luồng dữ liệu đang chạy (Data Flow), yêu cầu review `task.md`.

### 6.3. Hàng Rào Kiểm Tra Toàn Diện 6 Pha (6-Phase Verification Loop)
Kích hoạt trước mỗi commit, PR hoặc sau khi refactor lớn:
- **Phase 1: Build Verification**: Chạy lệnh build (`npm run build` / `pnpm build`). Nếu lỗi, DỪNG LẠI và sửa ngay.
- **Phase 2: Type Check**: Chạy `npx tsc --noEmit` (TypeScript) hoặc `pyright .` (Python). Báo cáo và sửa toàn bộ type errors.
- **Phase 3: Lint Check**: Chạy `npm run lint` hoặc `ruff check .`. Sửa sạch cảnh báo.
- **Phase 4: Test Suite**: Chạy test runner kèm coverage; xác nhận số lượng Passed/Failed và Coverage $\ge 80\%$.
- **Phase 5: Security Scan**: Rà soát lộ lọt API keys/secrets (`sk-`, `api_key`) và loại bỏ `console.log` thừa trong code production.
- **Phase 6: Diff Review**: Chạy `git diff --stat` và review từng file đã sửa, đảm bảo không có thay đổi ngoài ý muốn và không thiếu sót error handling.

### 6.4. Khung Đánh Giá Năng Lực & Kiểm Soát Hồi Quy (Eval Harness - EDD)
- **Triết lý Eval-Driven Development (EDD)**:
  - Coi Evals như Unit Tests của quá trình phát triển AI.
  - Định nghĩa hành vi mong đợi TRƯỚC KHI lập trình.
- **Hai Loại Eval Chủ Đạo**:
  - *Capability Evals*: Kiểm tra hệ thống thực hiện được năng lực mới chưa từng có trước đây.
  - *Regression Evals*: Đảm bảo sự thay đổi không làm gãy các tính năng cũ đã hoạt động ổn định.
- **Bộ Chấm Điểm (Grader Types)**:
  - *Code-Based Grader*: Kiểm tra tất định bằng mã (grep pattern, test runner, build status).
  - *Model-Based Grader*: Đánh giá định tính cấu trúc, xử lý lỗi theo thang điểm 1-5.
  - *Human Grader*: Cảnh báo rủi ro cao cần con người duyệt tay.
- **Chỉ Số Tin Cậy (Reliability Metrics)**:
  - `pass@k`: Ít nhất 1 lần thành công trong $k$ lần thử (mục tiêu `pass@3 > 90%` cho Capability).
  - `pass^k`: Toàn bộ $k$ lần thử liên tiếp đều thành công (`pass^3 = 100%` cho Regression trên các luồng trọng yếu).

---

## 7. MA TRẬN QUAN HỆ CHÉO & LUẬT BẤT BIẾN TOÀN DỰ ÁN (CROSS-CUTTING INVARIANTS)

Để tránh hiện tượng các quy tắc xung đột nhau khi tích hợp liên module, bảng ma trận sau đây hệ thống hóa các luật bất biến chéo giữa các tầng:

| Tầng Hệ Thống | Luật Bất Biến (Invariant Law) | Mối Liên Hệ Chéo Với Module Khác | Cách Thức Kiểm Tra Tự Động |
| :--- | :--- | :--- | :--- |
| **Dữ Liệu & Nguồn Sự Thật** | 100% dữ liệu từ Cổng Thuế GDT, Odoo dump và HĐ-2026. Cấm mock. | Ảnh hưởng tới toàn bộ DB, BoQ, Hóa đơn và Định mức. | `pytest tests/` từ chối các seed file chứa tên ảo hoặc MST không có thật. |
| **Kiến Trúc Lục Giác** | Presentation cấm SQL/DDL; Application cấm gọi HTTP client/LLM ngoài. | Giữ Domain thuần khiết, cô lập hạ tầng bên ngoài. | Chạy `pytest tests/test_architecture_boundary_enforcement.py` qua phân tích AST Python. |
| **API Routing** | Mọi API Endpoint mới bắt buộc mang prefix `/v1/erp`. | Đồng bộ tuyệt đối với API Gateway Nginx/Cloudflare Tunnel. | Bắt lỗi 404 khi test E2E hoặc kiểm tra route registry trong FastAPI. |
| **Độ Chính Xác Tài Chính** | Bắt buộc `NUMERIC(18,4)` trong PostgreSQL và `Decimal` trong Python. Cấm FLOAT. | Đảm bảo tính nhất quán giữa BoQ, Dự toán, Hóa đơn GTGT và Sổ kép. | Linter / Type checker và schema validation trong Pydantic/SQLAlchemy. |
| **Hạch Toán Xuất Thẳng** | Hạch toán thẳng TK 621/154 chân công trình. Cấm TK 152 kho ảo. | Phân bổ vật tư tự động theo định mức BoQ của các dự án đang thi công. | Kiểm tra ràng buộc tài khoản nợ/có trong module Kế toán Kho - BoQ. |
| **Định Mức Cừ Larsen** | Thuê/ép/nhổ cừ $VL=0$, 100% là $NC$ và $M$. $MR/T \in [40\%, 65\%]$. | Tích hợp giữa CAD Takeoff và Pricing Norms; cảnh báo nếu $MR/T > 75\%$. | Logic kiểm toán tự động trong `BoqAuditService` kích hoạt Anomaly Alert. |
| **Đơn Giá Thép Cốt** | Thép tấn $16,45\text{ tr/tấn}$ chỉ cho cốt thép bê tông. ĐVT đúng. | Loại trừ cừ thép, ván khuôn, bốc xếp, dây sét. | Negative keyword filter trong thuật toán ánh xạ giá vật tư. |
| **Giao Diện Dark Slate** | Bloomberg density, `Inter` cho text, `JetBrains Mono` cho số. | Zero Occlusion: layout có `margin-left: var(--sidebar-width)`. | Chụp ảnh kiểm thử qua `chrome-devtools-mcp` hoặc Playwright. |
| **Bản Vẽ CAD Vector** | Nét vẽ 1px non-scaling stroke, loại bỏ cyan blobs trên hatch. | Bounding Box cắt rác $>100\text{m}$, giải mã tiếng Việt TCVN3/VNI chuẩn. | Render kiểm thử file SVG/PNG của Model Space CAD. |
| **Quy Trình Triển Khai** | Deep Matrix D1-D6; Cấm scaffolding TODO giả; TDD $\ge 80\%$. | Đảm bảo mọi dòng code mới đều có kiểm thử hồi quy bảo vệ. | 6-Phase Verification Loop và checklist hoàn thành có timestamp. |

---

## 8. DANH MỤC FACTS CHUẨN HÓA SẴN SÀNG NẠP VÀO MEM0

Dưới đây là danh mục 25 facts cô đọng, súc tích, mang tính định hướng thiết kế và luật bất biến đã được chuẩn hóa để sẵn sàng nạp vào hệ thống bộ nhớ dài hạn Mem0 (qua `mem0_add`):

1. **[DSCons Root Rule]** Mọi dữ liệu hệ thống (hóa đơn, dự án, định mức, nhà cung cấp) bắt buộc 100% lấy từ nguồn sự thật: Cổng Thuế điện tử GDT, Odoo dump thực tế và hồ sơ dự toán HĐ-2026 của Công ty TNHH Xây Dựng Định Sơn (MST: 0202111150); tuyệt đối cấm dữ liệu mock ảo.
2. **[DSCons Architecture Rule]** Tuân thủ nghiêm ngặt Hexagonal Architecture: Tầng Presentation cấm viết SQL/DDL; Tầng Application cấm import HTTP clients cấp thấp hoặc gọi LLM bên ngoài; Tầng Domain độc lập 100% với Framework/DB/Mạng; Mọi thay đổi phải vượt qua pytest tests/test_architecture_boundary_enforcement.py.
3. **[DSCons Routing Rule]** Mọi API Endpoints và UI Dashboards mới bắt buộc phải có tiền tố /v1/erp (ví dụ: @router.get("/v1/erp/...")); cấm mount ở root level để tránh lỗi 404 do API Gateway chặn.
4. **[DSCons Financial Math]** Tuyệt đối cấm sử dụng FLOAT hoặc DOUBLE cho tiền tệ VNĐ và khối lượng BoQ; bắt buộc dùng NUMERIC(18,4) trong PostgreSQL và Decimal trong Python.
5. **[DSCons Ledger Rule]** Mọi biến động tài chính, dự toán và kho vật tư phải ghi theo cơ chế sổ kép bất biến (Double-entry ledger / Immutable event log) kèm khóa giao dịch Optimistic/Pessimistic locking.
6. **[DSCons Server Lifecycle]** Máy chủ FastAPI/Uvicorn luôn chạy với cờ --reload trên cổng 8000; phải kiểm tra hot-reload tiến trình trước khi nghiệm thu tính năng.
7. **[DSCons Test Teardown]** Toàn bộ test tự động chèn dữ liệu vào DB bắt buộc phải có cơ chế Teardown dọn dẹp sạch sẽ 100%; cấm để sót bản ghi mock/test (TEST-%, API_CAD%, SAMPLE_CAD%) sau khi test xong.
8. **[DSCons MCP Tooling]** Ưu tiên 100% công cụ MCP: lsp-mcp cho refactor/symbol/type; chrome-devtools-mcp cho kiểm thử E2E/chụp ảnh UI; markitdown cho bóc tách PDF/Excel; memory cho đồ thị tri thức dài hạn.
9. **[DSCons UI Theme]** Giao diện chuẩn Dark Slate doanh nghiệp với nền chính #0b0f19, Panel #111827, Viền #1e293b, import bắt buộc /static/css/erp_enterprise.css và dùng chung header .erp-navbar.
10. **[DSCons Typography]** Sử dụng Google Fonts Inter cho toàn bộ văn bản tiếng Việt; bắt buộc dùng JetBrains Mono cho toàn bộ số liệu tiền tệ VNĐ, đơn giá ca máy, mã vật tư và tọa độ CAD.
11. **[DSCons UI Density]** Thiết kế giao diện mật độ thông tin cao phong cách Bloomberg/Palantir: Gaps/Paddings 8-14px cho cards, 6-10px cho dòng bảng; Bố cục chia cột thông minh Multi-Column Split-View thay vì cuộn dài.
12. **[DSCons UI Layout]** Chống đè Sidebar (Zero Occlusion): .erp-main-layout bao bọc nội dung với margin-left: var(--sidebar-width) (260px desktop, 72px collapsed).
13. **[DSCons UI Interaction]** Luồng dữ liệu đơn chiều: switchTab/switchBoqViewMode là pure renderers không gọi ngược Action; áp dụng Idempotent locks (isSubmitting); Toast Anti-Flood tối đa 3 thông báo đồng thời và chặn trùng lặp.
14. **[DSCons Cache Buster]** Ảnh bản vẽ CAD gán img.src phải có ?v=${Date.now()}; Khi sửa đổi file JS/CSS lõi, bắt buộc dùng script PowerShell bump phiên bản ?v=x.x.x trên toàn bộ các file .html.
15. **[DSCons Business Pillar 1]** Trụ cột 1 là Thi công Xây lắp & Thủy lợi: Các dự án Kè Đa Độ, Cống Bến Kem, Chiếu sáng Kiến Minh, Rạng Đông, Bảo Long, Thiên Duyên, Bảo Lộc, Ngũ Phúc, Đại Đồng, Tân Trào.
16. **[DSCons Business Pillar 2-4]** Phân biệt nghiêm ngặt: Trụ cột 2 (Vận tải bùn Cty Thoát Nước Hải Phòng 0200149705), Trụ cột 3 (Cho thuê máy đào Cty Loan Khải 0201889988), Trụ cột 4 (Bán cát đá Cty Trung Kiên 0201805660); Tuyệt đối KHÔNG gộp các đối tác này thành Dự án Thi công Xây dựng.
17. **[DSCons Norms 2026]** Tuân thủ Luật Xây dựng 2025, Nghị định 206, 207, 210, 212/2026/NĐ-CP; Công tác thuê/ép/nhổ cừ Larsen hoặc tôn chống lầy (Thông tư 38) có 100% chi phí là Nhân công và Máy, tuyệt đối chi phí vật liệu VL = 0 VNĐ.
18. **[DSCons Budget Ratio]** Hàng rào kiểm toán tỷ trọng vật tư BoQ: 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; nếu tỷ lệ MR / T > 75% hệ thống phải kích hoạt Cảnh báo Bất thường (Anomaly Alert).
19. **[DSCons Pricing Matrix]** Hệ số tổng hợp kinh phí G_XD / T tra cứu theo loại công trình: Dân dụng ≈ 1,2636; Thủy lợi đê kè cống ≈ 1,2419 - 1,2543; Giao thông đường cầu ≈ 1,2505; Dự toán mẫu gốc NVH Thôn Đại Thắng có G_XD = 1.622.032.453 VNĐ.
20. **[DSCons Steel Price Guard]** Đơn giá thép Sở Xây dựng (16,15 - 16,45 tr/tấn) chỉ được áp dụng cho cốt thép chịu lực kết cấu bê tông; loại trừ 100% các từ khóa: cừ thép, thuê ván, ván khuôn, bốc xếp, dây sét, dàn giáo, sơn thép; Cấm áp giá thép tấn cho ĐVT m, m2, tấm, ca.
21. **[DSCons Project Ground Truth]** Hợp đồng thi công Cống Hộp Kênh Ông Đèn Đến Nhà Bà Lanh HĐ-2026 có giá trị trọn gói 6.482.295.000 VNĐ gồm 66 hạng mục e-GP; cấm dùng file cache 71 hạng mục cũ (4,49 tỷ) và cấm gán nhầm giá làm đội giá lên hàng nghìn tỷ.
22. **[DSCons Direct Accounting]** Vật tư xuất thẳng chân công trình hạch toán trực tiếp Nợ TK 621 (hoặc 154) / Nợ TK 1331 / Có TK 331, cấm dùng TK 152 tạo kho ảo; tự động phân bổ dự án theo định mức BoQ (BoQ-driven allocation).
23. **[DSCons CAD Takeoff Engine]** Giải mã chính xác phông chữ tiếng Việt TCVN3/VnTime/VNI theo bảng ánh xạ byte; nét vẽ vector CAD cố định stroke-width 1px non-scaling stroke; Bounding Box cắt bỏ Model Space rác >100m; run_takeoff_pipeline chạy nội bộ tất định, cấm gọi LLM ngoài.
24. **[DSCons Renovation Norms]** Nhận diện từ khóa cải tạo/sửa chữa kích hoạt RENOVATION_ENGINE: cấm sinh khối lượng đào móng, đúc mới dầm sàn hàng loạt; bắt buộc áp mã Chương SA và AA (đục tẩy SA.11611, cạo sơn SA.11821, phá dỡ AA.22221) với chi phí vật liệu VL = 0 VNĐ.
25. **[DSCons Workflow & QA]** Quy trình Deep Matrix D1-D6 phân rã chi tiết trong task.md có timestamp; cấm scaffolding TODO giả; TDD đạt độ bao phủ ≥ 80%; Quy trình 6 pha kiểm tra Build, Types, Lint, Tests, Security, Diff trước khi nghiệm thu.

---

## KẾT LUẬN
Báo cáo khảo sát trên cung cấp bức tranh toàn cảnh, toàn diện và tuyệt đối chuẩn xác về toàn bộ hệ sinh thái kỹ thuật của DSCons ERP. Mọi chuẩn mực đã được đối soát chéo với mã nguồn, test suite và các quy định pháp luật xây dựng 2026. Báo cáo này là cơ sở vững chắc để tiến hành dọn dẹp và nạp mới hệ thống bộ nhớ dài hạn Mem0.