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

# datai-salesforce-tooling 模块详细文档

## 模块概述

`datai-salesforce-tooling` 是 Datai 项目中专门用于管理 Salesforce Tooling API 相关功能的模块。该模块提供了对 Salesforce Tooling API 的连接管理、元数据操作、SOQL 查询、Apex 日志、测试管理、代码覆盖率等功能的完整支持。

**模块路径**: `d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-tooling`

**创建日期**: 2026-02-04

**版本**: 1.0.0

**Java 版本**: 22

---

## 技术栈

### 核心依赖

| 依赖 | 版本 | 说明 |
|------|------|------|
| datai-file-common | 1.0.0 | 文件通用模块 |
| datai-salesforce-auth | - | Salesforce 认证模块 |
| javapoet | 1.13.0 | Java 代码生成库 |
| salesforce-tooling | 0.0.1 | Salesforce Tooling 工具包（本地 JAR） |

### 技术框架

- **Spring Boot**: 应用框架
- **MyBatis**: ORM 框架
- **Swagger/OpenAPI**: API 文档
- **Spring Security**: 安全认证
- **Lombok**: 简化 Java 代码
- **JavaPoet**: 动态代码生成

---

## 模块架构

### 分层架构

```
datai-salesforce-tooling/
├── controller/          # 控制器层（16个）
├── service/            # 服务层
│   ├── I*Service.java  # 服务接口（16个）
│   └── impl/           # 服务实现（16个）
├── mapper/             # 数据访问层（15个）
├── model/              # 数据模型层
│   ├── domain/         # 领域模型（15个）
│   ├── dto/            # 数据传输对象（15个）
│   └── vo/             # 视图对象（17个）
├── enums/              # 枚举类（1个）
├── factory/            # 工厂类（1个）
└── resources/
    ├── mapper/tooling/  # MyBatis XML 映射文件（14个）
    └── lib/tooling.jar # Salesforce Tooling 工具包
```

---

## 功能模块

### 1. Tooling API 连接管理

**功能描述**: 管理 Salesforce Tooling API 的连接，包括连接创建、缓存清除、连接测试、调用选项设置、调试头部设置等。

**相关类**:
- Controller: [ToolingConnectionController.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-tooling\src\main\java\com\datai\tooling\controller\ToolingConnectionController.java)
- Service: [IToolingConnectionService.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-tooling\src\main\java\com\datai\tooling\service\IToolingConnectionService.java)
- Factory: [ToolingConnectionFactory.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-tooling\src\main\java\com\datai\tooling\factory\ToolingConnectionFactory.java)
- Enum: [ToolingConnectionErrorCode.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-tooling\src\main\java\com\datai\tooling\enums\ToolingConnectionErrorCode.java)

**API 端点**:
- `GET /salesforce/tooling/connection/get` - 获取 Tooling API 连接
- `DELETE /salesforce/tooling/connection/clear` - 清除连接缓存
- `GET /salesforce/tooling/connection/test` - 测试连接
- `POST /salesforce/tooling/connection/call-options` - 设置调用选项
- `POST /salesforce/tooling/connection/debugging-header` - 设置调试头部

**连接错误码**:

| 错误码 | 说明 |
|---------|------|
| TOOLING_CONN_001 | Session 无效或已过期 |
| TOOLING_CONN_002 | 连接创建失败 |
| TOOLING_CONN_003 | 网络超时 |
| TOOLING_CONN_004 | 权限不足 |
| TOOLING_CONN_005 | API 版本不支持 |
| TOOLING_CONN_006 | 用户未登录 |
| TOOLING_CONN_007 | 设置调用选项失败 |
| TOOLING_CONN_008 | 设置调试头部失败 |

**连接结果对象** ([ToolingConnectionResult.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-tooling\src\main\java\com\datai\tooling\model\vo\ToolingConnectionResult.java)):
- `success`: 是否成功
- `connectionId`: 连接 ID
- `sessionId`: Session ID
- `instanceUrl`: 实例 URL
- `connectionTime`: 连接时间
- `errorCode`: 错误码
- `errorMessage`: 错误消息
- `valid`: 是否有效
- `testTime`: 测试时间
- `responseTime`: 响应时间（毫秒）
- `client`: 客户端名称
- `debugLevel`: 调试级别

---

### 2. Apex 代码覆盖率管理

**功能描述**: 管理 Tooling API 的 Apex 代码覆盖率数据，包括类或触发器的覆盖率信息。

