kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
develop
datai/datai-scenes/datai-scene-salesforce/docs/design/2026-02-03-002-05-Flow覆盖率-设计.md

20 KiB
Raw Permalink Blame History

设计文档 - Flow 覆盖率功能

元数据

  • 需求编号：002-05
  • 创建时间：2026-02-03
  • 创建人：AI Assistant
  • 状态：进行中

设计概述

本设计文档描述 Salesforce Apex Flow 覆盖率功能的实现方案。Flow 覆盖率功能提供 Flow 覆盖率结果查询、Flow 覆盖率警告处理、Flow 覆盖率统计等功能。本功能与 002-03 测试执行功能紧密关联，Flow 覆盖率数据由测试执行功能生成并存储到数据库，本功能提供查询和统计能力。

架构设计

系统架构

┌─────────────────────────────────────────────────────────────┐
│                    前端应用层 (Vue 3)                        │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                  Controller 层                              │
│         ApexFlowCoverageController.java                     │
│  - 查询 Flow 覆盖率列表                                      │
│  - 查询 Flow 覆盖率详情                                      │
│  - 查询 Flow 覆盖率警告                                      │
│  - 查询总体 Flow 覆盖率                                      │
│  - 按类型统计 Flow 覆盖率                                    │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                   Service 层                                │
│         IApexFlowCoverageService.java                       │
│         ApexFlowCoverageServiceImpl.java                    │
│  - 查询 Flow 覆盖率                                          │
│  - 计算总体覆盖率                                            │
│  - 按类型统计覆盖率                                          │
│  - 数据转换和格式化                                          │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                   Mapper 层                                 │
│    DataiApexFlowCoverageMapper.java                         │
│    DataiApexFlowCoverageWarningMapper.java                  │
│  - 数据库访问                                                │
│  - SQL 映射                                                  │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                   Entity 层                                 │
│    DataiApexFlowCoverage.java                               │
│    DataiApexFlowCoverageWarning.java                        │
│  - 数据模型                                                  │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                   数据库层                                  │
│    datai_apex_flow_coverage 表                              │
│    datai_apex_flow_coverage_warning 表                      │
└─────────────────────────────────────────────────────────────┘

模块架构

本功能属于 datai-salesforce-apex 模块，与 002-03 测试执行功能共享部分数据库表。

模块结构：

datai-salesforce-apex/
├── src/main/java/com/datai/apex/
│   ├── controller/
│   │   └── ApexFlowCoverageController.java      # 控制器
│   ├── service/
│   │   ├── IApexFlowCoverageService.java        # 服务接口
│   │   └── impl/
│   │       └── ApexFlowCoverageServiceImpl.java # 服务实现
│   ├── mapper/
│   │   ├── DataiApexFlowCoverageMapper.java     # Flow 覆盖率 Mapper
│   │   └── DataiApexFlowCoverageWarningMapper.java # Flow 覆盖率警告 Mapper
│   ├── domain/
│   │   ├── DataiApexFlowCoverage.java           # Flow 覆盖率实体
│   │   └── DataiApexFlowCoverageWarning.java    # Flow 覆盖率警告实体
│   └── model/
│       ├── dto/
│       │   ├── QueryFlowCoverageDto.java        # 查询 Flow 覆盖率 DTO
│       │   └── QueryFlowCoverageSummaryDto.java # 查询 Flow 覆盖率统计 DTO
│       └── vo/
│           ├── FlowCoverageResultVo.java        # Flow 覆盖率结果 VO
│           ├── FlowCoverageWarningVo.java       # Flow 覆盖率警告 VO
│           ├── FlowCoverageSummaryVo.java       # Flow 覆盖率统计 VO
│           ├── FlowTypeSummaryVo.java           # 按类型统计 VO
│           └── FlowCoverageSummaryResponseVo.java # 统计响应 VO

数据流

1. 用户请求 -> Controller -> Service -> Mapper -> 数据库
2. 数据库 -> Mapper -> Service -> Controller -> 用户响应
3. 覆盖率计算在 Service 层进行
4. 覆盖率范围筛选在内存中进行

技术方案

技术选型

