11 KiB
AI合同平台V2与共享AI重构任务编排
日期：2026-06-22
1. 总结论
接下来不要把“合同平台 V2 重构”和“shared 重构”拆成两个互相独立的大工程。
正确做法是：
以
D:\yuqei-project\ai-contract-platform的main分支作为唯一 V2 主线，从第一天就落成yuqei-contract-platform、yuqei-ai-platform、yuqei-ai-sdk-python、yuqei-infra四个最终工程，形成“合同产品平台 + 统一 AI 中台 + OpenAPI 契约 + 正式 SDK + 统一基础设施”的一体化工程。
旧 shared 仓库不再继续扩展新功能，只作为历史参考、行为对照、代码迁移素材和数据导出来源。
2. 当前目录角色
| 目录 | 后续角色 | 操作原则 |
|---|---|---|
D:\yuqei-project\ai-contract-platform |
V2 主开发目录 | 所有 V2 新代码进入这里 |
D:\yuqei-project\ai-contract-platform-v1 |
V1 旧系统参考目录 | 只读参考，不继续开发新功能 |
D:\yuqei-project\shared-ai-platform |
旧 Python shared 原型 | 不新增能力，仅参考可复用代码和数据处理经验 |
D:\yuqei-project\shared-ai-platform-java |
旧 Java shared 主线 | 不新增能力，仅参考模块边界和接口设计 |
D:\yuqei-project\shared-ai-python-sdk |
旧 Python SDK 参考 | 参考客户端结构，V2 SDK 在 yuqei-ai-sdk-python 重做 |
D:\yuqei-project\shared-java-libs |
Java 公共库参考 | V2 当前不采用 Java 主线时不继续扩展 |
3. V2 新目录承载关系
V2 不再采用旧式 shared-* 多仓混合，也不采用临时混放路线。当前 main 从第一天就按四个最终工程组织：
yuqei-contract-platform/
apps/contract-web/ # 合同平台前端
services/contract-api/ # 合同业务后端
packages/design-system/ # 设计系统、组件规范、tokens
packages/contract-openapi/ # 合同业务 API 契约
yuqei-ai-platform/
services/ai-platform-api/ # 新共享 AI 中台服务
services/worker/ # 异步任务、文档解析、索引、导出
packages/ai-openapi/ # AI 中台 API 契约
yuqei-ai-sdk-python/ # 新正式 Python SDK
yuqei-infra/
docker/
compose/
nginx/
observability/
backup/
deploy/
shared 的新形态不是一个旧式 shared-* 大杂烩仓库，而是：
yuqei-ai-platform/services/ai-platform-api：共享 AI 中台服务。yuqei-ai-platform/packages/ai-openapi：AI 中台契约真相源。yuqei-ai-sdk-python：跨服务调用边界。yuqei-ai-platform/services/worker：AI、知识库、文档解析、导出等异步任务执行。yuqei-contract-platform/packages/design-system：前端体验统一，但不急于抽复杂组件库。
4. 关键原则
-
合同业务流程不进 shared。 合同模板、审批、台账、履约、归档、权限、审计仍属于
contract-api和contract-web。 -
AI 能力进入 AI 中台。 模型配置、Provider 路由、RAG、知识库、Prompt、法律问答依据、AI 审计、评测进入
ai-platform-api。 -
契约先行。 合同系统调用 AI 中台只能通过 OpenAPI/SDK，不在合同后端直接写模型 provider 适配。
-
旧 shared 不再扩功能。 旧
shared-ai-platform、shared-ai-platform-java、shared-ai-python-sdk只保留为参考，避免新旧主线继续分叉。 -
先打通最小闭环，再补复杂治理。 第一阶段不要先追求“大而全 AI 中台”，先完成合同系统真实需要的法律问答、合同起草、合同审查、引用依据、审计追踪。
5. 总体推进顺序
S0 旧 shared 盘点与冻结
↓
S1 V2 工程底座与契约骨架
↓
S2 AI 中台 MVP
↓
S3 SDK MVP
↓
S4 合同平台 MVP
↓
S5 企业协作与合同仓库
↓
S6 安全、性能、部署和数据迁移
6. S0：旧 shared 盘点与冻结
目标：避免旧 shared 仓库继续产生新分叉，同时把可复用资产盘清楚。
任务：
- 记录
shared-ai-platform当前未提交改动。 - 记录
shared-ai-platform-java当前未提交改动。 - 导出旧 AI 平台能力清单：
- 模型配置
- Chat/SSE
- 知识库
- 文档解析
- 法律审查 domain-pack
- Prompt 管理
- 任务/审计/用量
- 导出旧 Python SDK 能力清单：
- client 初始化
- 错误处理
- SSE 解析
- 请求/响应类型
- API prefix 行为
- 明确旧仓库状态：
- 不删除。
- 不继续新增 V2 能力。
- 必要时打
v1-archive分支或标签。
验收：
- 当前 V2 仓库中形成旧 shared 资产清单。
- 明确哪些代码迁移、哪些只参考、哪些废弃。
7. S1：V2 工程底座与契约骨架
目标：先把 V2 工程长出来，避免直接进入业务页面堆代码。
任务：
- 选择并冻结技术栈：
- 前端：Next.js/React 或重新确认更优方案。
- 后端：Python FastAPI 或重新确认更优方案。
- 数据库：PostgreSQL。
- 缓存/队列：Redis。
- 对象存储：MinIO/S3。
- 搜索：PostgreSQL FTS 起步，后续可扩展 OpenSearch/Meilisearch。
- 初始化四个最终工程的根目录、构建脚本和边界校验。
- 初始化
contract-api。 - 初始化
ai-platform-api。 - 初始化
contract-web。 - 初始化
yuqei-contract-platform/packages/contract-openapi和yuqei-ai-platform/packages/ai-openapi。 - 初始化基础 Docker Compose。
- 建立统一配置、日志、健康检查、错误码规范。
验收：
- 本地一条命令能启动基础服务。
contract-api和ai-platform-api都有/health。- OpenAPI 文档可生成。
- CI/本地验证命令可运行。
8. S2：AI 中台 MVP
目标：先把共享 AI 能力做成真实可调用服务。
范围：
- 模型连接配置可热更新。
- Provider 路由。
- Chat/SSE。
- 法律问答 with citations。
- 知识库文档入库、解析、检索。
- Prompt 模板和版本。
- AI 调用审计。
- 基础评测样本。
第一批接口：
POST /api/v1/ai/chat/stream
GET /api/v1/ai/conversations
POST /api/v1/knowledge-bases
POST /api/v1/knowledge-bases/{id}/documents
POST /api/v1/legal/qa
POST /api/v1/legal/review
GET /api/v1/audit/ai-runs
验收：
- 法律问答能返回答案和引用依据。
- 合同审查能返回结构化风险项。
- 所有 AI 调用有审计记录。
- 模型参数不写死在代码中。
9. S3：SDK MVP
目标：让合同系统通过正式 SDK 调 AI 中台。
任务：
- 在
yuqei-ai-platform/packages/ai-openapi固化 AI 中台契约。 - 在
yuqei-ai-sdk-python实现 Python SDK：- 同步 client
- 异步 client
- SSE 事件解析
- 类型定义
- 错误映射
- 超时、重试、trace id
- 如确需前端或 Node 侧直接调用 AI 中台，另建
yuqei-ai-sdk-typescript并按同样契约生成。 - 建立 SDK contract tests。
验收：
- SDK 不依赖旧 vendored 代码。
- 合同后端通过 SDK 调用 AI 中台。
- SDK 版本与 OpenAPI 契约一致。
10. S4：合同平台 MVP
目标：先让企业主线最小闭环跑通。
范围：
- 登录、租户、组织、角色。
- 合同起草。
- 合同审查。
- 合同详情。
- 下一步操作区。
- 文件上传和导出。
- 审计时间线。
- 合同列表和搜索。
原则：
- 工作台只突出“待我处理”和“快速发起”。
- 合同详情只突出“下一步操作”。
- 审批流条件出现，不默认压迫所有用户。
- 审计、版本、履约、归档保留但默认折叠。
- 管理员能力集中到管理区，普通用户不看到复杂配置。
验收：
- 起草、审查、下载、详情、审计闭环可跑通。
- 前端页面不再卡片堆叠、按钮过密。
- AI 能力全部通过 SDK 调用。
11. S5：企业协作与合同仓库
目标：从工具升级为企业合同管理平台。
范围：
- 审批工作台。
- 退回后重提。
- 审批时间线。
- 合同仓库。
- 文件预览。
- 批量下载。
- 合同台账。
- 生命周期筛选。
- 提醒与通知。
- 数据导出。
验收：
- 企业日常处理合同不需要理解复杂后台。
- 权限边界清晰。
- 搜索、台账、仓库、详情状态口径一致。
12. S6：安全、性能、部署和数据迁移
目标：达到商业交付标准。
范围：
- PostgreSQL schema 分层。
- Row Level Security 或等效租户隔离策略。
- 对象存储权限与加密。
- 审计不可篡改策略。
- 数据备份与恢复演练。
- 性能压测。
- 生产 Docker/Compose/K8s 可选部署。
- V1 数据迁移脚本。
- 灰度发布和回滚。
验收：
- 工作台 API p95 < 300ms，不含 AI 长任务。
- 合同详情 p95 < 500ms，不含大文件预览。
- AI 长任务可追踪、可重试、可恢复。
- 备份恢复演练通过。
- 发布前验证命令可一键执行。
13. 第一轮具体任务安排
当前最应该先做下面 6 件事：
T0-1：旧 shared 资产冻结清单
输出文件：
project-docs/V2旧shared资产盘点与迁移清单-2026-06-22.md
内容：
- 旧 shared 仓库当前状态。
- 可迁移模块。
- 只参考模块。
- 废弃模块。
- 未提交改动处理建议。
T0-2：V2 技术栈最终冻结
输出文件：
docs/adr/0001-v2-technology-stack.md
内容：
- 前端技术栈。
- 后端技术栈。
- 数据库/缓存/对象存储。
- AI 中台实现方式。
- 为什么不继续 Java shared 主线。
T0-3：V2 API 契约骨架
输出目录：
yuqei-ai-platform/packages/ai-openapi/
yuqei-contract-platform/packages/contract-openapi/
内容：
- OpenAPI 初始文件。
- API 命名规则。
- 错误码和分页规范。
T0-4：V2 后端基础工程
输出目录：
yuqei-contract-platform/services/contract-api/
yuqei-ai-platform/services/ai-platform-api/
yuqei-ai-platform/services/worker/
内容：
- health check。
- 配置加载。
- 日志。
- 数据库连接。
- 基础测试。
T0-5：V2 前端基础工程
输出目录：
yuqei-contract-platform/apps/contract-web/
yuqei-contract-platform/packages/design-system/
内容：
- 登录壳。
- 工作台壳。
- 主导航。
- 设计 tokens。
- 基础布局。
T0-6：本地开发与部署底座
输出目录：
yuqei-infra/compose/
yuqei-infra/docker/
yuqei-infra/nginx/
yuqei-infra/observability/
内容：
- 本地 Docker Compose。
- PostgreSQL、Redis、MinIO。
- 服务环境变量模板。
- 一键启动文档。
14. 下一步建议
下一步不要马上写合同业务页面，也不要先重写完整 AI 中台。
建议从 T0-1：旧 shared 资产冻结清单 开始，因为这一步能避免后续重构时反复纠结：
- 哪些旧 shared 代码要迁移？
- 哪些旧 shared 能力要废弃？
- 哪些接口要重新设计？
- 哪些未提交改动需要保存？
完成 T0-1 后，再进入 T0-2 技术栈 ADR 和 T0-3 OpenAPI 契约骨架。