kris/datai

Fork 0

3111404962 34dcb2811c feat：Tooling模块初步

2026-02-03 16:32:38 +08:00

16 KiB

Raw Permalink Blame History

设计文档

元数据

需求编号：004
子需求编号：004-06
子需求名称：访问和安全
阶段：阶段 2：方案设计
创建时间：2026-01-28
创建人：AI Assistant
状态：已完成
相关文档：

设计概述

本设计文档基于 Spring Boot 和若依框架，实现 Salesforce Tooling API 的访问和安全功能。核心设计包括：

连接管理复用：复用子需求 004-01 实现的 ToolingConnectionFactory，通过工厂模式获取 ToolingConnection
数据库日志记录：所有访问和安全操作都记录到数据库，支持操作审计和故障排查
异步日志记录：使用异步方式记录日志，避免影响主操作性能
异常处理机制：将 Salesforce 异常转换为自定义异常，提供友好的错误信息
SOQL 查询构建：使用 SoqlBuilder 构建 SOQL 查询，提高代码可读性和可维护性
RESTful API 设计：提供标准的 REST API 接口，包括查询访问方法、查询访问资源类型、查询 API 访问级别、查询 API 类型、查询激活平台连接器类型、查询激活平台创建类型、获取操作日志等功能
错误码枚举：使用 ToolingAccessSecurityErrorCode 枚举定义错误码

架构设计

系统架构图

graph TB
    subgraph "前端层"
        A[前端应用]
    end
    
    subgraph "API 层"
        B[ToolingAccessSecurityController]
    end
    
    subgraph "服务层"
        C[IToolingAccessSecurityService]
        D[ToolingAccessSecurityServiceImpl]
    end
    
    subgraph "工厂层"
        E[ToolingConnectionFactory]
    end
    
    subgraph "认证层"
        F[SessionManager]
    end
    
    subgraph "数据访问层"
        G[ToolingAccessSecurityLogMapper]
    end
    
    subgraph "数据库"
        H[(datai_tooling_access_security_log)]
    end
    
    subgraph "外部系统"
        I[Salesforce Tooling API]
    end
    
    A --> B
    B --> C
    C --> D
    D --> E
    E --> F
    D --> G
    G --> H
    D --> I

组件说明

组件	说明
ToolingAccessSecurityController	REST API 控制器，处理 HTTP 请求
IToolingAccessSecurityService	服务接口，定义访问和安全功能
ToolingAccessSecurityServiceImpl	服务实现，提供访问和安全功能
ToolingConnectionFactory	连接工厂，获取 ToolingConnection
SessionManager	会话管理器，管理用户会话
ToolingAccessSecurityLogMapper	数据访问对象，操作日志表
datai_tooling_access_security_log	数据库表，存储操作日志

数据流图

sequenceDiagram
    participant Client as 前端应用
    participant Controller as Controller
    participant Service as Service
    participant Factory as ConnectionFactory
    participant Session as SessionManager
    participant SF as Salesforce Tooling API
    participant DB as 数据库
    
    Client->>Controller: GET /access-methods
    Controller->>Service: getAccessMethods()
    Service->>Factory: getConnection("source")
    Factory->>Session: getSession()
    Session-->>Factory: Session
    Factory-->>Service: ToolingConnection
    Service->>SF: query(AccessMethod)
    SF-->>Service: List<AccessMethod>
    Service->>DB: insert(log)
    Service-->>Controller: List<AccessMethod>
    Controller-->>Client: JSON Response

技术方案

连接管理方案

方案描述：复用子需求 004-01 实现的 ToolingConnectionFactory，通过工厂模式获取 ToolingConnection。

实现要点：

使用 ToolingConnectionFactory.getConnection("source") 获取连接
固定使用 source ORG 类型的连接缓存
Session 过期时自动清除缓存并重新创建连接
使用 SessionManager 获取当前用户会话信息

优势：

统一连接管理，避免重复代码
连接缓存提高性能
自动处理 Session 过期

数据库日志记录方案

方案描述：所有访问和安全操作都记录到数据库，支持操作审计和故障排查。

