kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
6357f1c579
datai/datai-scenes/datai-scene-salesforce/docs/reference-code/datai-salesforce-metadata-module.md

37 KiB
Raw Blame History

datai-salesforce-metadata 模块详细文档

模块概述

datai-salesforce-metadata 模块是 Datai Salesforce 场景中负责 Salesforce Metadata API 操作的核心模块。该模块提供了完整的元数据检索、部署、查询、状态检查、列出和删除等功能，并记录所有操作的审计日志。

模块定位

  • 模块名称: datai-salesforce-metadata
  • 模块类型: 业务功能模块
  • 主要职责: Salesforce Metadata API 操作管理
  • 技术栈: Spring Boot + MyBatis + Salesforce Metadata API

核心功能

  1. Metadata API 检索操作 - 从 Salesforce 检索元数据
  2. Metadata API 部署操作 - 向 Salesforce 部署元数据
  3. Metadata API 查询操作 - 查询元数据结构和描述
  4. Metadata API 状态检查 - 检查异步操作状态
  5. Metadata API 列出操作 - 列出可用的元数据类型
  6. Metadata API 删除操作 - 删除 Salesforce 元数据
  7. 操作审计日志 - 记录所有操作的详细信息

技术架构

分层架构

┌─────────────────────────────────────────────────────────┐
│                    Controller Layer                      │
│         REST API 端点定义和请求处理                      │
└─────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────┐
│                     Service Layer                        │
│              业务逻辑处理和事务管理                       │
└─────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────┐
│                      Mapper Layer                        │
│              数据访问层和 SQL 映射                        │
└─────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────┐
│                    Database Layer                        │
│              MySQL 数据库存储                            │
└─────────────────────────────────────────────────────────┘

技术栈

技术 版本 用途
Spring Boot - 应用框架
MyBatis - ORM 框架
Swagger/OpenAPI - API 文档
Spring Security - 安全认证
Salesforce WSC 58.0.0 Salesforce Web Service Connector
Salesforce Metadata API - Salesforce 元数据 API

依赖配置

<dependencies>
    <dependency>
        <groupId>com.datai</groupId>
        <artifactId>datai-file-common</artifactId>
        <version>1.0.0</version>
    </dependency>
    <dependency>
        <groupId>com.datai</groupId>
        <artifactId>datai-salesforce-auth</artifactId>
    </dependency>
    <dependency>
        <groupId>com.force.api</groupId>
        <artifactId>force-wsc</artifactId>
        <version>58.0.0</version>
    </dependency>
    <dependency>
        <groupId>salesforce</groupId>
        <artifactId>salesforce-metadata</artifactId>
        <version>0.0.1</version>
        <scope>system</scope>
        <systemPath>${project.basedir}/src/main/resources/lib/metadata.jar</systemPath>
    </dependency>
</dependencies>

功能模块详解

1. Metadata API 检索操作

功能描述

从 Salesforce 检索元数据组件，支持异步操作和状态跟踪。

核心实体

DataiMetadataRetrieve - 检索操作日志

public class DataiMetadataRetrieve extends BaseEntity {
    private Long id;                    // 主键ID
    private String asyncId;              // 异步操作ID（Salesforce返回）
    private String status;               // 操作状态（Queued/InProgress/Succeeded/Failed）
    private Boolean done;                // 是否完成（0否 1是）
    private String message;              // 操作消息
    private String errorMessage;        // 错误消息
    private String sfUserId;             // Salesforce用户ID
    private String userId;               // 操作用户ID
    private Long deptId;                 // 部门ID
    private LocalDateTime retrieveTime; // 检索请求提交时间
    private Boolean delFlag;             // 删除标志（0正常 1删除）
}

API 端点

端点 方法 描述 权限
/metadata/metadataretrieve/list GET 查询检索操作日志列表 metadata:metadataretrieve:list
/metadata/metadataretrieve/export POST 导出检索操作日志 metadata:metadataretrieve:export
/metadata/metadataretrieve/{id} GET 获取检索操作日志详情 metadata:metadataretrieve:query
/metadata/metadataretrieve POST 新增检索操作日志 metadata:metadataretrieve:add
/metadata/metadataretrieve PUT 修改检索操作日志 metadata:metadataretrieve:edit
/metadata/metadataretrieve/{ids} DELETE 删除检索操作日志 metadata:metadataretrieve:remove

