# DSCons System Architecture Master (Single Source of Truth)

> **Trạng thái**: Active (Production-Ready 2026)  
> **Tiêu chuẩn Kiến trúc**: Domain-Driven Design (DDD) & Clean Architecture / Modular Monolith  
> **Hệ quy chiếu Pháp lý**: Luật Xây dựng 2025 (Luật số 135/2025/QH15 - hiệu lực 01/07/2026), Nghị định 123/2020/NĐ-CP, Nghị định 206, 207, 210, 212/2026/NĐ-CP  
> **Doanh nghiệp Chủ quản**: Công ty TNHH Xây Dựng Định Sơn (Mã số thuế: **`0202111150`**)  
> **Bộ Kiểm thử Tự động**: 100% Passed Automated Test Gate (`pytest tests -v`)

---

## 1. TỔNG QUAN HỆ THỐNG (SYSTEM OVERVIEW)

**DSCons Enterprise** là nền tảng **Hệ thống Trợ lý AI & Digital Twin Điều hành Doanh nghiệp Xây dựng Toàn diện (Autonomous Construction Enterprise)**. Hệ thống kết nối liền mạch giữa dữ liệu hiện trường (công trường, kho vật tư, ca máy, nhật ký thi công) với lớp quản trị văn phòng (hợp đồng FIDIC, hóa đơn điện tử, thanh toán IPC, kiểm soát chi phí EVM) thông qua mạng lưới Multi-Agent chuyên trách.

```mermaid
flowchart TB
    subgraph UI_Layer["Tầng Trình Diễn & Điều Hành (Enterprise UI / Dark Slate #0b0f19)"]
        D1["Dashboard Điều Hành Tổng Thể (/)"]
        D2["Bóc Tách Bản Vẽ & Dự Toán BoQ (/dashboard/drawing-takeoff)"]
        D3["Dự Án & Tiến Độ WBS (/dashboard/projects)"]
        D4["Hóa Đơn & Thuế GDT (/dashboard/invoices)"]
        D5["Đối Soát Giá Vật Tư 2026 (/dashboard/material-prices)"]
        D6["Hồ Sơ Chất Lượng & ERP (/dashboard/documents)"]
        D7["Sẵn Sàng Nghiệm Thu (/dashboard/readiness)"]
        D8["Nhân Lực & Ca Máy (/dashboard/employees)"]
        D9["Đối Tác & Khách Hàng (/dashboard/partners)"]
        D10["Quản Trị Người Dùng & RBAC (/dashboard/users)"]
    end

    subgraph API_Gateway["Tầng API Gateway & FastAPI Modular Routers"]
        R_Auth["/v1/auth (RBAC, JWT, OAuth2)"]
        R_Takeoff["/v1/takeoff (Dual PDF/CAD, BoQ 03a Excel, SSE Streaming)"]
        R_Invoices["/v1/invoices (XML NĐ123, MISA, GDT sync)"]
        R_Pillars["/v1/four-pillars (4 Trụ Cột Kinh Doanh Định Sơn)"]
        R_Prices["/v1/material-prices (Đối soát giá công bố Sở Xây Dựng 2026)"]
        R_Proj["/v1/projects (CRUD, AI WBS, Milestones, CPM)"]
        R_EVM["/v1/bim/evm & /v1/ai/site-diary"]
        R_Dossier["/v1/dossiers & /v1/workflows"]
        R_Ops["/v1/operations & /v1/company/operational-state (SSE)"]
        R_Agents["/v1/autonomous & /v1/knowledge"]
    end

    subgraph Shared_Utilities["Tầng Tiện Ích Dùng Chung (app/common/)"]
        U_Fin["financial.py (Decimal 18,4, VND format, Words to text)"]
        U_SSE["sse.py (Standardized SSE Event Serializer)"]
        U_XLS["excel_styler.py (Enterprise OpenPyXL Styling Palette)"]
    end

    subgraph Domain_Services["Tầng Nghiệp Vụ Chuyên Sâu (Domain Modular Packages)"]
        S_Takeoff["app/services/takeoff/ (CAD Converter, Gemini 3.1 Pro Vision, Excel 03a, AI Quỳnh Memory)"]
        S_Invoices["app/services/invoices/ (XML Parser, Tax Auditor, Pillar Classifier)"]
        S_Proj["ProjectManagementService & AIWBSGenerator"]
        S_EVM["EVMCalculationService (BAC, PV, EV, AC, CPI, SPI)"]
        S_Dossier["DossierReviewService & RemediationPlanning"]
        S_Ops["CompanyOperationalStateService & OperationsCase"]
        S_Auth["AuthService & RoleAccessControl (5 Roles)"]
        S_Orch["AgentOrchestrator (9 AI Personas Registry)"]
    end

    subgraph Storage_Layer["Tầng Lưu Trữ & Tri Thức (Persistence & Knowledge)"]
        PG[("PostgreSQL 16 (Double-Entry Ledger, Audit Logs, erp_client Mixins)")]
        QDR[("Qdrant Vector DB (Dense 1024-dim BAAI/bge-m3 / HĐ-2026)")]
        LLM["Hybrid LLM Stack (Gemini 3.1 Pro High Reasoning / OpenRouter / DeepSeek)"]
    end

    UI_Layer --> API_Gateway
    API_Gateway --> Domain_Services
    Domain_Services --> Shared_Utilities
    Domain_Services --> PG
    Domain_Services --> QDR
    Domain_Services --> LLM
```

