datai/docs/requirements/2026-01-21-003-07-salesforce-error-code-mapping.md

# Salesforce 错误码映射需求

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

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

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

## 业务上下文

### 当前问题
- 缺乏错误码映射机制
- 用户无法理解 Salesforce 返回的错误信息
- 缺乏错误重试机制

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

### 应用场景
1. **错误处理**：将 Salesforce 错误码映射为系统错误码，提供友好的错误提示
2. **错误重试**：根据错误码映射表中的配置决定是否重试及重试次数

## 功能需求

### 核心功能

#### 功能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 错误码查找枚举的方法
    // 根据系统错误码查找枚举的方法
}
```

错误级别枚举类：
```java
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 错误
  └─ 根据枚举类查找对应的系统错误码
  └─ 返回友好的错误提示
  └─ 根据枚举类中的配置决定是否重试
  └─ 根据枚举类中的配置决定重试次数和重试间隔
```

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

## 接口需求

### 错误码映射查询接口
1. **根据 Salesforce 错误码查询系统错误码**
   - 接口路径：GET /api/salesforce/error-code-mapping/sf/{sfErrorCode}
   - 请求参数：sfErrorCode（Salesforce 错误码）
   - 响应：系统错误码映射信息

2. **根据系统错误码查询 Salesforce 错误码**
   - 接口路径：GET /api/salesforce/error-code-mapping/system/{systemErrorCode}
   - 请求参数：systemErrorCode（系统错误码）
   - 响应：Salesforce 错误码映射信息

3. **获取所有错误码映射**
   - 接口路径：GET /api/salesforce/error-code-mapping/all
   - 响应：所有错误码映射列表

### 错误处理工具类接口
4. **根据 Salesforce 错误码获取系统错误信息**
   - 方法路径：SalesforceErrorCode.getBySfErrorCode(String sfErrorCode)
   - 返回值：SalesforceErrorCode 枚举实例
   - 说明：根据 Salesforce 错误码查找对应的枚举实例

5. **根据系统错误码获取 Salesforce 错误信息**
   - 方法路径：SalesforceErrorCode.getBySystemErrorCode(String systemErrorCode)
   - 返回值：SalesforceErrorCode 枚举实例
   - 说明：根据系统错误码查找对应的枚举实例

6. **判断错误是否可重试**
   - 方法路径：SalesforceErrorCode.isRetryable(String sfErrorCode)
   - 返回值：boolean（true=可重试 false=不可重试）
   - 说明：根据 Salesforce 错误码判断是否可重试

7. **获取重试次数**
   - 方法路径：SalesforceErrorCode.getRetryCount(String sfErrorCode)
   - 返回值：int（建议重试次数）
   - 说明：根据 Salesforce 错误码获取建议重试次数

8. **获取重试间隔**
   - 方法路径：SalesforceErrorCode.getRetryInterval(String sfErrorCode)
   - 返回值：long（建议重试间隔，毫秒）
   - 说明：根据 Salesforce 错误码获取建议重试间隔

## 依赖关系
- 依赖 `datai-salesforce-common` 模块
- 依赖 `datai-system` 模块的基础功能

## 后续需求
- 无