**相关类**:
- Controller: [DataiToolingApexCodeCoverageController.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-tooling\src\main\java\com\datai\tooling\controller\DataiToolingApexCodeCoverageController.java)
- Domain: [DataiToolingApexCodeCoverage.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-tooling\src\main\java\com\datai\tooling\model\domain\DataiToolingApexCodeCoverage.java)

**API 端点**:
- `GET /tooling/toolingapexcodecoverage/list` - 查询覆盖率列表
- `POST /tooling/toolingapexcodecoverage/export` - 导出覆盖率数据
- `GET /tooling/toolingapexcodecoverage/{id}` - 获取覆盖率详情
- `POST /tooling/toolingapexcodecoverage` - 新增覆盖率记录
- `PUT /tooling/toolingapexcodecoverage` - 修改覆盖率记录
- `DELETE /tooling/toolingapexcodecoverage/{ids}` - 删除覆盖率记录

**数据字段**:
- `id`: 主键ID
- `apexClassOrTriggerId`: 类或触发器ID
- `apexTestClassId`: 测试类ID
- `coverage`: 覆盖率百分比
- `numLinesCovered`: 覆盖行数
- `numLinesUncovered`: 未覆盖行数
- `resultTime`: 结果时间
- `sfUserId`: Salesforce用户ID

---

### 3. Apex 代码位置管理

**功能描述**: 管理 Apex 代码的位置信息。

**相关类**:
- Controller: [DataiToolingApexCodeLocationController.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-tooling\src\main\java\com\datai\tooling\controller\DataiToolingApexCodeLocationController.java)
- Domain: [DataiToolingApexCodeLocation.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-tooling\src\main\java\com\datai\tooling\model\domain\DataiToolingApexCodeLocation.java)

**API 端点**:
- `GET /tooling/toolingapexcodelocation/list` - 查询代码位置列表
- `POST /tooling/toolingapexcodelocation/export` - 导出代码位置数据
- `GET /tooling/toolingapexcodelocation/{id}` - 获取代码位置详情
- `POST /tooling/toolingapexcodelocation` - 新增代码位置记录
- `PUT /tooling/toolingapexcodelocation` - 修改代码位置记录
- `DELETE /tooling/toolingapexcodelocation/{ids}` - 删除代码位置记录

---

### 4. Apex 日志管理

**功能描述**: 管理 Tooling API 的 Apex 执行日志。

**相关类**:
- Controller: [DataiToolingApexLogController.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-tooling\src\main\java\com\datai\tooling\controller\DataiToolingApexLogController.java)
- Domain: [DataiToolingApexLog.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-tooling\src\main\java\com\datai\tooling\model\domain\DataiToolingApexLog.java)

**API 端点**:
- `GET /tooling/toolingapexlog/list` - 查询日志列表
- `POST /tooling/toolingapexlog/export` - 导出日志数据
- `GET /tooling/toolingapexlog/{id}` - 获取日志详情
- `POST /tooling/toolingapexlog` - 新增日志记录
- `PUT /tooling/toolingapexlog` - 修改日志记录
- `DELETE /tooling/toolingapexlog/{ids}` - 删除日志记录

**数据字段**:
- `id`: 主键ID
- `logId`: 日志ID
- `application`: 应用程序
- `durationMilliseconds`: 持续时间（毫秒）
- `location`: 位置
- `logLength`: 日志长度
- `operation`: 操作
- `startTime`: 开始时间
- `status`: 状态
- `sfUserId`: Salesforce用户ID

---

### 5. Apex 测试队列项管理

**功能描述**: 管理 Apex 测试队列项，包括测试类、测试方法、状态等信息。

**相关类**:
- Controller: [DataiToolingApexTestQueueItemController.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-tooling\src\main\java\com\datai\tooling\controller\DataiToolingApexTestQueueItemController.java)
- Domain: [DataiToolingApexTestQueueItem.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-tooling\src\main\java\com\datai\tooling\model\domain\DataiToolingApexTestQueueItem.java)

**API 端点**:
- `GET /tooling/toolingapextestqueueitem/list` - 查询测试队列项列表
- `POST /tooling/toolingapextestqueueitem/export` - 导出测试队列项数据
- `GET /tooling/toolingapextestqueueitem/{id}` - 获取测试队列项详情
- `POST /tooling/toolingapextestqueueitem` - 新增测试队列项记录
- `PUT /tooling/toolingapextestqueueitem` - 修改测试队列项记录
- `DELETE /tooling/toolingapextestqueueitem/{ids}` - 删除测试队列项记录

