yuqei
a3bb78e06b
Security Quality Gate / npm audit, Bandit, pip-audit, detect-secrets (pull_request) Failing after 16m35s
54 lines
3.2 KiB
Markdown
54 lines
3.2 KiB
Markdown
# V2 Phase 3 Structured Review Citation Response Overlay
|
|
|
|
Date: 2026-07-01
|
|
|
|
## Scope
|
|
|
|
This slice moves `ReviewTask.citations` response data toward structured `review_citations` as the primary source.
|
|
|
|
The public response still includes `citations` for compatibility. Legacy `review_tasks.citations` remains fallback and supplemental data.
|
|
|
|
## Changes
|
|
|
|
- `review_task_from_model(...)` now uses `display_citations_from_model(...)`.
|
|
- Response `citations` are built as:
|
|
- structured citation rows first
|
|
- legacy JSON fields merged when the same citation key exists
|
|
- legacy-only citations appended for compatibility
|
|
- If legacy `review_tasks.citations` is empty but structured rows exist, the API still emits compatible citation items.
|
|
- The merge key is `risk_item_id + source_id + article_id + reference`, with blank/whitespace values normalized before comparison.
|
|
- Existing JSON columns are not removed.
|
|
- `review_result_read_model.display_review_citations(...)` now follows the same structured-first plus legacy-only supplemental strategy, so unified search and other shared read paths can still see historical compatibility-only citation text.
|
|
|
|
## Validation
|
|
|
|
```powershell
|
|
python -m pytest yuqei-contract-platform\services\contract-api\tests\test_contract_workflow.py::test_review_task_response_citations_use_structured_overlay_with_legacy_fallback -q
|
|
python -m pytest yuqei-contract-platform\services\contract-api\tests\test_contract_workflow.py::test_unified_search_returns_contract_file_and_review_task -q
|
|
python -m pytest yuqei-contract-platform\services\contract-api\tests\test_contract_workflow.py::test_clause_repair_uses_structured_risk_when_legacy_json_is_empty -q
|
|
python -m pytest yuqei-contract-platform\services\contract-api\tests\test_contract_workflow.py -q -k "clause_repair"
|
|
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::test_review_worker_calls_ai_platform_and_persists_result yuqei-contract-platform\services\contract-api\tests\test_contract_workflow.py::test_unified_search_returns_contract_file_and_review_task -q
|
|
python -m py_compile yuqei-contract-platform\services\contract-api\src\yuqei_contract_api\persistence\review_tasks.py
|
|
```
|
|
|
|
Observed:
|
|
|
|
```text
|
|
. [100%]
|
|
. [100%]
|
|
. [100%]
|
|
... [100%]
|
|
......... [100%]
|
|
.. [100%]
|
|
```
|
|
|
|
Additional regression coverage:
|
|
|
|
- Same-key structured citation overrides title/reference/quote while preserving legacy compatibility fields such as `score`.
|
|
- Legacy-only citation JSON remains appended after structured rows.
|
|
|
|
## Next Step
|
|
|
|
Audit remaining write paths that mutate legacy `review_tasks.risk_items` / `review_tasks.citations`; after that, define whether those JSON fields become response-only compatibility payloads or are frozen for historical backcompat.
|