技术组件 版本/说明 选择理由
Spring Boot 2.7.x 项目基础框架
MyBatis 3.5.x 数据库访问，使用标准 MyBatis
PageHelper 1.4.x 分页查询
Lombok 1.18.x 简化代码
Salesforce Apex API 65.0 通过 apex.jar 调用

核心算法

Flow 覆盖率计算

coveragePercent = (numElementsCovered / numElements) * 100

总体 Flow 覆盖率计算

totalCoverage = (totalCovered / totalElements) * 100

按类型统计覆盖率

typeCoverage = (typeCovered / typeElements) * 100

计算规则

  • 保留两位小数（四舍五入）
  • 除零保护：当总元素数为 0 时，返回 0.0

集成方案

与 002-03 测试执行功能的集成

  • 复用 datai_apex_test_result 表的 id 字段作为外键
  • Flow 覆盖率数据由测试执行功能生成并存储
  • 本功能只提供查询和统计能力

Salesforce API 集成

  • 使用 apex.jar 中的 FlowCoverageResult 类
  • 数据通过测试执行时获取，本功能不涉及直接调用 Salesforce API

数据模型

数据库表设计

datai_apex_flow_coverage（Flow 覆盖率表）

字段名 类型 长度 是否必填 默认值 说明
id BIGINT - 是 自增 主键
test_result_id BIGINT - 是 - 测试结果 ID（外键）
name VARCHAR 255 是 - Flow 名称
type VARCHAR 50 是 - Flow 类型
namespace VARCHAR 255 否 NULL 命名空间
num_elements INT - 是 0 总元素数量
num_elements_covered INT - 是 0 覆盖的元素数量
num_elements_not_covered INT - 是 0 未覆盖的元素数量
coverage_percent DOUBLE - 是 0.0 覆盖率百分比
create_time DATETIME - 是 CURRENT_TIMESTAMP 创建时间
dept_id BIGINT - 是 - 部门 ID（标准字段）
create_by VARCHAR 64 是 - 创建者（标准字段）
update_by VARCHAR 64 是 - 更新者（标准字段）

索引设计：

  • 主键索引：id
  • 外键索引：test_result_id
  • 查询索引：name、type、namespace
  • 复合索引：test_result_id + type

datai_apex_flow_coverage_warning（Flow 覆盖率警告表）

字段名 类型 长度 是否必填 默认值 说明
id BIGINT - 是 自增 主键
test_result_id BIGINT - 是 - 测试结果 ID（外键）
name VARCHAR 255 是 - Flow 名称
type VARCHAR 50 是 - Flow 类型
namespace VARCHAR 255 否 NULL 命名空间
message TEXT - 是 - 警告消息
create_time DATETIME - 是 CURRENT_TIMESTAMP 创建时间
dept_id BIGINT - 是 - 部门 ID（标准字段）
create_by VARCHAR 64 是 - 创建者（标准字段）
update_by VARCHAR 64 是 - 更新者（标准字段）

索引设计：

  • 主键索引：id
  • 外键索引：test_result_id
  • 查询索引：name、type

实体类设计

DataiApexFlowCoverage.java

@Data
@EqualsAndHashCode(callSuper = true)
public class DataiApexFlowCoverage extends BaseEntity {
    private Long id;
    private Long testResultId;
    private String name;
    private String type;
    private String namespace;
    private Integer numElements;
    private Integer numElementsCovered;
    private Integer numElementsNotCovered;
    private Double coveragePercent;
    private Date createTime;
}

DataiApexFlowCoverageWarning.java

@Data
@EqualsAndHashCode(callSuper = true)
public class DataiApexFlowCoverageWarning extends BaseEntity {
    private Long id;
    private Long testResultId;
    private String name;
    private String type;
    private String namespace;
    private String message;
    private Date createTime;
}

DTO 设计

QueryFlowCoverageDto.java

@Data
public class QueryFlowCoverageDto {
    private Long testResultId;
    private String flowId;
    private String flowName;
    private String namespace;
    private String type;
    private Double minCoverage;
    private Double maxCoverage;
}

QueryFlowCoverageSummaryDto.java

@Data
public class QueryFlowCoverageSummaryDto {
    private Long testResultId;
}

VO 设计

FlowCoverageResultVo.java

