# DSCons Workflow & Data-Flow Master Guide > **Mục tiêu**: Định nghĩa toàn bộ chu trình xử lý dữ liệu và luồng nghiệp vụ của hệ thống **DSCons**. Đảm bảo mọi AI Agent và kỹ sư phát triển đều hiểu đúng: Dữ liệu bắt nguồn từ đâu, qua các tầng nghiệp vụ nào, lưu vào đâu và phục vụ màn hình/API nào. --- ## 1. TOÀN CẢNH LUỒNG DỮ LIỆU (DATA FLOW OVERVIEW) DSCons vận hành xoay quanh **8 luồng dữ liệu chính** kết nối chặt chẽ giữa hiện trường và văn phòng quản lý: | Luồng | Đầu vào (Inputs) | Xử lý Nghiệp vụ Chính | Nơi Lưu Trữ | Nơi Tiêu Thụ (Consumers) | | :--- | :--- | :--- | :--- | :--- | | **1. Hồ Sơ Công Trình & Pháp Lý** | PDF, DOCX, bản vẽ CAD, thư mục `HĐ-2026/` | Trích xuất text, chia chunk phân cấp, gắn metadata dự án | Qdrant (1024-dim) | Coverage, Readiness, Semantic Search, RAG | | **2. Hóa Đơn Điện Tử & Kế Toán** | File XML chuẩn NĐ 123/2020 & MISA meInvoice | Bóc tách XML, SHA-256 deduplication, tính thuế suất, hạch toán `Decimal(18,4)` | PostgreSQL 16 (`invoices`, `invoice_items`) | `/dashboard/invoices`, `/v1/invoices/*`, EVM AC (Actual Cost) | | **3. Dự Án, WBS & Chi Phí EVM** | Hợp đồng dự án, bảng dự toán BOQ, mốc nghiệm thu | CRUD dự án, AI WBS Generator, tính toán EVM (BAC, PV, EV, AC, CPI, SPI) | PostgreSQL 16 (`projects`, `project_milestones`) | `/dashboard/projects`, `/v1/projects/*`, `/v1/bim/evm/*` | | **4. Hồ Sơ Chất Lượng & ERP** | Biên bản nghiệm thu, chứng chỉ vật liệu, phiếu thí nghiệm | Upload file, AI Pre-Audit bóc tách thực thể và phân loại hồ sơ | PostgreSQL 16 (`erp_documents`) | `/dashboard/documents`, `/v1/erp/documents/*` | | **5. Dossier Review & Remediation** | Phát hiện thiếu hồ sơ, checklist kiểm toán | Vòng đời review 5 bước (`Start -> Assign -> Submit -> Verify -> Close`), sinh JSON Remediation Plan | PostgreSQL 16 (`dossier_review_*`) | `/dashboard/readiness`, `/v1/dossiers/*`, `/v1/remediation/*` | | **6. Nhật Ký Thi Công & Nhân Sự** | Log công việc hiện trường, chấm công, ca máy | Chuẩn hóa session/action, phân tích an toàn lao động & thời tiết bằng AI | PostgreSQL 16 (`employee_work_logs`) | `/dashboard/employees`, `/v1/employees/logs`, `/v1/ai/site-diary/*` | | **7. Con Người, Vai Trò & AI Workforce** | Sơ đồ tổ chức, quyền hạn, 8 AI Personas | Quản lý identity, phân vai trò RBAC, định tuyến prompt theo persona | PostgreSQL 16 (`users`) + Qdrant | `/dashboard/users`, `/v1/auth/*`, `/route-task`, `/v1/agents/*` | | **8. Digital Twin Vận Hành Công Ty** | Tín hiệu tổng hợp từ 7 luồng trên | Aggregate toàn diện (Projects, Cases, Actions, Blockers, Risks, Workforce) | PostgreSQL 16 + Cache | `/` (Dashboard Tổng Thể), `/v1/company/operational-state` (SSE Stream) | --- ## 2. CHI TIẾT CÁC LUỒNG NGHIỆP VỤ CỐT LÕI ### 2.1. Luồng Hóa Đơn Điện Tử & Kế Toán Công Trình (E-Invoices) 1. **Tiếp nhận XML**: Kế toán hoặc hệ thống tự động upload file XML hóa đơn vào `POST /v1/invoices/upload` hoặc đồng bộ tự động qua `POST /v1/invoices/sync/auto`. 2. **Kiểm tra Trùng Lặp**: Tính toán mã băm SHA-256 của toàn bộ nội dung XML để ngăn chặn gian lận hoặc nhập trùng hóa đơn. 3. **Bóc tách Dữ liệu (Parser Engine)**: * Nhận diện cấu trúc chuẩn Tổng cục Thuế (Nghị định 123/2020/NĐ-CP) hoặc định dạng MISA meInvoice. * Trích xuất thông tin Đơn vị bán, MST, Số hóa đơn, Ngày ký số, Chi tiết từng mặt hàng vật tư/thiết bị/dịch vụ ca máy. 4. **Đảm bảo Độ chính xác Số học**: * Tất cả số tiền (tiền hàng, thuế VAT, tổng thanh toán) được lưu dạng `NUMERIC(18, 4)` trong PostgreSQL. 5. **Cập nhật Chỉ số Tài chính (KPIs)**: Cung cấp số liệu thời gian thực cho `/v1/invoices/kpis` và tự động cập nhật vào chi phí thực tế (Actual Cost - AC) của dự án. ### 2.2. Luồng Dự Án, AI WBS Generator & Quản Lý Chi Phí EVM 1. **Khởi tạo Dự án**: Nhập thông tin gói thầu, hợp đồng, chủ đầu tư, giá trị `contract_value`. 2. **Sinh WBS Tự động bằng AI**: * Gửi yêu cầu tới `POST /v1/projects/{project_id}/wbs/generate`. * AI Agent (Kỹ sư QS - Quỳnh) phân tích loại hình công trình (dân dụng, hạ tầng, công nghiệp) để sinh cây phân rã công việc WBS 4 cấp độ kèm thời lượng dự kiến và tỷ trọng ngân sách (Planned Value - PV). 3. **Tính toán Chỉ số Earned Value Management (EVM)**: * Định kỳ tính toán tại `POST /v1/bim/evm/calculate`: * **BAC (Budget at Completion)**: Tổng ngân sách được duyệt. * **PV (Planned Value)**: Giá trị kế hoạch theo tiến độ WBS. * **EV (Earned Value)**: Giá trị khối lượng thực tế đã nghiệm thu nội bộ/A-B. * **AC (Actual Cost)**: Chi phí thực tế đã chi trả (từ hóa đơn & ca máy). * **CPI (Cost Performance Index) = EV / AC**: Hiệu quả chi phí (CPI < 1: Vượt ngân sách). * **SPI (Schedule Performance Index) = EV / PV**: Hiệu quả tiến độ (SPI < 1: Chậm tiến độ). ### 2.3. Luồng Kiểm Soát Hồ Sơ Chất Lượng & Vòng Đời Thẩm Tra (Dossier Review Lifecycle) 1. **Kiểm tra Độ phủ & Sẵn sàng**: * Gọi `GET /v1/dossiers/{project_code}/coverage` và `GET /v1/dossiers/{project_code}/readiness`. * Hệ thống so sánh danh mục hồ sơ hiện có trong Qdrant với bộ tiêu chuẩn hồ sơ pháp lý bắt buộc (Luật Xây dựng 2025). 2. **Khởi chạy Quy trình Review**: * Gọi `POST /v1/workflows/dossier-review/start`. * Hệ thống tự động tạo phiên review, phát hiện danh sách hồ sơ thiếu (Findings) và phân công (Assignments) cho kỹ sư hiện trường tương ứng. 3. **Nộp Bổ Sung & Thẩm Tra (Verify)**: * Kỹ sư nộp tài liệu bổ sung (`POST .../supplements`). * Agent Kiểm toán Tùng hoặc Kỹ sư trưởng thẩm tra (`POST .../verify`). * Khi tất cả findings được giải quyết, phiên rà soát được đóng (`POST .../close`) và điểm sẵn sàng của dự án được cập nhật. 4. **Remediation Planning**: * Với những hồ sơ thiếu phức tạp, hệ thống sinh kế hoạch chi tiết (`/v1/remediation/plans/build`) hướng dẫn rõ: biểu mẫu cần dùng, căn cứ pháp lý, người chịu trách nhiệm và thư mục lưu trữ chuẩn. ### 2.4. Luồng Digital Twin Vận Hành & Realtime SSE Stream 1. **Tổng hợp Dữ liệu Đa nguồn**: `CompanyOperationalStateService` định kỳ gom dữ liệu từ các bảng: `projects`, `invoices`, `dossier_review_sessions`, `employee_work_logs`, `erp_documents`. 2. **Phân loại Trạng thái & Rủi ro**: Xác định số lượng ca xử lý mở (Cases), đầu việc tồn đọng (Actions), điểm nghẽn nghiêm trọng (Blockers) và mức độ rủi ro tài chính/tiến độ. 3. **Phát sóng Realtime SSE**: Endpoint `GET /v1/company/operational-state/stream` đẩy luồng JSON cập nhật tới Dashboard giám đốc (`/`) mỗi vài giây một lần. --- ## 3. NGUYÊN TẮC BẢO VỆ NGỮ CẢNH VÀ BỘ NHỚ AI AGENT (ANTI-MEMORY-LOSS) Để đảm bảo các AI Agent không bao giờ bị "quên" ngữ cảnh công việc hoặc trả lời sai lệch: 1. **Nguyên tắc "PostgreSQL First"**: * Mọi trạng thái nghiệp vụ (ai làm gì, biên bản nào thiếu, hóa đơn nào chưa duyệt) **bắt buộc** phải lưu vào PostgreSQL dưới dạng bản ghi có khóa chính và audit log. * AI Agent không tự lưu trạng thái trong bộ nhớ RAM tạm thời; luôn đọc snapshot từ CSDL trước khi phản hồi. 2. **Nguyên tắc "RAG Grounding"**: * Trước khi tư vấn về quy chuẩn kỹ thuật hoặc điều khoản hợp đồng, Agent phải truy vấn semantic search từ Qdrant (`/v1/knowledge/search`). * Tuyệt đối không tự suy đoán định mức xây dựng hoặc số liệu ngoài tài liệu được nạp. 3. **Nguyên tắc Phân quyền Phối hợp (Multi-Agent Protocol)**: * Mỗi Agent chỉ xử lý đúng thẩm quyền của mình theo [docs/system-architecture-master.md](file:///c:/Projects/DSCons/docs/system-architecture-master.md#4-m%E1%BA%A1ng-l%C6%B0%E1%BB%9Bi-ai-personas-chuy%C3%AAn-tr%C3%A1ch-ai-workforce). * Khi gặp bài toán liên phòng ban (ví dụ: Kỹ sư QS Quỳnh phát hiện lệch chi phí cần chuyển sang Kế toán Nam), Agent phải kích hoạt kênh chuyển tiếp (`escalation_targets`).