---

## 2. 4 TRỤ CỘT KINH DOANH CỦA ĐỊNH SƠN (MST: 0202111150)

Toàn bộ hệ thống kế toán, hóa đơn và dự án tuân thủ nghiêm ngặt nguyên tắc **Zero Synthetic Data** và phân định 4 Trụ Cột:
1. **Trụ Cột 1: Thi công Xây lắp & Thủy lợi**: Dự án Kênh Ống Đen Kiến Minh, Nhà văn hóa Đại Thắng, Cống Bến Kem, Sông Đa Độ, Rạng Đông, Bảo Long...
2. **Trụ Cột 2: Dịch vụ Vận tải Xe Ben & Logistics Cơ Giới**: Vận chuyển bùn đất cấp I cho Cty Thoát Nước Hải Phòng (`0200149705`) — *Tuyệt đối không gộp vào dự án xây lắp*.
3. **Trụ Cột 3: Cho thuê Máy móc & Ca máy Cơ giới**: Cho thuê máy đào bánh xích, máy bơm bê tông cho Cty Loan Khải (`0201889988`) — *Tuyệt đối không gộp vào dự án xây lắp*.
4. **Trụ Cột 4: Mua bán Vật tư & San lấp**: Cung cấp cát đen san lấp, đá 1x2 từ Cty Trung Kiên (`0201805660`), Vicem, Thép Hòa Phát...

---

## 3. CƠ SỞ DỮ LIỆU POSTGRESQL & SCHEMAS

### 3.1. Phân Hệ Bóc Tách Bản Vẽ & Dự Toán BoQ (`db/migrations/0017` & `0018`)
- **`erp_drawing_takeoffs`**: Hồ sơ bóc tách bản vẽ kỹ thuật (`drawing_code`, `drawing_title`, `file_path`, `file_type`, `scale_ratio`, `drawing_type`, `takeoff_status`, `total_estimated_cost_vnd`, `total_concrete_volume_m3`, `total_rebar_weight_tons`, `total_formwork_area_m2`, `total_earthwork_volume_m3`).
- **`erp_drawing_takeoff_items`**: Danh mục chi tiết các đầu việc BoQ (`takeoff_id`, `item_order`, `wbs_code`, `norm_code`, `item_name`, `category`, `dimension_formula`, `unit`, `quantity`, `unit_price_vnd`, `total_amount_vnd`, `confidence_score`, `bounding_box_json`).
- **`erp_ai_takeoff_chat_messages`**: Lịch sử hội thoại studio huấn luyện tương tác với AI Quỳnh QS (`takeoff_id`, `sender_role`, `sender_name`, `message_text`, `suggested_corrections`, `extracted_rules`, `applied`).
- **`erp_ai_takeoff_learned_rules`**: Kho tri thức quy tắc rút kinh nghiệm vĩnh viễn (`drawing_type`, `category`, `error_pattern`, `correction_rule`, `learned_from_user`, `is_active`, `apply_count`, `confidence_weight`).

