# Contract metadata gold reference cho Kênh xây

## 1. Mục tiêu

Tài liệu này chốt cách ghi metadata cho bộ hồ sơ mẫu `Kênh Xây` khi dùng làm `gold reference` trong cụm `ingest-knowledge`.

Mục tiêu chính:

- chọn đúng hồ sơ mẫu có giá trị tra cứu cao
- ghi metadata thống nhất trước khi ingest vào Qdrant
- đồng bộ với `docs/knowledge-taxonomy.md`
- bám cách nhìn manifest trong `docs/project-dossier-manifest-template.md`
- giúp pipeline ingest chạy lại được và dễ truy vết nguồn

## 2. Phạm vi

Áp dụng cho hồ sơ mẫu của dự án `Kênh Xây` dùng để:

- làm mẫu chuẩn cho retrieval
- đối chiếu cấu trúc hồ sơ giữa các công trình
- hỗ trợ training nội bộ và grounding cho agent

Không dùng tài liệu này để:

- thay cho manifest tổng của công trình
- ghi log vận hành hằng ngày
- thay thế dữ liệu tác nghiệp trong PostgreSQL

## 3. Cách dùng nhanh

Quy trình khuyến nghị:

1. rà danh sách file từ nguồn gốc
2. loại file rác, file trùng, file bìa không có nội dung nghiệp vụ
3. gán nhóm hồ sơ và loại tài liệu
4. điền các trường bắt buộc
5. đánh dấu hồ sơ nào đủ điều kiện ingest
6. ưu tiên hồ sơ `required` và bản `effective`
7. chỉ ingest khi còn truy được `source_file`

## 4. Chủ thể metadata chính

### 4.1 Thông tin nguồn mẫu

| Trường | Giá trị chuẩn | Ghi chú |
| --- | --- | --- |
| `project_code` | `DS-HĐ26-004` | mã công trình dùng chung trong DSCons |
| `project_name` | `Kênh Xây` | tên ngắn để lọc |
| `source_project_template` | `kenh_xay_kien_minh` | khóa nhận diện bộ mẫu |
| `source_project_role` | `gold_reference_template` | vai trò của nguồn |
| `template_code` | `KX-KM-2026-TEMPLATE` | mã template cố định |
| `schema_version` | `1.0` | phiên bản contract này |

### 4.2 Cờ vận hành chính

| Trường | Ý nghĩa |
| --- | --- |
| `is_gold_reference` | hồ sơ thuộc bộ mẫu chuẩn |
| `gold_reference_role` | mức ưu tiên của hồ sơ trong bộ mẫu |
| `is_ingest_candidate` | có đưa vào Qdrant hay không |
| `requires_ocr` | có cần OCR trước ingest hay không |
| `version_role` | vai trò phiên bản: hiệu lực, nháp, trùng, mẫu biểu |

## 5. Trường bắt buộc nên có cho mỗi record

| Trường | Bắt buộc | Cách dùng |
| --- | --- | --- |
| `project_code` | có | lọc theo công trình |
| `project_name` | có | hiển thị |
| `source_project_template` | có | truy vết bộ mẫu |
| `source_project_role` | có | phân biệt với hồ sơ thật |
| `template_code` | có | gom cùng bộ reference |
| `schema_version` | có | kiểm soát version metadata |
| `raw_path` | có | đường dẫn nguồn để audit |
| `source_file` | có | đường dẫn hoặc tên file gốc |
| `source_filename` | có | tên file hiển thị |
| `source_format` | có | pdf, docx, xlsx, pages |
| `document_group` | có | nhóm hồ sơ lớn |
| `document_type` | có | loại tài liệu cụ thể |
| `task_type` | nên có | nhóm bài toán chính |
| `knowledge_type` | nên có | miền tri thức để retrieval |
| `stage` | có | giai đoạn hồ sơ |
| `status` | có | tình trạng record |
| `version_role` | có | vai trò phiên bản |
| `is_gold_reference` | có | luôn là `true` với record thuộc bộ mẫu |
| `gold_reference_role` | có | `required`, `optional`, `example`, `exclude` |
| `is_ingest_candidate` | có | `true` nếu đủ điều kiện ingest |
| `requires_ocr` | có | `true` nếu scan ảnh khó đọc |
| `used_for_tasks` | nên có | danh sách tác vụ downstream |

## 6. Quy ước điền các trường quan trọng

### 6.1 `gold_reference_role`

