datai/datai-scenes/datai-scene-salesforce/docs/design/2026-02-03-003-03-部署操作-设计.md

部署操作设计文档

元数据

• 需求编号：003-03
• 创建时间：2026-02-03
• 创建人：AI Assistant
• 状态：进行中

设计概述

本设计旨在实现 Salesforce Metadata API 的通用部署功能。提供一个通用的服务和接口，允许用户上传标准的 Metadata ZIP 包进行部署，并提供部署状态的查询、轮询和取消功能。此功能是元数据管理的核心基础设施，支持后续的各种元数据操作。

架构设计

系统架构

采用分层架构，基于若依（DataI Geek）框架：

1. Controller 层 (MetadataDeployController)：暴露 RESTful API，处理 ZIP 文件上传和部署控制请求。
2. Service 层 (MetadataDeployService)：封装 Metadata API 的 deploy、checkDeployStatus、cancelDeploy 操作，实现同步轮询逻辑。
3. Repository 层 (MetadataDeployRepository)：复用 003-02 定义的存储库，负责部署记录的持久化。
4. Integration 层 (MetadataConnectionFactory)：获取 Metadata API 连接。

数据流图

1. 提交部署：Client (ZIP) -> Controller -> Service -> Metadata API (deploy) -> AsyncResult -> DB (Queued) -> Client (DeployId)
2. 查询状态：Client (DeployId) -> Controller -> Service -> Metadata API (checkStatus) -> DB (Update) -> Client (Result)
3. 轮询状态：Client -> Controller -> Service (Loop checkStatus) -> Client (Final Result)
4. 取消部署：Client -> Controller -> Service -> Metadata API (cancelDeploy) -> DB (Canceled) -> Client

技术方案

技术选型

• Spring Boot Web: 处理 MultipartFile 上传。
• Salesforce Metadata API (WSC): 核心依赖，用于执行部署操作。
• MyBatis Plus: 数据库操作。
• Java Concurrency: 使用 Thread.sleep 实现简单的轮询机制。

核心逻辑

1. 通用部署：接收 byte[] 格式的 ZIP 包，直接透传给 Metadata API。这与 003-02 的区别在于，003-02 负责构建 ZIP，而本需求负责传输 ZIP。
2. 状态同步：每次查询或轮询状态时，同步更新数据库中的 datai_metadata_deploy 记录，确保数据库状态与 Salesforce 保持最终一致。
3. 部署选项：支持通过 JSON 字符串传递 DeployOptions，并在后端解析。

数据模型

数据库表设计

复用 003-02 设计的 datai_metadata_deploy 表。

字段名	类型	说明
id	BIGINT	主键
deploy_id	VARCHAR(100)	部署 ID
status	VARCHAR(50)	部署状态
...	...	(其他统计字段)

实体类设计

复用 MetadataDeployEntity。

接口设计

基础路径

/api/metadata/deploy

1. 通用部署接口

• URL: /
• Method: POST
• Content-Type: multipart/form-data
• Params:
  • file: ZIP 文件
  • deployOptions: JSON 字符串 (可选)
• Response: ApiResponse<AsyncResult>

2. 检查部署状态

• URL: /status/{deployId}
• Method: GET
• Response: ApiResponse<DeployResult>

3. 取消部署

• URL: /cancel/{deployId}
• Method: POST
• Response: ApiResponse<CancelResult>

4. 轮询部署状态 (同步等待)

• URL: /poll/{deployId}
• Method: GET
• Params:
  • maxRetries: 最大重试次数 (默认 30)
  • retryInterval: 间隔毫秒 (默认 5000)
• Response: ApiResponse<DeployResult>

实现要点

1. 部署选项解析

前端传递的 deployOptions 为 JSON 字符串，后端需使用 Jackson (ObjectMapper) 解析为 com.sforce.soap.metadata.DeployOptions 对象。需处理解析异常，并提供默认值（如 rollbackOnError=true）。

2. 状态同步策略

为了避免频繁数据库写入，状态更新策略如下：

• 提交时：插入记录，状态 Queued。
• 轮询/查询时：调用 Salesforce API 获取最新状态。
• 更新条件：仅当 Salesforce 返回的状态与数据库不一致，或状态为 Done 时，更新数据库记录。

3. 异常处理

• 文件读取异常：捕获 IOException。
• API 调用异常：捕获 ConnectionException，转换为 SalesforceOperationException。
• 中断异常：捕获 InterruptedException，恢复中断状态并抛出异常。

相关文档

• 需求文档
• 元数据类型定义设计 (复用数据模型)
• ADR-003-03 通用部署接口设计