相关实体

  • DataiMetadataRetrieveResult - 检索结果明细
  • DataiMetadataRetrieveMessage - 检索消息

2. Metadata API 部署操作

功能描述

向 Salesforce 部署元数据组件，支持自定义对象、字段、Apex 类等。

核心实体

DataiMetadataDeployLog - 部署操作日志

public class DataiMetadataDeployLog extends BaseEntity {
    private Long id;                    // 主键ID
    private String operationType;       // 操作类型
    private String metadataType;        // 元数据类型
    private String metadataName;        // 元数据名称
    private String deployId;            // 部署ID（Salesforce返回）
    private String status;              // 部署状态
    private String stateDetail;         // 状态详情
    private String errorMessage;        // 错误消息
    private String sfUserId;            // Salesforce用户ID
    private String userId;              // 操作用户ID
    private Long deptId;                // 部门ID
    private LocalDateTime deployTime;    // 部署请求提交时间
    private LocalDateTime completeTime; // 完成时间
    private Boolean delFlag;           // 删除标志（0正常 1删除）
}

API 端点

端点 方法 描述 权限
/metadata/metadatadeploylog/list GET 查询部署操作日志列表 metadata:metadatadeploylog:list
/metadata/metadatadeploylog/export POST 导出部署操作日志 metadata:metadatadeploylog:export
/metadata/metadatadeploylog/{id} GET 获取部署操作日志详情 metadata:metadatadeploylog:query
/metadata/metadatadeploylog POST 新增部署操作日志 metadata:metadatadeploylog:add
/metadata/metadatadeploylog PUT 修改部署操作日志 metadata:metadatadeploylog:edit
/metadata/metadatadeploylog/{ids} DELETE 删除部署操作日志 metadata:metadatadeploylog:remove

相关实体

  • DataiMetadataDeployDetail - 部署结果明细
  • DataiMetadataDeployMessage - 部署消息

3. Metadata API 查询操作

功能描述

查询 Salesforce 元数据结构和描述信息。

核心实体

DataiMetadataDescribe - 查询审计

public class DataiMetadataDescribe extends BaseEntity {
    private Long id;                       // 主键ID
    private String operationType;          // 操作类型（describe/list）
    private String metadataType;          // 元数据类型（list操作必填）
    private String folder;                 // 文件夹
    private String serverVersion;          // 服务器版本
    private String namespacePrefix;       // 命名空间前缀
    private Integer metadataObjectCount;  // 元数据对象数量
    private Integer resultCount;           // 结果数量
    private String status;                 // 状态（Succeeded/Failed）
    private String errorMessage;           // 错误信息
    private LocalDateTime queryTime;      // 查询时间
    private String sfUserId;              // Salesforce用户ID
    private Long deptId;                  // 部门ID
    private Boolean delFlag;              // 删除标志（0正常 1删除）
}

API 端点

端点 方法 描述 权限
/metadata/metadatadescribe/list GET 查询元数据查询审计列表 metadata:metadatadescribe:list
/metadata/metadatadescribe/export POST 导出元数据查询审计 metadata:metadatadescribe:export
/metadata/metadatadescribe/{id} GET 获取元数据查询审计详情 metadata:metadatadescribe:query
/metadata/metadatadescribe POST 新增元数据查询审计 metadata:metadatadescribe:add
/metadata/metadatadescribe PUT 修改元数据查询审计 metadata:metadatadescribe:edit
/metadata/metadatadescribe/{ids} DELETE 删除元数据查询审计 metadata:metadatadescribe:remove

相关实体

  • DataiMetadataDescribeValueType - 描述值类型明细

4. Metadata API 状态检查

功能描述

检查异步操作的状态，包括部署和检索操作。

核心实体

DataiMetadataStatusCheck - 状态检查日志

public class DataiMetadataStatusCheck extends BaseEntity {
    private Long id;                    // 主键ID
    private String checkId;             // 检查记录ID
    private String asyncId;             // 异步操作ID
    private String operationType;       // 操作类型（DEPLOY/RETRIEVE）
    private Long operationId;           // 操作记录ID
    private String status;              // 状态（Pending/InProgress/Succeeded/Failed/Canceled）
    private LocalDateTime checkTime;    // 检查时间
    private String errorMessage;        // 错误信息
    private String sfUserId;            // Salesforce用户ID
    private Long deptId;                // 部门ID
    private Boolean delFlag;            // 删除标志（0未删除 1已删除）
}