**数据字段**:
- `id`: 主键ID
- `queueItemId`: 队列项ID
- `apexClassId`: Apex类ID
- `methodNames`: 方法名列表
- `parentJobId`: 父作业ID
- `status`: 状态
- `extendedStatus`: 扩展状态
- `createdDate`: 创建时间
- `lastModifiedDate`: 最后修改时间

---

### 6. Flow 测试覆盖率管理

**功能描述**: 管理 Flow 测试覆盖率数据。

**相关类**:
- Controller: [DataiToolingFlowTestCoverageController.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-tooling\src\main\java\com\datai\tooling\controller\DataiToolingFlowTestCoverageController.java)
- Domain: [DataiToolingFlowTestCoverage.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-tooling\src\main\java\com\datai\tooling\model\domain\DataiToolingFlowTestCoverage.java)

**API 端点**:
- `GET /tooling/toolingflowtestcoverage/list` - 查询 Flow 测试覆盖率列表
- `POST /tooling/toolingflowtestcoverage/export` - 导出 Flow 测试覆盖率数据
- `GET /tooling/toolingflowtestcoverage/{id}` - 获取 Flow 测试覆盖率详情
- `POST /tooling/toolingflowtestcoverage` - 新增 Flow 测试覆盖率记录
- `PUT /tooling/toolingflowtestcoverage` - 修改 Flow 测试覆盖率记录
- `DELETE /tooling/toolingflowtestcoverage/{ids}` - 删除 Flow 测试覆盖率记录

---

### 7. 元数据对象管理

**功能描述**: 管理 Tooling API 的元数据对象，包括元数据类型、ID、名称、版本等信息。

**相关类**:
- Controller: [DataiToolingMetadataObjectController.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-tooling\src\main\java\com\datai\tooling\controller\DataiToolingMetadataObjectController.java)
- Domain: [DataiToolingMetadataObject.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-tooling\src\main\java\com\datai\tooling\model\domain\DataiToolingMetadataObject.java)

**API 端点**:
- `GET /tooling/toolingmetadataobject/list` - 查询元数据对象列表
- `POST /tooling/toolingmetadataobject/export` - 导出元数据对象数据
- `GET /tooling/toolingmetadataobject/{id}` - 获取元数据对象详情
- `POST /tooling/toolingmetadataobject` - 新增元数据对象记录
- `PUT /tooling/toolingmetadataobject` - 修改元数据对象记录
- `DELETE /tooling/toolingmetadataobject/{ids}` - 删除元数据对象记录

**数据字段**:
- `id`: 主键ID
- `metadataType`: 元数据类型
- `metadataId`: 元数据ID
- `metadataName`: 元数据名称
- `apiVersion`: API版本
- `status`: 状态
- `bodyCrc`: 代码CRC
- `attributes`: 对象属性JSON
- `createdDate`: 创建时间
- `lastModifiedDate`: 最后修改时间
- `sfUserId`: Salesforce用户ID

---

### 8. 元数据操作日志管理

**功能描述**: 记录 Tooling API 的元数据操作日志，包括创建、更新、删除、查询等操作。

**相关类**:
- Controller: [DataiToolingMetadataOperationLogController.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-tooling\src\main\java\com\datai\tooling\controller\DataiToolingMetadataOperationLogController.java)
- Domain: [DataiToolingMetadataOperationLog.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-tooling\src\main\java\com\datai\tooling\model\domain\DataiToolingMetadataOperationLog.java)

**API 端点**:
- `GET /tooling/toolingmetadataoperationlog/list` - 查询元数据操作日志列表
- `POST /tooling/toolingmetadataoperationlog/export` - 导出元数据操作日志数据
- `GET /tooling/toolingmetadataoperationlog/{id}` - 获取元数据操作日志详情
- `POST /tooling/toolingmetadataoperationlog` - 新增元数据操作日志记录
- `PUT /tooling/toolingmetadataoperationlog` - 修改元数据操作日志记录
- `DELETE /tooling/toolingmetadataoperationlog/{ids}` - 删除元数据操作日志记录

