yuqei
a3bb78e06b
Security Quality Gate / npm audit, Bandit, pip-audit, detect-secrets (pull_request) Failing after 16m35s
105 lines
3.0 KiB
Markdown
105 lines
3.0 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
GET /api/v1/contracts/{contract_id}/review-citations
|
|
```
|
|
|
|
Query parameters:
|
|
|
|
- `review_task_id`
|
|
- `risk_item_id`
|
|
- `source_id`
|
|
- `article_id`
|
|
- `limit`
|
|
|
|
Response shape:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```text
|
|
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
|
|
|
|
```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:
|
|
|
|
- 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.
|