API 端点

端点 方法 描述 权限
/metadata/metadatastatuscheck/list GET 查询状态检查日志列表 metadata:metadatastatuscheck:list
/metadata/metadatastatuscheck/export POST 导出状态检查日志 metadata:metadatastatuscheck:export
/metadata/metadatastatuscheck/{id} GET 获取状态检查日志详情 metadata:metadatastatuscheck:query
/metadata/metadatastatuscheck POST 新增状态检查日志 metadata:metadatastatuscheck:add
/metadata/metadatastatuscheck PUT 修改状态检查日志 metadata:metadatastatuscheck:edit
/metadata/metadatastatuscheck/{ids} DELETE 删除状态检查日志 metadata:metadatastatuscheck:remove

5. Metadata API 列出操作

功能描述

列出 Salesforce 中可用的元数据类型和组件。

核心实体

DataiMetadataListResult - 列出元数据结果

public class DataiMetadataListResult extends BaseEntity {
    private Long id;                    // 主键ID
    private String listId;              // 列出操作ID
    private String metadataType;        // 元数据类型
    private String folder;              // 文件夹
    private Integer resultCount;        // 结果数量
    private String status;              // 状态（Succeeded/Failed）
    private String errorMessage;        // 错误信息
    private LocalDateTime listTime;     // 列出时间
    private String sfUserId;            // Salesforce用户ID
    private Long deptId;                // 部门ID
    private Boolean delFlag;            // 删除标志（0正常 1删除）
}

DataiMetadataListItem - 列项明细

public class DataiMetadataListItem extends BaseEntity {
    private Long id;                    // 主键ID
    private Long listResultId;          // 列出结果ID
    private String metadataType;        // 元数据类型
    private String fullName;            // 完整名称
    private String fileName;            // 文件名
    private String namespacePrefix;     // 命名空间前缀
    private String manageableState;     // 可管理状态
    private String packageNames;        // 包名
    private Boolean delFlag;            // 删除标志（0正常 1删除）
}

API 端点

端点 方法 描述 权限
/metadata/metadatalistresult/list GET 查询列出结果列表 metadata:metadatalistresult:list
/metadata/metadatalistresult/export POST 导出列出结果 metadata:metadatalistresult:export
/metadata/metadatalistresult/{id} GET 获取列出结果详情 metadata:metadatalistresult:query
/metadata/metadatalistresult POST 新增列出结果 metadata:metadatalistresult:add
/metadata/metadatalistresult PUT 修改列出结果 metadata:metadatalistresult:edit
/metadata/metadatalistresult/{ids} DELETE 删除列出结果 metadata:metadatalistresult:remove
端点 方法 描述 权限
/metadata/metadatalistitem/list GET 查询列项明细列表 metadata:metadatalistitem:list
/metadata/metadatalistitem/export POST 导出列项明细 metadata:metadatalistitem:export
/metadata/metadatalistitem/{id} GET 获取列项明细详情 metadata:metadatalistitem:query
/metadata/metadatalistitem POST 新增列项明细 metadata:metadatalistitem:add
/metadata/metadatalistitem PUT 修改列项明细 metadata:metadatalistitem:edit
/metadata/metadatalistitem/{ids} DELETE 删除列项明细 metadata:metadatalistitem:remove

6. Metadata API 删除操作

功能描述

从 Salesforce 删除元数据组件。

核心实体

DataiMetadataDelete - 删除操作日志

public class DataiMetadataDelete extends BaseEntity {
    private Long id;                    // 主键ID
    private String asyncId;             // 异步操作ID（Salesforce返回）
    private String metadataType;        // 元数据类型
    private String fullName;            // 完整名称
    private String status;              // 删除状态（Queued/InProgress/Succeeded/Failed）
    private Boolean done;               // 是否完成（0否 1是）
    private String message;             // 操作消息
    private String errorMessage;        // 错误消息
    private String sfUserId;            // Salesforce用户ID
    private String userId;              // 操作用户ID
    private Long deptId;                // 部门ID
    private LocalDateTime deleteTime;  // 删除请求提交时间
    private Boolean delFlag;            // 删除标志（0正常 1删除）
}

API 端点

