ai-contract-platform/project-docs/V2-delivery-closeout-checklist-2026-06-26.md

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：

   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 数据库治理和生产密钥治理。