**数据字段**:
- `id`: 主键ID
- `operationType`: 操作类型（create/update/delete/query）
- `metadataType`: 元数据类型
- `metadataId`: 元数据ID
- `metadataName`: 元数据名称
- `requestData`: 请求数据（JSON 格式）
- `responseData`: 响应数据（JSON 格式）
- `status`: 操作状态（success/failed）
- `errorCode`: 错误码
- `errorMessage`: 错误消息
- `operationTime`: 操作时间
- `sfUserId`: Salesforce用户ID

---

### 9. SOQL 查询日志管理

**功能描述**: 记录 SOQL 查询操作日志，包括查询字符串、结果数量、执行时间等信息。

**相关类**:
- Controller: [DataiToolingSoqlQueryLogController.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-tooling\src\main\java\com\datai\tooling\controller\DataiToolingSoqlQueryLogController.java)
- Domain: [DataiToolingSoqlQueryLog.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-tooling\src\main\java\com\datai\tooling\model\domain\DataiToolingSoqlQueryLog.java)

**API 端点**:
- `GET /tooling/toolingsoqlquerylog/list` - 查询 SOQL 查询日志列表
- `POST /tooling/toolingsoqlquerylog/export` - 导出 SOQL 查询日志数据
- `GET /tooling/toolingsoqlquerylog/{id}` - 获取 SOQL 查询日志详情
- `POST /tooling/toolingsoqlquerylog` - 新增 SOQL 查询日志记录
- `PUT /tooling/toolingsoqlquerylog` - 修改 SOQL 查询日志记录
- `DELETE /tooling/toolingsoqlquerylog/{ids}` - 删除 SOQL 查询日志记录

**数据字段**:
- `id`: 主键ID
- `operationType`: 操作类型（execute_query/query_more/query_all）
- `queryString`: SOQL 查询字符串
- `queryLocator`: 查询定位器（用于 queryMore）
- `objectType`: 查询对象类型
- `resultCount`: 结果数量（当前批次）
- `totalSize`: 总大小（所有批次）
- `isDone`: 是否完成
- `status`: 操作状态（success/failed）
- `errorCode`: 错误码（TOOLING_SOQL_001 ~ TOOLING_SOQL_006）
- `errorMessage`: 错误消息
- `executionTimeMs`: 执行时间（毫秒）
- `operationTime`: 操作时间
- `sfUserId`: Salesforce用户ID

---

### 10. SOQL 查询结果管理

**功能描述**: 管理 SOQL 查询结果数据。

**相关类**:
- Controller: [DataiToolingSoqlQueryResultController.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-tooling\src\main\java\com\datai\tooling\controller\DataiToolingSoqlQueryResultController.java)
- Domain: [DataiToolingSoqlQueryResult.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-tooling\src\main\java\com\datai\tooling\model\domain\DataiToolingSoqlQueryResult.java)

**API 端点**:
- `GET /tooling/toolingsoqlqueryresult/list` - 查询 SOQL 查询结果列表
- `POST /tooling/toolingsoqlqueryresult/export` - 导出 SOQL 查询结果数据
- `GET /tooling/toolingsoqlqueryresult/{id}` - 获取 SOQL 查询结果详情
- `POST /tooling/toolingsoqlqueryresult` - 新增 SOQL 查询结果记录
- `PUT /tooling/toolingsoqlqueryresult` - 修改 SOQL 查询结果记录
- `DELETE /tooling/toolingsoqlqueryresult/{ids}` - 删除 SOQL 查询结果记录

---

### 11. 访问安全日志管理

**功能描述**: 记录 Tooling API 的访问安全日志。

**相关类**:
- Controller: [DataiToolingAccessSecurityLogController.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-tooling\src\main\java\com\datai\tooling\controller\DataiToolingAccessSecurityLogController.java)
- Domain: [DataiToolingAccessSecurityLog.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-tooling\src\main\java\com\datai\tooling\model\domain\DataiToolingAccessSecurityLog.java)

**API 端点**:
- `GET /tooling/toolingaccesssecuritylog/list` - 查询访问安全日志列表
- `POST /tooling/toolingaccesssecuritylog/export` - 导出访问安全日志数据
- `GET /tooling/toolingaccesssecuritylog/{id}` - 获取访问安全日志详情
- `POST /tooling/toolingaccesssecuritylog` - 新增访问安全日志记录
- `PUT /tooling/toolingaccesssecuritylog` - 修改访问安全日志记录
- `DELETE /tooling/toolingaccesssecuritylog/{ids}` - 删除访问安全日志记录

---

### 12. 动作自动化日志管理

**功能描述**: 记录动作自动化操作的日志。

