# Đề xuất nâng cấp DSCons: Operations Case Management và Command Center

Tài liệu này tổng hợp đánh giá bám theo codebase hiện tại của DSCons và đề xuất lộ trình nâng cấp để hệ thống đi từ mức “dashboard + API + pilot workflow” lên mức “hệ điều hành nội bộ cho hồ sơ và điều hành dự án”.

## 1. Kết luận điều hành ngắn

DSCons hiện **không còn là demo thuần**, vì đã có đủ các lớp nền quan trọng:

- knowledge + retrieval cho hồ sơ
- PostgreSQL cho vận hành
- workflow dossier review có persistence
- employee logs
- readiness API
- project management API
- company operational state aggregate + SSE stream

Tuy vậy, hệ thống vẫn còn **sơ sài ở lớp nghiệp vụ điều hành**, vì:

1. dữ liệu mạnh nhưng hành động chưa được mô hình hóa thành thực thể nghiệp vụ thống nhất
2. finding / assignment / employee log / project backlog vẫn là các mảnh liên quan nhưng chưa thành vòng đời khép kín
3. dashboard đã quan sát được tình hình nhưng chưa đủ để điều hành theo blocker, SLA, owner, escalation
4. AI hiện nghiêng về summary/phân tích hơn là planning/action có trách nhiệm và có thể persist

## 2. Đánh giá hiện trạng theo codebase

## 2.1. Những gì đã sẵn sàng để tái sử dụng

### A. Workflow dossier review đã có xương sống rất tốt
Các schema và service hiện có cho thấy DSCons đã có backbone cho workflow vận hành hồ sơ:

- `DossierReviewSessionRecord`
- `DossierReviewFindingItem`
- `DossierReviewAssignmentItem`
- `DossierReviewSubmissionItem`
- `DossierReviewActionItem`
- `DossierReviewSnapshotItem`
- `DossierReviewEvidenceItem`

Từ `app/services/workflow_persistence_service.py`, workflow hiện tại đã làm được:
- khởi tạo review session
- persist findings
- persist assignments
- persist submissions / verifications
- build next actions
- build escalation next actions
- ghi employee logs
- sinh workflow run summary

### B. Company operational state đã là aggregate layer rất giá trị
`app/services/company_operational_state_service.py` hiện đã hợp nhất được nhiều lớp dữ liệu:

- `projects`
- `risks`
- `blocked_items`
- `backlog`
- `workforce`
- `source_status`
- `summary`

Đây là backbone tốt nhất để xây **command center**.

### C. Readiness explainability bước đầu đã có
Từ `app/services/dossier_report_service.py` và các schema readiness hiện tại, hệ thống đã có khả năng trả về:
- `documents_present`
- `documents_missing`
- `critical_missing`
- `readiness`
- `summary`

Ngoài ra `app/services/generation_readiness_service.py` cho thấy đã có pattern explainability theo field/status, có thể tái sử dụng về tư duy thiết kế.

### D. Agent/persona layer đã có nền điều phối cơ bản
Hệ thống agent hiện có:
- `BaseTaskAgent`
- `orchestrator`
- `registry`
- `specialists`
- `personas`
- `workflow_policy_service`

Các điểm tái sử dụng tốt:
- persona metadata
- escalation targets trong persona
- retrieval filters
- policy evaluation hiện tại
- internal dossier review agent

## 2.2. Các điểm yếu chính hiện tại

### A. Chưa có first-class entity cho case/action/evidence/escalation
Hiện có nhiều khái niệm gần giống nhưng chưa thống nhất:
- finding
- assignment
- next_action
- employee log action
- backlog item
- blocked item

Thiếu thực thể chuẩn để quản trị vòng đời nghiệp vụ.

### B. Action queue đang phân mảnh
Hiện action đang nằm rải rác ở:
- `assignments`
- `next_actions`
- `employee_actions`
- `project backlog`
- `review follow-up`

Điều này khiến dashboard khó trả lời chính xác:
- việc nào là việc chính thức
- việc nào chỉ là gợi ý
- việc nào đã được nhận xử lý
- việc nào quá hạn
- việc nào bị blocked

### C. Aggregate layer chưa lộ đủ linkage
`CompanyOperationalStateResponse` hiện rất tốt cho summary, nhưng chưa lộ đầy đủ:
- `review_session_id`
- `finding_code`
- `employee_code`
- `department_code` chuẩn hóa
- `evidence`
- escalation queue

