# Chuẩn 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: chốt chuẩn phân loại hồ sơ và metadata để ingest nhất quán, hỗ trợ kiểm tra thiếu hồ sơ, retrieval và các workflow rà soát sau này.

## 1. Phạm vi dùng

- Áp dụng cho bộ hồ sơ mẫu Nam - Hưng Khánh.
- Dùng khi:
  - lập manifest và gap analysis
  - gắn metadata trước khi ingest
  - kiểm tra hồ sơ đã đủ cho từng giai đoạn hay chưa
- Đồng bộ với:
  - `docs/knowledge-taxonomy.md`
  - `docs/ingest-json-notes.md`
  - `workflow.md`

## 2. Nguyên tắc chuẩn hóa

- Mỗi tài liệu phải gắn được:
  - `doc_stage`
  - `doc_family`
  - `document_type`
  - trạng thái phiên bản hoặc hiệu lực nếu có
- Không coi file Word/DOCX là bản pháp lý cuối cùng nếu chưa có dấu hiệu bản ký hoặc bản phát hành chính thức.
- Không kết luận “đủ thanh toán” hoặc “đủ quyết toán” chỉ từ hợp đồng; phải có hồ sơ thực tế tương ứng.
- Metadata phải đủ để:
  - lọc theo công trình
  - lọc theo giai đoạn hồ sơ
  - truy ngược file nguồn
  - phân biệt tài liệu chính thức và tài liệu làm việc

## 3. Khung giai đoạn hồ sơ (`doc_stage`)

| `doc_stage` | Khi dùng | Ví dụ |
| --- | --- | --- |
| `pre_award` | chuẩn bị đầu tư, chuẩn bị lựa chọn nhà thầu | quyết định nhiệm vụ, BCKTKT, KHLCNT |
| `contracting` | lựa chọn nhà thầu, thương thảo, ký hợp đồng | KQLCNT, thương thảo, hợp đồng |
| `execution` | tổ chức thi công và điều hành hiện trường | bàn giao mặt bằng, nhật ký, bản vẽ thi công |
| `payment` | nghiệm thu khối lượng, đề nghị thanh toán | nghiệm thu công việc, bảng khối lượng, hồ sơ thanh toán |
| `finalization` | hoàn công, thanh lý, quyết toán | hoàn công, quyết toán, thanh lý |
| `safety_quality` | lớp hồ sơ an toàn, chất lượng, kiểm soát tuân thủ | vật liệu, thí nghiệm, ATLĐ, QLCL |

## 4. Khung nhóm hồ sơ (`doc_family`)

| `doc_family` | Ý nghĩa | Ví dụ |
| --- | --- | --- |
| `legal` | căn cứ pháp lý nền | quyết định nhiệm vụ, BCKTKT |
| `decision` | văn bản phê duyệt, chấp thuận | KHLCNT, KQLCNT, quyết toán |
| `tender` | hồ sơ đấu thầu, tiếp nhận thầu | đơn nhận thầu, hồ sơ mời thầu |
| `contract` | hồ sơ ràng buộc hợp đồng | hợp đồng, phụ lục, bảo lãnh |
| `drawing` | hồ sơ bản vẽ | bản vẽ thi công, hoàn công |
| `execution` | hồ sơ tổ chức thi công | bàn giao mặt bằng, nhật ký |
| `acceptance` | hồ sơ nghiệm thu | nghiệm thu công việc, hoàn thành |
| `payment` | hồ sơ thanh toán | đề nghị thanh toán, bảng giá trị |
| `settlement` | hồ sơ quyết toán, thanh lý | quyết toán, thanh lý |
| `safety` | hồ sơ an toàn | huấn luyện, biện pháp ATLĐ |
| `quality` | hồ sơ chất lượng | vật liệu, thí nghiệm, kiểm định |

## 5. Metadata tối thiểu cần có

### 5.1 Bắt buộc cho ingest

Theo `docs/knowledge-taxonomy.md`, mỗi tài liệu nên có tối thiểu:

| 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ụ chính |
| `knowledge_type` | miền tri thức để retrieval |
| `document_type` | loại tài liệu cụ thể |
| `schema_version` | phiên bản schema |

### 5.2 Nên có cho hồ sơ công trình mẫu

| 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 nếu có |
| `issue_date` | ngày ký hoặc 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 nháp, bản scan, bản cập nhật |
| `decision_no` | với quyết định, văn bản có số |
| `section_title` | hữu ích khi chunk hợp đồng hoặc văn bản dài |

### 5.3 Trường phục vụ kiểm tra readiness

Chỉ dùng khi đã đủ cơ sở:

- `readiness_weight`
- `required_for`
- `required_for_payment`
- `required_for_finalization`
- `required_for_commencement`

> Nếu chưa rõ logic chấm điểm, vẫn có thể để trống các trường readiness, nhưng không bỏ qua `doc_stage`, `doc_family`, `document_type`.

## 6. Mapping nhanh bộ hồ sơ hiện có

