# Rà soát full flow dossier review: `start -> assign -> submit -> verify -> close`

Tài liệu này tổng hợp hiện trạng API, khả năng automation, các khoảng trống và thứ tự vá cho chu trình dossier review end-to-end trong DSCons.

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

DSCons hiện **đã có gần đủ persistence primitives và API lifecycle** để chạy chu trình:

- start
- assign
- submit
- verify
- close

Hệ thống cũng đã có một **điểm vào orchestration mạnh** là:

- `POST /v1/workflows/dossier-review/start`

Endpoint này không chỉ tạo review session, mà trong điều kiện phù hợp còn có thể:
- tạo findings
- auto-assign
- auto-submit
- auto-verify
- auto-close
- ghi employee logs
- trả `WorkflowReviewRunSummary`

Tuy nhiên, hệ thống **chưa đạt mức full autonomous flow không cần thao tác tay** vì còn thiếu:

1. contract typed ổn định ở vài bước raw
2. summary step-by-step đủ tốt cho machine handoff
3. durable next actions sau close
4. resumable executors cho review đang dở dang
5. trigger định kỳ / event-driven
6. script chẩn đoán end-to-end có assertion chặt

---

## 2. API hiện có cho lifecycle

## 2.1. START

### API thật
- `POST /v1/workflows/dossier-review/start`

### Request schema
- `WorkflowReviewStartRequest`

### Response schema
- `WorkflowReviewRunSummary`

### Chức năng
- policy evaluation
- tạo review session
- persist baseline snapshot nếu có
- tạo findings
- auto-assign nếu payload/policy cho phép
- auto-submit nếu payload/policy cho phép
- auto-verify nếu payload/policy cho phép
- auto-close nếu điều kiện đủ
- persist employee logs
- build `next_actions`
- build `policy_checks`

### Nhận định
Đây là **autonomous entrypoint tốt nhất hiện có**.

---

## 2.2. ASSIGN

### API thật
- `POST /v1/dossiers/reviews/{review_id}/findings/{finding_id}/assignments`

### Request schema
- `WorkflowReviewAssignmentRequest`

### Response schema
- `DossierReviewSessionRecord`

### Chức năng
- tạo assignment dưới finding
- refresh full session
- tạo nền cho submit/verify tiếp theo

### Nhận định
- assign đã có API thật
- đồng thời có logic auto-assign trong `WorkflowPersistenceService`

---

## 2.3. SUBMIT

### API thật
- `POST /v1/dossiers/reviews/{review_id}/findings/{finding_id}/assignments/{assignment_id}/submissions`

### Request schema
- `WorkflowReviewSubmissionRequest`

### Response schema
- `DossierReviewSessionRecord`

### Chức năng
- persist supplement submission
- refresh full session

### Nhận định
- submit đã có API thật
- đồng thời có logic auto-submit trong workflow service

---

## 2.4. VERIFY

### API thật
- `POST /v1/dossiers/reviews/{review_id}/findings/{finding_id}/assignments/{assignment_id}/verify`

### Request schema
- `WorkflowReviewVerificationRequest`

### Response schema
- `DossierReviewSessionRecord`

### Chức năng
- verify finding/submission
- optional verification snapshot
- refresh full session

### Nhận định
- verify đã có API thật
- đồng thời có logic auto-verify trong workflow service

---

## 2.5. CLOSE

### API thật
- `POST /v1/dossiers/reviews/{review_id}/close`

### Request schema
- `WorkflowReviewCloseRequest`

### Response schema
- `DossierReviewSessionRecord`

### Chức năng
- close review session
- optionally force-close open findings
- persist audit action session_closed

### Nhận định
- close đã có API thật
- đồng thời có logic auto-close trong `start_review_run`

---

## 2.6. API nền quan trọng liên quan

### Review sessions
- `POST /v1/dossiers/reviews`
- `GET /v1/dossiers/reviews`
- `GET /v1/dossiers/reviews/{review_id}`

### Findings
- `POST /v1/dossiers/reviews/{review_id}/findings`

### Employee logs
- `GET /v1/employees/logs`

### Operational / backlog context
- `GET /v1/company/operational-state`
- `GET /v1/company/operational-state/stream`

---

## 3. Đánh giá mức độ sẵn sàng theo từng bước

