ai-contract-platform/project-docs/V2-phase3-structured-review-backend-read-path-2026-07-01.md

V2 Phase 3 Structured Review Backend Read Path

Date: 2026-07-01

Scope

This slice moves backend consumers that derive display/search behavior from review results toward structured review_risk_items / review_citations first.

Legacy review_tasks.risk_items and review_tasks.citations remain as fallback data. This does not remove JSON columns or change the review task response contract.

Changes

• Added yuqei_contract_api.review_result_read_model.
• ContractActionContext now reads latest review risk/repair state through the shared read model:
  • structured risk rows first
  • legacy JSON fallback only when structured rows are missing
• Unified search review-task indexing now reads risk and citation text through the same read model.
• Search rebuild preloads structured risks and citations for review tasks.
• Added regressions proving structured rows still drive:
  • next_action / next_actions when legacy risk_items is empty
  • unified review search when legacy risk_items and citations are empty

Validation

python -m pytest yuqei-contract-platform\services\contract-api\tests\test_contract_workflow.py::test_structured_review_results_drive_next_action_when_legacy_json_is_empty yuqei-contract-platform\services\contract-api\tests\test_contract_workflow.py::test_unified_search_returns_contract_file_and_review_task -q
python -m pytest yuqei-contract-platform\services\contract-api\tests\test_structured_review_results.py -q
python -m pytest yuqei-contract-platform\services\contract-api\tests\test_contract_workflow.py -q -k "structured_action_context or structured_review_results_drive_next_action or search_document_generation or unified_search_returns_contract_file_and_review_task or clause_repair"

Observed:

..                                                                       [100%]
.........                                                                [100%]
......                                                                   [100%]

Next Step

Continue the same pattern for clause repair orchestration: use structured risks to locate repair targets first, then keep legacy JSON mutation only as compatibility state until the write model is fully structured.