### D. SSE aggregate chưa thay thế được project detail
Hiện SSE rất phù hợp cho:
- company summary
- blocker queue
- action queue
- risk radar

Nhưng chưa thay thế được:
- `phase_progress`
- `milestones`
- `timeline`

Do đó kiến trúc UI cần phân rõ:
- top-level aggregate realtime
- detail fetch on demand

### E. AI output vẫn là text-first, chưa machine-safe
Hiện `BaseTaskAgent.run()` trả về `str`.
Điều này tốt cho chat/reply, nhưng chưa đủ cho:
- persist structured cases
- persist actions
- auto policy validation
- generate escalation queue
- update operational state

## 3. Mô hình nâng cấp đề xuất

Tôi đề xuất đưa vào 4 thực thể nghiệp vụ chuẩn.

## 3.1. `DossierCase`
Đại diện cho một vụ việc hồ sơ/vận hành có vòng đời.

Ví dụ:
- thiếu nhật ký thi công
- thiếu quyết định phê duyệt
- hồ sơ thanh toán chưa đủ bản ký
- blocker do sai phân vai hoặc thiếu xác minh

### Trường đề xuất
- `case_id`
- `case_code`
- `project_code`
- `review_session_id`
- `finding_code`
- `case_type`
- `title`
- `description`
- `dossier_stage`
- `department_code`
- `employee_code`
- `priority`
- `severity`
- `is_blocking`
- `current_status`
- `opened_at`
- `closed_at`
- `source_system`
- `source_record_type`
- `source_record_id`
- `readiness_impact`
- `operational_impact`
- `confidence_score`
- `metadata`

## 3.2. `ActionItem`
Đại diện cho một hành động cụ thể để xử lý case.

### Trường đề xuất
- `action_id`
- `action_code`
- `case_id`
- `project_code`
- `review_session_id`
- `finding_code`
- `action_type`
- `title`
- `description`
- `owner_department_code`
- `owner_employee_code`
- `priority`
- `due_date`
- `status`
- `dependency_refs`
- `expected_outcome`
- `success_criteria`
- `requires_human_confirmation`
- `completion_note`
- `created_at`
- `completed_at`
- `metadata`

## 3.3. `Evidence`
Đại diện cho căn cứ giải thích vì sao case tồn tại hoặc vì sao readiness bị chặn.

### Trường đề xuất
- `evidence_id`
- `case_id`
- `project_code`
- `review_session_id`
- `finding_code`
- `evidence_type`
- `source_system`
- `source_ref`
- `title`
- `excerpt`
- `availability`
- `strength`
- `supports_claim`
- `metadata`

## 3.4. `Escalation`
Đại diện cho việc đẩy xử lý lên người/cấp/bộ phận khác.

### Trường đề xuất
- `escalation_id`
- `case_id`
- `action_id`
- `project_code`
- `review_session_id`
- `target_department_code`
- `target_employee_code`
- `target_agent_code`
- `reason`
- `trigger_type`
- `priority`
- `status`
- `suggested_deadline_hours`
- `handoff_context`
- `created_at`
- `resolved_at`
- `metadata`

## 4. Mapping với code hiện có

## 4.1. Mapping gần đúng từ dữ liệu hiện tại

### `DossierCase`
Có thể derive ban đầu từ:
- `DossierReviewFindingItem`
- `DossierReviewSessionRecord`

### `ActionItem`
Có thể derive ban đầu từ:
- `DossierReviewAssignmentItem`
- `WorkflowReviewNextActionItem`
- project `backlog[]`

### `Evidence`
Có thể derive ban đầu từ:
- `DossierReviewEvidenceItem`
- `DossierReviewSnapshotItem`
- `DossierReadinessResponse`
- `document_index` / `critical_missing`

### `Escalation`
Có thể derive ban đầu từ:
- `WorkflowReviewPolicyCheckResult`
- `WorkflowReviewEscalationTargetItem`
- `DossierReviewActionItem` với `action_type=escalation_triggered`

## 4.2. Reuse points theo service

### `app/services/workflow_persistence_service.py`
Nên là điểm tích hợp phase 1 quan trọng nhất vì đã có:
- persist findings
- persist assignments
- build next actions
- build escalations
- persist employee logs

### `app/services/company_operational_state_service.py`
Nên là aggregate shell cho command center:
- tổng hợp projects
- tổng hợp blockers
- tổng hợp action queue
- workforce
- source health

