# 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、知识命中和耗时。

数据库迁移新增：

```text
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
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”。