kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
develop
datai/datai-scenes/datai-scene-salesforce/docs/design/2026-02-03-003-05-删除操作-设计.md

4.6 KiB
Raw Permalink Blame History

设计文档

元数据

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

设计概述

基于 Salesforce Metadata API 实现元数据的同步删除功能。该功能支持按类型和名称删除单个或多个元数据组件，支持批量删除操作，并自动将删除操作的结果（成功或失败）及详细错误信息持久化到本地数据库中，以便审计和历史查询。

架构设计

系统架构

采用标准的分层架构：

  • Web 层 (Controller): MetadataDeleteController，暴露 RESTful API，处理 HTTP 请求和响应封装。
  • 业务层 (Service): MetadataDeleteService，核心业务逻辑，调用 Salesforce Metadata API 执行删除，并调用 Repository 保存历史记录。
  • 数据层 (Repository): MetadataDeleteMapper，基于 MyBatis Plus 操作 datai_metadata_delete 表。
  • 基础设施层:
    • MetadataConnectionFactory: 获取 Salesforce Metadata API 连接。
    • SessionManager: 管理用户会话。

依赖关系

  • datai-salesforce-auth: 提供会话管理和连接工厂。
  • datai-salesforce-common: 提供通用异常 (SalesforceOperationException) 和常量。
  • metadata.jar: 提供 Salesforce Metadata API 的核心类 (DeleteResult, Error)。

技术方案

核心流程

  1. 接收请求: Controller 接收删除请求（类型、名称列表）。
  2. 获取连接: Service 通过 MetadataConnectionFactory 获取 MetadataConnection。
  3. 执行删除: 调用 connection.deleteMetadata(type, fullNames) 执行同步删除。
  4. 处理结果: 遍历 DeleteResult 数组。
  5. 持久化: 将每个删除项的结果（成功/失败、错误信息）转换为 MetadataDeleteEntity 并保存到数据库。
  6. 响应: 返回标准化的 ApiResponse，包含删除结果详情。

异常处理

  • 捕获 ConnectionException 并根据错误消息转换为特定的 SalesforceAuthException 或 SalesforceOperationException。
  • 即使 API 调用抛出异常，也尝试记录已知的失败状态（如果可能）。
  • 确保所有数据库操作的异常被捕获并记录日志，不影响 API 的主要响应（或者根据业务要求回滚）。

数据模型

数据库表设计

表名: datai_metadata_delete

字段名 类型 说明 约束
id BIGINT 主键 PK, Auto Increment
metadata_type VARCHAR(50) 元数据类型 Not Null
full_name VARCHAR(255) 元数据完整名称 Not Null
success BOOLEAN 是否删除成功 Not Null
error_message TEXT 错误消息 Nullable
delete_time DATETIME 删除时间 Not Null
user_id VARCHAR(50) 操作用户 ID Nullable

索引:

  • idx_metadata_type: (metadata_type)
  • idx_full_name: (full_name)
  • idx_delete_time: (delete_time)

实体类设计

@Data
@TableName("datai_metadata_delete")
public class MetadataDeleteEntity {
    @TableId(type = IdType.AUTO)
    private Long id;
    private String metadataType;
    private String fullName;
    private Boolean success;
    private String errorMessage;
    private Date deleteTime;
    private String userId;
}

接口设计

1. 删除元数据

  • URL: POST /api/metadata/delete/{type}
  • 说明: 删除指定类型的元数据。
  • 请求体: String[] (元数据完整名称列表)
  • 响应: ApiResponse<DeleteResult[]>

2. 批量删除元数据

  • URL: POST /api/metadata/delete/batch
  • 说明: 批量删除多种类型的元数据。
  • 请求体: List<DeleteRequest>
  • 响应: ApiResponse<DeleteResult[]>

3. 获取删除历史

  • URL: GET /api/metadata/delete/history
  • 说明: 分页获取删除操作历史记录。
  • 参数: limit (int, default 10)
  • 响应: ApiResponse<List<MetadataDeleteEntity>>

实现要点

关键逻辑

  • 同步调用: deleteMetadata 是同步调用，无需轮询。
  • 结果转换: 将 Salesforce 的 DeleteResult 和 Error 对象正确映射到数据库实体和 API 响应。
  • 错误聚合: 如果删除结果中包含错误，需要将多个 Error 对象的消息拼接成字符串存储。

安全性

  • 验证 metadataType 的合法性（防止 SQL 注入或 API 错误）。
  • 确保用户已登录并持有有效会话。

相关文档