# Workflow review hồ sơ

Tài liệu này mô tả workflow review hồ sơ trong DSCons theo hướng ngắn gọn, dễ triển khai và đồng bộ với `workflow.md` cùng `docs/next-steps-five-data-flows.md`.

## 1. Mục tiêu

Workflow review hồ sơ dùng để:

- xác định hồ sơ đã có, còn thiếu, thiếu ở mức nào
- chỉ ra đầu mục đang chặn readiness
- giao đúng bộ phận hoặc người phụ trách bổ sung
- theo dõi vòng lặp review -> bổ sung -> xác minh lại
- lưu lại blocker, warning, next action và dấu vết xử lý

## 2. Vị trí của workflow này trong DSCons

Workflow review hồ sơ nằm giữa 4 lớp dữ liệu:

| Lớp | Vai trò trong review hồ sơ |
| --- | --- |
| Hồ sơ công trình | cung cấp tài liệu gốc để đối chiếu |
| Manifest và gap analysis | cung cấp trạng thái hồ sơ, missing item, next action ban đầu |
| Con người và vai trò | xác định đúng bộ phận, đúng người phụ trách |
| Nhật ký nhân sự / vận hành | ghi lại phiên review, hành động, xác minh và follow-up |

Nói ngắn gọn:

- Qdrant giữ bối cảnh hồ sơ và gap analysis
- PostgreSQL giữ trạng thái review và vận hành follow-up
- reviewer là người chốt kết luận cuối cùng
- AI chỉ hỗ trợ phát hiện, gom evidence và gợi ý next action

## 3. Contract API typed đang chạy thực tế

Workflow dossier review hiện không còn nhận payload `dict` mơ hồ ở route layer. Các endpoint chính đã dùng schema typed trong `app/models/schemas.py`.

### 3.1. Tạo review session
`POST /v1/dossiers/reviews`

Payload tối thiểu:
- `project_code`
- `project_name`

Field chính:
- `dossier_scope` mặc định `project_dossier`
- `trigger_source` mặc định `manual`
- `initiated_by_employee_code`
- `lead_reviewer_employee_code`
- `lead_agent_code`
- `status` mặc định `draft`
- `review_reason`
- `review_summary`
- `assigned_departments`
- `metadata`

### 3.2. Tạo finding
`POST /v1/dossiers/reviews/{review_id}/findings`

Field chính:
- `finding_code`
- `finding_group`
- `finding_type`
- `title`
- `description`
- `document_type`
- `dossier_stage`
- `severity` mặc định `medium`
- `impact_level` mặc định `medium`
- `responsible_department_code` mặc định `synthesis`
- `supplement_status` mặc định `requested`
- `status` mặc định `open`
- `is_blocking`
- `due_date`
- `source_snapshot_id`
- `evidences`
- `metadata`

### 3.3. Giao assignment
`POST /v1/dossiers/reviews/{review_id}/findings/{finding_id}/assignments`

Field chính:
- `assigned_department_code`
- `assigned_employee_code`
- `assigned_by_employee_code`
- `status` mặc định `pending`
- `priority` mặc định `medium`
- `due_date`
- `assignment_note`
- `metadata`

### 3.4. Nộp bổ sung
`POST /v1/dossiers/reviews/{review_id}/findings/{finding_id}/assignments/{assignment_id}/submissions`

Field chính:
- `submission_type` mặc định `document_bundle`
- `submitted_by_employee_code`
- `submission_note`
- `attachment_count`
- `submitted_payload`
- `metadata`

### 3.5. Verify bổ sung
`POST /v1/dossiers/reviews/{review_id}/findings/{finding_id}/assignments/{assignment_id}/verify`

Field chính:
- `verification_result` mặc định `accepted`
- `verification_note`
- `verified_by_employee_code`
- `resolution_note`
- `verification_snapshot`
- `metadata`

Lưu ý:
- `assignment_id` đi theo path, không phải field bắt buộc của request body route-level
- `submission_id` hiện không nằm trong schema body route-level này

### 3.6. Đóng review session
`POST /v1/dossiers/reviews/{review_id}/close`

Field chính:
- `closure_note`
- `force_close_open_findings`
- `metadata`

### 3.7. Khởi chạy workflow persisted
`POST /v1/workflows/dossier-review/start`

Field chính:
- `project_code`
- `lead_agent_code`
- `lead_reviewer_employee_code`
- `initiated_by_employee_code`
- `dossier_scope` mặc định `project_dossier`
- `trigger_source` mặc định `system_proactive_review`
- `status` mặc định `in_review`
- `review_reason`
- `review_summary`
- `assigned_departments`
- `baseline_snapshot`
- `findings`
- `review_actions`
- `participating_employees`
- `metadata`

