# 5 luồng dữ liệu và bước triển khai tiếp theo

Tài liệu này chốt cách DSCons dùng 5 luồng dữ liệu để phục vụ 3 ưu tiên hiện tại:

1. thay dữ liệu demo bằng dữ liệu thật
2. vận hành ổn định như hệ thống nội bộ dùng hằng ngày
3. đóng gói workflow AI nghiệp vụ ngắn gọn, thực dụng, có thể kiểm chứng

## 1. Toàn cảnh 5 luồng dữ liệu

| Luồng | Vai trò chính | Nơi lưu chính | Đầu ra phục vụ |
| --- | --- | --- | --- |
| Hồ sơ công trình | tạo lớp tri thức từ hồ sơ dự án thật | Qdrant | retrieval, gap analysis, readiness |
| Manifest và gap analysis | phản ánh hồ sơ đã có, còn thiếu, next action | Qdrant | AI nghiệp vụ, readiness, truy vết thiếu hồ sơ |
| Nhật ký nhân sự | ghi ai đang làm gì, phát hiện gì, còn thiếu gì | PostgreSQL | API và dashboard nhân sự |
| Con người và vai trò | xác định đúng người, đúng bộ phận, đúng trách nhiệm | Qdrant + PostgreSQL | phân vai, giao việc, truy hồi bối cảnh |
| Điều hành dự án | theo dõi task, milestone, risk, timeline | PostgreSQL | API và dashboard điều hành dự án |

## 2. Vai trò từng luồng

### Luồng 1 - Hồ sơ công trình
**Đầu vào**
- thư mục dự án thật như `HĐ-2026/`
- file PDF, DOC, DOCX, XLSX
- hồ sơ pháp lý, hợp đồng, kỹ thuật, nghiệm thu, thanh toán

**Xử lý chính**
- trích xuất text
- chia chunk
- gắn metadata chuẩn như `project_code`, `document_type`, `doc_stage`, `doc_family`, `source_file`, `readiness_weight`
- phân biệt hồ sơ đã có, còn thiếu, bản nháp, bản ký

**Vai trò**
- là lớp tri thức lõi của dự án
- giúp AI trả lời theo hồ sơ thật thay vì trả lời chung chung
- là nền cho dossier report, gap analysis, readiness

### Luồng 2 - Manifest và gap analysis
**Đầu vào**
- manifest hồ sơ
- gap analysis
- ghi chú pilot và tài liệu nội bộ tương tự trong `docs/`

**Xử lý chính**
- chuẩn hóa trạng thái hồ sơ
- gắn mức độ tin cậy và readiness
- liên kết với công trình, giai đoạn và next action

**Vai trò**
- cho biết vì sao công trình chưa đủ hồ sơ
- bổ sung bối cảnh vận hành mà hồ sơ gốc không nói rõ
- giúp AI sinh checklist và việc cần làm tiếp theo

### Luồng 3 - Nhật ký nhân sự
**Đầu vào**
- log thao tác thực tế
- ghi chú ca làm việc
- kết quả AI request/response
- checklist thiếu hồ sơ theo từng người

**Xử lý chính**
- chuẩn hóa thành session và action
- gắn nhân sự, công trình, ngày làm việc, tiến độ, findings, missing items
- đưa về bảng vận hành để dashboard và API dùng trực tiếp

**Vai trò**
- phản ánh vận hành hằng ngày
- cho thấy ai đang xử lý gì và vướng ở đâu
- là cầu nối giữa AI workflow và công việc thực tế

### Luồng 4 - Con người và vai trò
**Đầu vào**
- `docs/company-people-knowledge.md`
- dữ liệu nhân sự thực
- thông tin bộ phận, vai trò, người phụ trách

**Xử lý chính**
- chuẩn hóa knowledge về người, vai trò, trách nhiệm
- liên kết knowledge với identity vận hành trong PostgreSQL
- gắn metadata về bộ phận, vai trò, phạm vi phụ trách

**Vai trò**
- giúp hệ thống trả lời đúng ai phụ trách việc gì
- hỗ trợ phân vai, giao việc, escalation
- giảm tình trạng AI gán nhầm người hoặc nhầm phòng ban

