ai-contract-platform/project-docs/archive/implementation-history/V2-phase3-structured-review-risk-read-api-2026-07-01.md

V2 Phase 3 Structured Review Risk Read API

Date: 2026-07-01

This note records the next Slice 3.5 step after the structured review result backfill passed in the remote smoke PostgreSQL environment.

Scope

Added a read-only Contract API path for querying structured review risks.

This slice does not change existing review task responses and does not remove legacy JSON fields:

• review_tasks.risk_items
• review_tasks.citations
• review_tasks.primary_sources

API

New endpoint:

GET /api/v1/contracts/{contract_id}/review-risks

Query parameters:

• review_task_id
• risk_level
• clause_id
• limit

Response shape:

{
  "items": [
    {
      "id": "review-risk-...",
      "contract_id": "contract-...",
      "review_task_id": "review-...",
      "risk_item_id": "risk-payment-acceptance",
      "risk_type": null,
      "risk_level": "high",
      "title": "Payment and acceptance terms need clarification",
      "summary": "...",
      "source_excerpt": null,
      "position": {},
      "recommended_clause_id": "CLAUSE-COMMON-BREACH-001",
      "repair_status": null,
      "created_at": "..."
    }
  ],
  "total": 1
}

Implementation

Added:

• StructuredReviewRisk
• StructuredReviewRiskPage
• list_structured_review_risks(...)

Repository path:

api.review -> ContractRepository -> SqlAlchemyReviewTaskOrchestration -> persistence.review_results

The in-memory repository returns an empty structured risk page for existing contracts. Structured risk rows are intentionally treated as a SQL persistence capability.

Compatibility

Kept unchanged:

• GET /api/v1/contracts/{contract_id}/review-tasks
• contract detail response shape
• clause repair behavior
• review completion dual-write behavior

No migration was added. Alembic head remains 20260630_0023.

Verification

python -m compileall -q yuqei-contract-platform\services\contract-api\src\yuqei_contract_api
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 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 alembic -c alembic.ini heads

Result:

• Compile passed.
• Structured review result tests passed.
• Contract API core regression passed.
• Alembic head is still 20260630_0023.

Next Step

Recommended next step:

• Add a structured citation read path, or connect the contract detail/admin UI to the new structured risk endpoint behind the existing review task JSON fallback.
• Keep legacy JSON fields until the structured read path is exercised in smoke and frontend consumers are migrated.