端点 方法 描述 权限
/metadata/metadatadelete/list GET 查询删除操作日志列表 metadata:metadatadelete:list
/metadata/metadatadelete/export POST 导出删除操作日志 metadata:metadatadelete:export
/metadata/metadatadelete/{id} GET 获取删除操作日志详情 metadata:metadatadelete:query
/metadata/metadatadelete POST 新增删除操作日志 metadata:metadatadelete:add
/metadata/metadatadelete PUT 修改删除操作日志 metadata:metadatadelete:edit
/metadata/metadatadelete/{ids} DELETE 删除删除操作日志 metadata:metadatadelete:remove

7. Metadata API 异步操作

功能描述

管理 Metadata API 的异步操作。

核心实体

DataiMetadataAsync - 异步操作日志

public class DataiMetadataAsync extends BaseEntity {
    private Long id;                    // 主键ID
    private String asyncId;             // 异步操作ID（Salesforce返回）
    private String operationType;       // 操作类型（DEPLOY/RETRIEVE/DELETE）
    private String status;              // 状态（Queued/InProgress/Succeeded/Failed）
    private Boolean done;               // 是否完成（0否 1是）
    private String message;             // 操作消息
    private String errorMessage;        // 错误消息
    private String sfUserId;            // Salesforce用户ID
    private String userId;              // 操作用户ID
    private Long deptId;                // 部门ID
    private LocalDateTime submitTime;   // 提交时间
    private LocalDateTime completeTime; // 完成时间
    private Boolean delFlag;            // 删除标志（0正常 1删除）
}

API 端点

端点 方法 描述 权限
/metadata/metadataasync/list GET 查询异步操作日志列表 metadata:metadataasync:list
/metadata/metadataasync/export POST 导出异步操作日志 metadata:metadataasync:export
/metadata/metadataasync/{id} GET 获取异步操作日志详情 metadata:metadataasync:query
/metadata/metadataasync POST 新增异步操作日志 metadata:metadataasync:add
/metadata/metadataasync PUT 修改异步操作日志 metadata:metadataasync:edit
/metadata/metadataasync/{ids} DELETE 删除异步操作日志 metadata:metadataasync:remove

数据模型

实体关系图

DataiMetadataRetrieve (检索操作日志)
    ├── DataiMetadataRetrieveResult (检索结果明细)
    └── DataiMetadataRetrieveMessage (检索消息)

DataiMetadataDeployLog (部署操作日志)
    ├── DataiMetadataDeployDetail (部署结果明细)
    └── DataiMetadataDeployMessage (部署消息)

DataiMetadataDescribe (查询审计)
    └── DataiMetadataDescribeValueType (描述值类型明细)

DataiMetadataListResult (列出结果)
    └── DataiMetadataListItem (列项明细)

DataiMetadataStatusCheck (状态检查日志)

DataiMetadataDelete (删除操作日志)

DataiMetadataAsync (异步操作日志)

数据表结构

datai_metadata_retrieve

检索操作日志表

字段名 类型 描述
id bigint 主键ID
async_id varchar 异步操作ID
status varchar 操作状态
done tinyint 是否完成
message text 操作消息
error_message text 错误消息
sf_user_id varchar Salesforce用户ID
user_id varchar 操作用户ID
dept_id bigint 部门ID
retrieve_time datetime 检索请求提交时间
create_by varchar 创建者
create_time datetime 创建时间
update_by varchar 更新者
update_time datetime 更新时间
del_flag tinyint 删除标志

datai_metadata_deploy_log

部署操作日志表

字段名 类型 描述
id bigint 主键ID
operation_type varchar 操作类型
metadata_type varchar 元数据类型
metadata_name varchar 元数据名称
deploy_id varchar 部署ID
status varchar 部署状态
state_detail text 状态详情
error_message text 错误消息
sf_user_id varchar Salesforce用户ID
user_id varchar 操作用户ID
dept_id bigint 部门ID
deploy_time datetime 部署请求提交时间
complete_time datetime 完成时间
create_by varchar 创建者
create_time datetime 创建时间
update_by varchar 更新者
update_time datetime 更新时间
del_flag tinyint 删除标志

datai_metadata_describe

元数据查询审计表

