# Verification strategy: workflow summary + company operational state

## Goal

Bổ sung verification coverage nhẹ, chạy được ngay bằng Python trong venv hiện tại, không giả định `pytest` đã được cài.

Phạm vi cần kiểm tra:

- `WorkflowReviewRunSummary` trả về đầy đủ các field mới:
  - `policy_summary`
  - `trigger_summary`
  - `post_close_actions`
  - `operational_state_snapshot`
- `CompanyOperationalStateResponse` trả về đầy đủ các field mới:
  - `operations_cases`
  - `operations_actions`
  - `operations_blockers`
  - `dossier_reviews`
  - `policy_overview`

Các script dưới đây nhắm vào server đang chạy tại `http://127.0.0.1:8000`.

---

## Existing verification baseline

Project đã có sẵn:

- `tmp/check_health_endpoints.py`
- `tmp/diagnose_dossier_review_full_lifecycle.py`

Hai script này hữu ích để:

- xác nhận server còn sống
- kiểm tra health/readiness
- chạy một luồng dossier review end-to-end mức cơ bản

Tuy nhiên chúng chưa assert rõ contract của các field mới vừa được thêm vào response schema. Vì vậy cần thêm verification script chuyên biệt.

---

## Added lightweight verification scripts

### 1. `tmp/verify_workflow_summary_contract.py`

Mục tiêu:

- gọi `POST /v1/workflows/dossier-review/start`
- tạo một workflow run nhỏ nhưng đủ để đi qua automation path
- assert response top-level có:
  - `policy_summary`
  - `trigger_summary`
  - `post_close_actions`
  - `operational_state_snapshot`
- assert shape cơ bản của từng object mới

Các kiểm tra chính:

- `policy_summary` là object và có các field summary cốt lõi
- `trigger_summary` là object và phản ánh `trigger_source` đã gửi lên
- `post_close_actions` là list và, với payload này, kỳ vọng có ít nhất 1 item
- `operational_state_snapshot` là object và có các counter/snapshot field chính

Chạy:

```bash
python tmp/verify_workflow_summary_contract.py
```

Exit code:

- `0`: pass
- `1`: API call failed
- `2`: API call thành công nhưng contract assertion fail

---

### 2. `tmp/verify_company_operational_state_contract.py`

Mục tiêu:

- gọi `GET /v1/company/operational-state`
- assert response top-level có:
  - `operations_cases`
  - `operations_actions`
  - `operations_blockers`
  - `dossier_reviews`
  - `policy_overview`

Các kiểm tra chính:

- 4 field dữ liệu trên là list
- `policy_overview` là object
- `policy_overview` có:
  - `policy_checks_count`
  - `risk_flagged_count`
  - `escalation_triggered_count`
  - `warnings`
- `source_status` có đủ source name liên quan:
  - `projects`
  - `employee_logs`
  - `dossier_reviews`
  - `operations_cases`
  - `operations_actions`
  - `operations_blockers`

Chạy:

```bash
python tmp/verify_company_operational_state_contract.py
```

Exit code:

- `0`: pass
- `1`: API call failed
- `2`: API call thành công nhưng contract assertion fail

---

## Recommended verification order

Nếu muốn chạy nhanh theo thứ tự hợp lý:

```bash
python tmp/check_health_endpoints.py
python tmp/verify_workflow_summary_contract.py
python tmp/verify_company_operational_state_contract.py
```

Nếu cần chẩn đoán sâu hơn luồng dossier review end-to-end:

```bash
python tmp/diagnose_dossier_review_full_lifecycle.py
```

Recommended flow:

1. chạy health check trước để tránh debug nhầm do server down
2. chạy workflow summary contract script để tạo dữ liệu mới và kiểm tra response mở rộng
3. chạy company operational state contract script để xác nhận aggregated state surfacing đúng các field mới
4. nếu có lỗi lifecycle/automation, dùng script diagnose full lifecycle để xem sâu hơn

---

## What these scripts intentionally verify

### Workflow response contract

Script `tmp/verify_workflow_summary_contract.py` đang verify các kỳ vọng sau:

