kris/datai

Fork 0

3111404962 34dcb2811c feat：Tooling模块初步

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

22 KiB

Raw Permalink Blame History

设计文档

元数据

需求编号：004
子需求编号：004-07
子需求名称：高级功能
阶段：阶段 2：方案设计
创建时间：2026-02-03
创建人：AI Assistant
状态：已完成
相关文档：

设计概述

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

连接管理复用：复用子需求 004-01 实现的 ToolingConnectionFactory，通过工厂模式获取 ToolingConnection
数据库日志记录：所有高级功能操作都记录到数据库，支持操作审计和故障排查
异步日志记录：使用异步方式记录日志，避免影响主操作性能
异常处理机制：将 Salesforce 异常转换为自定义异常，提供友好的错误信息
SOQL 查询构建：使用 SoqlBuilder 构建 SOQL 查询，提高代码可读性和可维护性
RESTful API 设计：提供标准的 REST API 接口，包括查询累积结果操作符、查询累积结果条件输入类型、查询聚合表达式结果列元数据、查询聚合查询结果列元数据、查询高级账户预测显示组类型、查询高级账户预测度量类型、查询高级账户预测公式类型、查询高级账户预测计算方法、查询激活 Flow 类型、查询激活功能类型、查询激活应用类型、查询 ACP 状态、获取操作日志等功能
错误码枚举：使用 ToolingAdvancedFeaturesErrorCode 枚举定义错误码

架构设计

系统架构图

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

组件说明

组件	说明
ToolingAdvancedFeaturesController	REST API 控制器，处理 HTTP 请求
IToolingAdvancedFeaturesService	服务接口，定义高级功能
ToolingAdvancedFeaturesServiceImpl	服务实现，提供高级功能
ToolingConnectionFactory	连接工厂，获取 ToolingConnection
SessionManager	会话管理器，管理用户会话
ToolingAdvancedFeaturesLogMapper	数据访问对象，操作日志表
datai_tooling_advanced_features_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 /accumulate-result-operators
    Controller->>Service: getAccumulateResultOperators()
    Service->>Factory: getConnection("source")
    Factory->>Session: getSession()
    Session-->>Factory: Session
    Factory-->>Service: ToolingConnection
    Service->>SF: query(AccumulateResultOperator)
    SF-->>Service: List<AccumulateResultOperator>
    Service->>DB: insert(log)
    Service-->>Controller: List<AccumulateResultOperator>
    Controller-->>Client: JSON Response

技术方案

连接管理方案

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

实现要点：

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

优势：

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

数据库日志记录方案

方案描述：所有高级功能操作都记录到数据库，支持操作审计和故障排查。

实现要点：

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

优势：

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

异步日志记录方案

方案描述：使用 CompletableFuture 异步记录日志，避免影响主操作性能。

实现要点：

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

优势：

不影响主操作性能
日志记录失败不影响主操作

异常处理方案

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

实现要点：

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

优势：

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

SOQL 查询构建方案

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

实现要点：

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

优势：

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

RESTful API 设计方案

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

实现要点：

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

优势：

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

数据模型

Service 层数据模型

IToolingAdvancedFeaturesService

public interface IToolingAdvancedFeaturesService {
    
    List<AccumulateResultOperatorVO> getAccumulateResultOperators();
    
    List<AccumulateResultCondInputTypeVO> getAccumulateResultCondInputTypes();
    
    List<AggregateExpressionResultColumnMetadataVO> getAggregateExpressionResultColumnMetadatas();
    
    List<AggregateQueryResultColumnMetadataVO> getAggregateQueryResultColumnMetadatas();
    
    List<AdvAcctFrcstDisplayGroupTypeVO> getAdvAcctFrcstDisplayGroupTypes();
    
    List<AdvAcctFcstMeasureTypeVO> getAdvAcctFcstMeasureTypes();
    
