# Kế hoạch triển khai workflow sinh tài liệu

## 1. Mục tiêu

Tài liệu này chốt hướng triển khai workflow sinh hồ sơ thiếu trong DSCons, ưu tiên nền dữ liệu trước khi làm render DOCX.

Mục tiêu chính:

- chuẩn hóa dữ liệu đầu vào cho từng loại hồ sơ
- chuẩn hóa template và placeholder để tái sử dụng
- tách dữ liệu đã xác minh, dữ liệu gợi ý và dữ liệu phải nhập tay
- có lớp readiness và review độc lập trước khi phát hành
- giữ tương thích với codebase hiện tại, chưa giả định có DB table hay API mới

Nguyên tắc:

- làm foundation data contract trước
- không đẩy business validation xuống tầng render
- chưa thêm dependency DOCX ở giai đoạn này
- pilot trên một loại tài liệu để kiểm chứng đầu-cuối

## 2. Phạm vi pilot

### Tài liệu pilot
- `document_type = bien_ban_ban_giao_mat_bang`

### Metadata chuẩn của template pilot

| Trường | Giá trị |
| --- | --- |
| `knowledge_type` | `template_form` |
| `doc_stage` | `execution` |
| `doc_family` | `execution` |
| `document_type` | `bien_ban_ban_giao_mat_bang` |

### Pilot cần chứng minh được

- có schema đầu vào riêng cho loại hồ sơ
- có template registry ở mức metadata
- có bộ placeholder thống nhất
- có lớp mapping từ dữ liệu hiện có sang placeholder
- có confidence policy ở mức field
- có readiness và review workflow tách biệt
- có thể nối sang DOCX engine ở giai đoạn sau

### Ngoài phạm vi hiện tại

- tạo DB table mới
- tạo API route mới
- tích hợp thư viện DOCX mới
- hỗ trợ toàn bộ loại hồ sơ thiếu
- hoàn thiện quy trình production end-to-end

## 3. Trình tự triển khai bắt buộc

Không đảo thứ tự dưới đây:

1. schema dữ liệu đầu vào cho từng loại hồ sơ
2. chuẩn hóa kho mẫu cũ thành template có placeholder
3. mapping dữ liệu hiện có sang placeholder
4. phân loại field theo độ tin cậy
5. tính generation readiness
6. review workflow
7. cuối cùng mới nối DOCX engine

Lý do:

- nếu làm render trước thì placeholder dễ sai chuẩn
- business rule sẽ bị dồn xuống tầng render
- khó phân biệt bản nháp với bản đủ điều kiện phát hành
- khó mở rộng sang nhiều loại tài liệu khác

## 4. Deliverable của sprint foundation

### Deliverable chính

- tài liệu triển khai workflow sinh tài liệu
- data contract khái niệm cho các thành phần chính
- định nghĩa template registry cho pilot
- định nghĩa confidence policy
- định nghĩa readiness state
- định nghĩa review status
- định nghĩa payload pilot cho `bien_ban_ban_giao_mat_bang`

### Kết quả mong đợi

Cuối sprint foundation, hệ thống cần đạt mức:

- mô tả được đầy đủ dữ liệu cần cho pilot
- mô tả được một template dưới dạng metadata + placeholder
- biết field nào đã đủ tin cậy, field nào cần nhập tay
- tính được readiness mà chưa cần render file
- mô tả được vòng đời review ở mức dữ liệu

## 5. Kiến trúc khái niệm

Workflow nên tách thành 6 lớp logic:

| Lớp | Vai trò |
| --- | --- |
| Input payload | dữ liệu đầu vào theo từng loại hồ sơ |
| Template registry | quản lý template, version, placeholder |
| Mapping | ánh xạ dữ liệu nguồn sang placeholder |
| Field assessment | gắn confidence, warning, blocker cho từng field |
| Generation readiness | đánh giá có đủ điều kiện sinh nháp/render hay chưa |
| Review workflow | quản lý trạng thái bản nháp sau khi sinh |

DOCX rendering chỉ là lớp cuối, nhận template đã chuẩn hóa và payload đã sẵn sàng.

## 6. Data contract cần chốt

### 6.1. Template registry

Mỗi template nên có tối thiểu:

- `template_code`
- `document_type`
- `template_version`
- `knowledge_type`
- `doc_stage`
- `doc_family`
- `placeholders`
- `required_placeholders`
- `is_active`
- `notes`