实现要点：

使用异步方式记录日志，避免影响主操作性能
记录完整的请求和响应信息（JSON 格式）
记录操作时间、用户 ID、操作状态等信息
提供日志查询接口，支持按操作类型、元数据类型、时间范围等条件查询

优势：

完整的操作审计
便于故障排查
支持数据分析

异常处理方案

方案描述：将 Salesforce 异常转换为自定义异常，提供友好的错误信息。

实现要点：

使用 ToolingAccessSecurityErrorCode 枚举定义错误码
捕获 Salesforce 异常并转换为 SalesforceAuthException
记录异常信息到日志
返回友好的错误信息给前端

优势：

统一的异常处理
友好的错误信息
便于问题定位

SOQL 查询构建方案

方案描述：使用 SoqlBuilder 构建 SOQL 查询，提高代码可读性和可维护性。

实现要点：

使用 SoqlBuilder 构建查询语句
支持动态添加查询条件
支持分页查询
优化查询性能

优势：

代码可读性高
易于维护
性能优化

RESTful API 设计方案

方案描述：遵循 RESTful API 设计规范，提供清晰的 API 接口。

实现要点：

使用 HTTP 方法表示操作类型（GET 用于查询）
使用资源路径表示操作对象
统一的响应格式
支持分页查询

优势：

符合 RESTful 规范
接口清晰易懂
易于集成

数据模型

Service 层数据模型

IToolingAccessSecurityService

public interface IToolingAccessSecurityService {
    
    List<AccessMethodVO> getAccessMethods();
    
    List<AccessResourceTypeVO> getAccessResourceTypes();
    
    List<APIAccessLevelVO> getAPIAccessLevels();
    
    List<APITypeVO> getAPITypes();
    
    List<ActivationPlatformConnectorTypeVO> getActivationPlatformConnectorTypes();
    
    List<ActivationPlatformCreationTypeVO> getActivationPlatformCreationTypes();
    
    PageInfo<ToolingAccessSecurityLogVO> getOperationLogs(AccessSecurityLogQueryRequest request);
}

Controller 层数据模型

ToolingAccessSecurityController

@RestController
@RequestMapping("/salesforce/tooling/access-security")
public class ToolingAccessSecurityController {
    
    @GetMapping("/access-methods")
    public AjaxResult getAccessMethods();
    
    @GetMapping("/access-resource-types")
    public AjaxResult getAccessResourceTypes();
    
    @GetMapping("/api-access-levels")
    public AjaxResult getAPIAccessLevels();
    
    @GetMapping("/api-types")
    public AjaxResult getAPITypes();
    
    @GetMapping("/activation-platform-connector-types")
    public AjaxResult getActivationPlatformConnectorTypes();
    
    @GetMapping("/activation-platform-creation-types")
    public AjaxResult getActivationPlatformCreationTypes();
    
    @GetMapping("/logs")
    public TableDataInfo getOperationLogs(AccessSecurityLogQueryRequest request);
}

DTO 数据模型

AccessSecurityLogQueryRequest

public class AccessSecurityLogQueryRequest {
    
    private String operationType;
    
    private String metadataType;
    
    private String startTime;
    
    private String endTime;
    
    private Integer pageNum;
    
    private Integer pageSize;
}

VO 数据模型

AccessMethodVO

public class AccessMethodVO {
    
    private String name;
    
    private String description;
}

AccessResourceTypeVO

public class AccessResourceTypeVO {
    
    private String name;
    
    private String description;
}

APIAccessLevelVO

public class APIAccessLevelVO {
    
    private String name;
    
    private String description;
}

APITypeVO

public class APITypeVO {
    
    private String name;
    
    private String description;
}

ActivationPlatformConnectorTypeVO

public class ActivationPlatformConnectorTypeVO {
    
    private String name;
    
    private String description;
}

ActivationPlatformCreationTypeVO

public class ActivationPlatformCreationTypeVO {
    
    private String name;
    
    private String description;
}

ToolingAccessSecurityLogVO

