ai-contract-platform/project-docs/V2-next-development-optimization-plan-2026-06-28.md

AI 合同平台 V2 下一阶段开发优化方案

日期：2026-06-28

方案目标

本方案用于约束 V2 后续开发方向，避免继续在临时数据库、过大的模块文件和未定型 schema 上叠加功能。

当前 V2 已经完成大量核心能力，包括合同工作台、模板资产、条款/规则库、审查推荐修复、AI Trace、质量闭环、法律全文库与法规变更影响 MVP。但项目正从“能跑起来”进入“可长期交付、可维护、可部署”的阶段，下一步重点应从继续堆功能转为：

1. 先统一数据库权威环境。
2. 再补运行时 schema 安全检查。
3. 然后拆分过大的后端模块。
4. 同步硬化数据库模型。
5. 最后继续吸收 V1 优秀资产并做交付收口。

当前判断

已经做对的方向

• V2 没有继续沿用 V1 单体后端结构，而是拆成合同平台、AI 中台、基础设施。
• 文档和 compose 已经明确三库目标：yuqei_contract、yuqei_ai、yuqei_ops。
• V1 的模板、条款、规则、黄金样本、法律全文能力已经开始按 V2 模型吸收，而不是直接复制 V1 页面和旧表结构。
• UI 方向已经明确为“V1 风格、V2 结构”，避免照搬 V1 混乱布局。
• 压测、安全扫描、CI 质量门、Docker smoke 已经进入收口阶段。

现在最容易跑偏的地方

• 继续不加区分地使用 192.168.3.90:5432/yuqei_contract，会把临时合同测试库误当成完整 V2 数据库。
• 在 Docker smoke、宿主机 PostgreSQL、旧 V1 库之间来回切换，但没有登记权威环境。
• 继续向 contracts.py、repository.py 这类大文件堆功能。
• 在数据库事实表里继续保留 UI 展示字段，例如 status_label、status_tone、next_action。
• 用 SQLite 单测结果替代 PostgreSQL 联调和准生产验收。
• 继续补新业务页面，而不是先把 schema、模块边界和运行检查收住。

总体推进原则

1. 不再临时新建 V2 数据库，除非先更新数据库登记表并说明用途。
2. 不删除旧库和临时库，先只读核验、登记、归档，再决定是否清理。
3. V1 资产只做“精选迁移”，不复制 V1 单体表结构。
4. 本地功能验收必须连接 PostgreSQL；SQLite 只用于轻量单测。
5. 新功能不能继续堆进大文件，必须先放进对应领域模块。
6. 先改基础结构，再补业务体验；先做可验证边界，再做页面扩展。
7. 每一阶段必须有验收标准，未通过不进入下一阶段。

阶段 0：开发总控与数据库权威确认

优先级：最高

目标：先确认后续开发到底连接哪套数据库，避免继续混乱。

任务：

1. 使用 yuqei-infra/scripts/inspect-v2-database-state.ps1 只读检查远端数据库状态。
2. 启动并核验 Docker smoke 环境 yuqei-contract-v2-smoke-*。
3. 确认 smoke PostgreSQL 中是否存在：
   • yuqei_contract
   • yuqei_ai
   • yuqei_ops
4. 确认迁移头：
   • contract_api_alembic_version
   • ai_platform_alembic_version
5. 确认扩展：
   • pg_trgm
   • vector
6. 更新 V2-active-database-registry-2026-06-28.md，明确唯一 V2 dev/smoke 权威环境。
7. 把 ai_contract_platform 标记为 V1/旧单体只读库。
8. 把宿主机 5432/yuqei_contract 标记为临时测试库，除非后续正式补齐三库并登记为 V2 环境。

验收标准：

• 文档中明确唯一 V2 权威开发/准生产数据库。
• 本地后端环境变量能清楚指向该权威库。
• 不再出现“这个库是不是 V2”的不确定状态。
• 没有删除、覆盖、重建任何历史库。

阶段 1：运行时 schema 检查与环境防误连

优先级：最高

目标：应用启动后不仅知道“服务活着”，还要知道“连的是正确数据库，schema 是正确版本”。

任务：

1. Contract API 增加 schema check 能力。
2. AI Platform API 增加 schema check 能力。
3. 检查内容包括：
   • 当前数据库名
   • 当前数据库 backend
   • Alembic version table 是否存在
   • Alembic version 是否等于当前 head
   • 核心表是否存在
   • PostgreSQL 必要扩展是否存在
4. Docker healthcheck 从 /health 升级为“服务健康 + schema ready”。
5. staging/production 下禁止：
   • SQLite
   • database auto create
   • demo seed
6. 本地 Codex 浏览器联调文档改为默认连接 PostgreSQL。

验收标准：

