# Checklist tích hợp ingest Kênh Xây

Checklist này dùng để chạy ingest theo đúng thứ tự thao tác, có kiểm soát metadata, có điểm xác nhận và có chỗ dừng khi phát hiện rủi ro.

## 1. Chuẩn bị trước khi chạy

### Tệp cần có
- `docs/kenh-xay-document-manifest.json`
- `docs/kenh-xay-gold-reference-metadata-schema.json`

### Xác nhận đầu vào
- manifest đọc được
- schema đọc được
- đường dẫn `relative_path` trong manifest trỏ đúng file trên disk
- đã thống nhất `project_code` và `template_code` cho toàn batch

### Default phải gắn cho mọi chunk
- `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"`
- `is_gold_reference = true`

## 2. Kiểm tra manifest trước ingest

### Dùng manifest làm nguồn quyết định phạm vi
- chỉ ingest record có `is_ingest_candidate = true`
- record `is_ingest_candidate = false` vẫn phải giữ trong summary audit

### Kiểm tra các record cần loại
Không ingest các nhóm sau:
- file trùng
- file bìa
- file chỉ làm cover hoặc noise
- file không còn tồn tại trên disk

### Điểm xác nhận
- đã thống kê đủ số record candidate và non-candidate
- đã có danh sách file chắc chắn bị exclude trước khi đọc nội dung

## 3. Normalize metadata trước khi chunk

### 3.1 Normalize `stage`
Map về bộ giá trị dùng chung:

| Giá trị cũ | Giá trị chuẩn |
| --- | --- |
| `project_setup` | `overview` |
| `approval` | `legal_setup` |
| `procurement_approval` | `procurement` |
| `consulting_assignment` | `legal_setup` |
| `contract_award` | `procurement` |
| `pre_contract` | `contracting` |
| `contract_execution` | `contracting` hoặc `execution` theo loại hồ sơ |
| `execution_quality` | `execution` |
| `completion` | `acceptance` |

### 3.2 Normalize `package_label`
- giữ nguyên nếu đã hợp lệ
- nếu là hồ sơ dùng chung toàn công trình thì gán `package_project_wide`
- chỉ dùng `package_unknown` khi không suy ra được

### 3.3 Normalize `document_type`
- override các file bìa về `bia_ho_so`
- không giữ raw manifest nếu biết chắc là cover-only
- các file mơ hồ cần cờ kiểm tra tay

### Điểm xác nhận
- không còn `stage` ngoài allowed values
- không còn `package_label = null`
- file bìa không bị giữ nhầm như hồ sơ chính

## 4. Derive metadata bắt buộc

### Field truy vết nguồn
- `raw_path = relative_path`
- `source_file = relative_path`
- `source_filename = file_name`
- `source_format = extension` dạng lowercase, bỏ dấu chấm

### Field phân loại và kiểm soát
- `version_role`
- `gold_reference_role`
- `requires_ocr`
- `used_for_tasks`

### Field khuyến nghị nên có
- `package_code`
- `package_name`
- `business_group`
- `knowledge_type`
- `task_type`
- `title`
- `folder_scope`
- `doc_family`
- `evidence_role`
- `required_for`
- `retrieval_priority`
- `training_value`
- `confidence_note`

### Field cấp chunk
- `chunk_index`
- `ingest_batch`
- `id`

## 5. Áp rule cho `version_role`

### Gán `duplicate`
- mọi record `is_ingest_candidate = false`
- file bìa
- file trùng hoặc bản copy

### Gán `template_form`
- các hồ sơ `mau_bieu_02a`

### Gán `effective`
- quyết định, phê duyệt
- hợp đồng, thương thảo
- bản vẽ, khối lượng, dự toán
- nghiệm thu, thanh toán, quyết toán
- nhật ký và hồ sơ chất lượng chính

### Gán `unknown`
- file tên mơ hồ
- record `needs_verification`
- trường hợp chưa đủ cơ sở để xếp là hồ sơ chính

### Điểm xác nhận
- không để trống `version_role`
- file mơ hồ không bị gán vội là `effective`

## 6. Áp rule cho `gold_reference_role`

### Gán `required`
- danh mục hồ sơ gốc
- quyết định pháp lý chính
- bản vẽ, khối lượng, dự toán gốc
- hợp đồng TCXD
- nghiệm thu khối lượng hoàn thành
- bộ hồ sơ thanh toán chính

### Gán `optional`
- hồ sơ bổ trợ
- hồ sơ phụ có giá trị tham chiếu nhưng không phải anchor

### Gán `example`
- `mau_bieu_02a`
- `vat_tu_dinh_muc`

### Gán `exclude`
- file trùng
- file bìa
- file non-candidate
- cover-only hoặc noise