- response vẫn trả `200`
- response vẫn backward-compatible với schema tổng thể cũ
- đồng thời đã surfacing thêm:
  - policy outcome summary
  - trigger explanation
  - post-close projected actions
  - operational twin snapshot

Điều này bám sát implementation hiện tại trong:

- `app/services/workflow_persistence_service.py`

Đặc biệt là phần build:

- `_build_policy_summary(...)`
- `_build_trigger_summary(...)`
- `_build_post_close_actions(...)`
- `_build_operational_state_snapshot(...)`

### Company operational state contract

Script `tmp/verify_company_operational_state_contract.py` verify rằng aggregated operational twin response không chỉ có `summary/projects/risks/...` mà còn surfacing thêm top-level operational slices:

- cases
- actions
- blockers
- dossier reviews
- policy overview

Điều này bám sát implementation hiện tại trong:

- `app/services/company_operational_state_service.py`

Đặc biệt là phần attach optional top-level payload:

- `operations_cases`
- `operations_actions`
- `operations_blockers`
- `dossier_reviews`
- `policy_overview`

---

## Notes about environment and fallback behavior

Các endpoint này có logic fallback khi PostgreSQL chưa khả dụng. Vì vậy cần hiểu:

- script company operational state chủ yếu verify **field presence + shape**
- không ép buộc list phải có dữ liệu
- `used_fallback=True` vẫn có thể là hợp lệ cho verification contract
- riêng workflow start script kỳ vọng server hiện tại đã cấu hình đủ để chạy được `POST /v1/workflows/dossier-review/start`

Nếu workflow start không chạy được do DB/config, script sẽ fail với exit code `1` và in ra full response để debug.

---

## Typical successful output

### Workflow contract script

Khi pass, script sẽ in JSON report dạng gần giống:

```json
{
  "ok": true,
  "status_code": 200,
  "review_id": "...",
  "review_code": "...",
  "automation_status": "completed",
  "close_executed": true,
  "post_close_actions_count": 2,
  "failures": []
}
```

### Company operational state contract script

Khi pass, script sẽ in JSON report dạng gần giống:

```json
{
  "ok": true,
  "status_code": 200,
  "counts": {
    "operations_cases": 1,
    "operations_actions": 3,
    "operations_blockers": 0,
    "dossier_reviews": 5
  },
  "failures": []
}
```

---

## Suggested future pytest migration

Khi project sẵn sàng cài `pytest`, có thể chuyển dần các script này thành API contract tests chính thức.

### Suggested install

Nếu venv cho phép:

```bash
pip install pytest
```

Nếu muốn test HTTP level gọn hơn sau này, có thể cân nhắc thêm:

```bash
pip install pytest httpx
```

`httpx` đã có trong project context, nên không tạo thêm dependency lạ cho codebase.

### Suggested test structure later

Ví dụ có thể tạo:

- `tests/test_workflow_summary_contract.py`
- `tests/test_company_operational_state_contract.py`

Và tái sử dụng logic hiện có từ các script:

- helper request function
- required field lists
- assertion blocks

### Why keep the tmp scripts even after pytest exists

Ngay cả khi có `pytest`, các script trong `tmp/` vẫn hữu ích cho:

- smoke test thủ công trên live dev server
- demo nhanh với stakeholder
- verify production-like environment không cần boot test harness
- debug integration issue khi không muốn chạy full test suite

---

## Minimal maintenance guidance

Khi schema tiếp tục mở rộng:

1. cập nhật list field bắt buộc trong script tương ứng
2. giữ assertion ở mức contract, không overfit vào dữ liệu seed cụ thể
3. ưu tiên kiểm tra:
   - field tồn tại
   - type đúng
   - vài semantic invariant quan trọng
4. tránh assert count cứng trừ khi seed data được kiểm soát hoàn toàn

Cách này giúp verification ổn định hơn khi dữ liệu pilot thay đổi theo thời gian.

---

## Quick command summary

```bash
python tmp/check_health_endpoints.py
python tmp/verify_workflow_summary_contract.py
python tmp/verify_company_operational_state_contract.py
python tmp/diagnose_dossier_review_full_lifecycle.py