# 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` 从第一天就按四个最终工程组织：

```text
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. 关键原则

1. 合同业务流程不进 shared。
   合同模板、审批、台账、履约、归档、权限、审计仍属于 `contract-api` 和 `contract-web`。

2. AI 能力进入 AI 中台。
   模型配置、Provider 路由、RAG、知识库、Prompt、法律问答依据、AI 审计、评测进入 `ai-platform-api`。

3. 契约先行。
   合同系统调用 AI 中台只能通过 OpenAPI/SDK，不在合同后端直接写模型 provider 适配。

4. 旧 shared 不再扩功能。
   旧 `shared-ai-platform`、`shared-ai-platform-java`、`shared-ai-python-sdk` 只保留为参考，避免新旧主线继续分叉。

5. 先打通最小闭环，再补复杂治理。
   第一阶段不要先追求“大而全 AI 中台”，先完成合同系统真实需要的法律问答、合同起草、合同审查、引用依据、审计追踪。

## 5. 总体推进顺序

```text
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 调用审计。
- 基础评测样本。

第一批接口：

```text
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 资产冻结清单

输出文件：

```text
project-docs/V2旧shared资产盘点与迁移清单-2026-06-22.md
```

内容：

- 旧 shared 仓库当前状态。
- 可迁移模块。
- 只参考模块。
- 废弃模块。
- 未提交改动处理建议。

### T0-2：V2 技术栈最终冻结

输出文件：

```text
docs/adr/0001-v2-technology-stack.md
```

内容：

- 前端技术栈。
- 后端技术栈。
- 数据库/缓存/对象存储。
- AI 中台实现方式。
- 为什么不继续 Java shared 主线。

### T0-3：V2 API 契约骨架

输出目录：

```text
yuqei-ai-platform/packages/ai-openapi/
yuqei-contract-platform/packages/contract-openapi/
```

内容：

- OpenAPI 初始文件。
- API 命名规则。
- 错误码和分页规范。

### T0-4：V2 后端基础工程

输出目录：

```text
yuqei-contract-platform/services/contract-api/
yuqei-ai-platform/services/ai-platform-api/
yuqei-ai-platform/services/worker/
```

内容：

- health check。
- 配置加载。
- 日志。
- 数据库连接。
- 基础测试。

### T0-5：V2 前端基础工程

输出目录：

```text
yuqei-contract-platform/apps/contract-web/
yuqei-contract-platform/packages/design-system/
```

内容：

- 登录壳。
- 工作台壳。
- 主导航。
- 设计 tokens。
- 基础布局。

### T0-6：本地开发与部署底座

输出目录：

```text
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 契约骨架。