### Luồng 5 - Điều hành dự án
**Đầu vào**
- dự án
- milestone
- task
- risk
- timeline event

**Xử lý chính**
- chuẩn hóa trạng thái điều hành
- map đúng quan hệ giữa dự án, công ty, nhân sự
- giữ được tiến độ, việc đang làm, việc sắp tới và rủi ro

**Vai trò**
- là lớp điều hành tổng thể
- giúp DSCons không chỉ tra cứu hồ sơ mà còn hỗ trợ theo dõi công trình
- cung cấp đầu ra cho tổng hợp tuần, dashboard và AI tóm tắt tình hình dự án

## 3. 5 luồng phục vụ 3 ưu tiên thế nào

### Ưu tiên 1 - Thay dữ liệu demo bằng dữ liệu thật
- Luồng 1 thay knowledge demo bằng hồ sơ công trình thật
- Luồng 2 thay ghi chú rời rạc bằng trạng thái hồ sơ có cấu trúc
- Luồng 3 thay log seed bằng nhật ký nhân sự thật
- Luồng 4 thay knowledge chung chung bằng sơ đồ người và vai trò thật
- Luồng 5 thay snapshot demo bằng dữ liệu điều hành dự án thật

**Trọng tâm trước mắt**
- Luồng 1
- Luồng 3
- Luồng 5

### Ưu tiên 2 - Vận hành ổn định
- Luồng 3 và 5 phải ổn định vì đang phục vụ dashboard và API
- Luồng 1 và 2 phải ingest chạy lại được, có metadata rõ, có summary kiểm tra
- Luồng 4 phải giữ identity nhất quán để không nhầm người khi giao việc

### Ưu tiên 3 - Workflow AI nghiệp vụ thực dụng
- AI lấy bối cảnh từ Luồng 1, 2, 4
- AI ghi kết quả và dấu vết xử lý vào Luồng 3
- AI phản ánh tình hình tổng thể qua Luồng 5
- như vậy workflow AI mới có đầu vào thật, đầu ra kiểm chứng được và gắn với người chịu trách nhiệm

## 4. Bảng, công cụ và điểm vào chính

### Công cụ ingest chính
- `tools/hd2026_ingest.py`
- `tools/ingest_dot1_pilot.py`
- `tools/ingest_people_knowledge.py`

### Bảng PostgreSQL chính
| Nhóm | Bảng chính |
| --- | --- |
| Nhật ký nhân sự | `employee_work_log_sessions`, `employee_work_log_actions` |
| Điều hành dự án | `projects`, `companies`, `employees`, `project_milestones`, `project_tasks`, `project_risks`, `project_timeline_events` |

### Điểm tiêu thụ chính
- API `/v1/knowledge/ingest`
- API `/v1/knowledge/search`
- API `/v1/employees/logs`
- API `/v1/project-management`
- dashboard readiness
- dashboard nhân sự
- dashboard điều hành dự án

## 5. Kế hoạch triển khai ngắn

### Bước 1 - Chốt hợp đồng dữ liệu
- giữ metadata lõi cho hồ sơ công trình
- tách rõ knowledge và operational data
- quy ước rõ bản nháp, bản ký, hồ sơ thiếu
- không đổi contract đọc hiện có của API và dashboard

### Bước 2 - Ổn định ingest hồ sơ công trình
- lấy `HĐ-2026/` làm nguồn thật đầu tiên
- chuẩn hóa thứ tự ingest: intake, pháp lý, hợp đồng, kỹ thuật
- giữ chunk ID ổn định để tránh trùng dữ liệu
- sinh summary sau mỗi lần ingest

### Bước 3 - Nạp manifest và gap analysis như knowledge chính thức
- ingest manifest và gap analysis cùng công trình
- gắn metadata về trạng thái, độ tin cậy, next action
- giúp retrieval trả lời được hồ sơ có gì, thiếu gì, thiếu vì sao

### Bước 4 - Thay log nhân sự seed bằng dữ liệu thật
- map dữ liệu vào schema nhật ký đang dùng
- bảo đảm join đúng nhân sự và công trình
- kiểm tra dashboard và API không cần sửa contract

