# DSCons ERP - HỆ THỐNG QUẢN TRỊ DOANH NGHIỆP XÂY DỰNG & CÔNG TRÌNH

**DSCons ERP** là hệ thống quản trị doanh nghiệp chuyên biệt cho **Ngành Xây dựng & Kỹ thuật Công trình (AEC)**, phục vụ công tác điều hành, bóc tách khối lượng (BOQ/WBS), quản lý hồ sơ chất lượng, kiểm soát chi phí (EVM), điều phối nhân lực & ca máy cơ giới và đối soát hóa đơn thuế điện tử.

---

## 🏛️ 4 Trụ Cột Kinh Doanh Cốt Lõi (Công ty TNHH Xây Dựng Định Sơn - MST: `0202111150`)

1. **Trụ Cột 1: Thi công Xây lắp & Thủy lợi**
   * Các dự án tiêu biểu: Đa Độ 2026, Kênh Xây, 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**
   * Hợp đồng vận chuyển bùn đất, phế thải công trình (tiêu biểu: Cty Thoát Nước Hải Phòng `0200149705`).
3. **Trụ Cột 3: Cho thuê Máy móc & Ca máy Cơ giới**
   * Hợp đồng cho thuê máy đào bánh xích, máy lu, máy ủi (tiêu biểu: Cty Loan Khải `0201889988`).
4. **Trụ Cột 4: Mua bán Vật tư & San lấp Mặt bằng**
   * Hợp đồng mua bán cát vàng bê tông (710k/m3), cát xây trát (510k/m3), cát đen san nền (215k/m3), đá cấp phối (tiêu biểu: Cty Trung Kiên `0201805660`).

---

## 📁 Bản Đồ Cấu Trúc Thư Mục Dự Án (Repository Map)

```
DSCons/
├── .agents/                  # Hệ thống Quy tắc (Rules) & Kỹ năng (Skills) của AI Sub-Agents
│   ├── rules/                # Quy chuẩn Git workflow, Điều phối Đa Agent, Verification Gates
│   └── skills/               # 11 bộ kỹ năng (TDD, Backend, Frontend, ClickHouse, Security...)
├── app/                      # Mã nguồn Backend ứng dụng chính (FastAPI + Python 3.11)
│   ├── api/                  # Tầng RESTful API routes & Controllers
│   ├── core/                 # Cấu hình hệ thống, Bảo mật, Database connection pools
│   ├── models/               # Pydantic Schemas & ORM Data Models (Decimal precision)
│   ├── routers/              # Bộ định tuyến giao diện Web UI & API Endpoints
│   ├── services/             # Domain & Business Logic (WBS, BOQ, EVM, IPC, OCR, RAG)
│   └── static/               # Enterprise Dark Slate Stylesheet & JavaScript Modules
├── db/                       # Cơ sở dữ liệu PostgreSQL (Migrations, DDL schemas, Triggers)
├── docs/                     # Kho tài liệu kỹ thuật, cẩm nang nghiệp vụ và hồ sơ dự án
│   └── README.md             # Mục lục tra cứu tài liệu tổng hợp
├── HĐ-2026/                  # 16 Thư mục hồ sơ dự toán, hợp đồng thi công thực tế năm 2026
├── KNOWLEDGE_BASE/           # Kho văn bản pháp luật xây dựng 2026 (Luật 2025, TT 38, NĐ 206-212)
├── Price_Ref/                # Biểu giá vật tư & định mức giá cát Hải Phòng (TB 478, TB 558)
├── reports/                  # Báo cáo kiểm toán hệ thống, kết quả kiểm tra sức khỏe dịch vụ
├── storage/                  # Lưu trữ an toàn (Secure Vault, CAD files, Backups, Screenshots)
├── scripts/                  # Kịch bản kiểm tra sức khỏe, chẩn đoán và tự phục hồi hệ thống
├── tests/                    # Bộ kiểm thử tự động toàn diện (237+ Unit, Integration & E2E Tests)
└── tools/                    # Bộ công cụ bóc tách CAD (LibreDWG, DXF/DWG parser, Ingest data)
```

---

## 🚀 Hướng Dẫn Cài Đặt & Khởi Chạy

### 1. Yêu Cầu Môi Trường
* **Hệ điều hành**: Windows 11 / Windows Server / macOS (hỗ trợ điều khiển qua Tailscale / SSH).
* **Python**: Phiên bản `3.11+` với môi trường ảo `.venv`.
* **Cơ sở dữ liệu**: PostgreSQL 16+ và Vector DB Qdrant (cổng `6333`).

### 2. Khởi Chạy Máy Chủ Backend (Uvicorn Live Auto-Reload)
```powershell
# Khởi chạy dịch vụ backend với chế độ tự động tải nóng mã nguồn
python run_server.py
# Hoặc chạy lệnh trực tiếp:
.venv\Scripts\python.exe -m uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload
```

Giao diện Web ERP sẽ khả dụng tại: `http://127.0.0.1:8000`  
Tài liệu tương tác API Swagger: `http://127.0.0.1:8000/docs`

### 3. Chạy Toàn Bộ Bộ Kiểm Thử Tự Động (Automated Regression Gate)
```powershell
.venv\Scripts\python.exe -m pytest tests -v
```
*Tiêu chuẩn nghiệm thu:* 100% Passed (Không có bất kỳ test nào thất bại).

---

## 🛡️ Tiêu Chuẩn Kỹ Thuật Bắt Buộc
1. **Độ chính xác tài chính**: Tuyệt đối không dùng `float` cho tiền tệ VNĐ và khối lượng BoQ, bắt buộc dùng `Decimal` / `NUMERIC(18, 4)`.
2. **Giao diện Enterprise Dark Slate**: Sử dụng stylesheet chuẩn `/static/css/erp_enterprise.css`, mật độ thông tin cao, Zero-Occlusion (menu không đè nội dung).
3. **Dữ liệu thực tế 100%**: Tuyệt đối cấm tự sinh dữ liệu ảo (Zero-Tolerance Synthetic Data), chỉ sử dụng dữ liệu thực tế từ Tổng Cục Thuế (GDT), Odoo và hồ sơ Công ty Định Sơn.