ai-contract-platform/project-docs/V2-phase3-review-citation-risk-linking-2026-07-01.md

V2 Phase 3 Structured Review Citation-Risk Linking

Date: 2026-07-01

Scope

This slice tightens the structured review result read path by linking legal citations to review risk items.

It does not add a database migration, remove legacy JSON fields, or switch frontend pages away from the legacy fallback yet. The goal is to make the existing review_citations.risk_item_id field reliable enough for the next UI/data-path migration.

Behavior

• AI review risk items may provide citation_refs, for example ["Civil Code Article 509"].
• AI review citations are normalized from title + reference, for example Civil Code Article 509.
• When a normalized citation ref matches a risk item's normalized citation_refs, the structured citation row is linked with that risk item's risk_item_id.
• If the same citation is referenced by multiple risk items, the structured review_citations rows are expanded so each linked risk item can be queried independently.
• If no match is found, the citation is still persisted with risk_item_id = null.

Compatibility

• The legacy review_tasks.citations JSON remains a list.
• During worker execution, legacy citation JSON is enriched with only the first matching risk_item_id.
• The structured persistence layer independently infers all matching risk links, so direct repository writes and backfill flows still produce the expanded structured rows.
• Existing API response fields remain compatible.

Validation

Local validation:

python -m pytest yuqei-contract-platform\services\contract-api\tests\test_contract_workflow.py::test_review_worker_calls_ai_platform_and_persists_result -q
python -m pytest yuqei-contract-platform\services\contract-api\tests\test_contract_workflow.py yuqei-contract-platform\services\contract-api\tests\test_health.py yuqei-contract-platform\services\contract-api\tests\test_display_cache_governance.py yuqei-contract-platform\services\contract-api\tests\test_structured_review_results.py -q
python -m compileall -q yuqei-contract-platform\services\contract-api\src\yuqei_contract_api
python -m alembic -c alembic.ini heads

Observed Alembic head:

20260630_0023 (head)

Remote smoke validation:

• Host: 192.168.3.90
• Path: /opt/apps/ai-contract-platform-v2-smoke
• Compose project: yuqei-contract-v2-smoke
• Contract API: http://192.168.3.90:18100
• Smoke contract id: contract-cd1bb757684c
• Smoke review task id: review-c9eafaca7bb0

Checks:

• /api/v1/runtime/schema-check: ok
• AI golden sample gate: passed, 90 samples, 6 suites, 16 checks
• Review task completed through the resident contract-review-worker
• Risk ids observed:
  • risk-payment-acceptance
  • risk-breach-liability
• GET /api/v1/contracts/{contract_id}/review-citations?review_task_id={review_task_id}&risk_item_id=risk-payment-acceptance: total = 3
• GET /api/v1/contracts/{contract_id}/review-citations?review_task_id={review_task_id}&risk_item_id=risk-breach-liability: total = 3
• Structured table grouping:

risk-breach-liability   | 3
risk-payment-acceptance | 3

Next Step

The structured citation/risk linkage is ready for the next slice: move contract detail/admin review consumers to prefer review-risks and review-citations, while keeping legacy review_tasks.risk_items/citations as fallback.