字段名 类型 描述
id bigint 主键ID
operation_type varchar 操作类型
metadata_type varchar 元数据类型
folder varchar 文件夹
server_version varchar 服务器版本
namespace_prefix varchar 命名空间前缀
metadata_object_count int 元数据对象数量
result_count int 结果数量
status varchar 状态
error_message text 错误信息
query_time datetime 查询时间
sf_user_id varchar Salesforce用户ID
dept_id bigint 部门ID
create_by varchar 创建者
create_time datetime 创建时间
update_by varchar 更新者
update_time datetime 更新时间
del_flag tinyint 删除标志

Controller 层

Controller 列表

Controller 路径前缀 描述
DataiMetadataRetrieveController /metadata/metadataretrieve Metadata API 检索操作日志管理
DataiMetadataDeployLogController /metadata/metadatadeploylog 元数据部署操作日志管理
DataiMetadataDescribeController /metadata/metadatadescribe 元数据查询审计管理
DataiMetadataStatusCheckController /metadata/metadatastatuscheck Metadata API 状态检查日志管理
DataiMetadataDeployDetailController /metadata/metadatadeploydetail 元数据部署结果明细管理
DataiMetadataDescribeValueTypeController /metadata/metadatadescribetype Metadata 描述值类型明细管理
DataiMetadataListItemController /metadata/metadatalistitem Metadata 列项明细管理
DataiMetadataRetrieveMessageController /metadata/metadataretrievemessage Metadata API 检索消息管理
DataiMetadataDeployMessageController /metadata/metadatadeploymessage 元数据部署消息管理
DataiMetadataRetrieveResultController /metadata/metadataretrieveresult Metadata API 检索结果管理
DataiMetadataAsyncController /metadata/metadataasync Metadata API 异步操作日志管理
DataiMetadataListResultController /metadata/metadatalistresult Metadata 列出元数据结果管理
DataiMetadataDeleteController /metadata/metadatadelete Metadata API 删除操作日志管理

Controller 特性

所有 Controller 都具备以下特性：

  1. 继承 BaseController - 提供基础功能
  2. RESTful API 设计 - 遵循 REST 规范
  3. Swagger 文档 - 自动生成 API 文档
  4. 权限控制 - 使用 @PreAuthorize 注解
  5. 操作日志 - 使用 @Log 注解记录操作
  6. 分页支持 - 集成分页功能
  7. 数据导出 - 支持 Excel 导出

Service 层

Service 接口列表

Service 接口 实现类 描述
IDataiMetadataRetrieveService DataiMetadataRetrieveServiceImpl Metadata API 检索操作日志服务
IDataiMetadataDeployLogService DataiMetadataDeployLogServiceImpl 元数据部署操作日志服务
IDataiMetadataDescribeService DataiMetadataDescribeServiceImpl 元数据查询审计服务
IDataiMetadataStatusCheckService DataiMetadataStatusCheckServiceImpl Metadata API 状态检查日志服务
IDataiMetadataDeployDetailService DataiMetadataDeployDetailServiceImpl 元数据部署结果明细服务
IDataiMetadataDescribeValueTypeService DataiMetadataDescribeValueTypeServiceImpl Metadata 描述值类型明细服务
IDataiMetadataListItemService DataiMetadataListItemServiceImpl Metadata 列项明细服务
IDataiMetadataRetrieveMessageService DataiMetadataRetrieveMessageServiceImpl Metadata API 检索消息服务
IDataiMetadataDeployMessageService DataiMetadataDeployMessageServiceImpl 元数据部署消息服务
IDataiMetadataRetrieveResultService DataiMetadataRetrieveResultServiceImpl Metadata API 检索结果服务
IDataiMetadataAsyncService DataiMetadataAsyncServiceImpl Metadata API 异步操作日志服务
IDataiMetadataListResultService DataiMetadataListResultServiceImpl Metadata 列出元数据结果服务
IDataiMetadataDeleteService DataiMetadataDeleteServiceImpl Metadata API 删除操作日志服务

Service 方法

每个 Service 接口都包含以下标准方法：

// 根据ID查询
public Entity selectEntityById(Long id);

// 查询列表
public List<Entity> selectEntityList(Entity entity);

// 新增
public int insertEntity(Entity entity);

// 修改
public int updateEntity(Entity entity);

// 批量删除
public int deleteEntityByIds(Long[] ids);

// 根据ID删除
public int deleteEntityById(Long id);