    List<AdvAcctFcstFormulaTypeVO> getAdvAcctFcstFormulaTypes();
    
    List<AdvAcctFcstComputationMethodVO> getAdvAcctFcstComputationMethods();
    
    List<ActivationFlowTypeVO> getActivationFlowTypes();
    
    List<ActivationFeatureTypeVO> getActivationFeatureTypes();
    
    List<ActivationAppTypeVO> getActivationAppTypes();
    
    List<ACPStatusVO> getACPStatuses();
    
    PageInfo<ToolingAdvancedFeaturesLogVO> getOperationLogs(AdvancedFeaturesLogQueryRequest request);
}

Controller 层数据模型

ToolingAdvancedFeaturesController

@RestController
@RequestMapping("/salesforce/tooling/advanced-features")
public class ToolingAdvancedFeaturesController {
    
    @GetMapping("/accumulate-result-operators")
    public AjaxResult getAccumulateResultOperators();
    
    @GetMapping("/accumulate-result-cond-input-types")
    public AjaxResult getAccumulateResultCondInputTypes();
    
    @GetMapping("/aggregate-expression-result-column-metadatas")
    public AjaxResult getAggregateExpressionResultColumnMetadatas();
    
    @GetMapping("/aggregate-query-result-column-metadatas")
    public AjaxResult getAggregateQueryResultColumnMetadatas();
    
    @GetMapping("/adv-acct-frcst-display-group-types")
    public AjaxResult getAdvAcctFrcstDisplayGroupTypes();
    
    @GetMapping("/adv-acct-fcst-measure-types")
    public AjaxResult getAdvAcctFcstMeasureTypes();
    
    @GetMapping("/adv-acct-fcst-formula-types")
    public AjaxResult getAdvAcctFcstFormulaTypes();
    
    @GetMapping("/adv-acct-fcst-computation-methods")
    public AjaxResult getAdvAcctFcstComputationMethods();
    
    @GetMapping("/activation-flow-types")
    public AjaxResult getActivationFlowTypes();
    
    @GetMapping("/activation-feature-types")
    public AjaxResult getActivationFeatureTypes();
    
    @GetMapping("/activation-app-types")
    public AjaxResult getActivationAppTypes();
    
    @GetMapping("/acp-statuses")
    public AjaxResult getACPStatuses();
    
    @GetMapping("/logs")
    public TableDataInfo getOperationLogs(AdvancedFeaturesLogQueryRequest request);
}

DTO 数据模型

AdvancedFeaturesLogQueryRequest

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

VO 数据模型

AccumulateResultOperatorVO

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

AccumulateResultCondInputTypeVO

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

AggregateExpressionResultColumnMetadataVO

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

AggregateQueryResultColumnMetadataVO

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

AdvAcctFrcstDisplayGroupTypeVO

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

AdvAcctFcstMeasureTypeVO

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

AdvAcctFcstFormulaTypeVO

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

AdvAcctFcstComputationMethodVO

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

ActivationFlowTypeVO

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

ActivationFeatureTypeVO

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

ActivationAppTypeVO

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

ACPStatusVO

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

ToolingAdvancedFeaturesLogVO

public class ToolingAdvancedFeaturesLogVO {
    
    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 数据模型

ToolingAdvancedFeaturesLog

@Data
@TableName("datai_tooling_advanced_features_log")
public class ToolingAdvancedFeaturesLog {
    
