# Kế hoạch ingest hồ sơ công trình mẫu: Đường từ nhà ông Nam đến cống chùa Hưng Khánh

> Mục đích: xác định thứ tự ingest, metadata, điểm kiểm tra và mốc xác nhận để nạp bộ hồ sơ mẫu vào DSCons theo cách an toàn và rerunnable.

## 1. Phạm vi và căn cứ

- Phạm vi:
  - chỉ áp dụng cho bộ hồ sơ mẫu Nam - Hưng Khánh
  - ưu tiên tài liệu đã có file thật
- Căn cứ đồng bộ:
  - `docs/knowledge-taxonomy.md`
  - `docs/ingest-json-notes.md`
  - `workflow.md`
  - `docs/duong-ong-nam-hung-khanh-ho-so-standard.md`

## 2. Mục tiêu ingest

- Giúp retrieval hiểu đúng công trình, gói thầu và hợp đồng đang xét.
- Ưu tiên use case:
  - hỏi hồ sơ đã có và hồ sơ còn thiếu
  - hỏi điều kiện hợp đồng cho thanh toán, quyết toán
  - phân biệt tài liệu chính thức với tài liệu làm việc
- Không đặt mục tiêu:
  - suy diễn tình trạng pháp lý nếu chưa có file thật
  - kết luận readiness cho thanh toán hoặc quyết toán khi thiếu hồ sơ thực tế

## 3. Metadata lõi cần gắn trước khi ingest

### 3.1 Trường bắt buộc

| Trường | Ghi chú |
| --- | --- |
| `project_code` | mã công trình thống nhất |
| `source_file` | tên file hoặc đường dẫn nguồn |
| `task_type` | nhóm bài toán nghiệp vụ |
| `knowledge_type` | miền tri thức |
| `document_type` | loại tài liệu |
| `schema_version` | phiên bản schema |

### 3.2 Trường nên có cho bộ mẫu này

| Trường | Ghi chú |
| --- | --- |
| `project_name` | tên công trình |
| `package_code` | mã gói thầu |
| `package_name` | tên gói thầu |
| `contract_code` | mã hợp đồng |
| `issue_date` | ngày ký hoặc ngày ban hành |
| `source_pages` | trang hoặc vùng chunk |
| `doc_stage` | giai đoạn hồ sơ |
| `doc_family` | nhóm hồ sơ |
| `revision` | phân biệt bản ký, bản Word, bản cập nhật |
| `decision_no` | với văn bản có số |
| `section_title` | hữu ích cho hợp đồng và tài liệu dài |

### 3.3 Bộ giá trị dùng lặp lại cho công trình

```json
{
  "project_name": "Cải tạo, sửa chữa tuyến đường từ nhà ông Nam đến cống chùa Hưng Khánh, thôn Tân Linh, xã Kiến Minh",
  "project_code": "DSC-HP-KIENMINH-2026-ONGNAM-HUNGKHANH",
  "package_name": "Gói 04: Thi công xây lắp và mua sắm thiết bị",
  "package_code": "GOI-04-TCXL-MSTB",
  "contract_code": "08.3.SCKM/2026/HĐTCXD",
  "schema_version": "1.0"
}
```

## 4. Thứ tự ingest đề xuất

### Pha 1 - Tài liệu điều phối và trạng thái hồ sơ

Ingest trước:

1. `docs/duong-ong-nam-hung-khanh-manifest.md`
2. `docs/duong-ong-nam-hung-khanh-ho-so-gap-analysis.md`
3. `docs/duong-ong-nam-hung-khanh-pilot-employee-logs.md`
4. file danh mục hồ sơ tổng nếu còn truy được nguồn

Mục tiêu:

- retrieval hiểu đây là công trình nào
- trả lời được hồ sơ đã có, hồ sơ thiếu, việc ưu tiên tiếp theo
- tạo ngữ cảnh đúng cho các pha sau

### Pha 2 - Chuỗi pháp lý, đấu thầu, thương thảo

Ingest tiếp:

1. `Pháp lý/06. QD PHE KHLCNT.signed.pdf`
2. `Pháp lý/06.Bieu kem theo.doc`
3. `01. Đơn nhận thầu TCXD & MSTB.doc`
4. `02. Biên bản thương thảo HĐTC.docx`
5. `03. QĐ PDKQLCNT TCXL & MSTB 06-03-2026.docx`

Mục tiêu:

- truy được chuỗi từ KHLCNT đến KQLCNT và hợp đồng
- chỉ ra tài liệu nào đang là bản scan ký, tài liệu nào mới là bản Word

### Pha 3 - Hợp đồng lõi

Ingest:

1. `04. HD TCXD Sửa chữa tuyến đường từ nhà ông Nam đến cống chùa Hưng Khánh.docx`

Mục tiêu:

- dùng để hỏi điều khoản thanh toán
- hỏi điều kiện nghiệm thu, quyết toán, thanh lý
- làm nguồn chính cho retrieval hợp đồng

### Pha 4 - Bản vẽ và kỹ thuật nền

Ingest:

1. `1.BD_DAI DONG.pdf`
2. `2.Chi tiet.pdf`

Mục tiêu:

- bổ sung ngữ cảnh kỹ thuật cơ bản
- chưa coi là đủ cho workflow thi công, nghiệm thu hay hoàn công

### Pha 5 - Bổ sung khi có file thật

Chỉ mở ingest khi đã có file rõ nguồn cho các nhóm:

