# AI 合同平台 V2 收口交付清单

日期：2026-06-26
本机核验时间：2026-06-26 17:23:32 +08:00
远端 Docker smoke 核验时间：2026-06-27 00:31:46 +08:00

## 结论

V2 的核心产品开发和 Phase 7 核心安全功能已经可以按“功能完成”处理。当前未完成项主要是发布前运维验收和生产化治理，不是新的业务功能开发。

当前本机已完成复核：

| 项目 | 状态 | 结果 |
| --- | --- | --- |
| Python 单元测试 | 通过 | `107 passed in 32.08s` |
| 前端 typecheck | 通过 | `npm run web:typecheck` 通过 |
| 前端生产构建 | 通过 | `npm run web:build` 通过 |
| npm 依赖审计 | 通过 | `found 0 vulnerabilities` |
| Bandit 代码扫描 | 通过 | 高/中/低危均为 0，`skipped_tests=0` |
| Python 依赖审计 | 通过 | `.venv-project` 依赖 39 个，漏洞 0 |
| Docker 本机验证 | 未通过环境检查 | 当前机器没有 `docker` 命令 |
| 远端 Docker smoke | 通过 | `project-docs/qa-artifacts/v2-smoke-docker-deploy/2026-06-27T00-14-39` |

## 本轮修正

Python 测试曾因旧测试仍导入已移除的 pgvector 动态 SQL helper 而失败。已改为断言当前固定 SQL 常量：

- `PGVECTOR_CANDIDATE_SQL_64`
- `PGVECTOR_CANDIDATE_SQL_64_FILTERED`
- `PGVECTOR_CANDIDATE_SQL_GENERIC`
- `PGVECTOR_CANDIDATE_SQL_GENERIC_FILTERED`

这样保持 Bandit 清零后的实现方向：不恢复动态 SQL helper，只保护固定查询模板的 64 维 HNSW 路径和通用维度回退路径。

## 已完成范围

| 范围 | 状态 | 交付物 |
| --- | --- | --- |
| 合同工作台、列表、详情、文件、审批、通知、义务、归档导出 | 已完成 | V2 功能文档和测试覆盖 |
| AI 中台、模型配置、Prompt、知识库、RAG explain、质量改进闭环 | 已完成 | V2 AI 系列文档和测试覆盖 |
| Phase 7 租户隔离 | 已完成 | `project-docs/V2-tenant-isolation-2026-06-26.md` |
| Phase 7 审计完整性 | 已完成 | `project-docs/V2-audit-integrity-2026-06-26.md` |
| Phase 7 数据备份 | 已完成 | `project-docs/V2-backup-restore-2026-06-26.md` |
| Phase 7 错误监控 | 已完成 | `project-docs/V2-error-monitoring-2026-06-26.md` |
| Phase 7 权限矩阵 | 已完成 | `project-docs/V2-permission-matrix-2026-06-26.md` |
| 性能数据库基线 | 已完成 | `project-docs/V2-performance-baseline-2026-06-26.md` |
| 安全扫描收口 | 已完成 | `project-docs/V2-security-scan-2026-06-26.md`、`bandit-project.json`、`pip-audit-project.json` |
| 部署 runbook | 已整理 | `project-docs/V2-deploy-runbook-2026-06-26.md` |
| 远端 Docker smoke | 已完成 | Web/API/AI/DB/worker/AI golden gate 全部通过 |
| 准生产接口级压测 | 已完成，性能门禁未全通过 | `project-docs/V2-interface-performance-baseline-2026-06-27.md` |

## 仍需完成

### P0 发布前必须验收

1. 目标 Docker 环境烟测

   已在 `192.168.3.90` 的独立 smoke 环境完成：

   - 产物：`project-docs/qa-artifacts/v2-smoke-docker-deploy/2026-06-27T00-14-39`
   - Web：`http://192.168.3.90:13000`
   - Contract API：`http://192.168.3.90:18100`
   - AI Platform API：`http://192.168.3.90:18101`
   - MinIO Console：`http://192.168.3.90:19001`

   验收结果：
   - Web、Contract API、AI Platform API 健康检查全部返回正常。
   - AI golden sample asset gate 通过：`90` samples、`6/6` suites、`16/16` checks。
   - PostgreSQL 中 `yuqei_contract`、`yuqei_ai`、`yuqei_ops` 均存在。
   - 合同审查 worker smoke 创建审查任务并处理成功，审查结果写回 `ai_audit_run_id`，风险项包含条款推荐。
   - 远端 smoke 容器最终状态均为 healthy。