Mục tiêu:

- tra cứu đúng template theo loại tài liệu
- version hóa template
- kiểm soát placeholder độc lập với file DOCX thô

### 6.2. Placeholder definition

Mỗi placeholder nên có:

- `name`
- `label`
- `required`
- `source_hint`
- `example_value`
- `minimum_confidence`

Quy ước đặt tên:

- dùng `snake_case`
- mô tả nghĩa nghiệp vụ
- không gắn với vị trí hiển thị trong file

Placeholder khởi tạo cho pilot:

- `document_title`
- `document_number`
- `project_name`
- `site_name`
- `handover_date`
- `handover_location`
- `transferor_org_name`
- `transferor_org_address`
- `transferor_signatory_full_name`
- `transferor_signatory_title`
- `recipient_org_name`
- `recipient_org_address`
- `recipient_signatory_full_name`
- `recipient_signatory_title`
- `handover_scope_summary`
- `handover_notes`
- `legal_basis_summary`

### 6.3. Generation field status

Mỗi field sau khi mapping nên có:

- `field_name`
- `placeholder_name`
- `value`
- `is_required`
- `confidence`
- `source_reference`
- `needs_manual_input`
- `review_note`
- `is_ready`

Mục đích:

- giải thích vì sao field đạt hoặc không đạt readiness
- làm nền cho UI/API sau này
- hỗ trợ audit và review

### 6.4. Generation readiness

Object readiness nên có:

- `status`
- `missing_required_fields`
- `manual_input_required_fields`
- `review_required_fields`
- `warnings`
- `summary`

### 6.5. Review workflow status

Object review nên có:

- `status`
- `reviewer_id` hoặc `reviewer_name`
- `reviewed_at`
- `revision_note`
- `issued_at`
- `issue_reference`

### 6.6. Payload pilot

Payload cho `bien_ban_ban_giao_mat_bang` cần biểu diễn được:

- metadata tài liệu
- dự án/công trình/gói thầu
- thông tin biên bản bàn giao
- bên giao
- bên nhận
- người đại diện ký
- thời gian và địa điểm bàn giao
- phạm vi hoặc nội dung bàn giao
- ghi chú hoặc căn cứ
- metadata generation nội bộ nếu có

## 7. Mapping và confidence policy

### Nguyên tắc mapping

Mapping phải là lớp trung gian giữa dữ liệu nghiệp vụ và template:

- không bind trực tiếp object business thô vào file
- theo dõi được nguồn dữ liệu và fallback
- cho phép gắn confidence theo từng field

### Các nguồn dữ liệu

| Nguồn | Ý nghĩa |
| --- | --- |
| nguồn xác minh trực tiếp | lấy từ hồ sơ hoặc dữ liệu đã xác minh |
| nguồn gợi ý | lấy từ template tương tự hoặc dữ liệu gần đúng |
| nguồn nhập tay | hệ thống chưa có hoặc không nên tự suy diễn |

### Bảng mapping khởi tạo cho pilot

| Placeholder | Nguồn dự kiến | Ghi chú |
| --- | --- | --- |
| `project_name` | metadata dự án/hồ sơ | ưu tiên dữ liệu chính thức |
| `site_name` | thông tin công trình/địa điểm | thiếu thì nhập tay |
| `handover_date` | dữ liệu biên bản hoặc lịch thực hiện | suy diễn không coi là verified |
| `handover_location` | địa điểm công trình hoặc nơi ký | có thể cần reviewer xác nhận |
| `transferor_org_name` | dữ liệu tổ chức bên giao | ưu tiên hồ sơ pháp lý |
| `recipient_org_name` | dữ liệu tổ chức bên nhận | tương tự bên giao |
| `transferor_signatory_full_name` | dữ liệu người ký/đại diện | chưa chốt thì manual |
| `recipient_signatory_full_name` | dữ liệu người ký/đại diện | chưa xác định thì manual |
| `handover_scope_summary` | mô tả phạm vi bàn giao | có thể là text nhập tay |
| `handover_notes` | ghi chú bổ sung | thường là nhập tay |

### Mức confidence dùng trong pilot

- `verified_from_source`
- `suggested_from_similar_template`
- `manual_input_required`

### Quy tắc tối thiểu

