yuqei
effbefc83d
Build and Test Quality Gate / Contract Web typecheck and build (pull_request) Successful in 3m46s
Build and Test Quality Gate / Python tests and Contract API migration (pull_request) Failing after 19m11s
Security Quality Gate / npm audit, Bandit, pip-audit, detect-secrets (pull_request) Successful in 8m8s
102 lines
4.6 KiB
Markdown
102 lines
4.6 KiB
Markdown
# 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”。
|