2. 准生产/生产数据量压测

   已在 `192.168.3.90` 远端 smoke 环境完成准生产数据量接口级压测：

   - 产物：`project-docs/V2-interface-performance-baseline-2026-06-27.md`
   - 明细：`project-docs/qa-artifacts/v2-interface-benchmark/2026-06-27T00-51-47`
   - 数据量：`contracts=12007`、`review_tasks=16003`、`ai_run_audits=50008`、`knowledge_documents=10002`、`knowledge_chunks=60002`
   - 稳定性：7 个场景、420 次正式请求全部 `200`，总错误率 `0%`
   - 性能结论：合同详情和知识库 chunk 混合检索达标；合同列表、审批待办、统一搜索、AI Trace、知识库文档检索未达标

   验收标准：
   - 覆盖合同列表、合同详情、审批待办、统一搜索、AI Trace、知识库检索：已完成。
   - 输出 p50/p95/p99、RPS、错误率、数据量和流量模型：已完成。
   - 对照 `project-docs/V2-performance-baseline-2026-06-26.md` 给出是否达标结论：已完成，结论为“稳定性通过、生产上线性能门禁未全通过”。

   后续阻塞生产性能门禁的 P0 优化：
   - `knowledge-documents/search` 已切到数据库侧过滤，并在复核中达到目标 p95。
   - `audit/ai-runs` 列表已瘦身为摘要接口，并在复核中达到目标 p95。
   - 修复本轮排除的 `workspace?role=approver` 和 AI 质量看板 500，再纳入下一轮压测。
   - 当前还需要继续盯合同列表与合同详情的 p95，属于主流程性能优化，不再是 AI Trace / 知识库文档检索的问题。

### P1 生产化治理

1. CI 质量门

   将以下命令纳入 CI：

   ```powershell
   python -m pytest
   npm run web:typecheck
   npm run web:build
   npm audit --omit=dev --audit-level=high
   .\.venv-audit\Scripts\bandit.exe -r yuqei-contract-platform\services\contract-api\src yuqei-ai-platform\services\ai-platform-api\src yuqei-ai-platform\services\worker\src yuqei-ai-sdk-python\src -f json -o bandit-project.json
   .\.venv-audit\Scripts\pip-audit.exe --path .venv-project\Lib\site-packages -f json -o pip-audit-project.json --progress-spinner off
   ```

   验收标准：CI 中高危安全问题为 0，测试/typecheck/build 必须通过。

2. 数据库生产治理

   需要补齐：
   - DB 级 RLS 或等效租户隔离。
   - 独立数据库账号与最小权限。
   - 真实备份/恢复演练。
   - DB 级审计 append-only 约束。
   - 慢查询监控与阈值告警。

   验收标准：每一项都有配置、演练记录或监控截图/日志归档。

3. 生产密钥和环境变量管理

   当前文档里的真实口令样例已经替换为占位符。上线前仍需在目标环境完成 secret 注入和权限校验。

   验收标准：
   - `.env.production.example` 只保留占位符。
   - 真实密钥只存在于目标 secret 管理或宿主机安全配置中。
   - 发布归档不包含真实口令、token、私钥。

### P2 可后置增强

1. 接入真实 embedding/provider 与质量评估集。
2. 扩展大体量 DOCX/PDF/OCR 解析压测。
3. 补全 provider token、成本、错误率的生产审计看板。
4. 把 RAG explain 质量指标沉淀成固定回归集。

## 下一步执行顺序

1. 用准生产数据量补接口级压测报告。
2. 把 CI 质量门接起来，确保后续不再靠手工复跑。
3. 进入 P1 数据库治理和生产密钥治理。