@Data
public class FlowCoverageResultVo {
    private Long id;
    private Long testResultId;
    private String name;
    private String type;
    private String namespace;
    private Integer numElements;
    private Integer numElementsCovered;
    private Integer numElementsNotCovered;
    private Double coveragePercent;
    private Date createTime;
}

FlowCoverageWarningVo.java

@Data
public class FlowCoverageWarningVo {
    private Long id;
    private Long testResultId;
    private String name;
    private String type;
    private String namespace;
    private String message;
    private Date createTime;
}

FlowCoverageSummaryVo.java

@Data
public class FlowCoverageSummaryVo {
    private Long testResultId;
    private Double totalCoverage;
    private Integer totalFlows;
    private Integer totalElements;
    private Integer totalCovered;
    private Integer totalNotCovered;
    private Double recordTriggeredFlowCoverage;
    private Double autolaunchedFlowCoverage;
    private Date testTime;
}

FlowTypeSummaryVo.java

@Data
public class FlowTypeSummaryVo {
    private String type;
    private Integer count;
    private Integer totalElements;
    private Integer notCovered;
    private Double coveragePercent;
}

FlowCoverageSummaryResponseVo.java

@Data
public class FlowCoverageSummaryResponseVo {
    private Long testResultId;
    private FlowTypeSummaryVo recordTriggeredFlowSummary;
    private FlowTypeSummaryVo autolaunchedFlowSummary;
    private FlowTypeSummaryVo overallSummary;
}

接口设计

RESTful API 设计

1. 查询 Flow 覆盖率列表

  • 接口名称：查询 Flow 覆盖率列表
  • 请求方式：GET
  • 请求路径：/api/apex/flow-coverage
  • 功能描述：查询 Flow 覆盖率列表，支持多条件筛选、分页查询、覆盖率范围筛选
  • 请求参数：
    参数名 类型 必填 说明
    testResultId Long 否 测试结果 ID
    flowId String 否 Flow ID
    flowName String 否 Flow 名称，支持模糊查询
    namespace String 否 命名空间，支持模糊查询
    type String 否 Flow 类型
    minCoverage Double 否 最小覆盖率（0-100）
    maxCoverage Double 否 最大覆盖率（0-100）
    pageNum Integer 否 页码，默认 1
    pageSize Integer 否 每页大小，默认 10
    orderByColumn String 否 排序字段，可选值：createTime、coveragePercent
    isAsc String 否 是否升序，可选值：asc、desc，默认 desc
  • 响应参数：
    参数名 类型 说明
    code Integer 状态码（200 成功，其他失败）
    msg String 提示信息
    rows Array Flow 覆盖率列表
    total Long 总记录数
  • 权限要求：apex:flow:coverage:query

2. 查询 Flow 覆盖率详情

  • 接口名称：查询 Flow 覆盖率详情
  • 请求方式：GET
  • 请求路径：/api/apex/flow-coverage/{id}
  • 功能描述：根据 ID 查询单条 Flow 覆盖率记录的详细信息
  • 路径参数：
    参数名 类型 必填 说明
    id Long 是 覆盖率记录 ID
  • 响应参数：
    参数名 类型 说明
    code Integer 状态码（200 成功，其他失败）
    msg String 提示信息
    data Object Flow 覆盖率详情
  • 权限要求：apex:flow:coverage:query

3. 查询 Flow 覆盖率警告

  • 接口名称：查询 Flow 覆盖率警告
  • 请求方式：GET
  • 请求路径：/api/apex/flow-coverage/warnings
  • 功能描述：查询 Flow 覆盖率警告列表
  • 请求参数：
    参数名 类型 必填 说明
    testResultId Long 否 测试结果 ID
    flowName String 否 Flow 名称，支持模糊查询
    pageNum Integer 否 页码，默认 1
    pageSize Integer 否 每页大小，默认 10
  • 响应参数：
    参数名 类型 说明
    code Integer 状态码（200 成功，其他失败）
    msg String 提示信息
    rows Array Flow 覆盖率警告列表
    total Long 总记录数
  • 权限要求：apex:flow:coverage:query

