# 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:

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

Query parameters:

- `review_task_id`
- `risk_level`
- `clause_id`
- `limit`

Response shape:

```json
{
  "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:

```text
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

```powershell
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.