### Bước 5 - Nạp dữ liệu điều hành dự án thật
- nạp `projects`, `project_milestones`, `project_tasks`, `project_risks`, `project_timeline_events`
- giữ đúng quan hệ với `companies` và `employees`
- xác nhận dashboard điều hành đọc được trực tiếp từ PostgreSQL

### Bước 6 - Bổ sung knowledge về con người và vai trò
- ingest knowledge về vai trò, bộ phận, đầu mối phụ trách
- liên kết với identity trong PostgreSQL
- dùng cho phân vai và giao việc đúng người

## 6. Rủi ro và chốt kiểm soát

| Rủi ro | Tác động | Chốt kiểm soát |
| --- | --- | --- |
| Nhầm bản nháp thành hồ sơ chính thức | AI và dashboard đánh giá sai readiness | gắn cờ draft/final, ưu tiên nguồn ký hoặc scan chính thức |
| Thiếu hồ sơ nhưng hệ thống vẫn tưởng là đủ | báo cáo sai, giao việc sai | ingest manifest/gap analysis như nguồn kiểm soát bắt buộc |
| Dữ liệu PostgreSQL không khớp dashboard hiện có | API và giao diện lỗi hoặc thiếu dữ liệu | giữ nguyên contract đọc hiện có, nạp dữ liệu theo schema đang dùng |
| Ingest lặp tạo chunk trùng | retrieval nhiễu, khó truy vết | dùng chunk ID ổn định, lưu `ingest_batch`, kiểm tra rerun |
| Chất lượng text từ PDF scan thấp | truy hồi kém, AI hiểu sai | gắn cờ nguồn yếu, cho phép rà soát tay, không coi là nguồn mạnh nếu text kém |
| Nhầm người hoặc nhầm vai trò | giao việc sai, tóm tắt sai | đồng bộ identity giữa knowledge và PostgreSQL |

## 7. Deliverable đầu tiên nên chốt

**Deliverable đầu tiên:** một lần ingest lặp lại được cho dự án `HĐ-2026/`, đưa hồ sơ thật và tài liệu kiểm soát liên quan vào Qdrant, có metadata chuẩn và có summary để kiểm tra.

### Vì sao chọn deliverable này trước
- thay ngay phần knowledge demo dễ thấy nhất bằng dữ liệu thật
- tận dụng công cụ sẵn có là `tools/hd2026_ingest.py`
- mở đường cho retrieval, readiness và gap analysis chính xác hơn

### Điều kiện hoàn thành
- ingest chạy lại được mà không làm dữ liệu trôi
- có cả hồ sơ công trình và tài liệu nội bộ phản ánh trạng thái thiếu/đủ
- metadata đủ để phân biệt loại hồ sơ, nguồn, giai đoạn, mức readiness
- truy hồi trả lời được 4 câu hỏi cơ bản:
  - công trình hiện có những hồ sơ nào
  - còn thiếu những gì
  - tài liệu nào là bản nháp, tài liệu nào là nguồn mạnh hơn
  - chuỗi pháp lý, hợp đồng và kỹ thuật hiện đang ở trạng thái nào

## 8. Thứ tự ưu tiên thực thi

1. Luồng 1 - hồ sơ công trình
2. Luồng 2 - manifest và gap analysis
3. Luồng 3 - nhật ký nhân sự
4. Luồng 5 - điều hành dự án
5. Luồng 4 - con người và vai trò

Lý do:
- Luồng 1 và 2 tạo nền tri thức thật
- Luồng 3 và 5 tạo khả năng vận hành hằng ngày
- Luồng 4 hoàn thiện bước phân vai và giao việc chính xác hơn

## 9. Kết luận ngắn

Nếu giữ đúng 5 luồng trên, DSCons sẽ có cấu trúc rõ:

- Qdrant giữ tri thức và ngữ cảnh
- PostgreSQL giữ vận hành và trạng thái
- API và dashboard là lớp tiêu thụ
- LLM là lớp phân tích và gợi ý

Điểm quan trọng nhất ở giai đoạn này không phải thêm nhiều tính năng mới, mà là làm cho 5 luồng dữ liệu thật chạy ổn định, truy vết được và phục vụ trực tiếp công việc hằng ngày.