4. 查询总体 Flow 覆盖率

  • 接口名称：查询总体 Flow 覆盖率
  • 请求方式：GET
  • 请求路径：/api/apex/flow-coverage/total
  • 功能描述：查询总体 Flow 覆盖率统计，包括总体覆盖率、Flow 数量、总元素数等
  • 请求参数：
    参数名 类型 必填 说明
    testResultId Long 否 测试结果 ID；不传则统计所有数据
  • 响应参数：
    参数名 类型 说明
    code Integer 状态码（200 成功，其他失败）
    msg String 提示信息
    data Object 总体覆盖率统计
    data.testResultId Long 测试结果 ID
    data.totalCoverage Double 总体覆盖率（0-100）
    data.totalFlows Integer 总 Flow 数
    data.totalElements Integer 总元素数
    data.totalCovered Integer 已覆盖元素数
    data.totalNotCovered Integer 未覆盖元素数
    data.recordTriggeredFlowCoverage Double RecordTriggeredFlow 覆盖率
    data.autolaunchedFlowCoverage Double AutolaunchedFlow 覆盖率
    data.testTime String 测试时间
  • 权限要求：apex:flow:coverage:query

5. 按类型统计 Flow 覆盖率

  • 接口名称：按类型统计 Flow 覆盖率
  • 请求方式：GET
  • 请求路径：/api/apex/flow-coverage/summary
  • 功能描述：按 Flow 类型（RecordTriggeredFlow、AutolaunchedFlow 等）分别统计覆盖率
  • 请求参数：
    参数名 类型 必填 说明
    testResultId Long 否 测试结果 ID；不传则统计所有数据
  • 响应参数：
    参数名 类型 说明
    code Integer 状态码（200 成功，其他失败）
    msg String 提示信息
    data Object 按类型统计结果
    data.testResultId Long 测试结果 ID
    data.recordTriggeredFlowSummary Object RecordTriggeredFlow 统计
    data.autolaunchedFlowSummary Object AutolaunchedFlow 统计
    data.overallSummary Object 总体统计
  • 权限要求：apex:flow:coverage:query

接口权限设计

所有接口使用统一的权限标识：

  • @PreAuthorize("@ss.hasPermi('apex:flow:coverage:query')")

实现要点

关键实现逻辑

1. 查询 Flow 覆盖率列表

  1. 构建查询条件（testResultId、name、namespace、type）
  2. 使用 PageHelper 进行分页查询
  3. 查询数据库获取 Flow 覆盖率列表
  4. 转换为 VO 对象
  5. 在内存中进行覆盖率范围筛选（minCoverage、maxCoverage）
  6. 返回分页结果

2. 查询总体 Flow 覆盖率

  1. 根据 testResultId 查询所有 Flow 覆盖率数据
  2. 统计总 Flow 数、总元素数、已覆盖元素数、未覆盖元素数
  3. 计算总体覆盖率
  4. 按类型（RecordTriggeredFlow、AutolaunchedFlow）分别统计
  5. 返回统计结果

3. 按类型统计 Flow 覆盖率

  1. 根据 testResultId 查询所有 Flow 覆盖率数据
  2. 按 type 字段分组
  3. 对每个分组统计数量、总元素数、未覆盖元素数
  4. 计算每种类型的覆盖率
  5. 返回分组统计结果

异常处理

异常类型

  1. SalesforceAuthException：认证失败、会话过期
  2. SalesforceOperationException：操作失败、数据访问失败
  3. DataAccessException：数据库访问异常

异常处理策略

  1. 所有 Service 方法声明 throws SalesforceOperationException
  2. 使用 try-catch 块捕获异常
  3. 记录详细的错误日志
  4. 返回友好的错误消息（中文）

性能优化

1. 数据库索引优化

  • 为常用查询字段创建索引（testResultId、name、type）
  • 创建复合索引（testResultId + type）

2. 分页查询优化

  • 使用 PageHelper 进行物理分页
  • 避免查询大量数据

3. 内存筛选优化

  • 覆盖率范围筛选在内存中进行
  • 使用 Java 8 Stream API 进行高效筛选

安全设计

1. 权限控制

  • 所有接口需要 apex:flow:coverage:query 权限
  • 使用 @PreAuthorize 注解进行权限控制

2. 数据安全

  • 不返回敏感信息
  • 参数校验防止 SQL 注入

相关文档