yuqei
a3bb78e06b
Security Quality Gate / npm audit, Bandit, pip-audit, detect-secrets (pull_request) Failing after 16m35s
72 lines
3.3 KiB
Markdown
72 lines
3.3 KiB
Markdown
# V2 Phase 3 Structured Review Citation-Risk Linking
|
|
|
|
Date: 2026-07-01
|
|
|
|
## Scope
|
|
|
|
This slice tightens the structured review result read path by linking legal citations to review risk items.
|
|
|
|
It does not add a database migration, remove legacy JSON fields, or switch frontend pages away from the legacy fallback yet. The goal is to make the existing `review_citations.risk_item_id` field reliable enough for the next UI/data-path migration.
|
|
|
|
## Behavior
|
|
|
|
- AI review risk items may provide `citation_refs`, for example `["Civil Code Article 509"]`.
|
|
- AI review citations are normalized from `title + reference`, for example `Civil Code Article 509`.
|
|
- When a normalized citation ref matches a risk item's normalized `citation_refs`, the structured citation row is linked with that risk item's `risk_item_id`.
|
|
- If the same citation is referenced by multiple risk items, the structured `review_citations` rows are expanded so each linked risk item can be queried independently.
|
|
- If no match is found, the citation is still persisted with `risk_item_id = null`.
|
|
|
|
## Compatibility
|
|
|
|
- The legacy `review_tasks.citations` JSON remains a list.
|
|
- During worker execution, legacy citation JSON is enriched with only the first matching `risk_item_id`.
|
|
- The structured persistence layer independently infers all matching risk links, so direct repository writes and backfill flows still produce the expanded structured rows.
|
|
- Existing API response fields remain compatible.
|
|
|
|
## Validation
|
|
|
|
Local validation:
|
|
|
|
```powershell
|
|
python -m pytest yuqei-contract-platform\services\contract-api\tests\test_contract_workflow.py::test_review_worker_calls_ai_platform_and_persists_result -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 compileall -q yuqei-contract-platform\services\contract-api\src\yuqei_contract_api
|
|
python -m alembic -c alembic.ini heads
|
|
```
|
|
|
|
Observed Alembic head:
|
|
|
|
```text
|
|
20260630_0023 (head)
|
|
```
|
|
|
|
Remote smoke validation:
|
|
|
|
- Host: `192.168.3.90`
|
|
- Path: `/opt/apps/ai-contract-platform-v2-smoke`
|
|
- Compose project: `yuqei-contract-v2-smoke`
|
|
- Contract API: `http://192.168.3.90:18100`
|
|
- Smoke contract id: `contract-cd1bb757684c`
|
|
- Smoke review task id: `review-c9eafaca7bb0`
|
|
|
|
Checks:
|
|
|
|
- `/api/v1/runtime/schema-check`: `ok`
|
|
- AI golden sample gate: `passed`, `90` samples, `6` suites, `16` checks
|
|
- Review task completed through the resident `contract-review-worker`
|
|
- Risk ids observed:
|
|
- `risk-payment-acceptance`
|
|
- `risk-breach-liability`
|
|
- `GET /api/v1/contracts/{contract_id}/review-citations?review_task_id={review_task_id}&risk_item_id=risk-payment-acceptance`: `total = 3`
|
|
- `GET /api/v1/contracts/{contract_id}/review-citations?review_task_id={review_task_id}&risk_item_id=risk-breach-liability`: `total = 3`
|
|
- Structured table grouping:
|
|
|
|
```text
|
|
risk-breach-liability | 3
|
|
risk-payment-acceptance | 3
|
|
```
|
|
|
|
## Next Step
|
|
|
|
The structured citation/risk linkage is ready for the next slice: move contract detail/admin review consumers to prefer `review-risks` and `review-citations`, while keeping legacy `review_tasks.risk_items/citations` as fallback.
|