yuqei/ai-contract-platform
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
main
ai-contract-platform/project-docs/V2旧shared资产盘点与迁移清单-2026-06-22.md
T

8.1 KiB
Raw Permalink Blame History

V2 旧 shared 资产盘点与迁移清单

日期：2026-06-22

1. 结论

旧 shared-* 仓库不再作为 V2 的继续开发主线。

V2 采用当前仓库 D:\yuqei-project\ai-contract-platform 的四个最终工程边界，把 shared 能力重新落到：

  • yuqei-ai-platform/services/ai-platform-api
  • yuqei-ai-platform/packages/ai-openapi
  • yuqei-ai-sdk-python
  • 如确需 TypeScript SDK，另建 yuqei-ai-sdk-typescript
  • yuqei-ai-platform/services/worker
  • yuqei-contract-platform/packages/design-system

旧 shared 仓库只作为历史参考、行为对照、迁移素材和测试样例来源。

2. 旧仓库当前状态

仓库 当前状态 未提交改动 V2 处理策略
shared-ai-platform Python 原型平台，含知识库、会话、任务、OCR、RAG、SDK 原型和大量文档 有 参考实现和数据处理经验，不继续扩展
shared-ai-platform-java Java 版共享 AI 平台，含 v0.2 contract、legal-review、knowledge、chat、prompt、provider-router 有 参考模块边界、契约和测试，不迁移 Java 技术栈
shared-ai-python-sdk 形式化 Python SDK，默认 /api/v0.2，含 SSE、错误处理、legal-review、document extraction 测试 无 迁移 API 设计和测试思想，V2 在 yuqei-ai-sdk-python 重做
shared-java-libs Java 公共库，含 shared-ai-sdk、shared-web、shared-storage、shared-notify、shared-core 有 V2 不采用 Java 主线，仅参考公共能力边界

3. shared-ai-platform 盘点

3.1 可迁移资产

  • OCR/文档解析经验：
    • Tesseract 与 PaddleOCR 双引擎思路。
    • 扫描件 PDF OCR 质量门禁。
    • OCR 失败原因结构化返回。
  • RAG/知识库经验：
    • knowledge-bases。
    • documents upload/retry。
    • retrieval service。
    • sync content。
  • Chat/SSE 经验：
    • conversations stream。
    • conversations history。
    • SSE 事件格式。
  • 平台治理经验：
    • apps。
    • tasks/jobs。
    • usage/costs。
    • evals。
    • ops/system。
  • 测试样例：
    • tests/test_v0_2_conversations_api.py
    • tests/test_v0_2_knowledge_api.py
    • tests/test_v0_2_document_extraction_api.py
    • tests/test_legal_review_domain_pack.py
    • tests/test_python_sdk.py

3.2 只参考不迁移

  • 旧 Python 原型的目录结构。
  • 旧 app/api/v0_2 具体路由实现。
  • 本地 _runtime、storage、local-knowledge。
  • 旧部署脚本。
  • 旧文档归档结构。

3.3 废弃

  • 作为生产 AI 中台主线的定位。
  • 与 V2 重复的 SDK 原型。
  • 旧 /api/v0.1 兼容包袱。

3.4 当前未提交改动处理建议

当前未提交改动集中在：

  • app/core/config.py
  • app/services/document_extraction_service.py
  • requirements.txt

内容是 PaddleOCR 支持和 OCR 引擎配置。

V2 处理建议：

  • 不在旧仓库继续提交该功能。
  • 将“可配置 OCR 引擎、OCR 质量门禁、OCR 失败结构化返回”作为 yuqei-ai-platform/services/worker 的文档解析需求。
  • PaddleOCR 是否启用作为 V2 技术栈 ADR 的可选项，默认不阻塞基础工程。

4. shared-ai-platform-java 盘点

4.1 可迁移资产

  • v0.2 contract 文档思路：
    • shared-ai-platform-contract/docs/shared-ai-v0.2-contract.md
    • 统一请求头。
    • 响应 envelope。
    • 分页规范。
    • snake_case 约定。
  • legal-review v0.2 兼容思路：
    • 同时支持 /api/v0.1/domain-packs/legal-review
    • 和 /api/v0.2/domain-packs/legal-review
  • legal-review 结构化审查经验：
    • 风险摘要。
    • 风险项。
    • 审查意见。
    • 建议动作。
    • confidence summary。
  • 模块边界：
    • provider-router。
    • prompts。
    • knowledge。
    • chat。
    • tasks。
    • usage。
    • domain-legal-review。
  • API smoke test 思路：
    • 同一测试覆盖 v0.1/v0.2 legal-review。
    • SDK/服务端契约一致性。

4.2 只参考不迁移

  • Spring Boot 多模块结构。
  • Maven BOM/dependencies。
  • Java DTO、Controller 和 Repository 实现。
  • Java provider-router 具体代码。

