ai-contract-platform/project-docs/V2-contract-flow-ai-platform-production-closure-2026-06-24.md

AI 合同平台 V2 - T7 合同流程接入 AI 中台生产级收口记录

日期：2026-06-24

对齐开发方案

本轮继续遵循《AI 合同平台 V2 重构版开发方案-2026-06-22》里的职责边界：

• yuqei-contract-platform 只处理合同业务流程、任务状态、附件来源、审计和结果展示。
• yuqei-contract-platform 只通过 yuqei-ai-sdk-python 调用 AI 中台。
• Prompt、模型参数、知识库检索、RAG、法条引用生成和 AI Trace 继续留在 yuqei-ai-platform。
• 不把 OCR、PDF/DOCX 解析和知识库检索逻辑塞回合同 API。

本轮完成

1. 审查源文档生产边界

合同审查 worker 不再直接默认读取合同正文，而是先通过仓储解析本次审查任务的真实来源：

• 如果任务来自上传文件，优先读取该文件的可读文本内容。
• 如果任务没有绑定文件，读取当前合同正文。
• 如果上传源文件不可读，不再静默回退到合同旧正文，而是将审查任务置为失败，并提示需要先走文档解析/OCR。

这样可以避免生产环境中出现“用户上传 A 文件发起审查，但系统实际审查了合同旧正文”的高风险问题。

2. AI 审查结果可追溯字段

审查任务结果新增：

• primary_sources：AI 中台返回的主要命中来源。
• confidence：AI 中台返回的置信度。
• ai_audit_run_id：AI Trace 编号，继续用于回看模型、Prompt、知识命中和耗时。

数据库迁移新增：

yuqei-contract-platform/services/contract-api/migrations/versions/20260624_0007_add_review_task_ai_source_fields.py

3. 合同详情轻量展示

合同详情页继续保持“下一步操作”主线不变，只在审查结果里增加必要的可信度信息：

• 风险等级
• 置信度
• 风险项
• 主要依据
• 命中来源
• AI Trace

这些信息仍在“附件与审查”折叠区域内展示，避免普通业务用户被技术细节压住。

验证结果

• python -m pytest yuqei-contract-platform\services\contract-api\tests -q：通过，22 passed。
• python -m compileall yuqei-contract-platform\services\contract-api\src\yuqei_contract_api：通过。
• Contract API OpenAPI YAML 解析：通过。
• Contract API Alembic 空库迁移到 head：通过，已覆盖 0007。
• npm --prefix yuqei-contract-platform/apps/contract-web run build：通过。
• npm --prefix yuqei-contract-platform/apps/contract-web run typecheck：通过。

当前取舍

本轮没有在合同系统内解析 PDF/DOCX，也没有在合同系统内做 OCR。原因是这属于 AI 中台“文档智能/知识库处理”的职责。合同系统现在只接受可读文本作为审查输入；生产上如果上传的是扫描件或二进制文档，应先由 AI 中台文档智能链路产出可审查文本，再进入合同审查 worker。

下一步建议

部署侧闭环补充

已继续完成 T7 部署侧收口：

1. contract-review-worker 的关键运行变量已从 compose 硬编码调整为 .env 可覆盖：
   • CONTRACT_API_DATABASE_URL
   • CONTRACT_API_AI_PLATFORM_BASE_URL
   • CONTRACT_API_AI_PLATFORM_TIMEOUT_SECONDS (must exceed the AI Provider request timeout; staging uses 240 seconds for a 180-second Provider budget)
   • CONTRACT_API_REVIEW_WORKER_NAME
   • CONTRACT_API_REVIEW_WORKER_POLL_INTERVAL_SECONDS
   • CONTRACT_API_REVIEW_WORKER_BATCH_LIMIT
   • CONTRACT_REVIEW_WORKER_SEED_DEMO_DATA
2. 新增 yuqei-infra/compose/.env.production.example，用于准生产/生产环境复制后替换占位值。
3. Contract API 运行时检查增强：
   • 生产环境禁止 AI 中台地址指向 localhost。
   • 审查 worker 名称不能为空。
4. 新增链路验证脚本：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File yuqei-infra\scripts\verify-contract-review-worker-flow.ps1 `
  -ContractApiBaseUrl http://localhost:8100 `
  -WorkerExecutionMode docker-compose `
  -RequireConfidence

该脚本会创建临时合同、上传可读文本文件、发起审查、触发或等待 worker 消费任务，并验证审查结果回写 ai_audit_run_id、confidence。如果目标环境知识库已准备好，可增加 -RequirePrimarySources 验证来源命中。

后续建议

下一步可以在准生产环境实际执行：

1. 在 compose/部署脚本中确认 Contract Review Worker 的生产环境变量完整。
2. 在生产或准生产环境创建一条上传文件审查任务，验证 worker 能调用 AI 中台并回写 primary_sources、confidence 和 ai_audit_run_id。
3. 将不可读文件的失败提示接入前端更友好的处理入口，例如“发起解析/OCR”。