`initiated_by_employee_code` sẽ tự fill từ `lead_reviewer_employee_code` nếu bị bỏ trống.

Lưu ý hardening hiện tại:
- nếu workflow persisted đã lưu thành công nhưng bước enrichment operational state phía sau bị lỗi, response vẫn ưu tiên trả workflow payload đã persist được
- phần operational snapshot trong response sẽ degrade an toàn với metadata báo rõ dependency nào đang unavailable, thay vì làm fail toàn bộ API sau khi side effect chính đã hoàn tất

## 4. Đầu vào

Một phiên review hồ sơ thường nhận các đầu vào sau:

### Hồ sơ và tri thức nền
- hồ sơ công trình đã ingest
- manifest hồ sơ
- gap analysis
- readiness hiện tại của dự án
- metadata như `project_code`, `document_type`, `doc_stage`, `source_file`

### Bối cảnh vận hành
- người yêu cầu review
- lý do review:
  - review định kỳ
  - chuẩn bị nghiệm thu / thanh toán / quyết toán
  - phát hiện thiếu hồ sơ
  - xác minh sau bổ sung
- danh sách người hoặc bộ phận liên quan

### Đầu vào do AI hỗ trợ
- danh sách missing item gợi ý
- mức độ tin cậy
- evidence trích từ tài liệu
- gợi ý blocker, warning, next action

## 5. Đầu ra

Sau một vòng review, hệ thống cần trả được các đầu ra rõ ràng:

| Nhóm đầu ra | Nội dung chính |
| --- | --- |
| Trạng thái phiên review | đang review, chờ bổ sung, đã xác minh, đã đóng |
| Findings | từng đầu mục thiếu, lệch, chưa đủ căn cứ |
| Blocker | mục chặn readiness hoặc chặn bước nghiệp vụ kế tiếp |
| Warning | mục chưa chặn ngay nhưng có rủi ro hoặc cần theo dõi |
| Next action | việc cần làm tiếp theo, giao cho ai, hạn khi nào |
| Snapshot | ảnh chụp trạng thái hồ sơ tại thời điểm review |
| Audit log | ai review, ai giao việc, ai xác minh, thay đổi gì |

## 6. Vai trò trong workflow

### Reviewer
Reviewer là người chịu trách nhiệm nghiệp vụ của phiên review.

Nhiệm vụ chính:
- đọc kết quả AI và hồ sơ gốc
- xác nhận finding nào hợp lệ
- phân loại blocker và warning
- quyết định có giao bổ sung hay không
- xác minh hồ sơ nộp lại
- chốt trạng thái phiên review

### AI / agent hỗ trợ
AI không thay reviewer, chỉ hỗ trợ:

- gom tài liệu liên quan
- phát hiện hồ sơ thiếu hoặc yếu
- trích evidence
- gợi ý bộ phận phụ trách
- gợi ý readiness impact và next action

### Bộ phận hoặc người được giao bổ sung
Vai trò này nhận assignment để:

- bổ sung tài liệu
- giải trình nếu hồ sơ chưa thể có ngay
- nộp lại để reviewer xác minh

## 7. Các trạng thái chính

### Trạng thái phiên review

| Trạng thái | Ý nghĩa | Khi nào dùng |
| --- | --- | --- |
| `draft` | mới tạo, chưa review thật | vừa khởi tạo phiên |
| `in_review` | đang rà soát hồ sơ | reviewer hoặc agent đang xử lý |
| `awaiting_assignment` | đã có finding nhưng chưa giao việc | cần chốt người/bộ phận phụ trách |
| `assigned` | đã giao bổ sung | đang chờ bộ phận xử lý |
| `partially_resolved` | đã xử lý được một phần | còn finding mở |
| `resolved` | mọi finding chính đã đạt | sẵn sàng đóng phiên |
| `closed` | kết thúc phiên review | hoàn tất lưu vết |
| `cancelled` | hủy phiên | không tiếp tục xử lý |

### Trạng thái finding

| Trạng thái | Ý nghĩa |
| --- | --- |
| `open` | mới phát hiện, chưa xử lý |
| `assigned` | đã giao phụ trách |
| `in_progress` | đang bổ sung hoặc giải trình |
| `pending_verification` | đã nộp lại, chờ reviewer kiểm tra |
| `resolved` | đã đạt yêu cầu |
| `waived` | chấp nhận bỏ qua có lý do |
| `rejected` | kết luận trước đó không hợp lệ hoặc evidence không đủ |

### Trạng thái mức độ ảnh hưởng

Nên chuẩn hóa tối thiểu theo 2 nhóm:

