ai-contract-platform/project-docs/V2-phase3-structured-review-admin-read-path-2026-07-01.md

V2 Phase 3 Structured Review Admin Read Path

Date: 2026-07-01

Scope

This slice adds an admin review-results surface that reads structured review risks and citations first.

It keeps legacy review_tasks.risk_items and review_tasks.citations as fallback data. It does not remove old JSON fields, add migrations, or change Contract API response compatibility.

Changes

• Added /admin/review-results.
• Added admin navigation and admin homepage entry for the review-results surface.
• Granted the page through the existing legal_assets admin capability for admin and legal roles.
• Added src/lib/review-results.ts as the shared Contract Web adapter for structured-first review display with legacy JSON fallback.
• The page:
  • Lists recent contracts.
  • Opens one selected contract.
  • Loads succeeded review tasks.
  • Reads structured review-risks and review-citations.
  • Shows citations under the linked risk item when risk_item_id is present.
  • Falls back to legacy review task JSON when structured rows are missing.
• Contract detail and admin review-results now share the same display adapter instead of each page reading review_tasks.risk_items / review_tasks.citations differently.
• Admin review-results metrics now count the final displayed risks and citations, so legacy fallback data is reflected until all old review tasks are backfilled.
• Added yuqei-infra/scripts/verify-review-results-page.py as a repeatable page smoke check.

Validation

Local validation:

npm --workspace @yuqei/contract-web run typecheck
npm --workspace @yuqei/contract-web run build
python -m pytest yuqei-contract-platform\services\contract-api\tests\test_structured_review_results.py -q
python -m py_compile yuqei-infra\scripts\verify-review-results-page.py
python yuqei-infra\scripts\verify-review-results-page.py --base-url http://localhost:3000

Consumer consolidation validation:

npm --workspace @yuqei/contract-web run typecheck
npm --workspace @yuqei/contract-web run build

Note: a stale generated .next/dev/types/routes.d.ts from a previous dev server run was truncated and caused tsc --noEmit syntax errors. Removing only the generated .next/dev directory fixed the cache issue; the subsequent typecheck passed.

Observed:

• Next.js build completed successfully.
• /admin/review-results appears in the route table.
• Page smoke passed locally:

REVIEW_RESULTS_PAGE_SMOKE_PASS url=http://localhost:3000/admin/review-results status=200

The first local smoke attempt failed before starting Next dev server because localhost:3000 was not listening. After starting the dev server, the smoke passed.

Remote Smoke Verification

Remote smoke target:

• Contract Web: http://192.168.3.90:13000
• Contract API: http://192.168.3.90:18100
• Known smoke contract: contract-cd1bb757684c

The Contract Web image was rebuilt and restarted on 192.168.3.90 after syncing the admin review-results page, structured proxy routes, service helpers, smoke script, and the shared src/lib/review-results.ts display adapter.

Remote page smoke passed:

python yuqei-infra\scripts\verify-review-results-page.py --base-url http://192.168.3.90:13000

Observed:

REVIEW_RESULTS_PAGE_SMOKE_PASS url=http://192.168.3.90:13000/admin/review-results status=200

Remote real-data smoke passed for linked risk citations:

python yuqei-infra\scripts\verify-review-results-page.py --base-url http://192.168.3.90:13000 --contract-id contract-cd1bb757684c --expect-risk "付款与验收条款需要进一步明确" --expect-risk "违约责任需与主要义务匹配" --expect-citation "知识库片段 7003" --expect-citation "知识库片段 7103" --expect-citation "知识库片段 7203"

Observed:

REVIEW_RESULTS_PAGE_SMOKE_PASS url=http://192.168.3.90:13000/admin/review-results?contract_id=contract-cd1bb757684c status=200

The same two remote smoke commands were rerun after consolidating Contract Detail and Admin Review Results onto the shared display adapter; both passed.

Next Step

Continue migrating any remaining review management consumers away from raw task JSON.