- field bắt buộc + `manual_input_required` => `not_ready`
- field bắt buộc + `suggested_from_similar_template` => tối thiểu `review_required`
- field bắt buộc + `verified_from_source` => có thể đạt readiness
- field không bắt buộc + `manual_input_required` => warning hoặc để trống theo policy template

## 8. Generation readiness

### Trạng thái readiness

- `not_ready`
- `draft_ready`
- `review_required`
- `ready_for_render`

### Logic tính readiness đề xuất

1. thiếu field bắt buộc -> `not_ready`
2. có field bắt buộc `manual_input_required` -> `not_ready`
3. có field bắt buộc cần reviewer xác nhận -> `review_required`
4. còn warning không chặn -> `draft_ready`
5. mọi điều kiện bắt buộc đều đạt -> `ready_for_render`

### Lưu ý

- readiness không đồng nghĩa với phê duyệt nghiệp vụ
- một tài liệu có thể `ready_for_render` nhưng review vẫn chưa xong

## 9. Review workflow

### Trạng thái review

- `draft_generated`
- `awaiting_review`
- `needs_revision`
- `approved_for_issue`
- `issued`

### Nguyên tắc

- review tách biệt với readiness
- không dùng trạng thái `issued` nếu field bắt buộc vẫn còn phải nhập tay
- bản sinh tự động mặc định là bản nháp cho tới khi có người review

## 10. Roadmap 3 giai đoạn

### Giai đoạn 1 - Foundation dữ liệu và workflow

Mục tiêu:

- chốt data contract
- chốt schema/model nền
- chốt metadata template registry
- chốt confidence/readiness/review convention
- chốt payload pilot

Đầu ra:

- mô tả được đầy đủ dữ liệu của một biên bản bàn giao mặt bằng
- đánh giá được readiness mà chưa cần render file

### Giai đoạn 2 - Mapping và draft generation nội bộ

Mục tiêu:

- ánh xạ dữ liệu hiện có sang placeholder
- sinh field status cho từng placeholder
- tạo draft payload hoàn chỉnh cho pilot
- cho reviewer thấy field nào verified, suggested, manual

Đầu ra:

- có object draft generation nhất quán cho pilot
- có thể dùng cho service nội bộ hoặc UI sau này

### Giai đoạn 3 - Render engine và phát hành có kiểm soát

Mục tiêu:

- nối template registry với DOCX rendering
- chỉ render khi readiness đạt policy
- đồng bộ với review workflow
- chuẩn hóa đầu ra để hỗ trợ phát hành nội bộ

Đầu ra:

- có thể sinh file từ template pilot
- có kiểm soát trước khi render
- phân tách rõ draft, review và issued

## 11. Rủi ro chính và cách giảm thiểu

| Rủi ro | Tác động | Giảm thiểu |
| --- | --- | --- |
| dữ liệu nguồn không đồng nhất | field map sai hoặc thiếu | dùng mapping riêng, lưu `source_reference`, áp confidence theo field |
| template cũ khó chuẩn hóa | placeholder lẫn trong text cứng, khó version | chọn 1 template pilot rõ ràng, chuẩn hóa thủ công trước |
| nhầm giữa “sinh được” và “phát hành được” | bản nháp bị dùng như bản cuối | tách readiness khỏi review, khóa `issued` khi còn blocker |
| người ký hoặc nội dung thực địa không chắc chắn | rủi ro pháp lý | bắt buộc manual/review với các field nhạy cảm |

## 12. Backlog / next steps

Ưu tiên tiếp theo:

1. chốt schema payload pilot cho `bien_ban_ban_giao_mat_bang`
2. chốt danh sách placeholder và naming convention
3. chọn 1 template cũ làm bản pilot chính
4. lập bảng mapping field -> nguồn dữ liệu -> confidence
5. định nghĩa object readiness và review status ở mức model/tài liệu
6. chỉ sau đó mới đánh giá nhu cầu nối DOCX engine

## 13. Kết luận

Hướng phù hợp cho DSCons là làm foundation dữ liệu và workflow trước, không bắt đầu bằng DOCX engine. Với pilot `bien_ban_ban_giao_mat_bang`, nhóm có thể kiểm chứng đầy đủ chuỗi:

- schema đầu vào
- template registry
- mapping dữ liệu
- confidence policy
- generation readiness
- review workflow

Khi các lớp này ổn định, việc bổ sung DOCX engine sẽ ít rủi ro hơn và dễ mở rộng sang các loại hồ sơ thiếu khác.