public class ToolingAccessSecurityLogVO {
    
    private Long id;
    
    private String operationType;
    
    private String metadataType;
    
    private String metadataId;
    
    private String metadataName;
    
    private String queryCondition;
    
    private Integer resultCount;
    
    private String status;
    
    private String errorCode;
    
    private String errorMessage;
    
    private String operationTime;
    
    private String userId;
}

Entity 数据模型

ToolingAccessSecurityLog

@Data
@TableName("datai_tooling_access_security_log")
public class ToolingAccessSecurityLog {
    
    @TableId(type = IdType.AUTO)
    private Long id;
    
    private String operationType;
    
    private String metadataType;
    
    private String metadataId;
    
    private String metadataName;
    
    private String queryCondition;
    
    private Integer resultCount;
    
    private String status;
    
    private String errorCode;
    
    private String errorMessage;
    
    private LocalDateTime operationTime;
    
    private String userId;
    
    @TableField(fill = FieldFill.INSERT)
    private LocalDateTime createTime;
    
    @TableField(fill = FieldFill.INSERT_UPDATE)
    private LocalDateTime updateTime;
}

接口设计

REST API 接口

1. 查询访问方法

接口: GET /salesforce/tooling/access-security/access-methods

功能: 查询访问方法列表

请求参数: 无

响应格式:

{
  "code": 200,
  "message": "查询访问方法成功",
  "data": {
    "success": true,
    "total": 5,
    "list": [
      {
        "name": "OAuth",
        "description": "OAuth 访问"
      },
      {
        "name": "SessionId",
        "description": "Session ID 访问"
      }
    ]
  }
}

2. 查询访问资源类型

接口: GET /salesforce/tooling/access-security/access-resource-types

功能: 查询访问资源类型列表

请求参数: 无

响应格式:

{
  "code": 200,
  "message": "查询访问资源类型成功",
  "data": {
    "success": true,
    "total": 10,
    "list": [
      {
        "name": "ApexClass",
        "description": "Apex 类"
      },
      {
        "name": "ApexTrigger",
        "description": "Apex 触发器"
      }
    ]
  }
}

3. 查询 API 访问级别

接口: GET /salesforce/tooling/access-security/api-access-levels

功能: 查询 API 访问级别列表

请求参数: 无

响应格式:

{
  "code": 200,
  "message": "查询 API 访问级别成功",
  "data": {
    "success": true,
    "total": 5,
    "list": [
      {
        "name": "FullAccess",
        "description": "完全访问"
      },
      {
        "name": "ReadOnly",
        "description": "只读访问"
      }
    ]
  }
}

4. 查询 API 类型

接口: GET /salesforce/tooling/access-security/api-types

功能: 查询 API 类型列表

请求参数: 无

响应格式:

{
  "code": 200,
  "message": "查询 API 类型成功",
  "data": {
    "success": true,
    "total": 8,
    "list": [
      {
        "name": "REST",
        "description": "REST API"
      },
      {
        "name": "SOAP",
        "description": "SOAP API"
      },
      {
        "name": "BULK",
        "description": "Bulk API"
      }
    ]
  }
}

5. 查询激活平台连接器类型

接口: GET /salesforce/tooling/access-security/activation-platform-connector-types

功能: 查询激活平台连接器类型列表

请求参数: 无

响应格式:

{
  "code": 200,
  "message": "查询激活平台连接器类型成功",
  "data": {
    "success": true,
    "total": 5,
    "list": [
      {
        "name": "MuleSoft",
        "description": "MuleSoft 连接器"
      },
      {
        "name": "Salesforce",
        "description": "Salesforce 连接器"
      }
    ]
  }
}

6. 查询激活平台创建类型

接口: GET /salesforce/tooling/access-security/activation-platform-creation-types

功能: 查询激活平台创建类型列表

请求参数: 无

响应格式:

{
  "code": 200,
  "message": "查询激活平台创建类型成功",
  "data": {
    "success": true,
    "total": 3,
    "list": [
      {
        "name": "Flow",
        "description": "Flow 创建"
      },
      {
        "name": "ProcessBuilder",
        "description": "Process Builder 创建"
      }
    ]
  }
}

