docs: clarify V2 shared module boundaries
This commit is contained in:
@@ -155,7 +155,52 @@ yuqei-platform-v2/
|
||||
- 合同系统和 AI 中台边界通过 OpenAPI 和 SDK 固化。
|
||||
- 后续团队规模扩大后，可以再按 `contract-platform`、`ai-platform`、`infra` 拆成独立仓库。
|
||||
|
||||
### 4.2 为什么不继续多个 shared 仓库
|
||||
### 4.2 最终逻辑边界与未来仓库命名
|
||||
|
||||
V2 当前采用 monorepo 是为了避免重构初期多仓库版本漂移，但产品和工程边界必须按下面四块执行。未来如果拆成独立仓库，仓库名直接采用下表，避免重新出现旧 `shared-*` 大杂烩结构。
|
||||
|
||||
| 最终逻辑仓库/产品线 | 当前 V2 workspace 承载 | 负责内容 | 不负责内容 |
|
||||
|---|---|---|---|
|
||||
| `yuqei-contract-platform` | `apps/contract-web`、`services/contract-api`、`packages/contract-openapi`、合同侧 worker 任务 | 企业合同系统：前端、后端、审批、台账、合同仓库、合同房间、权限、合同审计、业务通知 | 模型 provider、Prompt 拼装、RAG 检索、知识库内部表、AI 运行审计 |
|
||||
| `yuqei-ai-platform` | `services/ai-platform-api`、`packages/ai-openapi`、AI 侧 worker 任务 | 统一 AI 中台：模型网关、知识库、RAG、Prompt、法律审查、法条引用、文档智能、AI 审计、质量评测 | 合同审批流、合同台账、合同房间业务状态 |
|
||||
| `yuqei-ai-sdk-python` | `sdks/python` | 合同系统调用 AI 中台的正式 Python SDK，由 OpenAPI 生成基础客户端，再手写业务友好封装 | 业务数据库访问、模型 provider 直连、旧 vendored SDK 兼容层 |
|
||||
| `yuqei-infra` | `infra/*` | 部署、环境变量、监控、日志、备份、发布脚本、安全基线 | 业务功能、AI 业务能力、前端产品体验 |
|
||||
|
||||
旧模块最终处理方式：
|
||||
|
||||
| 旧模块 | V2 处理方式 |
|
||||
|---|---|
|
||||
| `shared-ai-platform-java` | 不作为未来主线；本项目未正式上线前不需要继续做线上兼容，只冻结为旧服务行为对照和接口参考；新 AI 能力不得再写入该模块。 |
|
||||
| `shared-ai-platform` | 保留历史文档、原型和数据处理经验；不再承接生产功能。 |
|
||||
| `shared-ai-python-sdk` | 保留 SDK 定位和测试思想；正式 SDK 在 `sdks/python` 重做，建议包名继续向 `yuqei-ai-sdk-python` 收敛。 |
|
||||
| `shared-java-libs` | 如果 V2 不采用 Java 主线，归档为参考，不再扩展。 |
|
||||
| `ai-contract-platform/backend/vendor/shared-ai-platform-sdk` | 最终删除；合同系统内不得再塞一份 SDK 副本。 |
|
||||
|
||||
合同系统只做业务。它只能通过 SDK/OpenAPI 向 AI 中台表达业务意图：
|
||||
|
||||
- 帮我审查这份合同。
|
||||
- 帮我回答这个法律问题，并返回依据。
|
||||
- 帮我生成这份合同。
|
||||
- 帮我改写这个条款。
|
||||
- 帮我提取履约义务。
|
||||
|
||||
AI 中台必须承接模型、Prompt、知识库、RAG、引用依据、运行审计和质量评测。合同系统不得因为开发方便而绕过 SDK 直接调用模型、拼 Prompt、查 AI 知识库内部表或写 AI 审计。
|
||||
|
||||
关键技术原则：
|
||||
|
||||
- API 先行：`packages/ai-openapi` 和 `packages/contract-openapi` 是跨边界契约真相源。
|
||||
- 长流程可靠：合同审查、文档解析、知识库索引、批量导入等长流程后续接入 durable workflow 方案，例如 Temporal 或同类能力。
|
||||
- 全链路可观测：AI 调用、RAG 命中、Prompt 版本、模型耗时、错误和费用后续纳入 OpenTelemetry 体系。
|
||||
|
||||
防跑偏检查清单：
|
||||
|
||||
- 新 AI 能力先看是否属于 `yuqei-ai-platform`，不要直接写进 `services/contract-api`。
|
||||
- `services/contract-api` 调 AI 只能使用 `yuqei_sdk` 或 OpenAPI 生成客户端。
|
||||
- 新 SDK 代码只能进入 `sdks/python` 或 `sdks/typescript`，不得恢复 `backend/vendor/shared-ai-platform-sdk`。
|
||||
- 新部署、环境变量、监控、备份、发布脚本进入 `infra`。
|
||||
- 旧 `shared-*` 仓库只能只读参考，不新增功能、不新增依赖。
|
||||
|
||||
### 4.3 为什么不继续多个 shared 仓库
|
||||
|
||||
旧 shared 结构的问题：
|
||||
|
||||
|
||||
@@ -0,0 +1,81 @@
|
||||
# V2 shared 路线防跑偏核查
|
||||
|
||||
日期：2026-06-22
|
||||
|
||||
## 1. 核查结论
|
||||
|
||||
当前 V2 方向总体没有跑偏。
|
||||
|
||||
现有方案已经明确不继续维护旧 `shared-ai-platform`、`shared-ai-platform-java`、`shared-ai-python-sdk`、`backend/vendor/shared-ai-platform-sdk` 这套历史结构，并且已经把新 shared 形态收敛为：
|
||||
|
||||
- 合同产品平台
|
||||
- 统一 AI 中台
|
||||
- 正式 SDK
|
||||
- 统一基础设施
|
||||
|
||||
本次补强了主方案中的最终逻辑命名，明确未来拆仓时对应：
|
||||
|
||||
- `yuqei-contract-platform`
|
||||
- `yuqei-ai-platform`
|
||||
- `yuqei-ai-sdk-python`
|
||||
- `yuqei-infra`
|
||||
|
||||
V2 当前保留 monorepo 只是开发阶段的工程组织方式，不代表把边界混在一起。
|
||||
|
||||
## 2. 已核查文档
|
||||
|
||||
- `project-docs/AI合同平台V2重构版开发方案-2026-06-22.md`
|
||||
- `project-docs/AI合同平台V2与共享AI重构任务编排-2026-06-22.md`
|
||||
- `project-docs/V2旧shared资产盘点与迁移清单-2026-06-22.md`
|
||||
- `docs/adr/0001-v2-technology-stack.md`
|
||||
- `README.md`
|
||||
- `V2-README.md`
|
||||
|
||||
## 3. 当前代码路线对照
|
||||
|
||||
| 目标边界 | 当前代码位置 | 当前状态 |
|
||||
|---|---|---|
|
||||
| `yuqei-contract-platform` | `apps/contract-web`、`services/contract-api`、`packages/contract-openapi` | 已建立 V2 前端壳、合同 API、合同 OpenAPI；合同 API 通过 SDK 调 AI。 |
|
||||
| `yuqei-ai-platform` | `services/ai-platform-api`、`packages/ai-openapi` | 已建立模型配置、知识文档检索、法律问答、AI run audit 的 MVP。 |
|
||||
| `yuqei-ai-sdk-python` | `sdks/python` | 已有 `AiPlatformClient` 和法律问答调用闭环；后续扩展合同审查、生成、改写、履约义务提取。 |
|
||||
| `yuqei-infra` | `infra/compose`、`infra/docker`、`infra/nginx`、`infra/observability`、`infra/backup`、`infra/deploy` | 已建立基础目录和本地 compose 底座；后续补 OpenTelemetry、备份、发布脚本和生产环境模板。 |
|
||||
|
||||
## 4. 旧 shared 处理状态
|
||||
|
||||
| 旧模块 | 当前判断 | 后续动作 |
|
||||
|---|---|---|
|
||||
| `shared-ai-platform-java` | 不作为未来主线 | 冻结为行为对照和接口参考；不新增 V2 功能。 |
|
||||
| `shared-ai-platform` | 不作为生产 AI 中台 | 只保留文档、原型和数据处理经验。 |
|
||||
| `shared-ai-python-sdk` | SDK 定位有价值，但实现重做 | 以 `sdks/python` 为正式 SDK 主线。 |
|
||||
| `shared-java-libs` | V2 不采用 Java 主线 | 归档参考。 |
|
||||
| `backend/vendor/shared-ai-platform-sdk` | 不应恢复 | 合同系统不得再内置 SDK 副本。 |
|
||||
|
||||
## 5. 代码核查结果
|
||||
|
||||
- 当前 `main` 分支已经是 V2 主线。
|
||||
- 当前目录没有发现 `backend/vendor/shared-ai-platform-sdk`。
|
||||
- 当前代码没有发现旧 `shared-ai-platform`、`shared-ai-platform-java`、`shared-java-libs` 的生产依赖。
|
||||
- `services/contract-api` 通过 `yuqei_sdk.AiPlatformClient` 调用 AI 中台，没有直接写模型 provider 适配。
|
||||
- `services/ai-platform-api` 正在承接模型配置、知识库检索、法律问答、AI 审计能力。
|
||||
- `packages/ai-openapi` 已描述 AI 中台 API 边界。
|
||||
- `packages/contract-openapi` 已声明 Contract API 只能通过 SDK/OpenAPI client 调 AI Platform。
|
||||
|
||||
## 6. 仍需注意的风险
|
||||
|
||||
1. `sdks/typescript` 还没有正式实现，后续如果前端或 Node 服务要直接调用 AI 中台，需要补契约生成和封装。
|
||||
2. `services/ai-platform-api` 目前还是 MVP，知识库和审计主要是内存实现，后续必须落数据库、迁移脚本和权限。
|
||||
3. OpenTelemetry、费用统计、模型耗时拆解还没有完成，不能把当前 MVP 当成最终可观测能力。
|
||||
4. Temporal 或同类 durable workflow 还未接入，长流程任务需要先用清晰接口预留边界。
|
||||
5. 后续开发中只要出现“为了方便在合同 API 里直接拼 Prompt 或查知识库”的需求，必须回退到 AI 中台边界重新设计。
|
||||
|
||||
## 7. 下一步建议
|
||||
|
||||
继续按这条路线推进，不要再回到旧 shared 多仓结构。
|
||||
|
||||
优先顺序：
|
||||
|
||||
1. AI Platform 数据持久化：provider config、prompt template、knowledge document、ai run audit。
|
||||
2. OpenAPI 生成和 SDK 契约测试，让 `sdks/python` 真正成为稳定调用边界。
|
||||
3. 法律审查、合同生成、条款改写、履约义务提取进入 AI 中台，而不是合同 API。
|
||||
4. 合同系统继续做企业合同主流程：工作台、合同房间、审批、台账、仓库、审计。
|
||||
5. `infra` 补环境模板、健康检查、监控日志、备份和发布脚本。
|
||||
Reference in New Issue
Block a user