Service 特性

  1. 业务逻辑封装 - 封装复杂业务逻辑
  2. 事务管理 - 使用 @Transactional 注解
  3. 用户信息注入 - 自动注入当前用户信息
  4. 时间戳管理 - 自动设置创建和更新时间
  5. 审计日志 - 记录操作审计信息

Mapper 层

Mapper 接口列表

Mapper 接口 XML 文件 描述
DataiMetadataRetrieveMapper DataiMetadataRetrieveMapper.xml Metadata API 检索操作日志映射
DataiMetadataDeployLogMapper DataiMetadataDeployLogMapper.xml 元数据部署操作日志映射
DataiMetadataDescribeMapper DataiMetadataDescribeMapper.xml 元数据查询审计映射
DataiMetadataStatusCheckMapper DataiMetadataStatusCheckMapper.xml Metadata API 状态检查日志映射
DataiMetadataDeployDetailMapper DataiMetadataDeployDetailMapper.xml 元数据部署结果明细映射
DataiMetadataDescribeValueTypeMapper DataiMetadataDescribeValueTypeMapper.xml Metadata 描述值类型明细映射
DataiMetadataListItemMapper DataiMetadataListItemMapper.xml Metadata 列项明细映射
DataiMetadataRetrieveMessageMapper DataiMetadataRetrieveMessageMapper.xml Metadata API 检索消息映射
DataiMetadataDeployMessageMapper DataiMetadataDeployMessageMapper.xml 元数据部署消息映射
DataiMetadataRetrieveResultMapper DataiMetadataRetrieveResultMapper.xml Metadata API 检索结果映射
DataiMetadataAsyncMapper DataiMetadataAsyncMapper.xml Metadata API 异步操作日志映射
DataiMetadataListResultMapper DataiMetadataListResultMapper.xml Metadata 列出元数据结果映射
DataiMetadataDeleteMapper DataiMetadataDeleteMapper.xml Metadata API 删除操作日志映射

Mapper 方法

每个 Mapper 接口都包含以下标准方法：

// 根据ID查询
public Entity selectEntityById(Long id);

// 查询列表
public List<Entity> selectEntityList(Entity entity);

// 新增
public int insertEntity(Entity entity);

// 修改
public int updateEntity(Entity entity);

// 根据ID删除
public int deleteEntityById(Long id);

// 批量删除
public int deleteEntityByIds(Long[] ids);

Mapper 特性

  1. MyBatis 注解 - 使用 MyBatis 注解和 XML 映射
  2. 动态 SQL - 支持动态 SQL 查询
  3. 结果映射 - 自动映射结果到实体对象
  4. 批量操作 - 支持批量插入和删除

Model 层

模型分类

模块包含三种类型的模型：

  1. Domain（领域模型） - 数据库实体映射
  2. DTO（数据传输对象） - API 请求/响应对象
  3. VO（视图对象） - 前端展示对象

Domain 模型列表

Domain 类 表名 描述
DataiMetadataRetrieve datai_metadata_retrieve Metadata API 检索操作日志
DataiMetadataDeployLog datai_metadata_deploy_log 元数据部署操作日志
DataiMetadataDescribe datai_metadata_describe 元数据查询审计
DataiMetadataStatusCheck datai_metadata_status_check Metadata API 状态检查日志
DataiMetadataDeployDetail datai_metadata_deploy_detail 元数据部署结果明细
DataiMetadataDescribeValueType datai_metadata_describe_value_type Metadata 描述值类型明细
DataiMetadataListItem datai_metadata_list_item Metadata 列项明细
DataiMetadataRetrieveMessage datai_metadata_retrieve_message Metadata API 检索消息
DataiMetadataDeployMessage datai_metadata_deploy_message 元数据部署消息
DataiMetadataRetrieveResult datai_metadata_retrieve_result Metadata API 检索结果
DataiMetadataAsync datai_metadata_async Metadata API 异步操作日志
DataiMetadataListResult datai_metadata_list_result Metadata 列出元数据结果
DataiMetadataDelete datai_metadata_delete Metadata API 删除操作日志

Domain 特性

  1. 继承 BaseEntity - 包含基础字段（id, createBy, createTime, updateBy, updateTime, delFlag）
  2. Swagger 注解 - 使用 @Schema 注解生成 API 文档
  3. Excel 注解 - 使用 @Excel 注解支持 Excel 导出
  4. Lombok 支持 - 简化 getter/setter 方法
  5. ToString 方法 - 重写 toString 方法便于调试