7. 获取操作日志

接口: GET /salesforce/tooling/access-security/logs

功能: 查询访问和安全操作日志

请求参数:

参数名	类型	必填	说明
operationType	String	否	操作类型
metadataType	String	否	元数据类型
startTime	String	否	开始时间（yyyy-MM-dd HH:mm:ss）
endTime	String	否	结束时间（yyyy-MM-dd HH:mm:ss）
pageNum	Integer	否	页码（默认 1）
pageSize	Integer	否	每页大小（默认 10）

响应格式:

{
  "code": 200,
  "message": "查询操作日志成功",
  "data": {
    "total": 100,
    "pageNum": 1,
    "pageSize": 10,
    "list": [
      {
        "id": 1,
        "operationType": "get_access_methods",
        "metadataType": "AccessMethod",
        "metadataName": "OAuth",
        "status": "success",
        "operationTime": "2026-01-28 10:00:00",
        "userId": "user001"
      }
    ]
  }
}

实现要点

连接管理

使用 ToolingConnectionFactory 获取连接
固定使用 source ORG 类型的连接缓存
Session 过期时自动清除缓存并重新创建连接

异步日志记录

使用 CompletableFuture 异步记录日志
使用线程池管理异步任务
日志记录失败不影响主操作

异常处理

捕获 Salesforce 异常并转换为自定义异常
使用 ToolingAccessSecurityErrorCode 枚举定义错误码
记录异常信息到日志

SOQL 查询构建

使用 SoqlBuilder 构建查询语句
支持动态添加查询条件
优化查询性能

RESTful API 设计

遵循 RESTful API 设计规范
统一的响应格式
支持分页查询

技术约束

直接使用 tooling.jar 中的现有类（AccessMethod、AccessResourceType、APIAccessLevel、APIType、ActivationPlatformConnectorType、ActivationPlatformCreationType 等）
使用 datai-salesforce-auth 的 SessionManager 管理会话
使用 datai-salesforce-auth 的 ToolingConnectionFactory 获取连接，固定使用 getConnection("source")
优先使用 datai-salesforce-common 模块中的现有异常
提供 Service 层和 Controller 层（REST API）
不进行不必要的二次封装
固定使用 source ORG 类型的连接缓存
Session 过期时自动清除缓存并重新创建连接
所有操作必须记录到数据库
REST API 接口必须符合 RESTful 规范
错误码必须使用 ToolingAccessSecurityErrorCode 枚举定义
使用 SoqlBuilder 构建 SOQL 查询
查询结果必须支持分页

参考资料

需求文档：2026-01-28-004-06-访问和安全.md
决策记录：2026-01-28-004-06-ADR-访问和安全功能技术选型.md
数据库脚本：2026-01-28-004-06-访问和安全操作日志表.sql

16 KiB Raw Permalink Blame History Unescape Escape

设计文档

元数据

设计概述

架构设计

系统架构图

组件说明

数据流图

技术方案

连接管理方案

数据库日志记录方案

异常处理方案

SOQL 查询构建方案

RESTful API 设计方案

数据模型

Service 层数据模型

IToolingAccessSecurityService

Controller 层数据模型

ToolingAccessSecurityController

DTO 数据模型

AccessSecurityLogQueryRequest

VO 数据模型

AccessMethodVO

AccessResourceTypeVO

APIAccessLevelVO

APITypeVO

ActivationPlatformConnectorTypeVO

ActivationPlatformCreationTypeVO

ToolingAccessSecurityLogVO

Entity 数据模型

ToolingAccessSecurityLog

接口设计

REST API 接口

1. 查询访问方法

2. 查询访问资源类型

3. 查询 API 访问级别

4. 查询 API 类型

5. 查询激活平台连接器类型

6. 查询激活平台创建类型

7. 获取操作日志

实现要点

连接管理

异步日志记录

异常处理

SOQL 查询构建

RESTful API 设计

技术约束

参考资料

16 KiB

Raw Permalink Blame History