    @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/advanced-features/accumulate-result-operators

功能: 查询累积结果操作符列表

请求参数: 无

响应格式:

{
  "code": 200,
  "message": "查询累积结果操作符成功",
  "data": {
    "success": true,
    "total": 10,
    "list": [
      {
        "name": "Sum",
        "description": "求和"
      },
      {
        "name": "Average",
        "description": "平均值"
      }
    ]
  }
}

2. 查询累积结果条件输入类型

接口: GET /salesforce/tooling/advanced-features/accumulate-result-cond-input-types

功能: 查询累积结果条件输入类型列表

请求参数: 无

响应格式:

{
  "code": 200,
  "message": "查询累积结果条件输入类型成功",
  "data": {
    "success": true,
    "total": 5,
    "list": [
      {
        "name": "Value",
        "description": "值"
      },
      {
        "name": "Expression",
        "description": "表达式"
      }
    ]
  }
}

3. 查询聚合表达式结果列元数据

接口: GET /salesforce/tooling/advanced-features/aggregate-expression-result-column-metadatas

功能: 查询聚合表达式结果列元数据列表

请求参数: 无

响应格式:

{
  "code": 200,
  "message": "查询聚合表达式结果列元数据成功",
  "data": {
    "success": true,
    "total": 8,
    "list": [
      {
        "name": "Sum",
        "description": "求和列"
      },
      {
        "name": "Count",
        "description": "计数列"
      }
    ]
  }
}

4. 查询聚合查询结果列元数据

接口: GET /salesforce/tooling/advanced-features/aggregate-query-result-column-metadatas

功能: 查询聚合查询结果列元数据列表

请求参数: 无

响应格式:

{
  "code": 200,
  "message": "查询聚合查询结果列元数据成功",
  "data": {
    "success": true,
    "total": 8,
    "list": [
      {
        "name": "Sum",
        "description": "求和列"
      },
      {
        "name": "Count",
        "description": "计数列"
      }
    ]
  }
}

5. 查询高级账户预测显示组类型

接口: GET /salesforce/tooling/advanced-features/adv-acct-frcst-display-group-types

功能: 查询高级账户预测显示组类型列表

请求参数: 无

响应格式:

{
  "code": 200,
  "message": "查询高级账户预测显示组类型成功",
  "data": {
    "success": true,
    "total": 5,
    "list": [
      {
        "name": "Opportunity",
        "description": "机会"
      },
      {
        "name": "Account",
        "description": "账户"
      }
    ]
  }
}

6. 查询高级账户预测度量类型

接口: GET /salesforce/tooling/advanced-features/adv-acct-fcst-measure-types

功能: 查询高级账户预测度量类型列表

请求参数: 无

响应格式:

{
  "code": 200,
  "message": "查询高级账户预测度量类型成功",
  "data": {
    "success": true,
    "total": 10,
    "list": [
      {
        "name": "Revenue",
        "description": "收入"
      },
      {
        "name": "Quantity",
        "description": "数量"
      }
    ]
  }
}

7. 查询高级账户预测公式类型

接口: GET /salesforce/tooling/advanced-features/adv-acct-fcst-formula-types

功能: 查询高级账户预测公式类型列表

请求参数: 无

响应格式:

{
  "code": 200,
  "message": "查询高级账户预测公式类型成功",
  "data": {
    "success": true,
    "total": 8,
    "list": [
      {
        "name": "Revenue",
        "description": "收入公式"
      },
      {
        "name": "Quantity",
        "description": "数量公式"
      }
    ]
  }
}

8. 查询高级账户预测计算方法

接口: GET /salesforce/tooling/advanced-features/adv-acct-fcst-computation-methods

功能: 查询高级账户预测计算方法列表

请求参数: 无

响应格式:

{
  "code": 200,
  "message": "查询高级账户预测计算方法成功",
  "data": {
    "success": true,
    "total": 5,
    "list": [
      {
        "name": "Standard",
        "description": "标准计算"
      },
      {
        "name": "Custom",
        "description": "自定义计算"
      }
    ]
  }
}

9. 查询激活 Flow 类型

接口: GET /salesforce/tooling/advanced-features/activation-flow-types

功能: 查询激活 Flow 类型列表

请求参数: 无

响应格式:

{
  "code": 200,
  "message": "查询激活 Flow 类型成功",
  "data": {
    "success": true,
    "total": 5,
    "list": [
      {
        "name": "Flow",
        "description": "Flow"
      },
      {
        "name": "Process",
        "description": "Process"
      }
    ]
  }
}

10. 查询激活功能类型

接口: GET /salesforce/tooling/advanced-features/activation-feature-types

功能: 查询激活功能类型列表

请求参数: 无

响应格式:

{
  "code": 200,
  "message": "查询激活功能类型成功",
  "data": {
    "success": true,
    "total": 8,
    "list": [
      {
        "name": "Flow",
        "description": "Flow 功能"
      },
      {
        "name": "Process",
        "description": "Process 功能"
      }
    ]
  }
}

11. 查询激活应用类型

接口: GET /salesforce/tooling/advanced-features/activation-app-types

功能: 查询激活应用类型列表

请求参数: 无

响应格式:

{
  "code": 200,
  "message": "查询激活应用类型成功",
  "data": {
    "success": true,
    "total": 3,
    "list": [
      {
        "name": "Flow",
        "description": "Flow 应用"
      },
      {
        "name": "Process",
        "description": "Process 应用"
      }
    ]
  }
}

12. 查询 ACP 状态

接口: GET /salesforce/tooling/advanced-features/acp-statuses

功能: 查询 ACP 状态列表

请求参数: 无

响应格式:

{
  "code": 200,
  "message": "查询 ACP 状态成功",
  "data": {
    "success": true,
    "total": 5,
    "list": [
      {
        "name": "Active",
        "description": "激活"
      },
      {
        "name": "Inactive",
        "description": "未激活"
      }
    ]
  }
}

13. 获取操作日志

接口: GET /salesforce/tooling/advanced-features/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_accumulate_result_operators",
        "metadataType": "AccumulateResultOperator",
        "metadataName": "Sum",
        "status": "success",
        "operationTime": "2026-02-03 10:00:00",
        "userId": "user001"
      }
    ]
  }
}

