# Data dictionary TT91 cho ingest DSCons

## 1. Mục tiêu

Tài liệu này tóm tắt các trường dữ liệu nên dùng khi xử lý bộ hồ sơ `TT91` trong cụm `ingest-knowledge`.

Mục tiêu chính:

- thống nhất cách hiểu dữ liệu trước khi ingest
- hỗ trợ map từ file gốc sang metadata chuẩn của DSCons
- giúp đội vận hành điền trường ngắn gọn, đúng ý
- giảm tình trạng mỗi file dùng một kiểu tên trường khác nhau

## 2. Phạm vi

Áp dụng cho:

- file manifest hoặc bảng rà soát hồ sơ TT91
- metadata đi kèm hồ sơ trước khi ingest vào Qdrant
- bước kiểm tra chất lượng dữ liệu đầu vào

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

- thay cho schema JSON
- thay cho bảng log công việc nhân sự
- mô tả dữ liệu tác nghiệp trong PostgreSQL

## 3. Cách dùng nhanh

Khi xử lý một hồ sơ TT91, đi theo thứ tự:

1. xác định công trình hoặc bộ hồ sơ gắn với file
2. ghi rõ file nguồn và định dạng
3. xác định `task_type`, `knowledge_type`, `document_type`
4. bổ sung các trường ngữ cảnh như gói thầu, đợt thanh toán, số quyết định
5. kiểm tra phiên bản và chất lượng file
6. quyết định có ingest hay chưa

## 4. Nhóm trường cốt lõi

### 4.1 Nhóm nhận diện nguồn

| Trường | Bắt buộc | Ý nghĩa |
| --- | --- | --- |
| `project_code` | có | mã công trình hoặc mã bộ hồ sơ |
| `project_name` | nên có | tên hiển thị của công trình |
| `package_code` | nên có | mã gói nếu hồ sơ gắn theo gói |
| `package_name` | nên có | tên gói để người vận hành dễ đọc |
| `contract_code` | nên có | mã hợp đồng nếu có |
| `source_file` | có | tên file hoặc đường dẫn gốc |
| `source_pages` | nên có | trang nguồn khi chia chunk |
| `source_format` | nên có | pdf, docx, xlsx, scan, image |

### 4.2 Nhóm phân loại tri thức

| Trường | Bắt buộc | Ý nghĩa |
| --- | --- | --- |
| `task_type` | có | hồ sơ phục vụ bài toán gì |
| `knowledge_type` | có | hồ sơ thuộc miền tri thức nào |
| `document_type` | có | đây là loại tài liệu cụ thể nào |
| `doc_family` | nên có | nhóm hồ sơ lớn như pháp lý, hợp đồng, thanh toán |
| `doc_stage` | nên có | giai đoạn như nháp, ký, hoàn công, quyết toán |

### 4.3 Nhóm truy vết pháp lý và nghiệp vụ

| Trường | Khi dùng |
| --- | --- |
| `issue_date` | có ngày ban hành hoặc ngày ký |
| `effective_date` | cần tách ngày hiệu lực |
| `decision_no` | có số quyết định hoặc số văn bản |
| `agency_name` | có cơ quan ban hành hoặc chủ đầu tư |
| `legal_basis` | cần ghi căn cứ pháp lý |
| `revision` | có nhiều phiên bản |
| `section_title` | cần bám theo mục/chương khi chunk |

### 4.4 Nhóm thanh toán, quyết toán, kiểm toán

| Trường | Khi dùng |
| --- | --- |
| `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 hoặc giải trình |
| `cost_item_code` | cần gắn mã chi phí |
| `work_item_code` | cần gắn mã công việc hoặc hạng mục |

## 5. Cách hiểu 3 trường phân loại chính

| Trường | Câu hỏi nó trả lời |
| --- | --- |
| `task_type` | hồ sơ này phục vụ workflow gì trong DSCons |
| `knowledge_type` | hồ sơ này thuộc miền tri thức nào để retrieval |
| `document_type` | tên loại tài liệu cụ thể là gì |

Nguyên tắc:

- không dùng 3 trường này thay thế cho nhau
- `task_type` để route workflow
- `knowledge_type` để gom retrieval
- `document_type` để gọi đúng tên hồ sơ

## 6. Bộ giá trị khuyến nghị cho TT91

### 6.1 `task_type`

| Giá trị | Khi dùng |
| --- | --- |
| `legal_compliance` | quyết định, văn bản pháp lý, căn cứ |
| `procurement_tender` | hồ sơ lựa chọn nhà thầu |
| `contract_management` | hợp đồng, phụ lục, điều chỉnh |
| `technical_delivery` | bản vẽ, nhật ký, nghiệm thu, hồ sơ chất lượng |
| `payment_settlement` | thanh toán, quyết toán |
| `audit_inspection` | kiểm toán, thanh tra, giải trình |

### 6.2 `knowledge_type`

| Giá trị | Khi dùng |
| --- | --- |
| `decision_document` | quyết định, phê duyệt |
| `project_approval` | hồ sơ phê duyệt dự án |
| `procurement_plan` | kế hoạch lựa chọn nhà thầu |
| `bidding_document` | hồ sơ mời thầu, hồ sơ dự thầu |
| `contract_document` | hợp đồng |
| `contract_appendix` | phụ lục hợp đồng |
| `construction_diary` | nhật ký thi công |
| `acceptance_record` | biên bản nghiệm thu |
| `as_built_record` | hồ sơ hoàn công |
| `payment_dossier` | hồ sơ thanh toán |
| `interim_payment` | phụ lục/bảng giá trị thanh toán đợt |
| `settlement_dossier` | hồ sơ quyết toán |
| `audit_report` | báo cáo kiểm toán |
| `template_form` | biểu mẫu, form chuẩn |

### 6.3 `document_type`

| Giá trị | Ví dụ |
| --- | --- |
| `quyet_dinh_phe_duyet` | quyết định phê duyệ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_thuong_thao` | biên bản thương thảo |
| `hop_dong` | hợp đồng chính |
| `phu_luc_hop_dong` | phụ lục hợp đồng |
| `nhat_ky_thi_cong` | nhật ký thi công |
| `bien_ban_nghiem_thu` | biên bản nghiệm thu |
| `de_nghi_thanh_toan` | đề nghị thanh toán |
| `bang_xac_dinh_gia_tri_khoi_luong` | bảng 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 |