DTO/VO 模型

每个 Domain 模型都有对应的 DTO 和 VO 模型：

  • DTO - 用于 API 请求和响应，包含静态转换方法
  • VO - 用于前端展示，包含静态转换方法

转换方法示例：

// DTO to Domain
public static DataiMetadataRetrieve toObj(DataiMetadataRetrieveDto dto) {
    // 转换逻辑
}

// Domain to VO
public static DataiMetadataRetrieveVo objToVo(DataiMetadataRetrieve obj) {
    // 转换逻辑
}

API 使用示例

1. 查询检索操作日志列表

请求

GET /metadata/metadataretrieve/list?pageNum=1&pageSize=10

响应

{
  "total": 100,
  "rows": [
    {
      "id": 1,
      "asyncId": "1SRxx0000000001",
      "status": "Succeeded",
      "done": true,
      "message": "Retrieve completed successfully",
      "errorMessage": null,
      "sfUserId": "005xx0000001",
      "userId": "admin",
      "deptId": 100,
      "retrieveTime": "2026-02-04T10:00:00",
      "createTime": "2026-02-04T10:00:00",
      "updateTime": "2026-02-04T10:00:00"
    }
  ],
  "code": 200,
  "msg": "查询成功"
}

2. 新增部署操作日志

请求

POST /metadata/metadatadeploylog
Content-Type: application/json

{
  "operationType": "deploy_custom_object",
  "metadataType": "CustomObject",
  "metadataName": "MyCustomObject__c",
  "deployId": "0Afxx0000000001",
  "status": "Queued",
  "sfUserId": "005xx0000001",
  "userId": "admin",
  "deptId": 100,
  "deployTime": "2026-02-04T10:00:00"
}

响应

{
  "code": 200,
  "msg": "操作成功",
  "data": 1
}

3. 获取查询审计详情

请求

GET /metadata/metadatadescribe/1

响应

{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "id": 1,
    "operationType": "describe",
    "metadataType": null,
    "folder": null,
    "serverVersion": "58.0",
    "namespacePrefix": "",
    "metadataObjectCount": 500,
    "resultCount": 500,
    "status": "Succeeded",
    "errorMessage": null,
    "queryTime": "2026-02-04T10:00:00",
    "sfUserId": "005xx0000001",
    "deptId": 100,
    "createTime": "2026-02-04T10:00:00",
    "updateTime": "2026-02-04T10:00:00"
  }
}

4. 导出操作日志

请求

POST /metadata/metadataasync/export
Content-Type: application/json

{
  "status": "Succeeded"
}

响应

Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Content-Disposition: attachment; filename=MetadataAsync.xlsx

[Excel 文件内容]

权限控制

权限列表

权限代码 描述
metadata:metadataretrieve:list 查询检索操作日志列表
metadata:metadataretrieve:export 导出检索操作日志
metadata:metadataretrieve:query 查询检索操作日志详情
metadata:metadataretrieve:add 新增检索操作日志
metadata:metadataretrieve:edit 修改检索操作日志
metadata:metadataretrieve:remove 删除检索操作日志
metadata:metadatadeploylog:list 查询部署操作日志列表
metadata:metadatadeploylog:export 导出部署操作日志
metadata:metadatadeploylog:query 查询部署操作日志详情
metadata:metadatadeploylog:add 新增部署操作日志
metadata:metadatadeploylog:edit 修改部署操作日志
metadata:metadatadeploylog:remove 删除部署操作日志
metadata:metadatadescribe:list 查询元数据查询审计列表
metadata:metadatadescribe:export 导出元数据查询审计
metadata:metadatadescribe:query 查询元数据查询审计详情
metadata:metadatadescribe:add 新增元数据查询审计
metadata:metadatadescribe:edit 修改元数据查询审计
metadata:metadatadescribe:remove 删除元数据查询审计
metadata:metadatastatuscheck:list 查询状态检查日志列表
metadata:metadatastatuscheck:export 导出状态检查日志
metadata:metadatastatuscheck:query 查询状态检查日志详情
metadata:metadatastatuscheck:add 新增状态检查日志
metadata:metadatastatuscheck:edit 修改状态检查日志
metadata:metadatastatuscheck:remove 删除状态检查日志
metadata:metadataasync:list 查询异步操作日志列表
metadata:metadataasync:export 导出异步操作日志
metadata:metadataasync:query 查询异步操作日志详情
metadata:metadataasync:add 新增异步操作日志
metadata:metadataasync:edit 修改异步操作日志
metadata:metadataasync:remove 删除异步操作日志
metadata:metadatadelete:list 查询删除操作日志列表
metadata:metadatadelete:export 导出删除操作日志
metadata:metadatadelete:query 查询删除操作日志详情
metadata:metadatadelete:add 新增删除操作日志
metadata:metadatadelete:edit 修改删除操作日志
metadata:metadatadelete:remove 删除删除操作日志

