499 lines
16 KiB
Markdown
499 lines
16 KiB
Markdown
# datai-salesforce-apex 模块详细文档
|
||
|
||
## 模块概述
|
||
|
||
`datai-salesforce-apex` 是 Datai 项目中专门用于管理 Salesforce Apex 相关功能的模块。该模块提供了对 Apex 代码执行、日志管理、测试管理、WSDL 转换等功能的完整支持。
|
||
|
||
**模块路径**: `d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-apex`
|
||
|
||
**创建日期**: 2026-02-04
|
||
|
||
**版本**: 1.0.0
|
||
|
||
**Java 版本**: 22
|
||
|
||
---
|
||
|
||
## 技术栈
|
||
|
||
### 核心依赖
|
||
|
||
| 依赖 | 版本 | 说明 |
|
||
|------|------|------|
|
||
| datai-file-common | 1.0.0 | 文件通用模块 |
|
||
| datai-salesforce-auth | - | Salesforce 认证模块 |
|
||
| salesforce-apex | 0.0.1 | Salesforce Apex 工具包（本地 JAR） |
|
||
|
||
### 技术框架
|
||
|
||
- **Spring Boot**: 应用框架
|
||
- **MyBatis**: ORM 框架
|
||
- **Swagger/OpenAPI**: API 文档
|
||
- **Spring Security**: 安全认证
|
||
- **Lombok**: 简化 Java 代码
|
||
|
||
---
|
||
|
||
## 模块架构
|
||
|
||
### 分层架构
|
||
|
||
```
|
||
datai-salesforce-apex/
|
||
├── controller/ # 控制器层（10个）
|
||
├── service/ # 服务层
|
||
│ ├── I*Service.java # 服务接口（10个）
|
||
│ └── impl/ # 服务实现（10个）
|
||
├── mapper/ # 数据访问层（10个）
|
||
├── model/ # 数据模型层
|
||
│ ├── domain/ # 领域模型（10个）
|
||
│ ├── dto/ # 数据传输对象（10个）
|
||
│ └── vo/ # 视图对象（10个）
|
||
└── resources/
|
||
├── mapper/apex/ # MyBatis XML 映射文件（10个）
|
||
└── lib/apex.jar # Salesforce Apex 工具包
|
||
```
|
||
|
||
---
|
||
|
||
## 功能模块
|
||
|
||
### 1. 匿名 Apex 执行历史管理
|
||
|
||
**功能描述**: 记录和管理匿名 Apex 代码的执行历史，包括执行结果、编译状态、异常信息等。
|
||
|
||
**相关类**:
|
||
- Controller: [DataiApexExecuteAnonymousHistoryController.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-apex\src\main\java\com\datai\apex\controller\DataiApexExecuteAnonymousHistoryController.java)
|
||
- Service: [IDataiApexExecuteAnonymousHistoryService.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-apex\src\main\java\com\datai\apex\service\IDataiApexExecuteAnonymousHistoryService.java)
|
||
- Domain: [DataiApexExecuteAnonymousHistory.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-apex\src\main\java\com\datai\apex\model\domain\DataiApexExecuteAnonymousHistory.java)
|
||
|
||
**API 端点**:
|
||
- `GET /apex/apexexecutehistory/list` - 查询列表
|
||
- `POST /apex/apexexecutehistory/export` - 导出数据
|
||
- `GET /apex/apexexecutehistory/{id}` - 获取详情
|
||
- `POST /apex/apexexecutehistory` - 新增记录
|
||
- `PUT /apex/apexexecutehistory` - 修改记录
|
||
- `DELETE /apex/apexexecutehistory/{ids}` - 删除记录
|
||
|
||
**数据字段**:
|
||
- `id`: 主键ID
|
||
- `executeCode`: 匿名代码内容
|
||
- `success`: 执行是否成功
|
||
- `compiled`: 编译是否成功
|
||
- `compileProblem`: 编译问题描述
|
||
- `exceptionMessage`: 异常消息
|
||
- `exceptionStackTrace`: 异常堆栈
|
||
- `line`: 错误行号
|
||
- `column`: 错误列号
|
||
- `apexLogId`: Apex日志ID
|
||
- `executeTime`: 执行时间
|
||
- `sfUserId`: Salesforce用户ID
|
||
|
||
---
|
||
|
||
### 2. Apex 日志管理
|
||
|
||
**功能描述**: 管理 Salesforce Apex 执行日志，包括日志ID、应用程序、持续时间、操作等信息。
|
||
|
||
**相关类**:
|
||
- Controller: [DataiApexLogController.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-apex\src\main\java\com\datai\apex\controller\DataiApexLogController.java)
|
||
- Domain: [DataiApexLog.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-apex\src\main\java\com\datai\apex\model\domain\DataiApexLog.java)
|
||
|
||
**API 端点**:
|
||
- `GET /apex/apexlog/list` - 查询日志列表
|
||
- `POST /apex/apexlog/export` - 导出日志
|
||
- `GET /apex/apexlog/{id}` - 获取日志详情
|
||
- `POST /apex/apexlog` - 新增日志
|
||
- `PUT /apex/apexlog` - 修改日志
|
||
- `DELETE /apex/apexlog/{ids}` - 删除日志
|
||
|
||
**数据字段**:
|
||
- `id`: 主键ID
|
||
- `logId`: 日志ID（Salesforce 日志 ID）
|
||
- `application`: 应用程序
|
||
- `durationMilliseconds`: 持续时间（毫秒）
|
||
- `location`: 位置
|
||
- `logLength`: 日志长度
|
||
- `operation`: 操作
|
||
- `startTime`: 开始时间
|
||
- `status`: 状态
|
||
- `sfUserId`: Salesforce用户ID
|
||
- `userId`: 用户ID
|
||
|
||
---
|
||
|
||
### 3. Apex 日志分类管理
|
||
|
||
**功能描述**: 管理 Apex 日志的分类信息。
|
||
|
||
**相关类**:
|
||
- Controller: [DataiApexLogCategoryController.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-apex\src\main\java\com\datai\apex\controller\DataiApexLogCategoryController.java)
|
||
- Domain: [DataiApexLogCategory.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-apex\src\main\java\com\datai\apex\model\domain\DataiApexLogCategory.java)
|
||
|
||
**API 端点**:
|
||
- `GET /apex/apexlogcategory/list` - 查询分类列表
|
||
- `POST /apex/apexlogcategory/export` - 导出分类
|
||
- `GET /apex/apexlogcategory/{id}` - 获取分类详情
|
||
- `POST /apex/apexlogcategory` - 新增分类
|
||
- `PUT /apex/apexlogcategory` - 修改分类
|
||
- `DELETE /apex/apexlogcategory/{ids}` - 删除分类
|
||
|
||
---
|
||
|
||
### 4. Apex 测试管理
|
||
|
||
#### 4.1 Apex 测试请求
|
||
|
||
**功能描述**: 管理 Apex 测试请求配置，包括测试类、测试方法、命名空间等。
|
||
|
||
**相关类**:
|
||
- Controller: [DataiApexTestRequestController.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-apex\src\main\java\com\datai\apex\controller\DataiApexTestRequestController.java)
|
||
- Domain: [DataiApexTestRequest.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-apex\src\main\java\com\datai\apex\model\domain\DataiApexTestRequest.java)
|
||
|
||
**API 端点**:
|
||
- `GET /apex/apextestrequest/list` - 查询请求列表
|
||
- `POST /apex/apextestrequest/export` - 导出请求
|
||
- `GET /apex/apextestrequest/{id}` - 获取请求详情
|
||
- `POST /apex/apextestrequest` - 新增请求
|
||
- `PUT /apex/apextestrequest` - 修改请求
|
||
- `DELETE /apex/apextestrequest/{ids}` - 删除请求
|
||
|
||
**数据字段**:
|
||
- `id`: 主键ID
|
||
- `testResultId`: 测试结果ID（外键）
|
||
- `testRunId`: 测试运行ID
|
||
- `allTests`: 是否运行所有测试
|
||
- `classes`: 测试类列表
|
||
- `namespace`: 命名空间
|
||
- `packages`: 包列表
|
||
- `tests`: 测试方法列表
|
||
- `maxFailedTests`: 最大失败测试数
|
||
- `skipCodeCoverage`: 是否跳过代码覆盖率
|
||
|
||
#### 4.2 Apex 测试结果
|
||
|
||
**功能描述**: 记录 Apex 测试执行结果，包括测试数量、失败数量、覆盖率等信息。
|
||
|
||
**相关类**:
|
||
- Controller: [DataiApexTestResultController.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-apex\src\main\java\com\datai\apex\controller\DataiApexTestResultController.java)
|
||
- Domain: [DataiApexTestResult.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-apex\src\main\java\com\datai\apex\model\domain\DataiApexTestResult.java)
|
||
|
||
**API 端点**:
|
||
- `GET /apex/apextestresult/list` - 查询结果列表
|
||
- `POST /apex/apextestresult/export` - 导出结果
|
||
- `GET /apex/apextestresult/{id}` - 获取结果详情
|
||
- `POST /apex/apextestresult` - 新增结果
|
||
- `PUT /apex/apextestresult` - 修改结果
|
||
- `DELETE /apex/apextestresult/{ids}` - 删除结果
|
||
|
||
**数据字段**:
|
||
- `id`: 主键ID
|
||
- `testRunId`: 测试运行ID
|
||
- `numTestsRun`: 运行的测试数量
|
||
- `numFailures`: 失败的测试数量
|
||
- `totalTime`: 总执行时间（毫秒）
|
||
- `apexLogId`: Apex日志ID
|
||
- `testTime`: 测试时间
|
||
- `allPassed`: 是否全部通过
|
||
- `totalCoverage`: 总体覆盖率百分比
|
||
|
||
#### 4.3 Apex 测试成功详情
|
||
|
||
**功能描述**: 记录 Apex 测试成功的详细信息。
|
||
|
||
**相关类**:
|
||
- Controller: [DataiApexTestSuccessController.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-apex\src\main\java\com\datai\apex\controller\DataiApexTestSuccessController.java)
|
||
- Domain: [DataiApexTestSuccess.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-apex\src\main\java\com\datai\apex\model\domain\DataiApexTestSuccess.java)
|
||
|
||
#### 4.4 Apex 测试失败详情
|
||
|
||
**功能描述**: 记录 Apex 测试失败的详细信息。
|
||
|
||
**相关类**:
|
||
- Controller: [DataiApexTestFailureController.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-apex\src\main\java\com\datai\apex\controller\DataiApexTestFailureController.java)
|
||
- Domain: [DataiApexTestFailure.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-apex\src\main\java\com\datai\apex\model\domain\DataiApexTestFailure.java)
|
||
|
||
---
|
||
|
||
### 5. Apex Flow 覆盖率警告管理
|
||
|
||
**功能描述**: 管理 Apex Flow 覆盖率警告信息。
|
||
|
||
**相关类**:
|
||
- Controller: [DataiApexFlowCoverageWarningController.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-apex\src\main\java\com\datai\apex\controller\DataiApexFlowCoverageWarningController.java)
|
||
- Domain: [DataiApexFlowCoverageWarning.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-apex\src\main\java\com\datai\apex\model\domain\DataiApexFlowCoverageWarning.java)
|
||
|
||
**API 端点**:
|
||
- `GET /apex/apexflowwarning/list` - 查询警告列表
|
||
- `POST /apex/apexflowwarning/export` - 导出警告
|
||
- `GET /apex/apexflowwarning/{id}` - 获取警告详情
|
||
- `POST /apex/apexflowwarning` - 新增警告
|
||
- `PUT /apex/apexflowwarning` - 修改警告
|
||
- `DELETE /apex/apexflowwarning/{ids}` - 删除警告
|
||
|
||
**数据字段**:
|
||
- `id`: 主键ID
|
||
- `testResultId`: 测试结果ID（外键）
|
||
- `name`: Flow名称
|
||
- `type`: Flow类型
|
||
- `namespace`: 命名空间
|
||
- `message`: 警告消息
|
||
|
||
---
|
||
|
||
### 6. WSDL 转换管理
|
||
|
||
#### 6.1 WSDL 转换记录
|
||
|
||
**功能描述**: 管理 WSDL 到 Apex 类的转换记录。
|
||
|
||
**相关类**:
|
||
- Controller: [DataiApexWsdlConversionController.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-apex\src\main\java\com\datai\apex\controller\DataiApexWsdlConversionController.java)
|
||
- Domain: [DataiApexWsdlConversion.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-apex\src\main\java\com\datai\apex\model\domain\DataiApexWsdlConversion.java)
|
||
|
||
**API 端点**:
|
||
- `GET /apex/apexwsdlconversion/list` - 查询转换记录列表
|
||
- `POST /apex/apexwsdlconversion/export` - 导出转换记录
|
||
- `GET /apex/apexwsdlconversion/{id}` - 获取转换记录详情
|
||
- `POST /apex/apexwsdlconversion` - 新增转换记录
|
||
- `PUT /apex/apexwsdlconversion` - 修改转换记录
|
||
- `DELETE /apex/apexwsdlconversion/{ids}` - 删除转换记录
|
||
|
||
**数据字段**:
|
||
- `id`: 转换ID
|
||
- `wsdlUrl`: WSDL URL
|
||
- `packageName`: 包名
|
||
- `generateAsync`: 是否生成异步代码
|
||
- `status`: 转换状态（pending/processing/success/failed）
|
||
- `errorMessage`: 错误信息
|
||
|
||
#### 6.2 WSDL 转换生成的 Apex 类
|
||
|
||
**功能描述**: 管理 WSDL 转换后生成的 Apex 类代码。
|
||
|
||
**相关类**:
|
||
- Controller: [DataiApexWsdlClassController.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-apex\src\main\java\com\datai\apex\controller\DataiApexWsdlClassController.java)
|
||
- Domain: [DataiApexWsdlClass.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-apex\src\main\java\com\datai\apex\model\domain\DataiApexWsdlClass.java)
|
||
|
||
**API 端点**:
|
||
- `GET /apex/apexwsdlclass/list` - 查询 Apex 类列表
|
||
- `POST /apex/apexwsdlclass/export` - 导出 Apex 类
|
||
- `GET /apex/apexwsdlclass/{id}` - 获取 Apex 类详情
|
||
- `POST /apex/apexwsdlclass` - 新增 Apex 类
|
||
- `PUT /apex/apexwsdlclass` - 修改 Apex 类
|
||
- `DELETE /apex/apexwsdlclass/{ids}` - 删除 Apex 类
|
||
|
||
**数据字段**:
|
||
- `id`: 类ID
|
||
- `conversionId`: 转换ID
|
||
- `className`: 类名
|
||
- `classCode`: 类代码
|
||
|
||
---
|
||
|
||
## 数据模型设计
|
||
|
||
### 统一基类
|
||
|
||
所有 Domain 类都继承自 `BaseEntity`，包含以下公共字段：
|
||
|
||
```java
|
||
- createBy: 创建人
|
||
- createTime: 创建时间
|
||
- updateBy: 更新人
|
||
- updateTime: 更新时间
|
||
- remark: 备注
|
||
```
|
||
|
||
### 模型转换
|
||
|
||
模块采用三层模型设计：
|
||
|
||
1. **Domain（领域模型）**: 对应数据库表结构，用于持久化
|
||
2. **DTO（数据传输对象）**: 用于接收前端请求参数
|
||
3. **VO（视图对象）**: 用于返回前端响应数据
|
||
|
||
**转换方法**:
|
||
- `Dto.toObj()`: DTO 转 Domain
|
||
- `Dto.fromObj()`: Domain 转 DTO
|
||
- `Vo.objToVo()`: Domain 转 VO
|
||
|
||
---
|
||
|
||
## 安全控制
|
||
|
||
### 权限注解
|
||
|
||
所有 Controller 方法都使用 `@PreAuthorize` 注解进行权限控制：
|
||
|
||
```java
|
||
@PreAuthorize("@ss.hasPermi('apex:模块:操作')")
|
||
```
|
||
|
||
**权限格式**: `apex:{模块名}:{操作}`
|
||
|
||
**操作类型**:
|
||
- `list`: 查询列表
|
||
- `query`: 查询详情
|
||
- `add`: 新增
|
||
- `edit`: 修改
|
||
- `remove`: 删除
|
||
- `export`: 导出
|
||
|
||
### 日志记录
|
||
|
||
使用 `@Log` 注解记录业务操作日志：
|
||
|
||
```java
|
||
@Log(title = "模块名称", businessType = BusinessType.INSERT/UPDATE/DELETE/EXPORT)
|
||
```
|
||
|
||
---
|
||
|
||
## API 文档
|
||
|
||
### Swagger/OpenAPI
|
||
|
||
所有 API 接口都使用 Swagger 3.0 注解进行文档化：
|
||
|
||
```java
|
||
@Tag(name = "【模块名称】管理")
|
||
@Operation(summary = "操作说明")
|
||
```
|
||
|
||
访问路径: `/swagger-ui.html` 或 `/doc.html`
|
||
|
||
---
|
||
|
||
## 数据库映射
|
||
|
||
### MyBatis 配置
|
||
|
||
所有 Mapper XML 文件位于 `src/main/resources/mapper/apex/` 目录下。
|
||
|
||
**命名规范**:
|
||
- Mapper 接口: `DataiApexXxxMapper.java`
|
||
- XML 映射文件: `DataiApexXxxMapper.xml`
|
||
|
||
**表命名规范**: `datai_apex_xxx`
|
||
|
||
### 结果映射
|
||
|
||
使用 `<resultMap>` 定义数据库字段到 Java 对象的映射：
|
||
|
||
```xml
|
||
<resultMap type="DataiApexXxx" id="DataiApexXxxResult">
|
||
<result property="javaField" column="db_column" />
|
||
</resultMap>
|
||
```
|
||
|
||
### 动态 SQL
|
||
|
||
使用 MyBatis 动态 SQL 标签：
|
||
- `<where>`: 动态 WHERE 条件
|
||
- `<if>`: 条件判断
|
||
- `<trim>`: 去除多余逗号
|
||
- `<foreach>`: 批量操作
|
||
|
||
---
|
||
|
||
## 代码规范
|
||
|
||
### Controller 层
|
||
|
||
1. 继承 `BaseController`
|
||
2. 使用 `@RestController` 注解
|
||
3. 统一返回 `AjaxResult` 或 `TableDataInfo`
|
||
4. 使用 Stream API 进行 DTO/VO 转换
|
||
|
||
### Service 层
|
||
|
||
1. 定义接口 `IXxxService`
|
||
2. 实现类 `XxxServiceImpl`
|
||
3. 使用 `@Service` 注解
|
||
4. 自动注入 Mapper
|
||
|
||
### Mapper 层
|
||
|
||
1. 定义接口 `XxxMapper`
|
||
2. 使用 MyBatis 注解或 XML 映射
|
||
3. 支持增删改查操作
|
||
|
||
### 模型层
|
||
|
||
1. Domain 使用 `@Schema` 注解
|
||
2. DTO 使用 `@Data` 注解（Lombok）
|
||
3. VO 使用 `@Data` 注解（Lombok）
|
||
4. 使用 `BeanUtils.copyProperties()` 进行属性拷贝
|
||
|
||
---
|
||
|
||
## 依赖关系
|
||
|
||
### 外部依赖
|
||
|
||
```
|
||
datai-salesforce-apex
|
||
├── datai-file-common (文件通用模块)
|
||
└── datai-salesforce-auth (Salesforce 认证模块)
|
||
```
|
||
|
||
### 内部依赖
|
||
|
||
```
|
||
Controller → Service → Mapper → Database
|
||
↓ ↓
|
||
DTO Domain
|
||
↓ ↓
|
||
VO VO
|
||
```
|
||
|
||
---
|
||
|
||
## 扩展点
|
||
|
||
### 1. 自定义 Apex 执行逻辑
|
||
|
||
在 Service 实现类中扩展 Apex 代码执行逻辑。
|
||
|
||
### 2. 自定义测试报告
|
||
|
||
扩展测试结果处理逻辑，生成自定义测试报告。
|
||
|
||
### 3. 自定义 WSDL 转换
|
||
|
||
扩展 WSDL 转换逻辑，支持更多转换选项。
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. **权限控制**: 所有 API 接口都需要相应的权限才能访问
|
||
2. **数据校验**: 建议在 DTO 层添加数据校验注解
|
||
3. **事务管理**: Service 层方法可根据需要添加 `@Transactional` 注解
|
||
4. **异常处理**: 建议统一使用全局异常处理器
|
||
5. **日志记录**: 重要操作需要记录日志
|
||
6. **分页查询**: 列表查询接口支持分页参数
|
||
|
||
---
|
||
|
||
## 更新日志
|
||
|
||
### 2026-02-04
|
||
|
||
- 初始版本创建
|
||
- 实现 10 个功能模块的 CRUD 接口
|
||
- 完成数据模型设计
|
||
- 配置 MyBatis 映射
|
||
- 集成 Swagger API 文档
|
||
|
||
---
|
||
|
||
## 联系方式
|
||
|
||
**模块负责人**: datai
|
||
|
||
**创建日期**: 2026-02-04
|
||
|
||
**文档版本**: 1.0.0
|