## 3.1. Những gì đã có đủ để chạy flow
Các thành phần đã đủ mạnh:
- DB persistence cho session/finding/assignment/submission/verification/close
- manual APIs cho toàn bộ lifecycle
- automated start flow có thể chain nhiều bước
- employee logs write path nội bộ
- machine-readable run summary ở bước start
- backlog / blocked items aggregate ở company operational state

## 3.2. Những gì còn thiếu để chạy “không thao tác tay”

### A. Thiếu typed contract ở một số raw endpoints
Hiện còn raw/không typed:
- `POST /v1/dossiers/reviews`
- `POST /v1/dossiers/reviews/{review_id}/findings`

Điều này làm contract machine-to-machine kém ổn định.

### B. Thiếu orchestration continuity sau lần POST start đầu tiên
Hiện workflow auto-chain tốt trong **một request start đồng bộ**.

Nhưng thiếu khả năng tiếp tục với các review đang dở dang:
- finding chưa assigned
- assignment chưa submitted
- submission chưa verified
- review đã resolved nhưng chưa closed

### C. `next_actions` chưa durable
`WorkflowReviewRunSummary` có `next_actions`, nhưng theo code đã rà soát:
- đây chủ yếu là output response
- chưa được persist thành queue chính thức có lifecycle riêng

Hệ quả:
- khó pick up lại bởi worker/scheduler
- khó surfacing nhất quán trên command center
- khó chạy autonomous continuation

### D. Thiếu event-driven hoặc periodic trigger
Chưa thấy lớp backend nào tự động:
- quét findings chưa assign
- quét assignments chờ submit
- quét submissions chờ verify
- quét reviews đã resolved để close
- quét next actions sau close

SSE hiện có chỉ là **broadcast trạng thái**, chưa phải backend automation trigger.

### E. Thiếu machine handoff summary chuẩn hóa theo step
Hiện `WorkflowReviewRunSummary` là output tốt nhất, nhưng vẫn thiếu:
- `correlation_id`
- `run_id`
- `requires_manual_intervention`
- `resumable_from_step`
- `close_executed`
- `assigned_findings_count`
- `submitted_findings_count`
- `verified_findings_count`
- `escalated_findings_count`
- `manual_follow_up_count`
- `blocked_reasons[]` chuẩn hóa
- metadata lịch chạy cho next actions

### F. Thiếu public write API cho employee logs
Hiện:
- `GET /v1/employees/logs` đã có
- write path chủ yếu là logic nội bộ trong `WorkflowPersistenceService`

Điều này không chặn full flow hiện tại, nhưng hạn chế khả năng orchestration/agent khác phát event độc lập.

---

## 4. Gap analysis theo lifecycle

## 4.1. START
### Đã có
- autonomous entrypoint mạnh
- policy checks
- structured output
- inline auto-chain

### Còn thiếu
- idempotency / correlation id
- trigger tự động gọi start từ backlog/risk/schedule
- hook hậu xử lý sau close như memory ingest / backlog persistence

---

## 4.2. ASSIGN
### Đã có
- manual API
- auto-assign inline
- policy escalation synthesis

### Còn thiếu
- worker/sweeper cho findings chưa assigned
- persisted queue item cho manual assignment required
- summary step-specific rõ ràng cho machine follow-up

---

## 4.3. SUBMIT
### Đã có
- manual API
- auto-submit inline

### Còn thiếu
- resume submit cho review đang dở
- integration thật với generation/artifact production
- validation chứng cứ/attachment tồn tại trước submit
- run-level submission summary rõ hơn

---

## 4.4. VERIFY
### Đã có
- manual API
- auto-verify inline
- persistence semantics accepted/insufficient/rejected

### Còn thiếu
- resume verify cho pending verification
- verification snapshot auto-generated
- policy re-check trước verify/close
- rework loop rõ ràng cho rejected/insufficient flows

---

## 4.5. CLOSE
### Đã có
- manual API
- auto-close inline

### Còn thiếu
- autonomous closer cho resolved reviews ngoài request start
- post-close queue chính thức
- memory ingestion / backlog follow-up / escalation routing sau close

---

## 5. Script chẩn đoán end-to-end: hiện trạng và đề xuất

## 5.1. Nền tốt nhất hiện có
File tốt nhất để dùng làm base:
- `tmp/diagnose_workflow_runtime.py`