• 连到 ai_contract_platform 时，V2 schema check 必须报错。
• 连到缺 yuqei_ai 的环境时，AI 平台 schema check 必须报错。
• 连到迁移头落后的库时，schema check 必须报错。
• Docker smoke 全量通过后才能继续业务开发。

阶段 2：后端模块化拆分

优先级：高

目标：把当前过大的模块拆成可维护结构，先拆结构，不改行为。

Contract API 拆分目标：

yuqei_contract_api/
  api/
  domain/
  persistence/
  services/
  seed/

第一批拆分任务：

1. 从 contracts.py 拆出 SQLAlchemy models。
2. 从 contracts.py 拆出 Pydantic schemas/domain models。
3. 从 contracts.py 拆出 repository：
   • contracts
   • files
   • review_tasks
   • templates
   • legal_assets
   • audit
4. 从 main.py 拆出 FastAPI routers：
   • contracts
   • files
   • review
   • templates
   • legal assets
   • admin/system
5. 保持现有 API 路径和响应不变。

AI Platform 拆分目标：

yuqei_ai_platform_api/
  api/
  domain/
  persistence/
  services/

第一批拆分任务：

1. 拆 Provider 配置仓储。
2. 拆 Prompt 生命周期仓储。
3. 拆 Knowledge/RAG 仓储。
4. 拆 AI Run/Audit 仓储。
5. 拆 Quality 仓储。
6. 拆 Worker runtime 仓储。

验收标准：

• 拆分后测试全部通过。
• API path 不变，前端不需要同步大改。
• 单个模块不再继续承载多个领域。
• 后续新增功能必须进入对应领域模块。

阶段 3：数据库 schema 硬化

优先级：高

目标：把 MVP 数据模型推进到长期生产模型。

合同平台任务：

1. 新增 contract_versions，合同正文从 contracts.body_content 逐步迁移到版本表。
2. 新增正式审批模型：
   • approval_instances
   • approval_steps
   • approval_actions
3. 逐步迁出 UI 展示字段：
   • status_label
   • status_tone
   • next_action
   • next_actions
4. 核心表补齐：
   • tenant_id
   • created_by
   • updated_by
   • deleted_at
5. 审查风险项从 JSON 快照逐步结构化：
   • risk item
   • citation
   • recommended clause
   • applied repair action
6. 模板、条款、规则、法律全文、法规变更影响扫描建立清晰的版本和发布快照关系。

AI 平台任务：

1. 知识库、AI Trace、质量评估补齐 tenant_id。
2. AI Trace 增加脱敏、保留周期和归档策略。
3. Provider/OCR/API key 改为加密存储或密钥服务引用。
4. 高频表评估分区：
   • ai_run_audits
   • worker executions
   • ingestion jobs
5. pgvector 维度、索引、重建流程固定为可运维方案。

验收标准：

• 合同正文修改有版本历史。
• 审批动作能追溯到步骤、人员、时间、结果。
• 列表/搜索/待办不依赖 JSON 全表扫描。
• 数据库字段表达业务事实，不表达 UI 文案。
• 迁移能从空 PostgreSQL 一键跑到 head。

2026-07-01 Phase 3 display cache 收口状态

当前 Phase 3 中 status_label/status_tone/next_action/next_actions 的治理状态已更新：

• 旧 display cache 列仍保留，继续作为 API 兼容、回滚和 cleanup migration 前保护面。
• smoke PostgreSQL 已按完整 ContractActionContext 口径完成一致性 backfill。
• 最新 /api/v1/runtime/schema-check 中 display_cache_consistency.mismatch_count=0，display_cache_cleanup_prestate.status=ok。
• 完整上下文已纳入审查风险、条款修复、审批实例、履约任务和 action_hint，不再只按合同状态默认值判断旧缓存一致性。
• contract-api 容器 healthcheck 已改回轻量 /api/v1/health；重型 schema-check 继续作为 smoke/CI 质量门。

后续小片已继续推进到旧动作缓存列停写：

• 生产 SQLAlchemy 写路径不再刷新 contracts.next_action/next_actions。
• display_cache_consistency 调整为只检查 status_label/status_tone 与派生状态展示一致。
• next_action/next_actions 用户可见值继续由完整 ContractActionContext 派生。
• 详细记录见 project-docs/V2-phase3-stop-legacy-next-action-writes-2026-07-01.md。
• 前端编辑入口和 API/OpenAPI 已明确：人工提示只写 action_hint，旧 next_action/next_actions 写入字段仅保留 deprecated 兼容。详见 project-docs/V2-phase3-action-hint-ui-api-semantics-2026-07-01.md。

因此，下一片仍不进入删列 migration。优先部署 smoke 验证旧动作列停写后合同列表、详情、workspace、统一搜索和审查/审批/条款修复链路不退化；连续多轮 smoke 通过后，再评审是否进入 cleanup migration。

