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

V2 Phase 3 Structured Review Citation Read API

Date: 2026-07-01

This note records the companion read API for structured review citations after the structured review risk read API.

Scope

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

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-citations

Query parameters:

• review_task_id
• risk_item_id
• source_id
• article_id
• limit

Response shape:

{
  "items": [
    {
      "id": "review-citation-...",
      "review_task_id": "review-...",
      "risk_item_id": "risk-payment-acceptance",
      "source_id": "LAW-CIVIL-001",
      "article_id": "LEGAL-CIVIL-0509",
      "title": "Civil Code",
      "reference": "Article 509",
      "quote": "Perform obligations.",
      "created_at": "..."
    }
  ],
  "total": 1
}

Implementation

Added:

• StructuredReviewCitation
• StructuredReviewCitationPage
• list_structured_review_citations(...)

Repository path:

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

Because review_citations is keyed by review_task_id, the SQL read path first resolves the contract's review task ids and then filters citations by that task set. This keeps contract-level citation queries tenant- and contract-scoped.

The in-memory repository returns an empty structured citation page for existing contracts. Structured citation 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:

• Exercise both structured read endpoints in the remote smoke PostgreSQL environment.
• Then migrate contract detail/admin UI consumers to prefer structured review-risks and review-citations, with old review_tasks.risk_items/citations retained as fallback.