# Blueprint dùng hồ sơ Kênh xây làm mẫu huấn luyện

## 1. Mục tiêu

Dùng công trình mẫu `Kênh xây Kiến Minh` như một bộ hồ sơ tham chiếu để:

- huấn luyện nhân viên đọc đúng cấu trúc hồ sơ;
- huấn luyện agent map file thực tế sang taxonomy chuẩn;
- tạo bộ ingest ưu tiên cho pilot retrieval;
- làm khuôn mẫu để đối chiếu công trình khác.

File này tập trung vào công dụng thực tế trong chuẩn hóa và ingest, không mô tả automation chi tiết.

## 2. Kênh xây đóng vai trò gì trong DSCons

| Vai trò | Dùng để làm gì |
|---|---|
| `gold reference project` | công trình mẫu có cấu trúc đủ rõ để làm chuẩn |
| `training template` | dạy cách nhận diện hồ sơ theo nhóm, giai đoạn, gói |
| `ingest reference` | chọn file nào nên nạp trước, file nào nên loại/trì hoãn |
| `gap baseline` | làm checklist đối chiếu khi công trình mới thiếu hồ sơ |

## 3. 3 lớp dữ liệu cần giữ

### Lớp 1 - Raw source

- giữ nguyên tên file và thư mục gốc;
- dùng cho audit và truy vết nguồn;
- không sửa tên để tránh mất ngữ cảnh thực tế.

### Lớp 2 - Canonical manifest

- map từng file về `document_group`, `document_type`, `stage`, `package_label`;
- đánh dấu `available`, `needs_verification`, `duplicate`, `ingest_candidate`;
- đây là lớp chính để ingest và kiểm tra chất lượng dữ liệu.

### Lớp 3 - Training assets

- chọn các anchor docs tốt nhất;
- viết checklist hồ sơ chuẩn;
- tạo ví dụ câu hỏi - câu trả lời có dẫn nguồn;
- tạo tình huống “thiếu hồ sơ thì phải nói gì”.

## 4. Output nên có từ bộ mẫu này

| Output | Công dụng thực tế |
|---|---|
| manifest chuẩn | làm inventory có cấu trúc cho ingest |
| checklist hồ sơ chuẩn | đối chiếu công trình khác |
| anchor doc list | ưu tiên retrieval và citation |
| missing-doc register | hỗ trợ rà thiếu hồ sơ |
| guidance cho agent | hạn chế suy diễn khi thiếu căn cứ |

## 5. Taxonomy nên dùng nhất quán

Giữ đồng bộ với cụm hồ sơ mẫu hiện có:

- `project_overview`
- `technical_design_estimate`
- `legal_approvals`
- `construction_package`
- `consulting_packages`
- `execution_quality_payment`

Gắn thêm nhãn theo gói khi có thể:

- `package_01_tcxd`
- `package_02_tvgs`
- `package_03_tvqlda`
- `package_04_kiem_toan_doc_lap`
- `package_design`
- `package_tham_tra`

## 6. Tiêu chí chọn file làm training template

### Nên chọn

- file thể hiện rõ loại hồ sơ trong tên;
- file nằm đúng vị trí nghiệp vụ trong cây thư mục;
- file có giá trị căn cứ cao cho pháp lý, hợp đồng, nghiệm thu, thanh toán;
- file giúp giải thích được workflow từ đầu đến cuối.

### Không nên ưu tiên

- file bìa;
- file lock hoặc file hệ thống;
- file trùng ở thư mục khác;
- file tên quá mơ hồ mà chưa xác minh;
- asset nội bộ của `.pages`.

## 7. Thứ tự ingest khuyến nghị

### Đợt 1 - Anchor docs

- `0.DM hồ sơ - Kênh xây Kiến Minh_2026.xlsx`
- `Kenh Xay Kien Minh_TKTC_Ban Ve 2025.pdf`
- `Kenh Xay Kien Minh_TKTC_Khoi Luong.xlsx`
- `Kenh Xay Kien Minh_TKTC_Du toan sau tham dinh.xls`
- các quyết định `QĐ ...pdf`
- `4. HD TCXD kenh xay.docx`
- `nghiem thu khoi luong hoan thanh.docx`