### Điểm xác nhận
- hồ sơ anchor đã được gán `required`
- nhóm exclude không đi vào batch ingest

## 7. Áp rule cho `used_for_tasks`

Tối thiểu mọi ingest candidate nên có:
- `template_training`
- `retrieval_grounding`

Bổ sung theo loại hồ sơ:
- `danh_muc_ho_so`: `inventory_mapping`, `missing_doc_detection`
- pháp lý, quyết định, lựa chọn nhà thầu: `legal_timeline_check`, `package_classification`
- hợp đồng, thương thảo, pháp lý hợp đồng: `contract_review`
- bản vẽ, khối lượng, dự toán: `execution_guidance`, `payment_check`
- nghiệm thu, hồ sơ chất lượng, nhật ký: `quality_check`, `execution_guidance`
- đề nghị thanh toán, phụ lục thanh toán: `payment_check`
- quyết toán: `settlement_check`, `audit_preparation`

## 8. Đọc text và kiểm soát chất lượng nội dung

### Kiểm tra khi đọc file
- file có tồn tại không
- extractor có trả text không
- text sau normalize có rỗng không

### Rule `requires_ocr`
- PDF: mặc định `true` nếu chưa có detector text layer
- DOC, DOCX, XLS, XLSX: thường `false`

### Điểm xác nhận
- file `missing` được ghi rõ lý do
- file `empty` được ghi rõ lý do
- PDF scan kém được gắn cờ để rà soát sau ingest

## 9. Chunk và gắn metadata cấp chunk

### Cần làm
- chọn `chunk_size` và `overlap` theo loại file
- gắn `chunk_index`
- gắn `id` ổn định
- gắn `ingest_batch` cho mọi chunk

### Điểm xác nhận
- chunk không quá ngắn hoặc quá dài bất thường
- ID không thay đổi vô lý giữa các lần rerun
- mọi chunk đều truy về được `source_file`

## 10. Upsert và kiểm tra rerun

### Trước khi upsert
- metadata đã normalize xong
- đã loại file exclude
- payload chunk có đủ `text` và `metadata`

### Sau khi upsert
- có tổng số chunk thành công
- có danh sách file ingest thành công
- có danh sách file skip hoặc lỗi

### Điểm xác nhận
- rerun không sinh chunk trùng
- `ingest_batch` đủ rõ để audit
- summary phản ánh đúng số lượng thực tế

## 11. Summary bắt buộc sau batch

### Ở cấp batch
- `status`
- `project_code`
- `template_code`
- `ingest_batch`
- `manifest_path`
- `schema_path`
- `total_manifest_records`
- `total_files_ready`
- `total_files_skipped`
- `total_chunks`

### Ở cấp file
- `file`
- `relative_path`
- `document_type`
- `package_label`
- `status`
- `chunks`
- `reason`

### Lý do skip tối thiểu
- `manifest_marked_non_candidate`
- `file_not_found`
- `no_extractable_text`

## 12. Các record cần kiểm tra tay

Nhóm `needs_verification`:
- vẫn có thể ingest để tăng coverage
- nhưng nên gắn:
  - `confidence_note` nêu rõ đang phân loại theo tên file
  - `version_role = unknown`
  - `gold_reference_role = optional`

### Điểm xác nhận
- không để hồ sơ mơ hồ chen vào nhóm anchor
- có danh sách riêng để rà soát thủ công sau batch

## 13. Thứ tự ưu tiên khi chạy thật

1. danh mục hồ sơ gốc
2. bản vẽ, khối lượng, dự toán
3. quyết định pháp lý chính
4. hợp đồng TCXD
5. nghiệm thu khối lượng hoàn thành
6. hồ sơ thanh toán chính
7. hồ sơ bổ trợ còn lại

Lý do:
- đây là nhóm hỗ trợ trực tiếp cho retrieval, gap analysis và readiness
- giúp batch đầu có giá trị nghiệp vụ ngay, không phải ingest dàn trải

## 14. Chốt dừng nếu gặp lỗi

Dừng batch để rà soát nếu gặp một trong các dấu hiệu:
- số file `missing` tăng bất thường
- nhiều file anchor bị `empty`
- `stage` chưa normalize hết
- có quá nhiều chunk từ file bìa hoặc file trùng
- rerun làm tăng mạnh số chunk mà không có file mới

## 15. Kết luận vận hành

Batch ingest đạt yêu cầu khi:
- chỉ ingest đúng candidate
- metadata đã được normalize trước khi upsert
- mọi chunk truy vết được về file gốc
- summary đủ để audit, rerun và hỗ trợ bước kiểm tra tiếp theo

Nếu thiếu một trong các điểm trên, chưa nên coi batch là hoàn tất.