## 7. Quy ước điền trường thực dụng

### 7.1 Định dạng chung

- dùng `snake_case` cho giá trị taxonomy
- giữ tiếng Việt không dấu cho `document_type` khi cần tạo mới
- ngày theo chuẩn `YYYY-MM-DD`
- tên file giữ nguyên như nguồn nếu chưa cần chuẩn hóa
- không bỏ trống `source_file`

### 7.2 Khi chưa chắc chắn

- nếu chưa rõ bản hiệu lực, dùng `doc_stage` hoặc `revision` để ghi chú
- nếu chưa rõ loại tài liệu, chọn loại gần nhất và thêm `notes`
- nếu OCR kém, chưa nên ingest ngay
- nếu thiếu trang hoặc thiếu ký, phải ghi rõ trong manifest

### 7.3 Khi có nhiều phiên bản

Ưu tiên tách rõ:

- bản nháp
- bản ký
- bản điều chỉnh
- bản scan lại

Không gộp nhiều phiên bản vào một record nếu có thể tách riêng.

## 8. Map nhanh theo nhóm hồ sơ thường gặp

| Nhóm hồ sơ | `task_type` | `knowledge_type` | `document_type` gợi ý |
| --- | --- | --- | --- |
| Pháp lý | `legal_compliance` | `decision_document` | `quyet_dinh_phe_duyet` |
| Đấu thầu | `procurement_tender` | `procurement_plan`, `bidding_document` | `ke_hoach_lua_chon_nha_thau`, `ho_so_moi_thau` |
| Hợp đồng | `contract_management` | `contract_document`, `contract_appendix` | `hop_dong`, `phu_luc_hop_dong` |
| Thi công | `technical_delivery` | `construction_diary` | `nhat_ky_thi_cong` |
| Nghiệm thu | `technical_delivery` | `acceptance_record` | `bien_ban_nghiem_thu` |
| Thanh toán | `payment_settlement` | `payment_dossier`, `interim_payment` | `de_nghi_thanh_toan`, `bang_xac_dinh_gia_tri_khoi_luong` |
| Quyết toán | `payment_settlement` | `settlement_dossier` | `ho_so_quyet_toan` |
| Kiểm toán | `audit_inspection` | `audit_report` | `bao_cao_kiem_toan` |

## 9. Mẫu metadata tối thiểu cho TT91

```json
{
  "project_code": "TT91-001",
  "project_name": "Bộ hồ sơ TT91",
  "source_file": "TT91/Ho so thanh toan dot 1.pdf",
  "task_type": "payment_settlement",
  "knowledge_type": "payment_dossier",
  "document_type": "de_nghi_thanh_toan",
  "issue_date": "2025-10-01",
  "payment_stage": "dot_01",
  "schema_version": "1.0"
}
```

## 10. Checklist trước khi ingest

- [ ] Có `project_code`
- [ ] Có `source_file`
- [ ] Đã chọn `task_type`, `knowledge_type`, `document_type`
- [ ] Đã phân biệt bản nháp và bản hiệu lực
- [ ] Đã kiểm tra file có đọc được hay cần OCR
- [ ] Đã ghi thêm `payment_stage`, `settlement_stage` hoặc `audit_focus` nếu cần
- [ ] Không trộn hồ sơ tri thức với log vận hành

## 11. Rủi ro hay gặp

| Rủi ro | Hậu quả | Cách xử lý |
| --- | --- | --- |
| thiếu `source_file` | không truy ngược được hồ sơ gốc | bắt buộc điền trước khi ingest |
| chọn sai `document_type` | retrieval lệch ngữ cảnh | map theo taxonomy chuẩn, soát lại file quan trọng |
| gộp nhiều phiên bản vào một record | AI trích sai bản | tách record và ghi `revision` |
| file scan mờ | chunk lỗi, OCR sai | đánh dấu cần OCR và xử lý trước |
| lẫn dữ liệu tác nghiệp với knowledge | khó bảo trì, khó truy vấn | bám ranh giới trong `workflow.md` |

## 12. Nguyên tắc vận hành

- ưu tiên dữ liệu thật, không dùng nhãn demo
- metadata phải ngắn gọn nhưng đủ để lọc
- cùng một nhóm hồ sơ nên dùng cùng bộ giá trị taxonomy
- mọi ingest cần rerunnable và truy vết được
- nếu chưa chắc chắn, ghi rõ trạng thái thay vì đoán

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

Data dictionary TT91 là bảng quy ước nhẹ để đội DSCons:

- hiểu cùng một ngôn ngữ metadata
- điền trường nhất quán trước khi ingest
- giảm sai lệch giữa manifest, taxonomy và pipeline ingest
- giữ cụm `ingest-knowledge` gọn, thực dụng và dễ dùng hằng ngày