ai-contract-platform/project-docs/V2-phase3-structured-review-results-backfill-query-2026-06-30.md

V2 Phase 3 Structured Review Results Backfill And Query

Date: 2026-06-30

This note records the second Slice 3.5 step after the structured review result tables were added.

Scope

Implemented an idempotent historical backfill command for existing review_tasks.risk_items and review_tasks.citations, plus a persistence-level structured risk query helper.

This slice does not change API responses, frontend behavior, or the legacy JSON compatibility fields.

Backfill Command

Module:

• yuqei_contract_api.review_results_backfill_cli

Commands:

python -m yuqei_contract_api.review_results_backfill_cli assess
python -m yuqei_contract_api.review_results_backfill_cli backfill
python -m yuqei_contract_api.review_results_backfill_cli backfill --apply
python -m yuqei_contract_api.review_results_backfill_cli backfill --apply --force

Behavior:

• assess is read-only.
• backfill without --apply is dry-run.
• backfill --apply only rebuilds missing or count-inconsistent structured rows.
• backfill --apply --force rebuilds all succeeded review tasks.
• Repeated non-force apply runs are idempotent and should report updated_task_count = 0 after the first successful completion.

Query Helper

Added query_structured_review_risks(...) in:

• yuqei_contract_api.persistence.review_results

Supported filters:

• tenant_id
• contract_id
• review_task_id
• risk_level
• clause_id
• limit

This helper intentionally remains persistence-only for now. No public API endpoint was added in this slice.

Compatibility

Still retained:

• review_tasks.risk_items
• review_tasks.citations
• review_tasks.primary_sources

No cleanup migration was added. No old JSON fields were removed.

Verification

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 backfill/query tests passed.
• Contract API core regression passed.
• Alembic head remains 20260630_0023.

Next Step

Recommended next step:

• Run assess and non-force backfill --apply in the 192.168.3.90 smoke PostgreSQL environment after the 20260630_0023 migration is applied.
• Then decide whether to expose structured risk query read paths through Contract API endpoints.