datai/datai-scenes/datai-scene-salesforce/docs/reference-code/datai-salesforce-apex-module.md

# 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