- `blocker`: chặn readiness hoặc chặn bước nghiệp vụ kế tiếp
- `warning`: chưa chặn ngay nhưng cần theo dõi

## 8. Blocker và warning

### Khi nào là blocker
Một finding nên được đánh dấu blocker nếu thuộc một trong các trường hợp:

- thiếu hồ sơ bắt buộc cho bước đang chuẩn bị thực hiện
- thiếu hồ sơ pháp lý hoặc nghiệm thu quan trọng
- thiếu hồ sơ khiến readiness chưa thể đạt mức dùng được
- hồ sơ có nhưng là bản nháp, bản scan yếu hoặc không đủ căn cứ
- có mâu thuẫn dữ liệu giữa manifest, gap analysis và hồ sơ gốc chưa được giải quyết

### Khi nào là warning
Một finding nên là warning nếu:

- hồ sơ chưa đủ đẹp nhưng chưa chặn bước hiện tại
- còn thiếu bản ký chính thức nhưng đã có bản nháp để theo dõi tạm
- metadata chưa chuẩn hoặc thiếu thông tin truy vết
- cần bổ sung để hoàn thiện hồ sơ về sau

### Quy tắc thực dụng
- blocker ảnh hưởng trực tiếp đến readiness hoặc mốc nghiệp vụ
- warning ảnh hưởng đến độ hoàn chỉnh và khả năng truy vết
- reviewer là người chốt cuối cùng, không để AI tự quyết định hoàn toàn

## 9. Next action

Mỗi finding sau review nên có `next action` rõ ràng, gồm tối thiểu:

| Trường | Ý nghĩa |
| --- | --- |
| việc cần làm | bổ sung gì hoặc xác minh gì |
| người/bộ phận phụ trách | ai phải xử lý |
| lý do | vì sao việc này cần làm |
| deadline | khi nào cần xong |
| điều kiện hoàn thành | thế nào được coi là đạt |

Ví dụ next action:
- bổ sung biên bản nghiệm thu hoàn thành có chữ ký và dấu
- đối chiếu lại hồ sơ thanh toán đợt 2 với bảng khối lượng
- xác nhận quyết định phê duyệt đang là bản scan ký hay chỉ là bản nháp

## 10. Quan hệ với readiness

Workflow review hồ sơ không tách rời readiness.

### Review dùng readiness để ưu tiên
Readiness giúp reviewer biết:

- bước nghiệp vụ nào đang bị chặn
- nhóm hồ sơ nào ảnh hưởng mạnh nhất
- mục nào là critical missing cần xử lý trước

### Review cập nhật ngược vào readiness
Sau mỗi vòng review hoặc xác minh lại:

- finding đã đạt có thể giảm số lượng missing item
- blocker được gỡ có thể nâng trạng thái readiness
- finding mới có thể làm readiness giảm hoặc chuyển sang blocked
- nếu coverage/remediation lookup bị thiếu manifest hoặc thiếu đúng `project_code`, service nên ưu tiên trả degraded-safe fallback response có shape ổn định để reviewer vẫn thấy được trạng thái hữu ích

### Quy tắc liên kết
- readiness là trạng thái tổng quan
- review session là vòng xử lý cụ thể
- finding là đơn vị chi tiết để giải thích vì sao readiness đang như vậy

## 11. Quan hệ với gap analysis

Gap analysis là đầu vào quan trọng của workflow review.

### Gap analysis cung cấp
- danh sách hồ sơ đã có và còn thiếu
- mức độ thiếu
- ghi chú bối cảnh
- next action sơ bộ

### Review làm rõ lại gap analysis
Review bổ sung các phần mà gap analysis chưa chốt được:

- missing item nào là blocker thật
- bộ phận nào chịu trách nhiệm chính
- evidence nào đủ mạnh
- finding nào cần giao việc ngay
- finding nào chỉ cần theo dõi

### Cách hiểu đơn giản
- gap analysis trả lời: đang thiếu gì
- review workflow trả lời: thiếu gì, ảnh hưởng thế nào, ai xử lý, xử lý đến đâu

## 12. Luồng xử lý chuẩn

### Bước 1 - Tạo phiên review
- khởi tạo review theo dự án hoặc scope hồ sơ
- nạp readiness hiện tại
- nạp manifest và gap analysis liên quan
- chụp snapshot baseline

**Đầu ra**
- phiên review ở trạng thái `draft` hoặc `in_review`
- có snapshot ban đầu để đối chiếu

### Bước 2 - Rà soát và tạo finding
- reviewer và AI đọc hồ sơ, manifest, gap analysis
- tạo từng finding riêng
- gắn evidence, mức độ ảnh hưởng và gợi ý người phụ trách
- xác định blocker hay warning

