ai-contract-platform/project-docs/V2-phase3-structured-review-read-endpoints-smoke-verification-2026-07-01.md

V2 Phase 3 Structured Review Read Endpoints Smoke Verification

Date: 2026-07-01

Remote smoke environment:

• 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
• Database: yuqei_contract

Deploy

Updated the smoke environment with the current V2 code without resetting PostgreSQL volumes.

Deploy artifact:

• project-docs/qa-artifacts/v2-smoke-docker-deploy/2026-07-01T00-55-56

Deploy result:

• Remote Docker preflight passed.
• Compose deploy passed.
• Contract Web, Contract API, and AI Platform API health checks passed.
• AI golden sample gate passed: 90 samples, 6 suites, 16 checks.
• V2 databases yuqei_contract, yuqei_ai, and yuqei_ops exist.

Schema Check

/api/v1/runtime/schema-check result:

• Overall status: ok
• database_backend: ok
• database_name: ok
• alembic_version: ok
• core_tables: ok
• governance_columns: ok
• action_hint_columns: ok
• display_cache_consistency: ok
• display_cache_cleanup_prestate: ok
• postgres_extensions: ok

Historical Backfill Read Smoke

Sampled historical backfilled data:

• Contract id: contract-9d8c4d18c05a
• Review task id: review-79a4c3ae6aed

Endpoint results:

{
  "review_risks": {
    "total": 2,
    "items": 2
  },
  "review_citations": {
    "total": 3,
    "items": 3
  }
}

This confirms that historical backfilled structured rows are readable through both Contract API endpoints.

New Review Read Smoke

Created a new smoke contract and review task:

• Contract id: contract-2dd13e4fc6f6
• Review task id: review-9dd699df5c41
• AI audit run id: run-a83b73cc876a

Review task JSON result:

{
  "status": "succeeded",
  "risk_items": 2,
  "citations": 3,
  "ai_audit_run_id": "run-a83b73cc876a"
}

Structured read endpoint results:

{
  "review_risks": {
    "total": 2,
    "items": 2,
    "first_risk": "risk-payment-acceptance"
  },
  "review_citations": {
    "total": 3,
    "items": 3,
    "first_risk_item_id": null
  }
}

Structured table counts for the new review task:

structured_risks:     2
structured_citations: 3

Note: the new review's structured citations currently have risk_item_id = null because the AI review citation payload does not yet carry explicit risk linkage. Querying citations by review_task_id is verified. Filtering citations by risk_item_id returns 0 for this sample until the review output mapping includes risk-linked citations.

Result

Smoke verification passed:

• GET /api/v1/contracts/{contract_id}/review-risks works for historical backfilled data and newly completed reviews.
• GET /api/v1/contracts/{contract_id}/review-citations works for historical backfilled data and newly completed reviews.
• Runtime schema-check is healthy.
• All smoke containers are healthy after deployment.

Next Step

Recommended next step:

• Add explicit risk-to-citation linkage in the AI review output mapping when possible.
• Then migrate contract detail/admin UI consumers to prefer structured review-risks and review-citations, while retaining old review_tasks.risk_items/citations as fallback.