kris/datai

Fork 0

Kris 13c66c20dd 【feat】提交被忽略代码

2026-01-22 10:52:30 +08:00

9.8 KiB

Raw Permalink Blame History

Salesforce 错误码映射需求

元数据

需求编号：2026-01-21-003-07
父需求编号：2026-01-21-003
创建时间：2026-01-21
创建人：SSOT 架构师
状态：待开始
优先级：高

需求概述

建立完整的错误码映射枚举类，提供友好的错误提示。映射 Salesforce 错误码到系统错误码，提供友好的错误提示。支持错误级别（E=错误 W=警告 I=信息），支持是否可重试（Y=可重试 N=不可重试），支持建议重试次数，支持建议重试间隔（毫秒）。在 datai-salesforce-common 模块中生成枚举类去维护。

目标

错误码映射：建立完整的错误码映射枚举类
友好错误提示：提供友好的错误提示
错误级别：支持错误级别（E=错误 W=警告 I=信息）
可重试配置：支持是否可重试（Y=可重试 N=不可重试）
重试配置：支持建议重试次数、建议重试间隔（毫秒）
枚举类维护：在 datai-salesforce-common 模块中生成枚举类去维护

业务上下文

当前问题

缺乏错误码映射机制
用户无法理解 Salesforce 返回的错误信息
缺乏错误重试机制

业务场景

Salesforce 错误码映射
├─ 在 datai-salesforce-common 模块中生成枚举类
├─ 映射 Salesforce 错误码到系统错误码
├─ 提供友好的错误提示
├─ 支持错误级别（E=错误 W=警告 I=信息）
├─ 支持是否可重试（Y=可重试 N=不可重试）
├─ 支持建议重试次数
└─ 支持建议重试间隔（毫秒）

应用场景

错误处理：将 Salesforce 错误码映射为系统错误码，提供友好的错误提示
错误重试：根据错误码映射表中的配置决定是否重试及重试次数

功能需求

核心功能

功能1：错误码映射枚举类

描述：在 datai-salesforce-common 模块中生成错误码映射枚举类
验收标准：
1. 在 datai-salesforce-common 模块中生成错误码映射枚举类
2. 枚举类包含 Salesforce 错误码
3. 枚举类包含系统错误码
4. 枚举类包含系统错误信息（友好的错误提示）
5. 枚举类包含错误级别（E=错误 W=警告 I=信息）
6. 枚举类包含是否可重试（Y=可重试 N=不可重试）
7. 枚举类包含建议重试次数
8. 枚举类包含建议重试间隔（毫秒）
9. 枚举类包含错误描述
优先级：高
依赖关系：无

功能2：错误码映射

描述：映射 Salesforce 错误码到系统错误码，提供友好的错误提示
验收标准：
1. 根据枚举类映射 Salesforce 错误码到系统错误码
2. 提供 Salesforce 错误信息
3. 提供系统错误信息（友好的错误提示）
4. 支持错误级别（E=错误 W=警告 I=信息）
5. 支持错误描述
优先级：高
依赖关系：依赖错误码映射枚举类功能

功能3：错误重试机制

描述：根据错误码映射枚举类中的配置决定是否重试及重试次数
验收标准：
1. 支持是否可重试（Y=可重试 N=不可重试）
2. 支持建议重试次数
3. 支持建议重试间隔（毫秒）
4. 根据枚举类中的配置决定是否重试
5. 根据枚举类中的配置决定重试次数
6. 根据枚举类中的配置决定重试间隔
优先级：高
依赖关系：依赖错误码映射枚举类功能

功能4：错误码查询

描述：支持查询错误码映射
验收标准：
1. 支持按 Salesforce 错误码查询对应的系统错误码
2. 支持按系统错误码查询对应的 Salesforce 错误码
3. 返回完整的错误码映射信息
4. 错误码不存在时返回默认错误信息
优先级：高
依赖关系：依赖错误码映射枚举类功能

非功能需求

性能需求

查询时间：错误码查询响应时间 < 10ms
并发用户数：支持 100+ 并发用户

安全需求

访问控制：只有授权用户才能管理错误码映射

可用性需求

系统可用性：99.9%

可维护性需求

代码可读性：代码符合项目编码规范，注释完整
测试覆盖率：单元测试覆盖率 ≥ 80%

数据需求

数据模型

SalesforceErrorCode（Salesforce 错误码映射枚举类）

枚举类路径：datai-salesforce-common/src/main/java/exception/SalesforceErrorCode.java

枚举类字段：
├─ sfErrorCode (String) - Salesforce 错误码
├─ sfErrorMessage (String) - Salesforce 错误信息
├─ systemErrorCode (String) - 系统错误码
├─ systemErrorMessage (String) - 系统错误信息（友好的错误提示）
├─ errorLevel (ErrorLevel) - 错误级别（ERROR=错误 WARN=警告 INFO=信息）
├─ isRetryable (boolean) - 是否可重试（true=可重试 false=不可重试）
├─ retryCount (int) - 建议重试次数
├─ retryInterval (long) - 建议重试间隔（毫秒）
└─ description (String) - 错误描述

