# 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 |
### 依赖配置
```xml
com.datai
datai-file-common
1.0.0
com.datai
datai-salesforce-auth
com.force.api
force-wsc
58.0.0
salesforce
salesforce-metadata
0.0.1
system
${project.basedir}/src/main/resources/lib/metadata.jar
```
## 功能模块详解
### 1. Metadata API 检索操作
#### 功能描述
从 Salesforce 检索元数据组件，支持异步操作和状态跟踪。
#### 核心实体
**DataiMetadataRetrieve** - 检索操作日志
```java
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** - 部署操作日志
```java
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** - 查询审计
```java
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** - 状态检查日志
```java
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** - 列出元数据结果
```java
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** - 列项明细
```java
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** - 删除操作日志
```java
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** - 异步操作日志
```java
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 接口都包含以下标准方法：
```java
// 根据ID查询
public Entity selectEntityById(Long id);
// 查询列表
public List 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 接口都包含以下标准方法：
```java
// 根据ID查询
public Entity selectEntityById(Long id);
// 查询列表
public List 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** - 用于前端展示，包含静态转换方法
转换方法示例：
```java
// DTO to Domain
public static DataiMetadataRetrieve toObj(DataiMetadataRetrieveDto dto) {
// 转换逻辑
}
// Domain to VO
public static DataiMetadataRetrieveVo objToVo(DataiMetadataRetrieve obj) {
// 转换逻辑
}
```
## API 使用示例
### 1. 查询检索操作日志列表
**请求**
```http
GET /metadata/metadataretrieve/list?pageNum=1&pageSize=10
```
**响应**
```json
{
"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. 新增部署操作日志
**请求**
```http
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"
}
```
**响应**
```json
{
"code": 200,
"msg": "操作成功",
"data": 1
}
```
### 3. 获取查询审计详情
**请求**
```http
GET /metadata/metadatadescribe/1
```
**响应**
```json
{
"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. 导出操作日志
**请求**
```http
POST /metadata/metadataasync/export
Content-Type: application/json
{
"status": "Succeeded"
}
```
**响应**
```http
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 注解进行权限控制：
```java
@PreAuthorize("@ss.hasPermi('metadata:metadataretrieve:list')")
@GetMapping("/list")
public TableDataInfo list(DataiMetadataRetrieveDto dto) {
// 业务逻辑
}
```
## 操作日志
### 日志记录
所有修改操作都会记录操作日志：
```java
@Log(title = "元数据部署操作日志", businessType = BusinessType.INSERT)
@PostMapping
public AjaxResult add(@RequestBody DataiMetadataDeployLogDto dto) {
// 业务逻辑
}
```
### 日志类型
- **INSERT** - 新增操作
- **UPDATE** - 修改操作
- **DELETE** - 删除操作
- **EXPORT** - 导出操作
- **OTHER** - 其他操作
## 分页支持
### 分页参数
| 参数名 | 类型 | 描述 |
|--------|------|------|
| pageNum | int | 当前页码 |
| pageSize | int | 每页条数 |
### 分页响应
```json
{
"total": 100,
"rows": [...],
"code": 200,
"msg": "查询成功"
}
```
## 数据导出
### 导出功能
所有列表查询都支持 Excel 导出：
```java
@Operation(summary = "导出元数据部署操作日志列表")
@PreAuthorize("@ss.hasPermi('metadata:metadatadeploylog:export')")
@Log(title = "元数据部署操作日志", businessType = BusinessType.EXPORT)
@PostMapping("/export")
public void export(HttpServletResponse response, DataiMetadataDeployLogDto dto) {
List list = service.selectDataiMetadataDeployLogList(DataiMetadataDeployLogDto.toObj(dto));
ExcelUtil util = new ExcelUtil(DataiMetadataDeployLog.class);
util.exportExcel(response, list, "元数据部署操作日志数据");
}
```
### Excel 注解
使用 @Excel 注解标记需要导出的字段：
```java
@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 | 服务器内部错误 |
### 错误响应
```json
{
"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. **状态跟踪** - 跟踪操作状态和结果
该模块采用标准的分层架构，代码结构清晰，易于维护和扩展。