| Giá trị | Khi dùng |
| --- | --- |
| `required` | hồ sơ trục chính, nên ưu tiên retrieval |
| `optional` | hữu ích nhưng không phải anchor chính |
| `example` | mẫu biểu, ví dụ tốt để tham khảo |
| `exclude` | có trong nguồn nhưng không ingest |

### 6.2 `version_role`

| Giá trị | Khi dùng |
| --- | --- |
| `effective` | bản đang dùng hoặc bản hiệu lực rõ |
| `draft` | bản nháp |
| `duplicate` | file trùng, bìa, bản sao không tăng giá trị |
| `template_form` | mẫu biểu |
| `unknown` | chưa đủ chắc chắn để kết luận |

### 6.3 `status`

| Giá trị | Khi dùng |
| --- | --- |
| `available` | file đang có và dùng được |
| `needs_verification` | mới phân loại theo tên file, cần kiểm tra thêm |
| `excluded_noise` | file rác hoặc không dùng để retrieval |

### 6.4 `stage`

Bộ giá trị nên dùng thống nhất:

- `overview`
- `design_estimate`
- `legal_setup`
- `procurement`
- `contracting`
- `execution`
- `acceptance`
- `payment`
- `settlement`
- `unknown`

## 7. Quy ước phân loại theo taxonomy DSCons

### 7.1 `document_group`

| Giá trị | Cách hiểu |
| --- | --- |
| `project_overview` | hồ sơ tổng quan, danh mục |
| `technical_design_estimate` | bản vẽ, khối lượng, dự toán |
| `legal_approvals` | quyết định, phê duyệt, văn bản pháp lý |
| `construction_package` | hồ sơ gói thi công xây dựng |
| `consulting_packages` | hồ sơ các gói tư vấn |
| `execution_quality_payment` | hồ sơ thi công, chất lượng, thanh toán, quyết toán |
| `system_noise` | file rác, file hệ thống, file loại bỏ |

### 7.2 Map sang `task_type` và `knowledge_type`

| `document_type` | `task_type` | `knowledge_type` |
| --- | --- | --- |
| `danh_muc_ho_so` | `project_planning` | `template_form` |
| `ban_ve` | `technical_delivery` | `boq_norms_pricing` |
| `khoi_luong` | `technical_delivery` | `boq_norms_pricing` |
| `du_toan` | `technical_delivery` | `boq_norms_pricing` |
| `quyet_dinh` | `legal_compliance` | `decision_document` |
| `ke_hoach_lua_chon_nha_thau` | `procurement_tender` | `procurement_plan` |
| `phe_duyet_ket_qua_lcnt` | `procurement_tender` | `decision_document` |
| `don_nhan_thau` | `procurement_tender` | `bidding_document` |
| `bien_ban_thuong_thao` | `contract_management` | `bid_evaluation` |
| `hop_dong` | `contract_management` | `contract_document` |
| `nghiem_thu` | `technical_delivery` | `acceptance_record` |
| `nhat_ky` | `technical_delivery` | `construction_diary` |
| `de_nghi_thanh_toan` | `payment_settlement` | `payment_dossier` |
| `phu_luc_thanh_toan` | `payment_settlement` | `interim_payment` |
| `quyet_toan` | `payment_settlement` | `settlement_dossier` |
| `mau_bieu_02a` | `payment_settlement` | `template_form` |
| `noise` | không dùng | không dùng |

Ghi chú:

- ưu tiên dùng giá trị đã có trong `docs/knowledge-taxonomy.md`
- không tự tạo taxonomy mới nếu chưa thật sự cần
- nếu chưa rõ, chọn giá trị gần nhất và ghi thêm `notes`

## 8. Quy ước theo gói hồ sơ

### 8.1 `package_label`

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

### 8.2 `package_code` và `package_name`

| `package_label` | `package_code` | `package_name` |
| --- | --- | --- |
| `package_project_wide` | `KX-KM-P00-ALL` | Hồ sơ dùng chung toàn công trình |
| `package_01_tcxd` | `KX-KM-P01-TCXD` | Gói 01 - Thi công xây dựng |
| `package_02_tvgs` | `KX-KM-P02-TVGS` | Gói 02 - Tư vấn giám sát |
| `package_03_tvqlda` | `KX-KM-P03-TVQLDA` | Gói 03 - Tư vấn quản lý dự án |
| `package_04_kiem_toan_doc_lap` | `KX-KM-P04-KTDL` | Gói 04 - Kiểm toán độc lập |
| `package_design` | `KX-KM-P05-TK` | Nhóm thiết kế - lập BCKTKT |
| `package_tham_tra` | `KX-KM-P06-TTR` | Nhóm thẩm tra |
| `package_unknown` | `KX-KM-P99-UNK` | Chưa xác định gói |