- quyết định nhiệm vụ, dự toán
- BCKTKT
- bàn giao mặt bằng
- nhật ký thi công
- QLCL, vật liệu, thí nghiệm
- nghiệm thu
- hoàn công
- thanh toán
- quyết toán
- thanh lý

## 5. Mapping metadata cho các nhóm chính

| Nhóm tài liệu | `task_type` | `knowledge_type` | Gợi ý `document_type` |
| --- | --- | --- | --- |
| Manifest, gap analysis, pilot log | `legal_compliance` | `internal_process` | file điều phối hoặc checklist nội bộ |
| Quyết định, biểu kèm theo | `procurement_tender` hoặc `legal_compliance` | `decision_document` | `quyet_dinh_phe_duyet` |
| Đơn nhận thầu, thương thảo | `procurement_tender` | `bidding_document` | tài liệu đấu thầu hoặc thương thảo |
| Hợp đồng | `contract_management` | `contract_document` | `hop_dong` |
| Bản vẽ | `technical_delivery` | `as_built_record` hoặc nhóm gần nhất đang dùng | `ban_ve_thi_cong` |

> Nếu chưa có loại thật khớp trong taxonomy, ưu tiên dùng giá trị gần nhất và ghi chú rõ trong notes ingest.

## 6. Quy tắc chunking và gắn metadata

### 6.1 Với hợp đồng và văn bản dài

- Chunk theo chương hoặc mục lớn.
- Mỗi chunk nên có:
  - `section_title`
  - `source_pages`
  - metadata chung của tài liệu mẹ

Gợi ý mục chunk cho hợp đồng:

- thông tin chung
- phạm vi công việc
- giá hợp đồng
- tạm ứng, thanh toán
- nghiệm thu
- quyết toán
- thanh lý
- quyền và nghĩa vụ các bên

### 6.2 Với quyết định và văn bản ngắn

- Có thể ingest cả tài liệu nếu độ dài phù hợp.
- Giữ rõ:
  - `decision_no`
  - `issue_date`
  - `revision`

### 6.3 Với bản vẽ

- Nếu OCR hoặc text extraction yếu, vẫn ingest nhưng phải ghi chú hạn chế.
- Không hứa hẹn retrieval kỹ thuật sâu nếu file chủ yếu là hình.

## 7. Nguyên tắc kiểm tra trước khi nạp

Checklist tối thiểu cho từng file:

- [ ] Có file thật và mở được
- [ ] Ghi đúng `source_file`
- [ ] Gắn đủ metadata bắt buộc
- [ ] Xác định được `doc_stage` và `doc_family`
- [ ] Gắn `revision` nếu là bản Word hoặc bản chưa chốt
- [ ] OCR trước nếu PDF scan mờ
- [ ] Ghi chú nếu thiếu trang, thiếu dấu, thiếu nguồn xác nhận

## 8. Điểm xác nhận sau từng pha

### Sau pha 1

- hỏi được:
  - công trình này đang thiếu gì
  - hồ sơ đã có ở mức nào
  - việc ưu tiên tiếp theo là gì

### Sau pha 2

- hỏi được:
  - chuỗi pháp lý hiện có đến đâu
  - tài liệu nào đã có bản ký
  - tài liệu nào mới là bản làm việc

### Sau pha 3

- hỏi được:
  - hợp đồng yêu cầu gì cho thanh toán
  - điều kiện nghiệm thu, quyết toán, thanh lý là gì
  - cần đối chiếu gì giữa thương thảo và hợp đồng

### Sau pha 4

- hỏi được:
  - hiện có những bản vẽ nền nào
  - có đủ hồ sơ kỹ thuật để tra cứu sâu chưa

## 9. Rủi ro chính và cách chặn

| Rủi ro | Cách chặn |
| --- | --- |
| Lẫn bản Word với bản pháp lý chính thức | luôn gắn `revision`, ghi chú trạng thái file |
| Thiếu metadata nên retrieval lọc sai công trình | bắt buộc `project_code`, `source_file`, `task_type`, `knowledge_type`, `document_type` |
| Trả lời quá mức về thanh toán, quyết toán | chỉ kết luận khi đã có hồ sơ nghiệm thu, thanh toán, hoàn công tương ứng |
| PDF scan mờ làm OCR kém | OCR trước hoặc gắn cờ chất lượng thấp |
| Không truy lại được tài liệu gốc | luôn giữ `source_file`, `source_pages` |

## 10. Điều chưa nên ingest ngay

- tài liệu mới chỉ được nhắc tên nhưng chưa có file
- file chưa rõ nguồn hoặc chưa xác định phiên bản
- hồ sơ scan thiếu trang, mờ nặng mà chưa ghi chú
- tài liệu có nguy cơ làm hệ thống hiểu sai là “đã hoàn chỉnh pháp lý”

## 11. Kết luận

Thứ tự ingest an toàn cho bộ mẫu này là:

1. tài liệu điều phối
2. chuỗi pháp lý và đấu thầu đang có
3. hợp đồng lõi
4. bản vẽ nền
5. hồ sơ thi công, nghiệm thu, thanh toán, quyết toán khi có file thật

Nếu bám đúng thứ tự này, DSCons sẽ hỗ trợ tốt hơn cho workflow rà thiếu hồ sơ, tra cứu hợp đồng và xác định bước tiếp theo mà không tạo cảm giác “đã đủ hồ sơ” khi thực tế chưa đủ.