# Taxonomy tri thức cho ingest DSCons

## 1. Mục tiêu

Tài liệu này dùng để chuẩn hóa metadata khi ingest tài liệu vào Qdrant.

Mục tiêu chính:

- tăng độ chính xác khi search và retrieval
- lọc đúng theo công trình, nhóm hồ sơ, giai đoạn xử lý
- tách bạch knowledge trong Qdrant với dữ liệu vận hành trong PostgreSQL
- giúp pipeline ingest rerunnable và dễ truy vết nguồn

## 2. Phạm vi áp dụng

Áp dụng cho các tài liệu được ingest vào luồng knowledge của DSCons, gồm:

- hồ sơ công trình
- manifest, gap analysis, ghi chú dossier
- tài liệu mẫu, hướng dẫn nội bộ, biểu mẫu
- tri thức pháp lý hoặc nghiệp vụ cần AI tra cứu lại

Không dùng tài liệu này để mô tả log vận hành hằng ngày hoặc bảng trạng thái tác nghiệp trong PostgreSQL.

## 3. Nhóm metadata cốt lõi

### 3.1 Bắt buộc

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

### 3.2 Nên có nếu xác định được

| Trường | Mục đí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 ban hành hoặc ngày ký |
| `source_pages` | trang nguồn nếu ingest theo trang/chunk |
| `doc_stage` | giai đoạn hồ sơ như nháp, ký, hoàn công |
| `doc_family` | nhóm hồ sơ lớn như pháp lý, hợp đồng, thanh toán |
| `readiness_weight` | trọng số phục vụ readiness nếu có dùng |

### 3.3 Bổ sung theo ngữ cảnh

| Trường | Dùng khi nào |
| --- | --- |
| `agency_name` | văn bản từ cơ quan, chủ đầu tư, đơn vị kiểm toán |
| `decision_no` | tài liệu có số quyết định, số văn bản |
| `effective_date` | cần phân biệt ngày hiệu lực với ngày ký |
| `revision` | có nhiều phiên bản |
| `section_title` | chunk thuộc mục hoặc chương cụ thể |
| `legal_basis` | cần bám căn cứ pháp lý |
| `work_item_code` | hồ sơ gắn với mã công việc |
| `cost_item_code` | hồ sơ gắn với mã chi phí |
| `payment_stage` | hồ sơ thanh toán theo đợt |
| `settlement_stage` | hồ sơ quyết toán theo chặng |
| `audit_focus` | hồ sơ kiểm toán theo issue |
| `vendor_or_client` | cần xác định đối tác/chủ đầu tư |

## 4. Cách hiểu 3 trường chính

| Trường | Câu hỏi nó trả lời |
| --- | --- |
| `task_type` | tài liệu này chủ yếu phục vụ bài toán gì |
| `knowledge_type` | tài liệu này thuộc miền tri thức nào |
| `document_type` | đây chính xác là loại tài liệu gì |

Quy ước dùng:

- `task_type` để route workflow hoặc lọc theo bài toán
- `knowledge_type` để gom cụm retrieval
- `document_type` để phân loại hồ sơ cụ thể
- không dùng 3 trường này thay thế cho nhau

## 5. Danh mục `task_type` đề xuất

| Giá trị | Khi dùng |
| --- | --- |
| `legal_compliance` | hồ sơ pháp lý, căn cứ phê duyệt, văn bản quản lý |
| `project_planning` | kế hoạch dự án, tiến độ, chuẩn bị triển khai |
| `procurement_tender` | hồ sơ đấu thầu, lựa chọn nhà thầu |
| `contract_management` | hợp đồng, phụ lục, điều chỉnh, bảo lãnh |
| `technical_delivery` | hồ sơ kỹ thuật, thi công, nghiệm thu kỹ thuật |
| `payment_settlement` | thanh toán, đối chiếu, quyết toán |
| `audit_inspection` | kiểm toán, thanh tra, giải trình |

## 6. Danh mục `knowledge_type` đề xuất

### 6.1 Nhóm pháp lý và hướng dẫn
- `legal_normative`
- `regulatory_guidance`
- `decision_document`

### 6.2 Nhóm chuẩn bị dự án và đấu thầu
- `project_approval`
- `procurement_plan`
- `bidding_document`
- `bid_evaluation`

### 6.3 Nhóm hợp đồng
- `contract_document`
- `contract_appendix`

### 6.4 Nhóm thi công và nghiệm thu
- `boq_norms_pricing`
- `construction_diary`
- `acceptance_record`
- `as_built_record`

### 6.5 Nhóm thanh toán và quyết toán
- `payment_dossier`
- `advance_payment`
- `interim_payment`
- `final_payment`
- `settlement_dossier`