| Tài liệu hiện có | `doc_stage` | `doc_family` | `document_type` | Ghi chú |
| --- | --- | --- | --- | --- |
| `06. QD PHE KHLCNT.signed.pdf` | `pre_award` | `decision` | `quyet_dinh_phe_duyet` | bản scan ký, ưu tiên cao |
| `06.Bieu kem theo.doc` | `pre_award` | `legal` | `ke_hoach_lua_chon_nha_thau` hoặc file phụ trợ | cần xác nhận bản chốt |
| `01. Đơn nhận thầu TCXD & MSTB.doc` | `contracting` | `tender` | tài liệu đấu thầu | dùng cho ngữ cảnh lựa chọn nhà thầu |
| `02. Biên bản thương thảo HĐTC.docx` | `contracting` | `contract` | `bien_ban_thuong_thao` | tài liệu lõi trước hợp đồng |
| `03. QĐ PDKQLCNT TCXL & MSTB 06-03-2026.docx` | `contracting` | `decision` | `quyet_dinh_phe_duyet` | mới là DOCX, chưa coi là bản pháp lý cuối |
| `04. HD TCXD ... .docx` | `contracting` | `contract` | `hop_dong` | tài liệu lõi cho thanh toán, quyết toán |
| `1.BD_DAI DONG.pdf` | `execution` | `drawing` | `ban_ve_thi_cong` | cần xác nhận phiên bản sử dụng chính thức |
| `2.Chi tiet.pdf` | `execution` | `drawing` | `ban_ve_thi_cong` | dùng làm ngữ cảnh kỹ thuật nền |

## 7. Checklist hồ sơ lõi theo giai đoạn

### 7.1 `pre_award`

- Nên có:
  - quyết định nhiệm vụ và dự toán
  - BCKTKT
  - KHLCNT
  - biểu kèm theo
- Hiện trạng mẫu:
  - đã có KHLCNT
  - thiếu nhiều tài liệu pháp lý đầu chuỗi

### 7.2 `contracting`

- Nên có:
  - đơn nhận thầu
  - KQLCNT
  - biên bản thương thảo
  - hợp đồng
  - phụ lục, bảo lãnh nếu có
- Hiện trạng mẫu:
  - có lõi hợp đồng tương đối tốt
  - thiếu xác nhận bản ký/chính thức ở một số file

### 7.3 `execution`

- Nên có:
  - bàn giao mặt bằng
  - nhật ký thi công
  - bản vẽ thi công
  - hồ sơ vật liệu
  - QLCL, thí nghiệm, kiểm định
- Hiện trạng mẫu:
  - mới có bản vẽ nền
  - thiếu hồ sơ hiện trường trọng yếu

### 7.4 `payment`

- Nên có:
  - nghiệm thu công việc
  - xác nhận khối lượng
  - hồ sơ thanh toán đợt
  - đề nghị thanh toán
  - chứng từ liên quan
- Hiện trạng mẫu:
  - gần như chưa có

### 7.5 `finalization`

- Nên có:
  - nghiệm thu hoàn thành
  - hồ sơ hoàn công
  - bản vẽ hoàn công
  - quyết toán
  - thanh lý
- Hiện trạng mẫu:
  - chưa đủ cơ sở kết luận readiness

## 8. Nguyên tắc kiểm tra trước khi ingest

- Kiểm tra đúng file nguồn:
  - tên file
  - định dạng
  - số trang hoặc tình trạng mở được
- Kiểm tra trạng thái tài liệu:
  - bản scan ký
  - bản Word làm việc
  - bản chưa rõ nguồn
- Kiểm tra metadata cốt lõi:
  - đủ `project_code`, `source_file`, `task_type`, `knowledge_type`, `document_type`, `schema_version`
- Kiểm tra metadata ngữ cảnh:
  - `doc_stage`
  - `doc_family`
  - `issue_date` nếu xác định được
  - `revision` nếu có nhiều phiên bản
- Kiểm tra nội dung có dùng được không:
  - PDF scan mờ cần OCR
  - file thiếu trang phải ghi chú
  - bản vẽ khó đọc cần note hạn chế retrieval

## 9. Điểm xác nhận bắt buộc

Trước khi coi một tài liệu là “đủ chuẩn để ingest”, cần chốt 5 điểm:

| Điểm xác nhận | Câu hỏi cần trả lời |
| --- | --- |
| Nguồn | File này lấy từ đâu, lưu ở đâu |
| Loại tài liệu | Đây chính xác là hồ sơ gì |
| Giai đoạn | Hồ sơ này thuộc `doc_stage` nào |
| Phiên bản | Là bản ký, bản scan, bản Word hay bản chưa chốt |
| Vai trò vận hành | Tài liệu này phục vụ bước nào: hợp đồng, thi công, thanh toán hay quyết toán |

## 10. Rủi ro nếu chuẩn hóa không chặt

- Retrieval trả lời nhầm bản Word là văn bản pháp lý cuối cùng.
- Lẫn tài liệu nội bộ với tài liệu chính thức.
- Hỏi về thanh toán hoặc quyết toán nhưng AI suy diễn từ hợp đồng, không dựa trên hồ sơ thật.
- Không lọc đúng theo công trình hoặc gói thầu vì thiếu metadata lõi.
- Không truy ngược được chunk về file gốc khi cần kiểm tra lại.

## 11. Kết luận

Chuẩn hồ sơ này là lớp nền cho cụm hồ sơ mẫu Nam - Hưng Khánh.

Nếu giữ đúng `doc_stage`, `doc_family`, metadata lõi và quy tắc xác nhận phiên bản, DSCons có thể:

- ingest nhất quán
- kiểm tra thiếu hồ sơ rõ hơn
- hỗ trợ workflow rà soát hồ sơ đáng tin cậy hơn
- giảm rủi ro trả lời sai về thanh toán và quyết toán