**相关类**:
- Controller: [DataiToolingActionAutomationLogController.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-tooling\src\main\java\com\datai\tooling\controller\DataiToolingActionAutomationLogController.java)
- Domain: [DataiToolingActionAutomationLog.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-tooling\src\main\java\com\datai\tooling\model\domain\DataiToolingActionAutomationLog.java)

**API 端点**:
- `GET /tooling/toolingactionautomationlog/list` - 查询动作自动化日志列表
- `POST /tooling/toolingactionautomationlog/export` - 导出动作自动化日志数据
- `GET /tooling/toolingactionautomationlog/{id}` - 获取动作自动化日志详情
- `POST /tooling/toolingactionautomationlog` - 新增动作自动化日志记录
- `PUT /tooling/toolingactionautomationlog` - 修改动作自动化日志记录
- `DELETE /tooling/toolingactionautomationlog/{ids}` - 删除动作自动化日志记录

---

### 13. 高级功能日志管理

**功能描述**: 记录高级功能操作的日志。

**相关类**:
- Controller: [DataiToolingAdvancedFeaturesLogController.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-tooling\src\main\java\com\datai\tooling\controller\DataiToolingAdvancedFeaturesLogController.java)
- Domain: [DataiToolingAdvancedFeaturesLog.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-tooling\src\main\java\com\datai\tooling\model\domain\DataiToolingAdvancedFeaturesLog.java)

**API 端点**:
- `GET /tooling/toolingadvancedfeatureslog/list` - 查询高级功能日志列表
- `POST /tooling/toolingadvancedfeatureslog/export` - 导出高级功能日志数据
- `GET /tooling/toolingadvancedfeatureslog/{id}` - 获取高级功能日志详情
- `POST /tooling/toolingadvancedfeatureslog` - 新增高级功能日志记录
- `PUT /tooling/toolingadvancedfeatureslog` - 修改高级功能日志记录
- `DELETE /tooling/toolingadvancedfeatureslog/{ids}` - 删除高级功能日志记录

---

### 14. AI 操作日志管理

**功能描述**: 记录 AI 相关操作的日志。

**相关类**:
- Controller: [DataiToolingAiOperationLogController.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-tooling\src\main\java\com\datai\tooling\controller\DataiToolingAiOperationLogController.java)
- Domain: [DataiToolingAiOperationLog.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-tooling\src\main\java\com\datai\tooling\model\domain\DataiToolingAiOperationLog.java)

**API 端点**:
- `GET /tooling/toolingaioperationlog/list` - 查询 AI 操作日志列表
- `POST /tooling/toolingaioperationlog/export` - 导出 AI 操作日志数据
- `GET /tooling/toolingaioperationlog/{id}` - 获取 AI 操作日志详情
- `POST /tooling/toolingaioperationlog` - 新增 AI 操作日志记录
- `PUT /tooling/toolingaioperationlog` - 修改 AI 操作日志记录
- `DELETE /tooling/toolingaioperationlog/{ids}` - 删除 AI 操作日志记录

---

### 15. 开发工具操作日志管理

**功能描述**: 记录开发工具操作的日志。