**Đầu ra**
- danh sách finding
- danh sách blocker
- danh sách warning

### Bước 3 - Giao việc bổ sung
- chọn bộ phận hoặc người phụ trách
- gắn deadline
- ghi rõ điều kiện hoàn thành
- chuyển finding sang trạng thái có assignment

**Đầu ra**
- assignment cho từng finding cần xử lý
- next action rõ ràng

### Bước 4 - Bộ phận phụ trách bổ sung hoặc giải trình
- nộp tài liệu mới
- nộp bản thay thế
- gửi giải trình nếu chưa thể bổ sung đủ

**Đầu ra**
- submission hoặc note giải trình
- trạng thái finding chuyển sang `pending_verification` khi đã nộp lại

### Bước 5 - Reviewer xác minh lại
- kiểm tra hồ sơ bổ sung
- đối chiếu với điều kiện hoàn thành
- quyết định accepted, insufficient hoặc rejected
- cập nhật snapshot mới và readiness nếu cần

**Đầu ra**
- finding `resolved` nếu đạt
- finding quay lại `in_progress` hoặc assignment `returned` nếu chưa đạt

### Bước 6 - Đóng phiên
- khi không còn blocker mở hoặc đã chốt lý do waiver
- cập nhật tổng kết phiên review
- lưu đầy đủ audit log

**Đầu ra**
- phiên review `resolved` hoặc `closed`
- có tổng kết rõ hồ sơ còn thiếu gì và bước tiếp theo là gì

## 13. Snapshot và audit log

### Snapshot nên lưu gì
Mỗi snapshot nên giữ tối thiểu:

- thời điểm chụp
- trạng thái readiness
- danh sách missing item chính
- blocker đang mở
- warning đang mở
- next action đang hiệu lực

### Audit log nên ghi gì
Mọi thay đổi quan trọng nên có log:

- tạo phiên review
- tạo hoặc sửa finding
- đánh dấu blocker / warning
- giao việc
- nộp bổ sung
- xác minh kết quả
- đóng phiên review

Mục đích:
- truy vết được ai làm gì
- giải thích được vì sao readiness thay đổi
- hỗ trợ follow-up và kiểm toán nội bộ

## 14. Gợi ý cấu trúc dữ liệu tối thiểu

Nếu chuẩn hóa vào PostgreSQL, workflow này nên có các nhóm bản ghi sau:

| Nhóm | Mục đích |
| --- | --- |
| review session | đại diện một vòng review |
| finding | đại diện một thiếu sót hoặc điểm cần xác minh |
| evidence | căn cứ cho finding |
| assignment | giao việc cho bộ phận hoặc nhân sự |
| submission | lần nộp bổ sung hoặc giải trình |
| snapshot | ảnh chụp trạng thái hồ sơ |
| action log | audit trail của toàn bộ workflow |

Tên bảng có thể giữ theo cụm `dossier_review_*` để đồng bộ với các bảng vận hành khác.

## 15. Quy tắc gán người phụ trách

Khi xác định người hoặc bộ phận xử lý, nên ưu tiên theo thứ tự:

1. bộ phận chính chịu trách nhiệm loại hồ sơ đó
2. người đang phụ trách dự án hoặc giai đoạn liên quan
3. đầu mối tổng hợp nếu finding liên quan nhiều bên
4. reviewer chỉ giữ vai trò xác minh, không ôm phần bổ sung thay bộ phận

Nếu chưa xác định được đúng người:
- vẫn phải gán được bộ phận
- không để finding ở trạng thái mở nhưng vô chủ
- cho phép escalated về đầu mối tổng hợp hoặc follow-up

## 16. Kết quả mà workflow này phải trả lời được

Một workflow review hồ sơ tốt phải trả lời được 6 câu hỏi:

1. dự án đang thiếu hồ sơ gì
2. mục nào là blocker, mục nào chỉ là warning
3. readiness đang bị ảnh hưởng ra sao
4. ai phải bổ sung hoặc giải trình
5. bước tiếp theo là gì
6. sau khi bổ sung thì tình trạng đã thay đổi thế nào

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

Workflow review hồ sơ là lớp nối giữa:

- tri thức hồ sơ trong Qdrant
- trạng thái readiness và gap analysis
- người phụ trách ngoài thực tế
- dữ liệu vận hành trong PostgreSQL

Nếu làm đúng, DSCons không chỉ biết hồ sơ thiếu gì, mà còn biết:

- thiếu đó có chặn việc hay không
- ai phải xử lý
- xử lý đến đâu
- khi nào có thể nâng readiness và chuyển sang bước tiếp theo