### 3.2. Phân Hệ Giá Vật Tư Công Bố (`db/migrations/0015`)
- **`erp_state_published_prices`**: Đơn giá vật liệu, nhân công, ca máy công bố của Sở Xây dựng TP. Hải Phòng (`province`, `period`, `material_code`, `material_name`, `unit`, `price_before_vat`, `supplier_name`).
- **`erp_material_price_comparisons`**: Bảng so sánh chênh lệch giữa giá mua thực tế của Định Sơn với giá công bố nhà nước.

### 3.3. Phân Hệ Tự Động Hóa Nhân Sự AI (`db/migrations/0016`)
- **`erp_autonomous_agent_sessions`**: Phiên chạy tự động của 9 AI Personas (`agent_code`, `task_name`, `status`, `logs`, `cost_vnd`).

---

## 4. TẦNG TIỆN ÍCH DÙNG CHUNG (SHARED UTILITIES)

1. **`app/common/financial.py`**:
   - Số học tiền tệ chính xác cao `Decimal(18, 4)` theo chuẩn kế toán Việt Nam.
   - Hàm `format_vnd(val)`: Định dạng tiền tệ có dấu phân cách hàng nghìn (`123.456.789 ₫`).
   - Hàm `number_to_vietnamese_words(val)`: Chuyển đổi số tiền thành chữ tiếng Việt chuẩn biên bản tài chính và phụ lục hợp đồng.
2. **`app/common/sse.py`**:
   - Quản lý Server-Sent Events (SSE) streaming đa persona.
   - Hàm `serialize_sse_payload`: Serialization an toàn cho các kiểu `Decimal`, `datetime`, `date`.
   - Hàm `format_sse_event(event, data)`: Format event chunk chuẩn SSE (`event: ...\ndata: ...\n\n`).
3. **`app/common/excel_styler.py`**:
   - Bảng màu chuẩn doanh nghiệp: Header Navy `#0F172A`, Viền slate `#94A3B8`, Highlight `#0D9488`.
   - Định dạng số tiền `#,##0" ₫"` và khối lượng `#,##0.00`.

---

## 5. BẢNG MÃ HÓA 9 NHÂN SỰ AI (MULTI-AGENT WORKFORCE)

| AI Persona | Vai Trò Chuyên Trách | Phân Hệ Phụ Trách | Mô Hình Mặc Định |
| :--- | :--- | :--- | :--- |
| **Quỳnh** | Kỹ sư Trưởng QS & Dự toán BoQ | Bóc Tách Bản Vẽ & BoQ Hub | `gemini-3.1-pro` / `stealth/ox-alpha` |
| **Hùng** | Chỉ huy trưởng Hiện trường & Bản vẽ | Nhật Ký Thi Công & Hiện Trường | `gemini-3.1-pro` |
| **Thủy** | Trợ lý Ban Giám Đốc & Kế toán | Bảng Điều Hành & Hóa Đơn | `stealth/ox-alpha` |
| **Minh** | Giám đốc Kỹ thuật & Chuẩn Định Mức | Pháp chế & Định Mức 2026 | `stealth/ox-alpha` |
| **Tùng** | Kiểm toán Nội bộ & Thẩm tra | Hồ Sơ Nghiệm Thu & Kiểm Toán | `deepseek-r1` |
| **Thảo** | Pháp chế & Hợp đồng FIDIC | Hợp đồng & Thanh Toán IPC | `stealth/ox-alpha` |
| **Nam** | Kế toán Trưởng & Quản trị Dòng tiền | Dòng Tiền & Công Nợ | `stealth/ox-alpha` |
| **Lan** | Chăm sóc Khách hàng & Đối tác | Quản Lý Đối Tác & Nhà Cung Cấp | `stealth/ox-alpha` |
| **Phúc** | Kỹ sư Điều độ & Tiến độ CPM | Dự Án & Tiến Độ WBS/Gantt | `stealth/ox-alpha` |