### `app/services/dossier_report_service.py`
Nên là evidence/readiness explainer cho selected project/case.

### `app/services/workflow_policy_service.py`
Nên được nâng thành policy/evaluation engine cho:
- requires escalation
- no owner
- blocking without department
- high severity
- readiness risk

## 5. Đề xuất kiến trúc command center

## 5.1. Nguyên tắc
Không nên dùng một payload duy nhất cho mọi lớp giao diện.

### Lớp aggregate realtime
Dùng:
- `GET /v1/company/operational-state`
- `GET /v1/company/operational-state/stream`

Phù hợp cho:
- KPI tổng
- blocker board
- action queue
- risk radar
- workforce strip
- source health

### Lớp drill-down
Dùng:
- `GET /v1/projects/management`
- `GET /v1/dossiers/{project_code}/readiness`
- `GET /v1/dossiers/reviews?project_code=...`
- `GET /v1/dossiers/reviews/{review_id}`

Phù hợp cho:
- project deep dive
- readiness explainability
- review session detail
- evidence detail

## 5.2. Các khối UI nên có

### 1. Company pulse
Nguồn: `operational_state.summary`
Hiển thị:
- tổng công trình
- số blocked
- số high risk
- số open risks
- số blocked items
- số backlog
- số active review sessions
- số employees blocked

### 2. Portfolio table
Nguồn: `operational_state.projects[]`
Hiển thị:
- project
- manager
- phase
- progress
- budget status
- open risks count
- blocked items count
- backlog count
- milestone count

### 3. Blocker board
Nguồn: `operational_state.blocked_items[]`
Hiển thị:
- blocker title
- project
- owner
- reason
- source type
- due date
- age
- impact

### 4. Action queue
Nguồn: `operational_state.backlog[]`
Hiển thị:
- action
- assignee
- priority
- due date
- source type
- status
- project
- link tới case/review/finding

### 5. Readiness explainability panel
Nguồn:
- dossier readiness API
- dossier review detail API

Hiển thị:
- vì sao chưa ready
- thiếu cái gì
- blocker nào đang ảnh hưởng stage nào
- evidence nào đã có / còn thiếu

### 6. Workforce execution board
Nguồn:
- `operational_state.workforce`
- `GET /v1/employees/logs`

Hiển thị:
- người đang blocked
- người đang in_progress
- người đang completed
- quá tải theo bộ phận
- việc chưa có owner

### 7. Source trust panel
Nguồn: `operational_state.source_status[]`
Hiển thị:
- nguồn nào đang fallback
- nguồn nào thiếu record
- nguồn nào đang real-time / real-data
- độ tin cậy của aggregate

## 6. Đề xuất nâng cấp AI layer

## 6.1. Từ text summary sang structured planning
Agent layer hiện nên được mở rộng theo hai chế độ:

### Chế độ 1: text response
Giữ tương thích ngược cho chat/reply.

### Chế độ 2: structured planning output
Trả về object machine-safe để persist.

## 6.2. Output schema AI đề xuất

```json
{
  "planning_mode": "case_triage",
  "task_type": "dossier_review",
  "agent_code": "minh",
  "project_code": "PILOT-NAM-HK-2026",
  "review_session_id": "review-123",
  "overall_assessment": {
    "status": "blocked",
    "readiness_score": 42,
    "risk_level": "high",
    "requires_escalation": true,
    "blocking_reasons": ["Thiếu nhật ký thi công"]
  },
  "cases": [
    {
      "case_external_ref": "CASE-001",
      "case_type": "dossier_gap",
      "title": "Thiếu nhật ký thi công",
      "description": "Chưa có chứng cứ execution log hợp lệ",
      "status": "new",
      "priority": "high",
      "severity": "high",
      "is_blocking": true,
      "project_code": "PILOT-NAM-HK-2026",
      "review_session_id": "review-123",
      "finding_code": "FND-PILOT-NAM-HK-001",
      "department_code": "technical",
      "employee_code": "NV-04",
      "confidence_score": 0.92,
      "evidence": [],
      "actions": [],
      "escalations": []
    }
  ]
}
```

## 6.3. Điểm tích hợp
### `app/agents/base.py`
- thêm structured output path
- parse/validate output
- vẫn giữ text path cho backward compatibility

### `app/agents/orchestrator.py`
- thêm planning mode
- route result nên hỗ trợ structured payload
- truyền `project_code`, `review_session_id`, `agent_scope`