实现要点

连接管理

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

异步日志记录

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

异常处理

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

SOQL 查询构建

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

RESTful API 设计

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

技术约束

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

参考资料

需求文档：2026-01-28-004-07-高级功能.md

22 KiB Raw Permalink Blame History Unescape Escape

设计文档

元数据

设计概述

架构设计

系统架构图

组件说明

数据流图

技术方案

连接管理方案

数据库日志记录方案

异步日志记录方案

异常处理方案

SOQL 查询构建方案

RESTful API 设计方案

数据模型

Service 层数据模型

IToolingAdvancedFeaturesService

Controller 层数据模型

ToolingAdvancedFeaturesController

DTO 数据模型

AdvancedFeaturesLogQueryRequest

VO 数据模型

AccumulateResultOperatorVO

AccumulateResultCondInputTypeVO

AggregateExpressionResultColumnMetadataVO

AggregateQueryResultColumnMetadataVO

AdvAcctFrcstDisplayGroupTypeVO

AdvAcctFcstMeasureTypeVO

AdvAcctFcstFormulaTypeVO

AdvAcctFcstComputationMethodVO

ActivationFlowTypeVO

ActivationFeatureTypeVO

ActivationAppTypeVO

ACPStatusVO

ToolingAdvancedFeaturesLogVO

Entity 数据模型

ToolingAdvancedFeaturesLog

接口设计

REST API 接口

1. 查询累积结果操作符

2. 查询累积结果条件输入类型

3. 查询聚合表达式结果列元数据

4. 查询聚合查询结果列元数据

5. 查询高级账户预测显示组类型

6. 查询高级账户预测度量类型

7. 查询高级账户预测公式类型

8. 查询高级账户预测计算方法

9. 查询激活 Flow 类型

10. 查询激活功能类型

11. 查询激活应用类型

12. 查询 ACP 状态

13. 获取操作日志

实现要点

连接管理

异步日志记录

异常处理

SOQL 查询构建

RESTful API 设计

技术约束

参考资料

22 KiB

Raw Permalink Blame History