# HANDOFF REPORT: DSCons ERP Core Knowledge Extraction & Standards Survey **Mã Agent**: `teamwork_preview_explorer_survey_2` **Đường dẫn làm việc**: `c:\Projects\DSCons\.agents\teamwork\teamwork_preview_explorer_survey_2` **Người nhận (Parent Agent)**: `2c75583f-c14a-419c-82d2-6487ff809fec` **Ngày báo cáo**: 2026-10-05T20:32:00Z --- ## 1. OBSERVATION Các quan sát trực tiếp từ 12 file tài liệu gốc và tệp điều phối dự án: 1. **Tài liệu Yêu cầu Gốc (`ORIGINAL_REQUEST.md`)**: - Dòng 61-95: Yêu cầu nhiệm vụ đợt 2026-10-05T20:25:13Z quy định rõ mục tiêu: Dọn dẹp các dữ liệu cũ liên quan đến DSCons trong Mem0 và trích xuất toàn diện tri thức từ 5 mảng tài liệu cốt lõi để nạp bộ nhớ dài hạn chuẩn xác cho DSCons ERP. 2. **Quy chuẩn Gốc (`.agents\AGENTS.md` & `GEMINI.md`)**: - `.agents\AGENTS.md` (Dòng 8 - 26): Liệt kê 7 Điều luật cốt lõi bất biến: (1) Cấm dữ liệu ảo / Zero-tolerance synthetic data; (2) Hàng rào kiểm thử hồi quy `pytest tests -v` 100% Passed; (3) Kiểm thử trình duyệt thực tế qua `chrome-devtools-mcp` hoặc Playwright; (4) Uvicorn chạy hot-reload `--reload`; (5) Chống hội chứng "Bus Factor" (tài liệu hóa & inline comments); (6) Tuân thủ DDD & Kiến trúc lục giác (Presentation cấm SQL/DDL, Application cấm HTTP client cấp thấp hoặc LLM API ngoài, AST test `pytest tests/test_architecture_boundary_enforcement.py` 100% Passed); (7) Bắt buộc dùng MCP servers (`lsp-mcp`, `chrome-devtools-mcp`, `markitdown`, `memory`, `StitchMCP`, `gemini-api_gemini-api-docs`). - `.agents\AGENTS.md` (Dòng 29 - 33): Điều phối 5 Sub-Agents chuyên trách: `Architect-DB`, `Dev-Backend`, `Dev-Frontend`, `Domain-AEC-Auditor`, `QA-SecOps`. 3. **Quy chuẩn Backend & Cơ sở dữ liệu (`backend-clean-architecture/SKILL.md`, `backend-patterns/SKILL.md`, `coding-standards/SKILL.md`)**: - `backend-clean-architecture/SKILL.md` (Dòng 8 - 25): 4 tầng kiến trúc nghiêm ngặt (Driving presentation, Application use cases, Domain core, Driven infrastructure). Tích hợp AI Gateway duy nhất qua `EnterpriseAiGateway`. - `backend-clean-architecture/SKILL.md` (Dòng 32 - 38): Sổ kép (Double-entry ledger), Optimistic/Pessimistic locking, tuyệt đối cấm FLOAT/DOUBLE cho VNĐ và BoQ, bắt buộc dùng `NUMERIC(18, 4)` / `BIGINT` trong PostgreSQL và `Decimal` trong Python. - `backend-clean-architecture/SKILL.md` (Dòng 43 - 46): Thu dọn dữ liệu kiểm thử (Strict Automated Test Teardown), cấm sót bản ghi mock/test (`TEST-%`, `API_CAD%`, `SAMPLE_CAD%`). - `backend-clean-architecture/SKILL.md` (Dòng 47 - 49): API Gateway prefix bắt buộc `/v1/erp` (tránh lỗi 404 do Nginx/Cloudflare Tunnel chặn). - `backend-patterns/SKILL.md` (Dòng 123 - 193): Tránh N+1 query, tối ưu hóa query (chọn cột cụ thể), Transaction pattern, Redis Cache-Aside, Exponential Backoff retry, Structured JSON logging. - `coding-standards/SKILL.md` (Dòng 12 - 35, 66 - 80): Nguyên lý Readability First, KISS, DRY, YAGNI; Bắt buộc Immutability pattern qua spread operator `...`; Cấm sử dụng kiểu `any`. 4. **Quy chuẩn Frontend & Giao diện Doanh nghiệp (`enterprise-ui-darkslate/SKILL.md`, `frontend-patterns/SKILL.md`)**: - `enterprise-ui-darkslate/SKILL.md` (Dòng 8 - 16): Bắt buộc import `/static/css/erp_enterprise.css`, dùng header `.erp-navbar`, bảng màu Dark Slate `#0b0f19` / `#080d1a`, panel `#111827`, viền `#1e293b`. - `enterprise-ui-darkslate/SKILL.md` (Dòng 11 - 15): Google Fonts `Inter` cho text, `JetBrains Mono` cho số liệu VNĐ, đơn giá ca máy, mã vật tư, tọa độ CAD. Phân cấp cỡ chữ 15-17px tiêu đề, 13-14px thẻ, 12-13px nội dung, 10.5-11.5px meta. - `enterprise-ui-darkslate/SKILL.md` (Dòng 17 - 23): Zero Occlusion (chống đè sidebar, margin-left 260px desktop, 72px collapsed); Mật độ thông tin cao Bloomberg (gap/padding 8-14px cards, 6-10px bảng tính); Bố cục Multi-Column Split-View. - `enterprise-ui-darkslate/SKILL.md` (Dòng 24 - 29): Luồng dữ liệu đơn chiều; switchTab/switchBoqViewMode là pure renderers; cờ `isSubmitting`; Toast Anti-Flood tối đa 3 toasts; Cache buster cho ảnh CAD `?v=${Date.now()}` và script bump phiên bản HTML `?v=x.x.x`. - `frontend-patterns/SKILL.md` (Dòng 12 - 89, 331 - 373): Component composition, Compound components, Hooks (`useToggle`, `useQuery`, `useDebounce`), Context + Reducer, Virtualization danh sách dài (`@tanstack/react-virtual`). 5. **Quy chuẩn Nghiệp vụ Xây dựng AEC & Định mức (`aec-pricing-norms/SKILL.md`, `aec-cad-takeoff/SKILL.md`)**: - `aec-pricing-norms/SKILL.md` (Dòng 8 - 13): 4 Trụ cột kinh doanh Định Sơn (MST `0202111150`): Trụ cột 1 (Xây lắp & Thủy lợi Kè Đa Độ, Cống Bến Kem...); 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 CẤM gộp Trụ cột 2, 3, 4 thành Dự án Thi công Xây dựng. - `aec-pricing-norms/SKILL.md` (Dòng 14 - 22): Pháp lý Luật XD 2025 (hiệu lực 01/07/2026), Nghị định 206, 207, 210, 212/2026/NĐ-CP; Cừ Larsen (Thông tư 38) có 100% chi phí là Nhân công ($NC$) và Ca máy ($M$), tuyệt đối $VL = 0\text{ VNĐ}$; Tỷ trọng vật tư $MR/T \in [40\%, 65\%]$, kích hoạt Anomaly Alert nếu $MR/T > 75\%$. - `aec-pricing-norms/SKILL.md` (Dòng 28 - 36): Cấu trúc 4 cấp độ dự toán: Cấp 1 Chi phí trực tiếp $T$; Cấp 2 Dự toán XD sau thuế $G_{XD} = (T+GT+TL) \times (1+\text{VAT})$; Cấp 3 Dự toán gói thầu $G_{GTXD}$; Cấp 4 Tổng mức đầu tư $G_{TMĐT}$. Hệ số THKP: Dân dụng $\approx 1,2636$, Thủy lợi $\approx 1,2419 - 1,2543$, Giao thông $\approx 1,2505$. Dự toán chuẩn mẫu NVH Đại Thắng $G_{XD} = 1.622.032.453\text{ VNĐ}$. - `aec-pricing-norms/SKILL.md` (Dòng 50 - 67): Kiểm soát đơn giá thép Sở XD ($16,15 - 16,45\text{ tr/tấn}$) chỉ áp dụng cho cốt thép bê tông, khớp đúng ĐVT; loại trừ 100% cừ thép, ván khuôn, bốc xếp, dây sét, dàn giáo. Hồ sơ Cống hộp Kênh Ông Đèn chuẩn trọn gói theo e-GP là $6.482.295.000\text{ VNĐ}$ (66 hạng mục); CẤM dùng cache 71 hạng mục (4,49 tỷ) và cấm gán nhầm giá lên $4.753\text{ tỷ}$. - `aec-pricing-norms/SKILL.md` (Dòng 68 - 72): Hạch toán xuất thẳng chân công trường Nợ TK 621 (hoặc 154) / Nợ TK 1331 / Có TK 331; CẤM TK 152 tạo kho ảo; tự động phân bổ theo định mức BoQ (BoQ-driven). - `aec-cad-takeoff/SKILL.md` (Dòng 8 - 26): Bảng ánh xạ byte chuẩn xác TCVN3/VnTime/VNI; kiểm tra ngữ nghĩa ngành XD (*"ghi chú"*, *"chống sét"*, *"thép"*, *"sàn"*, *"đá"*, *"bể phốt"*); lọc bỏ mã `%%u`, `%%c` ($\text{Ø}$), `%%d` ($^\circ$), `%%p` ($\pm$). - `aec-cad-takeoff/SKILL.md` (Dòng 27 - 41): Nét vẽ 1px non-scaling stroke, cấm ép nét dày lên hatch gây cyan blobs; Bounding Box loại bỏ Model Space rác $>100\text{m}$; Phân định Xây mới vs Cải tạo (từ khóa sửa chữa kích hoạt RENOVATION_ENGINE áp mã Chương SA, AA với $VL=0$); `run_takeoff_pipeline` chạy hoàn toàn bằng logic nội bộ, cấm gọi LLM ngoài. 6. **Quy chuẩn Kiểm thử, Đánh giá & Quản trị Tác vụ (`tdd-workflow/SKILL.md`, `workflow-plan-task-test-report/SKILL.md`, `verification-loop/SKILL.md`, `eval-harness/SKILL.md`)**: - `tdd-workflow/SKILL.md` (Dòng 20 - 28): Tests trước code; Coverage tối thiểu 80% cho Unit, Integration và E2E; Arrange-Act-Assert. - `workflow-plan-task-test-report/SKILL.md` (Dòng 12 - 40): Deep Matrix D1 đến D6 trong `task.md` (D1 Epic, D2 Flow, D3 Rules, D4 State/Data, D5 Dependencies/EventBus, D6 File execution); Checkbox và Timestamp bắt buộc; CẤM TUYỆT ĐỐI scaffolding TODO giả; Báo cáo sau mỗi wave. - `verification-loop/SKILL.md` (Dòng 18 - 87): Hàng rào 6 pha (Build, Type, Lint, Test, Security scan secrets & console.log, Diff review). - `eval-harness/SKILL.md` (Dòng 18 - 95): Eval-Driven Development (EDD); Capability evals và Regression evals; Code/Model/Human graders; Chỉ số `pass@k` và `pass^k`. --- ## 2. LOGIC CHAIN - **Bước 1 (Xác định mục tiêu tối hậu)**: Từ `ORIGINAL_REQUEST.md` (Mục 2026-10-05T20:25:13Z), toàn bộ quá trình tái cấu trúc Mem0 đòi hỏi loại bỏ tri thức cũ gây nhiễu và nạp mới các "facts" cô đọng, tuyệt đối chuẩn xác cho DSCons ERP. - **Bước 2 (Tổng hợp từ gốc rễ)**: Việc bắt đầu từ `.agents/AGENTS.md` và `GEMINI.md` xác lập 7 Điều luật tối cao, xác định rõ thẩm quyền Giám đốc Kỹ thuật và nguyên tắc Zero-Synthetic-Data (MST: `0202111150`). - **Bước 3 (Khoanh vùng ranh giới kỹ thuật)**: `backend-clean-architecture` phối hợp với `backend-patterns` và `coding-standards` xác lập mô hình 4 tầng lục giác, trong đó hàng rào AST `test_architecture_boundary_enforcement.py` bảo đảm tính thi hành của các lệnh cấm (cấm SQL trong presentation, cấm HTTP client trong application/domain). Tiếp đó, quy tắc số học `NUMERIC(18,4)` và tiền tố route `/v1/erp` loại bỏ các lỗi runtime chết người (sai số tiền tệ, lỗi 404 gateway). - **Bước 4 (Chuẩn hóa trải nghiệm)**: `enterprise-ui-darkslate` và `frontend-patterns` thiết lập chuẩn Bloomberg/Palantir: màu Dark Slate, font Inter + JetBrains Mono, chống đè sidebar (Zero Occlusion) và cơ chế Toast Anti-Flood cùng Cache Buster. - **Bước 5 (Đóng gói tri thức nghiệp vụ cốt lõi)**: `aec-pricing-norms` và `aec-cad-takeoff` chứa các tri thức đặc thù không thể tìm thấy trong tài liệu phổ thông: 4 Trụ cột Định Sơn, cừ Larsen $VL=0$, tỷ trọng vật tư $MR/T \in [40\%, 65\%]$, đơn giá thép cốt, hạch toán xuất thẳng TK 621/154, giải mã byte TCVN3/VnTime, Bounding Box $>100\text{m}$, và mã định mức cải tạo Chương SA/AA. - **Bước 6 (Thiết lập quy trình kiểm soát chất lượng)**: `tdd-workflow`, `workflow-plan-task-test-report`, `verification-loop`, và `eval-harness` tạo thành pháo đài 4 lớp: TDD $\ge 80\%$, Deep Matrix D1-D6 chống scaffolding rỗng, 6-Phase Verification Loop và EDD metrics. - **Bước 7 (Chưng cất thành danh mục Facts)**: Toàn bộ các nguyên tắc trên được chưng cất thành 25 facts độc lập, súc tích, có định danh danh mục rõ ràng, sẵn sàng để agent tiếp theo nạp trực tiếp vào Mem0 qua `mem0_add`. --- ## 3. CAVEATS 1. **Phạm vi thẩm quyền**: Sub-agent thực hiện khảo sát ở chế độ **Read-Only Investigation**. Không có bất kỳ file mã nguồn dự án nào bị chỉnh sửa trong phiên làm việc này. Toàn bộ tài liệu sinh ra nằm trong thư mục được phân quyền: `.agents/teamwork/teamwork_preview_explorer_survey_2/`. 2. **Các file tham chiếu ngoài lề**: Tài liệu `docs/boq-driven-material-allocation-and-direct-site-accounting-guide.md` được trích dẫn trong `aec-pricing-norms/SKILL.md` như một tài liệu bổ trợ chuyên sâu; các quy tắc cốt lõi về TK 621 và phân bổ BoQ đã được trích xuất đầy đủ vào báo cáo. 3. **Môi trường cơ sở dữ liệu Mem0**: Việc dọn dẹp (selective cleanup) và gọi lệnh nạp (`mem0_add`) thuộc về nhiệm vụ của các sub-agent tiếp theo hoặc orchestrator theo kế hoạch phân rã của parent agent. Báo cáo này chuẩn bị sẵn sàng dữ liệu đầu vào chuẩn hóa (Fact Catalog). --- ## 4. CONCLUSION Tất cả 12 tài liệu thuộc 5 phân hệ tri thức cốt lõi của DSCons ERP đã được nghiên cứu, đối soát và trích xuất hoàn chỉnh vào file báo cáo chi tiết: `c:\Projects\DSCons\.agents\teamwork\teamwork_preview_explorer_survey_2\analysis.md`. Các phát hiện và hệ thống tri thức đã được đóng gói thành: - **Ma trận tổng hợp 5 khu vực** (Root Standards, Backend/DB, Frontend, AEC Business Domain, Testing/Workflow). - **Bảng ma trận quan hệ chéo và luật bất biến toàn dự án (Cross-Cutting Invariants)**. - **Danh mục 25 facts nguyên tử (Fact Catalog)** đã được tiền xử lý và chuẩn hóa cấu trúc để nạp vào Mem0. --- ## 5. VERIFICATION METHOD Để độc lập kiểm chứng các kết luận trong báo cáo này: 1. **Kiểm tra báo cáo chi tiết**: - Xem file: `c:\Projects\DSCons\.agents\teamwork\teamwork_preview_explorer_survey_2\analysis.md` - Đọc đối chiếu các dòng trích dẫn trực tiếp trong phần Observation của báo cáo này với các file gốc. 2. **Kiểm chứng tính tuân thủ quy chuẩn dự án bằng lệnh CLI**: - Chạy lệnh kiểm tra ranh giới kiến trúc lục giác: ```powershell pytest tests/test_architecture_boundary_enforcement.py -v ``` - Chạy toàn bộ test suite dự án: ```powershell pytest tests -v ``` - Kiểm tra trạng thái dịch vụ Mem0: ```powershell powershell -ExecutionPolicy Bypass -File C:\Users\Admin\.gemini\config\scripts\mem0_ctl.ps1 status ``` 3. **Điều kiện hủy bỏ (Invalidation Conditions)**: - Nếu phát hiện bất kỳ quy chuẩn nào trong 12 file trên mâu thuẫn với 25 facts đã trích xuất, hoặc phát hiện dữ liệu mock/ảo được chấp nhận trong codebase, kết luận của báo cáo sẽ cần được hiệu chỉnh lại.