Điểm mạnh:
- đã gọi lifecycle đúng thứ tự:
  - start
  - assign
  - submit
  - verify
  - close
- đã tạo dữ liệu unique theo timestamp
- đã gom kết quả theo step

## 5.2. Những phần có thể tái sử dụng thêm
- `tmp/check_employee_logs_api.py`
- `tmp/dump_employee_log_rows.py`
- `tmp/check_employee_reference_rows.py`
- `tmp/check_real_log_tables.py`
- `tools/check_project_readiness.py`
- `tmp/verify_project_management_response.py`

## 5.3. Assertion còn thiếu trong script hiện tại
Cần bổ sung:
- assert HTTP status từng bước
- assert có `review_id`, `finding_id`, `assignment_id`
- assert state progression:
  - review được tạo
  - assignment được link vào finding
  - submission được persist
  - verification_result đúng
  - review được close
- assert `GET /v1/dossiers/reviews` trả review vừa tạo
- assert employee logs được ghi cho NV-01 / NV-04
- assert có snapshot/action trail nếu payload yêu cầu
- assert summary đủ ổn định cho machine use
- assert downstream backlog/operational impact nếu mong đợi sau close

## 5.4. Cấu trúc script đề xuất
Script end-to-end nên có 6 phần:
1. preflight
2. unique run context
3. lifecycle execution
4. cross-endpoint verification
5. structured assertions
6. optional cleanup/report-only mode

---

## 6. Thứ tự vá backend được đề xuất

## Bước 1 — Chuẩn hóa summary cho machine handoff
Mở rộng `WorkflowReviewRunSummary` để thêm:
- `correlation_id`
- `run_id`
- `requires_manual_intervention`
- `resumable_from_step`
- `close_executed`
- per-step counts
- normalized `blocked_reasons`
- scheduling metadata cho `next_actions`

Đây là bước nhỏ nhưng hiệu quả cao nhất cho autonomous continuation.

## Bước 2 — Persist `next_actions`
Biến `next_actions` từ response-only thành queue bền vững:
- lưu DB hoặc queue table
- có state riêng: pending / claimed / completed / skipped
- surfacing lên operational state

## Bước 3 — Tạo resumable executors
Cần service/backend operations để tiếp tục review đang dở:
- auto-assign unresolved findings
- auto-submit pending assignments
- auto-verify submitted assignments
- auto-close resolved reviews

## Bước 4 — Bổ sung trigger định kỳ hoặc event-driven
Hai lựa chọn:
- sweeper định kỳ
- event chaining sau mỗi DB transition

Nên làm tối thiểu:
- periodic sweeper trước
- event chaining sau

## Bước 5 — Nối artifact generation thật vào submit
Hiện auto-submit chủ yếu còn synthetic.
Cần nối với generation/artifact pipeline thực tế.

## Bước 6 — Thêm post-close automation
Sau close cần:
- persist follow-up tasks
- optionally ingest review memory
- optionally ingest project memory
- route escalation / monitoring work

---

## 7. Kế hoạch implement ngắn gọn cho mục todo hiện tại

## 7.1. Hoàn thành item “Rà soát toàn bộ API hiện có...”
Kết quả: **đã hoàn tất** về mặt phân tích.

## 7.2. Item tiếp theo nên làm ngay
Theo thứ tự hợp lý:

1. tạo script chẩn đoán end-to-end chuẩn hóa từ `tmp/diagnose_workflow_runtime.py`
2. chuẩn hóa `WorkflowReviewRunSummary`
3. vá các lỗi backend phát hiện qua script
4. persist `next_actions`
5. thêm sweeper định kỳ cho review dang dở
6. xác minh full flow với dữ liệu pilot

---

## 8. Kết luận cuối

DSCons hiện đã ở trạng thái:
- **đủ API để chạy full lifecycle**
- **đủ persistence để lưu trọn vòng đời**
- **đủ summary để bắt đầu machine handoff**

Nhưng chưa đủ để gọi là **full autonomous workflow** vì còn thiếu:
- durable continuation
- resumable automation
- trigger backend
- strong step-level summary
- strict end-to-end diagnostic script

Nút thắt lớn nhất hiện tại không còn là thiếu endpoint, mà là thiếu **lớp điều phối liên tục sau bước start**.