### 6.6 Nhóm kiểm toán và nội bộ
- `audit_report`
- `inspection_conclusion`
- `template_form`
- `internal_process`
- `faq_case_law`

## 7. Danh mục `document_type` gợi ý

| Giá trị | Ví dụ |
| --- | --- |
| `quyet_dinh_phe_duyet` | quyết định phê duyệt dự án, dự toán |
| `bao_cao_ktkt` | báo cáo kinh tế kỹ thuật |
| `ke_hoach_lua_chon_nha_thau` | kế hoạch lựa chọn nhà thầu |
| `ho_so_moi_thau` | hồ sơ mời thầu |
| `bien_ban_mo_thau` | biên bản mở thầu |
| `hop_dong` | hợp đồng chính |
| `phu_luc_hop_dong` | phụ lục hợp đồng |
| `bien_ban_nghiem_thu` | biên bản nghiệm thu |
| `nhat_ky_thi_cong` | nhật ký thi công |
| `de_nghi_tam_ung` | hồ sơ đề nghị tạm ứng |
| `de_nghi_thanh_toan` | hồ sơ đề nghị thanh toán |
| `bang_xac_dinh_gia_tri_khoi_luong` | bảng xác định giá trị khối lượng |
| `ho_so_quyet_toan` | hồ sơ quyết toán |
| `bao_cao_kiem_toan` | báo cáo kiểm toán |
| `ket_luan_thanh_tra` | kết luận thanh tra |

Nếu chưa có loại phù hợp:

- ưu tiên chọn giá trị gần nhất và ghi rõ trong notes ingest
- chỉ bổ sung loại mới khi thật sự lặp lại nhiều lần
- giữ cách đặt tên snake_case, không viết tiếng Việt có dấu

## 8. Mẫu metadata tối thiểu

```json
{
  "project_code": "DA-001",
  "project_name": "Tên dự án",
  "package_code": "GT-001",
  "contract_code": "HD-001",
  "task_type": "payment_settlement",
  "knowledge_type": "payment_dossier",
  "document_type": "de_nghi_thanh_toan",
  "source_file": "ho_so.pdf",
  "source_pages": "12-13",
  "issue_date": "2025-10-01",
  "schema_version": "1.0"
}
```

## 9. Quy tắc vận hành khi ingest

- luôn giữ `source_file` để truy ngược tài liệu gốc
- nếu có nhiều phiên bản, phải phân biệt bằng `revision` hoặc `doc_stage`
- không coi bản nháp là bản chính thức nếu chưa ghi rõ
- tài liệu scan mờ cần note OCR trước khi ingest
- chunk nào không biết rõ nguồn thì không ingest vội
- metadata phải đủ để lọc theo công trình và loại hồ sơ
- script ingest cần chạy lại được mà không làm rối taxonomy

## 10. Cách dùng thực tế trong DSCons

Khi chuẩn bị ingest một tài liệu:

1. xác định công trình: `project_code`, `project_name`
2. xác định bài toán chính: `task_type`
3. xác định miền tri thức: `knowledge_type`
4. xác định loại hồ sơ cụ thể: `document_type`
5. điền nguồn và phiên bản: `source_file`, `source_pages`, `issue_date`, `revision`
6. bổ sung trường ngữ cảnh nếu có: `payment_stage`, `audit_focus`, `section_title`

## 11. Gợi ý map nhanh theo nhóm hồ sơ

| Nhóm hồ sơ | `task_type` thường dùng | `knowledge_type` thường dùng |
| --- | --- | --- |
| Pháp lý | `legal_compliance` | `legal_normative`, `project_approval` |
| Đấu thầu | `procurement_tender` | `bidding_document`, `bid_evaluation` |
| Hợp đồng | `contract_management` | `contract_document`, `contract_appendix` |
| Thi công | `technical_delivery` | `construction_diary`, `boq_norms_pricing` |
| Nghiệm thu | `technical_delivery` | `acceptance_record`, `as_built_record` |
| Thanh toán | `payment_settlement` | `payment_dossier`, `advance_payment`, `interim_payment` |
| Quyết toán | `payment_settlement` | `settlement_dossier`, `final_payment` |
| Kiểm toán | `audit_inspection` | `audit_report`, `inspection_conclusion` |

## 12. Lưu ý cuối

Taxonomy này là khung dùng chung cho cụm `ingest-knowledge`.

Nguyên tắc ưu tiên:

- đơn giản trước, mở rộng sau
- nhất quán giữa các file ingest
- phục vụ search và workflow thật, không phân loại quá chi tiết chỉ để đẹp metadata