**相关类**:
- Controller: [DataiToolingDevtoolsOperationLogController.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-tooling\src\main\java\com\datai\tooling\controller\DataiToolingDevtoolsOperationLogController.java)
- Domain: [DataiToolingDevtoolsOperationLog.java](file:///d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-tooling\src\main\java\com\datai\tooling\model\domain\DataiToolingDevtoolsOperationLog.java)

**API 端点**:
- `GET /tooling/toolingdevtoolsoperationlog/list` - 查询开发工具操作日志列表
- `POST /tooling/toolingdevtoolsoperationlog/export` - 导出开发工具操作日志数据
- `GET /tooling/toolingdevtoolsoperationlog/{id}` - 获取开发工具操作日志详情
- `POST /tooling/toolingdevtoolsoperationlog` - 新增开发工具操作日志记录
- `PUT /tooling/toolingdevtoolsoperationlog` - 修改开发工具操作日志记录
- `DELETE /tooling/toolingdevtoolsoperationlog/{ids}` - 删除开发工具操作日志记录

---

## 数据模型设计

### 统一基类

所有 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

---

## 连接管理

### 连接工厂

**ToolingConnectionFactory** 继承自 `AbstractConnectionFactory`，提供 ToolingConnection 实例的创建和管理。

**API 版本**: 60.0

**连接创建流程**:
1. 从 SessionManager 获取当前登录结果
2. 验证登录状态和 Session ID
3. 创建 ConnectorConfig 配置
4. 设置 Service Endpoint
5. 创建 ToolingConnection 实例
6. 设置会话头

**连接配置**:
- `sessionId`: 会话 ID
- `serviceEndpoint`: 服务端点（`{instanceUrl}/services/Soap/T/60.0`）
- `compression`: 启用压缩
- `traceMessage`: 禁用消息跟踪

---

## 安全控制

### 权限注解

所有 Controller 方法都使用 `@PreAuthorize` 注解进行权限控制：

```java
@PreAuthorize("@ss.hasPermi('tooling:模块:操作')")
```

**权限格式**: `tooling:{模块名}:{操作}`

**操作类型**:
- `list`: 查询列表
- `query`: 查询详情
- `add`: 新增
- `edit`: 修改
- `remove`: 删除
- `export`: 导出
- `get`: 获取
- `clear`: 清除
- `test`: 测试
- `callOptions`: 设置调用选项
- `debuggingHeader`: 设置调试头部

### 日志记录

使用 `@Log` 注解记录业务操作日志：

```java
@Log(title = "模块名称", businessType = BusinessType.INSERT/UPDATE/DELETE/EXPORT/OTHER)
```

---

## API 文档

### Swagger/OpenAPI

所有 API 接口都使用 Swagger 3.0 注解进行文档化：

```java
@Tag(name = "模块名称", description = "模块描述")
@Operation(summary = "操作说明", description = "详细描述")
```

访问路径: `/swagger-ui.html` 或 `/doc.html`

---

## 数据库映射

### MyBatis 配置

所有 Mapper XML 文件位于 `src/main/resources/mapper/tooling/` 目录下。

**命名规范**:
- Mapper 接口: `DataiToolingXxxMapper.java`
- XML 映射文件: `DataiToolingXxxMapper.xml`

**表命名规范**: `datai_tooling_xxx`

### 结果映射

使用 `<resultMap>` 定义数据库字段到 Java 对象的映射：

```xml
<resultMap type="DataiToolingXxx" id="DataiToolingXxxResult">
    <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 转换
5. 使用 `@Slf4j` 进行日志记录

### 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()` 进行属性拷贝

### 工厂层

1. 继承 `AbstractConnectionFactory`
2. 使用 `@Component` 注解
3. 实现 `createConnection` 方法
4. 使用 `@Slf4j` 进行日志记录

---

## 依赖关系

### 外部依赖

```
datai-salesforce-tooling
├── datai-file-common (文件通用模块)
├── datai-salesforce-auth (Salesforce 认证模块)
├── javapoet (Java 代码生成库)
└── salesforce-tooling (Salesforce Tooling 工具包)
```

### 内部依赖

```
Controller → Service → Mapper → Database
     ↓          ↓
    DTO      Domain
     ↓          ↓
    VO      VO
```

---

## 扩展点

### 1. 自定义连接配置

在 `ToolingConnectionFactory` 中扩展连接配置逻辑。

### 2. 自定义错误处理

扩展 `ToolingConnectionErrorCode` 枚举，添加新的错误码。

### 3. 自定义元数据操作

扩展元数据操作日志，支持更多元数据类型。

### 4. 自定义 SOQL 查询

扩展 SOQL 查询日志，支持更多查询类型。

---

## 注意事项

1. **权限控制**: 所有 API 接口都需要相应的权限才能访问
2. **数据校验**: 建议在 DTO 层添加数据校验注解
3. **事务管理**: Service 层方法可根据需要添加 `@Transactional` 注解
4. **异常处理**: 建议统一使用全局异常处理器
5. **日志记录**: 重要操作需要记录日志
6. **分页查询**: 列表查询接口支持分页参数
7. **连接管理**: Tooling API 连接需要定期刷新
8. **API 版本**: 当前使用 API 版本 60.0，升级时需要同步更新

---

## 更新日志

### 2026-02-04

- 初始版本创建
- 实现 15 个功能模块的 CRUD 接口
- 实现 Tooling API 连接管理功能
- 完成数据模型设计
- 配置 MyBatis 映射
- 集成 Swagger API 文档
- 添加连接工厂和错误码枚举

---

## 联系方式

**模块负责人**: datai

**创建日期**: 2026-02-04

**文档版本**: 1.0.0