权限注解

使用 Spring Security 的 @PreAuthorize 注解进行权限控制：

@PreAuthorize("@ss.hasPermi('metadata:metadataretrieve:list')")
@GetMapping("/list")
public TableDataInfo list(DataiMetadataRetrieveDto dto) {
    // 业务逻辑
}

操作日志

日志记录

所有修改操作都会记录操作日志：

@Log(title = "元数据部署操作日志", businessType = BusinessType.INSERT)
@PostMapping
public AjaxResult add(@RequestBody DataiMetadataDeployLogDto dto) {
    // 业务逻辑
}

日志类型

  • INSERT - 新增操作
  • UPDATE - 修改操作
  • DELETE - 删除操作
  • EXPORT - 导出操作
  • OTHER - 其他操作

分页支持

分页参数

参数名 类型 描述
pageNum int 当前页码
pageSize int 每页条数

分页响应

{
  "total": 100,
  "rows": [...],
  "code": 200,
  "msg": "查询成功"
}

数据导出

导出功能

所有列表查询都支持 Excel 导出：

@Operation(summary = "导出元数据部署操作日志列表")
@PreAuthorize("@ss.hasPermi('metadata:metadatadeploylog:export')")
@Log(title = "元数据部署操作日志", businessType = BusinessType.EXPORT)
@PostMapping("/export")
public void export(HttpServletResponse response, DataiMetadataDeployLogDto dto) {
    List<DataiMetadataDeployLog> list = service.selectDataiMetadataDeployLogList(DataiMetadataDeployLogDto.toObj(dto));
    ExcelUtil<DataiMetadataDeployLog> util = new ExcelUtil<DataiMetadataDeployLog>(DataiMetadataDeployLog.class);
    util.exportExcel(response, list, "元数据部署操作日志数据");
}

Excel 注解

使用 @Excel 注解标记需要导出的字段：

@Excel(name = "操作类型")
private String operationType;

@Excel(name = "元数据类型")
private String metadataType;

@Excel(name = "部署状态", readConverterExp = "Q=ueued,InProgress,Succeeded,Failed")
private String status;

错误处理

错误码

错误码 描述
200 操作成功
401 未授权
403 禁止访问
404 资源不存在
500 服务器内部错误

错误响应

{
  "code": 500,
  "msg": "操作失败",
  "data": null
}

最佳实践

1. 使用 DTO/VO 模式

始终使用 DTO 和 VO 进行数据传输，避免直接暴露 Domain 模型。

2. 权限控制

所有 API 端点都应该添加权限控制注解。

3. 操作日志

所有修改操作都应该记录操作日志。

4. 参数校验

在 Controller 层添加参数校验注解。

5. 异常处理

在 Service 层捕获和处理异常，返回友好的错误信息。

6. 事务管理

在 Service 层使用 @Transactional 注解管理事务。

7. 用户信息注入

在 Service 层自动注入当前用户信息。

8. 时间戳管理

在 Service 层自动设置创建和更新时间。

总结

datai-salesforce-metadata 模块提供了完整的 Salesforce Metadata API 操作管理功能，包括：

  1. 完整的 CRUD 操作 - 支持所有实体的增删改查
  2. 权限控制 - 基于角色的访问控制
  3. 操作审计 - 记录所有操作日志
  4. 数据导出 - 支持 Excel 导出
  5. 分页查询 - 支持分页和排序
  6. 异步操作 - 支持异步操作管理
  7. 状态跟踪 - 跟踪操作状态和结果

该模块采用标准的分层架构，代码结构清晰，易于维护和扩展。