详细记录见：

• project-docs/V2-phase3-display-cache-context-prestate-2026-07-01.md

阶段 4：V1 优秀资产继续吸收

优先级：中高

目标：继续吸收 V1 优秀部分，但只按 V2 新模型导入。

优先顺序：

1. 模板库资产完整迁移。
2. 标准条款库完整迁移。
3. 审查规则库完整迁移。
4. 黄金样本、Prompt 评估集迁移。
5. 精选法律全文迁移。
6. 法规变更影响分析增强。
7. 公开首页、演示申请、套餐计费后置。

导入规则：

• 每条资产保留 V1 source id。
• 每次导入保留 batch id。
• 每条资产计算 hash。
• 支持幂等重复导入。
• 生成差异报告。
• 不直接复制 V1 表结构。

验收标准：

• V2 能从空库迁移到 head 后导入 V1 精选资产。
• 导入脚本可重复执行。
• 后台管理页看到的是 V2 模型资产，不是 V1 旧结构镜像。

阶段 5：前端体验统一与运营后台完善

优先级：中

目标：延续“V1 风格、V2 结构”，但不再照搬 V1 页面结构。

任务：

1. 保持左侧树形/导航 + 右侧工作区的 V2 清晰结构。
2. 继续吸收 V1 的视觉元素：
   • 更精致的卡片层次
   • 状态标签
   • 图标按钮
   • 细腻背景和边框
   • 管理后台表格密度
3. 管理后台继续补：
   • 法律全文库列表/详情
   • 法规变更影响扫描
   • 影响项跳转到模板/条款/规则草稿
   • schema/runtime 状态页
4. 避免 V1 大而全页面。

验收标准：

• 页面结构仍保持 V2 的清晰左右布局。
• 样式统一到当前 V1 风格基线。
• 管理后台可以完成资产运营闭环。
• 不出现页面过载和入口混乱。

阶段 6：交付收口

优先级：中

目标：把系统从开发态推进到可交付态。

任务：

1. Docker smoke 全量通过。
2. CI 质量门包括：
   • 后端测试
   • 前端 typecheck
   • 安全扫描
   • 依赖审计
   • AI golden gate
3. 接口级压测基线复跑：
   • 合同列表
   • 合同详情
   • 审批待办
   • 统一搜索
   • AI Trace
   • 知识库检索
4. 安全扫描复跑：
   • Bandit
   • pip-audit
   • npm audit 或同类前端依赖扫描
5. 部署文档整理：
   • 环境变量
   • 数据库初始化
   • 迁移顺序
   • smoke 测试
   • 回滚步骤
   • 备份恢复

验收标准：

• Docker smoke 通过。
• CI 质量门通过。
• 压测报告有 p50/p95/p99 和错误率。
• 安全扫描无高危未解释项。
• 部署文档可交给运维照着执行。

当前最推荐的下一步

阶段 0 已在 2026-06-28 完成：Docker smoke 环境已部署当前 V2 代码并通过三库、迁移头、扩展和核心表核验，yuqei-contract-v2-smoke 已登记为当前 V2 dev/smoke 权威环境。

阶段 1 已在 2026-06-28 完成：Contract API 和 AI Platform API 已新增 /api/v1/runtime/schema-check，Docker healthcheck 已升级为 schema ready，远端 smoke 验证通过。

现在进入阶段 2，不再继续新增业务页面。

具体顺序：

1. 先拆 Contract API 的 SQLAlchemy models 和 repository 边界。
2. 再拆 Contract API 的 FastAPI routers。
3. 拆 AI Platform repository 的 Provider、Prompt、Knowledge、AI Run、Quality、Worker 子领域。
4. 保持现有 API path 和响应结构不变。
5. 每次拆分后跑对应测试和 Docker smoke。

不做清单

在阶段 0 和阶段 1 完成前，暂不做：

• 不继续创建新的 V2 数据库。
• 不删除旧库。
• 不把 5432/yuqei_contract 默认当成完整 V2 环境。
• 不继续往 contracts.py 和 repository.py 大文件里堆新功能。
• 不继续扩大 SQLite 验收范围。
• 不迁移商业订单、发票、计费后台。
• 不照搬 V1 页面结构。

决策门

后续每次开始新任务前先判断：

1. 是否依赖权威数据库？如果是，先确认数据库登记表。
2. 是否会新增表或迁移？如果是，先确认归属 yuqei_contract 还是 yuqei_ai。
3. 是否会改大文件？如果是，优先拆模块。
4. 是否只是补 V1 功能？如果是，必须确认是按 V2 模型吸收，而不是复制 V1。
5. 是否可验收？如果没有验收标准，不进入开发。

这五个问题都能回答清楚，再进入实现。