ai-contract-platform/project-docs/V2-contract-review-worker-async-closure-2026-06-24.md

V2 合同审查 worker 异步化闭环记录

日期：2026-06-24

本轮目标

把合同审查从“详情页按钮同步等待 AI 返回”改为“创建审查任务后由合同侧 worker 异步执行”，降低用户操作负担，并支持运行中状态、失败重试和详情页自动刷新。

架构边界

• yuqei-contract-platform：只负责合同、附件、审查任务状态、失败重试、详情页展示。
• yuqei-ai-platform：继续负责模型调用、RAG 检索、法条依据、AI 审计和质量评测。
• yuqei-ai-sdk-python：继续作为合同系统调用 AI 中台的正式 SDK。
• yuqei-infra：补充 contract-review-worker 容器运行入口。

本轮没有把模型参数、Prompt 拼接、知识库检索逻辑塞回合同系统，符合 V2 重构版方案。

已完成

1. review_tasks 增加 worker 状态字段：

   • started_at
   • completed_at
   • retry_count
   • worker_name

2. Contract API 新增任务队列能力：

   • 创建审查任务后状态为 queued。
   • worker 领取任务后状态变为 running。
   • AI 审查成功后状态变为 succeeded，并回写风险项、依据、AI Trace。
   • AI 审查失败后状态变为 failed，保留错误信息。
   • 失败任务可通过原 /run 入口重新排队。

3. 新增合同审查 worker：

   • 模块：yuqei_contract_api.review_worker
   • 支持 --health
   • 支持 --run-once
   • 默认循环消费 queued 审查任务。

4. 前端详情页体验调整：

   • queued 状态显示“已加入审查队列”。
   • running 状态显示“AI 正在审查，页面会自动刷新”。
   • 失败状态才显示“重新排队”按钮。
   • 详情页在存在 queued/running 任务时自动刷新。

5. 部署配置：

   • Docker Compose 增加 contract-review-worker 服务。
   • contract-api 镜像补齐 psycopg[binary] 和 alembic 依赖。

简化原则

用户主流程保持为：

上传合同 / 进入详情 -> 发起审查 -> 等待结果自动刷新 -> 根据结果修改或提交审批

用户不需要理解模型、Prompt、RAG、worker、队列等技术细节。

后续建议

下一轮可以做“审查任务队列轻量可视化”，只给管理员看 worker 健康、最近失败任务和重试入口；普通用户继续只看到“下一步操作”和审查结果。