## 9. Hồ sơ không được ingest

Các trường hợp dưới đây nên manifest hóa nhưng không đưa vào Qdrant:

- `.DS_Store`
- file lock dạng `~$...`
- dữ liệu phụ của `.pages`
- file bìa chỉ để in
- file trùng không tăng giá trị tra cứu
- file hệ thống hoặc preview

Quy ước metadata cho nhóm này:

| Trường | Giá trị khuyến nghị |
| --- | --- |
| `document_group` | `system_noise` |
| `document_type` | `noise` hoặc `bia_ho_so` |
| `gold_reference_role` | `exclude` |
| `is_ingest_candidate` | `false` |
| `status` | `excluded_noise` |
| `version_role` | `duplicate` hoặc `unknown` |

## 10. Record mẫu cấp file

```json
{
  "project_code": "DS-HĐ26-004",
  "project_name": "Kênh Xây",
  "source_project_template": "kenh_xay_kien_minh",
  "source_project_role": "gold_reference_template",
  "template_code": "KX-KM-2026-TEMPLATE",
  "schema_version": "1.0",
  "raw_path": "HĐ-2026/Phòng KT xã Kiến Minh-2026/Kênh xây/Gói TCXD/4. HD TCXD kenh xay.docx",
  "source_file": "HĐ-2026/Phòng KT xã Kiến Minh-2026/Kênh xây/Gói TCXD/4. HD TCXD kenh xay.docx",
  "source_filename": "4. HD TCXD kenh xay.docx",
  "source_format": "docx",
  "document_group": "construction_package",
  "document_type": "hop_dong",
  "task_type": "contract_management",
  "knowledge_type": "contract_document",
  "stage": "contracting",
  "status": "available",
  "version_role": "effective",
  "is_gold_reference": true,
  "gold_reference_role": "required",
  "is_ingest_candidate": true,
  "requires_ocr": false,
  "package_label": "package_01_tcxd",
  "package_code": "KX-KM-P01-TCXD",
  "package_name": "Gói 01 - Thi công xây dựng",
  "used_for_tasks": [
    "template_training",
    "contract_review",
    "payment_check",
    "settlement_check",
    "retrieval_grounding"
  ],
  "notes": "Hồ sơ anchor cho chuỗi hợp đồng - nghiệm thu - thanh toán."
}
```

## 11. Record mẫu cấp chunk

Nếu ingest theo chunk, giữ metadata file-level và bổ sung:

```json
{
  "id": "DS-HĐ26-004::hop_dong::4-hd-tcxd-kenh-xay::chunk-1",
  "chunk_index": 1,
  "section_title": "Hợp đồng thi công Kênh xây",
  "ingest_batch": "kenh_xay_gold_reference_v1"
}
```

## 12. Quy tắc vận hành thực dụng

- chỉ ingest hồ sơ còn truy được `source_file`
- ưu tiên bản `effective`, không đẩy nháp vào nhóm chuẩn
- file `.pages` chỉ ingest khi pipeline đọc được ổn định
- nếu phân loại mới dựa trên tên file, để `status=needs_verification`
- không dùng gold reference để thay cho hồ sơ thật của công trình khác
- metadata phải đủ để lọc theo công trình, gói, giai đoạn, loại hồ sơ
- cùng một file không nên có nhiều cách đặt `document_type`

## 13. Rủi ro cần lưu ý

| Rủi ro | Tác động | Cách giảm |
| --- | --- | --- |
| phân loại sai do chỉ nhìn tên file | retrieval sai ngữ cảnh | gắn `needs_verification`, soát lại các file anchor |
| ingest nhầm file bìa hoặc file trùng | tăng noise trong Qdrant | loại trước bằng `is_ingest_candidate=false` |
| dùng taxonomy ngoài chuẩn DSCons | khó lọc chéo giữa dự án | bám `docs/knowledge-taxonomy.md` |
| không tách bản hiệu lực và bản nháp | AI trích sai căn cứ | dùng rõ `version_role` |
| thiếu đường dẫn nguồn | khó audit, khó sửa lại | luôn giữ `raw_path` và `source_file` |

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

Contract này giúp đội DSCons dùng bộ hồ sơ `Kênh Xây` như một nguồn `gold reference` có kiểm soát:

- biết file nào được ingest
- biết file nào chỉ giữ để manifest
- biết cách map metadata sang taxonomy chung
- giữ retrieval gọn, đúng ngữ cảnh và dễ mở rộng cho các bộ mẫu sau