4.3 废弃

  • 作为 V2 生产 AI 中台主技术栈。
  • 继续新增 V2 能力到旧 Java shared。
  • 继续维护多套 shared 主线。

4.4 当前未提交改动处理建议

当前未提交改动集中在：

  • README.md
  • PlatformLegalReviewController.java
  • SharedAiPlatformApiSmokeTest.java
  • shared-ai-platform-contract/docs/

内容是 v0.2 contract 和 legal-review v0.2 兼容入口。

V2 处理建议：

  • 不在旧 Java 仓库继续扩展。
  • 把 v0.2 contract 的思想迁移到 yuqei-ai-platform/packages/ai-openapi/openapi.yaml。
  • 把 legal-review v0.2 路径设计迁移为 V2 新接口，但路径统一为 /api/v1/legal/review，避免继续沿用 domain-pack 历史命名。

5. shared-ai-python-sdk 盘点

5.1 可迁移资产

  • SharedAIPlatformClient 的基础结构。
  • RequestContext。
  • SSE 解析：
    • parse_sse_payload
    • iter_sse_events
  • 错误映射：
    • transport error。
    • envelope error。
  • API prefix 归一化。
  • 文件上传。
  • knowledge sync。
  • legal review client。
  • tests：
    • test_sse.py
    • test_legal_review.py
    • test_errors.py
    • test_client_paths.py
    • test_document_extraction.py

5.2 只参考不迁移

  • 包名 shared-ai-platform-sdk。
  • 旧 /api/v0.2 路径命名。
  • 与 Java shared contract 绑定的 DTO 命名。

5.3 V2 迁移策略

V2 在 yuqei-ai-sdk-python 重新实现正式 SDK：

  • 包名建议：yuqei-ai-sdk-python。
  • Python import 建议：yuqei_ai_sdk。
  • 由 yuqei-ai-platform/packages/ai-openapi/openapi.yaml 生成基础类型。
  • 手写业务友好封装。
  • 默认调用 /api/v1。
  • 必须支持：
    • timeout。
    • retry。
    • trace id。
    • SSE。
    • typed errors。
    • contract tests。

6. shared-java-libs 盘点

6.1 可参考资产

  • shared-web 的条件装配思路：
    • trace id filter 可开关。
    • request log filter 可开关。
    • global exception handler 可开关。
  • shared-storage 的抽象：
    • local。
    • MinIO。
    • noop。
  • shared-notify 的抽象：
    • noop。
    • logging。
    • Aliyun SMS sandbox。
  • shared-ai-sdk 的 Java 客户端边界。
  • shared-core 的分页、错误码、响应模型思想。

6.2 不迁移内容

  • Java 代码。
  • Spring Boot starter。
  • Maven 多模块结构。
  • Java SDK。

6.3 V2 处理策略

V2 使用 Python/TypeScript 主线，因此只吸收“能力边界”和“默认不改变业务项目行为”的原则。

对应落地：

  • yuqei-contract-platform/services/contract-api 和 yuqei-ai-platform/services/ai-platform-api 的 middleware 必须可配置。
  • 错误响应必须标准化，但不能让 SDK 与 HTTP 状态混淆。
  • storage/notify 作为应用内可替换 adapter，不做跨仓库 Java shared。

7. V2 迁移优先级

P0：必须迁移

  • AI 中台 OpenAPI 契约。
  • 法律问答与法律审查接口边界。
  • SDK 请求上下文和错误处理。
  • SSE 事件格式。
  • 知识库文档上传、解析、检索、同步的核心流程。
  • AI 调用审计。

P1：第二批迁移

  • OCR 引擎配置与文档解析质量门禁。
  • Prompt 模板版本管理。
  • 任务/Job 状态机。
  • 使用量和成本记录。
  • 基础评测样本。

P2：后续再做

  • 多 domain-pack 插件体系。
  • 复杂 provider-router。
  • 复杂预算/限流/成本治理。
  • 前端组件库抽象。
  • Java SDK。

8. V2 废弃清单

V2 不再保留：

  • shared-ai-platform-java 作为生产主线。
  • shared-ai-platform 作为生产主线。
  • V1 vendored SDK。
  • 多套 /api/v0.1、/api/v0.2 历史路径。
  • domain-packs 作为对外 API 路径。
  • 未经第二个真实项目验证的业务流程 shared 化。

9. 后续执行项

  1. 建立 V2 技术栈 ADR。
  2. 建立 yuqei-ai-platform/packages/ai-openapi/openapi.yaml。
  3. 建立 yuqei-contract-platform/packages/contract-openapi/openapi.yaml。
  4. 初始化 yuqei-ai-platform/services/ai-platform-api。
  5. 初始化 yuqei-ai-sdk-python。
  6. 迁移 SSE、错误处理、RequestContext 的测试思想。
  7. 初始化合同系统只通过 SDK 调用 AI 中台的边界。
Reference in New Issue View Git Blame Copy Permalink