### `app/agents/specialists.py`
Bổ sung ít nhất 3 specialist:
- `case_triage_agent`
- `action_planning_agent`
- `readiness_diagnosis_agent`

### `app/services/workflow_policy_service.py`
Dùng làm validator sau AI:
- owner missing
- department missing
- escalation required
- severity policy
- blocking policy

## 7. Lộ trình triển khai thực tế

## Phase 1 — Operations Case Management baseline
Mục tiêu: biến finding/assignment/log thành vòng đời điều hành tối thiểu.

### Việc làm
1. định nghĩa schema mới cho:
   - `DossierCase`
   - `ActionItem`
   - `Evidence`
   - `Escalation`
2. build mapping từ data hiện tại sang schema mới
3. persist case/action/escalation tối thiểu
4. mở API:
   - `/v1/operations/cases`
   - `/v1/operations/actions`
   - `/v1/operations/blockers`
5. mở rộng aggregate operational state để surfacing:
   - `review_session_id`
   - `finding_code`
   - `employee_code`
   - `department_code`

### Kết quả
- có queue điều hành chuẩn
- có linkage xuyên suốt từ review đến action

## Phase 2 — Readiness with evidence
Mục tiêu: readiness không chỉ là score/status.

### Việc làm
1. gắn readiness với blockers và evidence
2. thêm explainability fields:
   - `blocking_reasons`
   - `evidence_found`
   - `evidence_missing`
   - `confidence`
3. cho phép command center mở detail readiness theo case/project

### Kết quả
- dashboard giải thích được tại sao project đỏ/vàng

## Phase 3 — Command center UI
Mục tiêu: hợp nhất dashboard thành hệ điều hành điều phối.

### Việc làm
1. nâng `project_management_dashboard.html` thành command center
2. thêm:
   - KPI strip
   - blocker board
   - action queue
   - source trust
   - workforce board
3. giữ drill-down fetch sang project detail/readiness/review APIs

### Kết quả
- dashboard từ “xem một dự án” thành “điều hành toàn danh mục”

## Phase 4 — AI planning + escalation
Mục tiêu: AI không chỉ phân tích mà còn đề xuất action có trách nhiệm.

### Việc làm
1. structured output contracts
2. policy validation sau LLM
3. persist recommended case/action/escalation
4. hiển thị AI recommendation panel

### Kết quả
- AI trở thành copilot điều hành có thể kiểm chứng

## 8. Phase 1 nên implement ngay trong codebase

Nếu triển khai ngay một phase ngắn, đáng làm nhất là:

## `Operations Case Management Phase 1`
Phạm vi nên gồm:
- schema/app model mới cho case/action/evidence/escalation
- service adapter từ dossier review sang case/action
- API list cases/actions/blockers
- aggregate payload mở rộng metadata linkage
- dashboard hiển thị blocker/action queue tốt hơn

### Lý do chọn phase này
- tận dụng mạnh nhất những gì đã có
- ít rủi ro hơn việc thay toàn bộ readiness engine
- tạo nền bắt buộc cho mọi nâng cấp sau
- biến hệ thống từ “quan sát được” sang “điều hành được”

## 9. Những quyết định thiết kế nên giữ

- tiếp tục tách Qdrant = knowledge, PostgreSQL = operational
- tiếp tục dùng company operational state làm aggregate shell
- tiếp tục giữ dossier review như nguồn workflow gốc
- không ép SSE aggregate thay cho project detail API
- giữ tương thích ngược ở agent layer bằng cách thêm structured mode, không thay toàn bộ text mode

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

DSCons hiện đã có nền dữ liệu, workflow và aggregate đủ tốt để bước sang giai đoạn trưởng thành hơn.

Điểm thiếu lớn nhất không còn là “có dashboard hay không”, mà là:

- thiếu mô hình case/action thống nhất
- thiếu readiness explainability gắn với evidence
- thiếu command center để điều hành theo owner/blocker/SLA
- thiếu AI structured planning để nối từ phân tích sang hành động

Bước nâng cấp đúng nhất lúc này là xây **Operations Case Management** làm lõi trung gian giữa:
- dossier review
- readiness
- employee logs
- project management
- company operational state
- AI planning

Khi lớp này hoàn chỉnh, DSCons mới thực sự chuyển từ “hệ thống quan sát + trợ lý phân tích” sang “hệ điều hành nội bộ cho hồ sơ và dự án”.