yuqei
a3bb78e06b
Security Quality Gate / npm audit, Bandit, pip-audit, detect-secrets (pull_request) Failing after 16m35s
106 lines
2.9 KiB
Markdown
106 lines
2.9 KiB
Markdown
# 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.
|