Mục tiêu:

- khóa trục pháp lý - kỹ thuật - hợp đồng;
- tạo nền cho trả lời các câu hỏi readiness.

### Đợt 2 - Hồ sơ payment/settlement

- `3a thanh toan lan 1.xls`
- `Quyết toán kx kien minh.xls`
- `6a.De nghi thanh toan - ...docx`
- `Phụ lục 03 ...xls`
- `Mẫu 02A ...xlsx`

Mục tiêu:

- bổ sung chuỗi thanh toán theo gói;
- hỗ trợ truy vấn về khối lượng, thanh toán, quyết toán.

### Đợt 3 - Hồ sơ cần xác minh

- `5A.docx`
- `4A.docx`
- `8A thi công - theo trọn gói.docx`
- `BGHĐ - kenh xay.xls`

Mục tiêu:

- chỉ ingest sau khi xác nhận đúng vai trò tài liệu;
- tránh làm retrieval nhiễu.

## 8. Checklist chuẩn hóa trước khi dùng làm training

- [ ] Giữ `raw_path` gốc cho mọi record.
- [ ] Gắn đủ metadata nhóm hồ sơ, loại hồ sơ, giai đoạn, gói.
- [ ] Đánh dấu file trùng và file không ưu tiên ingest.
- [ ] Tách anchor docs khỏi tài liệu phụ trợ.
- [ ] Kiểm tra file tên mơ hồ trước khi đưa vào bộ mẫu chính.
- [ ] Ghi rõ hồ sơ nào chỉ dùng để audit, không dùng để trả lời chính.

## 9. Cách dùng cho nhân viên và agent

### Với nhân viên

- học cách nhận diện một bộ hồ sơ đầy đủ;
- học chỗ nào là căn cứ mạnh, chỗ nào chỉ là tài liệu phụ;
- học cách rà thiếu hồ sơ theo checklist.

### Với agent

- chỉ kết luận khi có anchor doc hoặc metadata đã xác nhận;
- nếu chưa thấy hồ sơ bắt buộc thì phải báo thiếu;
- ưu tiên trích dẫn từ file `available` và `is_ingest_candidate = true`;
- không dùng file bìa hoặc file trùng làm căn cứ chính.

## 10. Rủi ro cần kiểm soát

| Rủi ro | Cách xử lý |
|---|---|
| file trùng ở nhiều thư mục | chọn 1 bản chính để ingest |
| tên file mơ hồ | gắn `needs_verification` |
| file bìa làm nhiễu retrieval | để `is_ingest_candidate = false` |
| package `.pages` khó xử lý | chuyển đổi hoặc fallback, không dùng asset nội bộ |
| suy diễn từ thư mục thay vì từ hồ sơ chính | luôn ưu tiên anchor docs |

## 11. Cách áp sang công trình khác

Khi dùng Kênh xây làm mẫu đối chiếu, cần trả lời 4 câu:

1. công trình mới map được vào taxonomy chuẩn chưa;
2. đã có các anchor docs tối thiểu chưa;
3. còn thiếu hồ sơ nào cho payment/settlement/readiness;
4. file nào có thể ingest ngay, file nào phải xác minh trước.

## 12. Liên kết với các file cùng cụm

- manifest chuẩn: `docs/kenh-xay-document-manifest.md`
- khảo sát cấu trúc: `docs/kenh-xay-template-survey.md`

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

Giá trị lớn nhất của `Kênh xây` không nằm ở số lượng file, mà ở chỗ:

- có thể map thành checklist hồ sơ chuẩn;
- có đủ anchor docs cho nhiều giai đoạn;
- phù hợp để thử ingest có kiểm soát;
- đủ rõ để huấn luyện agent trả lời thận trọng, không suy diễn.