枚举类示例：
```java
public enum SalesforceErrorCode {
    INVALID_LOGIN_CREDENTIALS(
        "INVALID_LOGIN_CREDENTIALS",
        "Invalid username, password, security token; or user locked out.",
        "SF_AUTH_001",
        "登录失败：用户名、密码、安全令牌无效或用户被锁定",
        ErrorLevel.ERROR,
        false,
        0,
        0,
        "登录凭证无效"
    ),
    
    SESSION_EXPIRED(
        "SESSION_EXPIRED",
        "Session expired or invalid.",
        "SF_AUTH_002",
        "会话已过期或无效",
        ErrorLevel.ERROR,
        true,
        3,
        5000,
        "会话过期"
    ),
    
    RATE_LIMIT_EXCEEDED(
        "RATE_LIMIT_EXCEEDED",
        "Rate limit exceeded.",
        "SF_API_001",
        "API 调用频率超限",
        ErrorLevel.WARN,
        true,
        5,
        60000,
        "API 频率限制"
    );
    
    private final String sfErrorCode;
    private final String sfErrorMessage;
    private final String systemErrorCode;
    private final String systemErrorMessage;
    private final ErrorLevel errorLevel;
    private final boolean isRetryable;
    private final int retryCount;
    private final long retryInterval;
    private final String description;
    
    // 构造函数、getter 方法
    // 根据 Salesforce 错误码查找枚举的方法
    // 根据系统错误码查找枚举的方法
}

错误级别枚举类：

public enum ErrorLevel {
    ERROR("E", "错误"),
    WARN("W", "警告"),
    INFO("I", "信息");
    
    private final String code;
    private final String description;
    
    // 构造函数、getter 方法
}

数据存储需求

存储方式：Java 枚举类
维护位置：datai-salesforce-common 模块
更新方式：修改枚举类代码后重新编译部署

数据流转需求

错误码映射
  └─ 在 datai-salesforce-common 模块中维护枚举类
  └─ 枚举类包含 Salesforce 错误码、系统错误码、错误级别、重试配置
  └─ 提供友好的错误提示

错误处理
  └─ 捕获 Salesforce 错误
  └─ 根据枚举类查找对应的系统错误码
  └─ 返回友好的错误提示
  └─ 根据枚举类中的配置决定是否重试
  └─ 根据枚举类中的配置决定重试次数和重试间隔

业务规则

错误码映射：所有 Salesforce 错误码必须在枚举类中映射到系统错误码，提供友好的错误提示
错误重试机制：根据枚举类中的配置决定是否重试及重试次数
错误级别：支持错误级别（ERROR=错误 WARN=警告 INFO=信息）
可重试配置：支持是否可重试（true=可重试 false=不可重试）
重试配置：支持建议重试次数、建议重试间隔（毫秒）
枚举类维护：在 datai-salesforce-common 模块中维护枚举类

接口需求

错误码映射查询接口

根据 Salesforce 错误码查询系统错误码
- 接口路径：GET /api/salesforce/error-code-mapping/sf/{sfErrorCode}
- 请求参数：sfErrorCode（Salesforce 错误码）
- 响应：系统错误码映射信息
根据系统错误码查询 Salesforce 错误码
- 接口路径：GET /api/salesforce/error-code-mapping/system/{systemErrorCode}
- 请求参数：systemErrorCode（系统错误码）
- 响应：Salesforce 错误码映射信息
获取所有错误码映射
- 接口路径：GET /api/salesforce/error-code-mapping/all
- 响应：所有错误码映射列表

错误处理工具类接口

根据 Salesforce 错误码获取系统错误信息
- 方法路径：SalesforceErrorCode.getBySfErrorCode(String sfErrorCode)
- 返回值：SalesforceErrorCode 枚举实例
- 说明：根据 Salesforce 错误码查找对应的枚举实例
根据系统错误码获取 Salesforce 错误信息
- 方法路径：SalesforceErrorCode.getBySystemErrorCode(String systemErrorCode)
- 返回值：SalesforceErrorCode 枚举实例
- 说明：根据系统错误码查找对应的枚举实例
判断错误是否可重试
- 方法路径：SalesforceErrorCode.isRetryable(String sfErrorCode)
- 返回值：boolean（true=可重试 false=不可重试）
- 说明：根据 Salesforce 错误码判断是否可重试
获取重试次数
- 方法路径：SalesforceErrorCode.getRetryCount(String sfErrorCode)
- 返回值：int（建议重试次数）
- 说明：根据 Salesforce 错误码获取建议重试次数
获取重试间隔
- 方法路径：SalesforceErrorCode.getRetryInterval(String sfErrorCode)
- 返回值：long（建议重试间隔，毫秒）
- 说明：根据 Salesforce 错误码获取建议重试间隔

依赖关系

依赖 datai-salesforce-common 模块
依赖 datai-system 模块的基础功能

9.8 KiB Raw Permalink Blame History Unescape Escape