datai/docs/requirements/2026-01-21-003-salesforce-multi-system-auth.md

# Salesforce 多系统认证需求

## 元数据
- 需求编号：2026-01-21-003
- 创建时间：2026-01-21
- 创建人：SSOT 架构师
- 状态：进行中
- 优先级：高

## 需求概述
实现 Salesforce 多系统认证功能，支持配置多个不同类型的 Salesforce 系统，使用策略模式实现登录（支持 OAuth2、Session ID、Salesforce CLI、Legacy Credential 登录），区分源 org 和目标 org（支持同一系统既是源 org 又是目标 org），记录登录历史信息（包含审计信息），回写 SF 返回信息到系统配置表，并使用 Redis 缓存保存登录信息（支持缓存有效性校验）。支持选择历史登录成功信息快速登录为源 org 或目标 org。支持会话管理，会话失效时自动重新登录。建立完整的错误码映射枚举类，提供友好的错误提示，支持错误重试机制。

## 子需求列表
本需求已拆分为以下 7 个可独立实现的子需求：

1. **[2026-01-21-003-01-salesforce-multi-system-config](./2026-01-21-003-01-salesforce-multi-system-config.md)** - Salesforce 多系统配置
   - 支持配置多个不同类型的 Salesforce 系统
   - 支持用户自定义系统类型
   - 支持区分源 org 和目标 org
   - 支持敏感信息加密存储

2. **[2026-01-21-003-02-salesforce-strategy-login](./2026-01-21-003-02-salesforce-strategy-login.md)** - Salesforce 策略模式登录
   - 使用策略模式实现不同类型的 Salesforce 系统登录
   - 支持 OAuth2 登录策略
   - 支持 Session ID 登录策略
   - 登录策略工厂使用工厂方法模式

3. **[2026-01-21-003-03-salesforce-login-history](./2026-01-21-003-03-salesforce-login-history.md)** - Salesforce 登录历史
   - 记录所有登录历史信息
   - 包含审计信息
   - 支持选择历史登录成功信息快速登录

4. **[2026-01-21-003-04-salesforce-cache-optimization](./2026-01-21-003-04-salesforce-cache-optimization.md)** - Salesforce 缓存优化
   - 登录成功后将 SF 登录信息保存到 Redis 缓存
   - 使用时校验有效性
   - 结构化缓存键设计
   - 缓存刷新和清理

5. **[2026-01-21-003-05-salesforce-session-management](./2026-01-21-003-05-salesforce-session-management.md)** - Salesforce 会话管理
   - 支持会话管理
   - 会话失效时自动重新登录
   - 获取当前 Session ID 和 Instance URL

6. **[2026-01-21-003-06-salesforce-login-status-query](./2026-01-21-003-06-salesforce-login-status-query.md)** - Salesforce 登录状态查询
   - 提供登录状态查询接口
   - 显示每个系统的登录状态
   - Session ID 脱敏处理

7. **[2026-01-21-003-07-salesforce-error-code-mapping](./2026-01-21-003-07-salesforce-error-code-mapping.md)** - Salesforce 错误码映射
   - 建立完整的错误码映射表
   - 提供友好的错误提示
   - 支持错误重试机制

## 目标
本需求已拆分为 7 个可独立实现的子需求，详细目标请参考各子需求文档。

## 实现顺序建议
建议按照以下顺序实现各子需求：

1. **2026-01-21-003-01**：多系统配置（基础功能，其他子需求依赖）
2. **2026-01-21-003-02**：策略模式登录（核心登录功能）
3. **2026-01-21-003-03**：登录历史（审计功能）
4. **2026-01-21-003-04**：缓存优化（性能优化）
5. **2026-01-21-003-05**：会话管理（会话管理功能）
6. **2026-01-21-003-06**：登录状态查询（查询功能）
7. **2026-01-21-003-07**：错误码映射（错误处理功能）

## 业务上下文

### 当前问题
- 系统只支持单个 Salesforce 系统配置
- 缺乏对不同类型 Salesforce 系统的支持
- 缺乏源 org 和目标 org 的区分
- 缺乏登录历史记录功能
- 缺乏登录信息缓存机制
- 缺乏审计信息记录功能
- 缺乏会话管理功能
- 缺乏会话失效时自动重新登录机制

### 业务场景
```
Salesforce 多系统认证
├─ 系统配置
│  ├─ 支持多个 Salesforce 系统
│  ├─ 支持用户自定义系统类型
│  ├─ 支持区分源 org 和目标 org
│  ├─ 支持同一系统既是源 org 又是目标 org
│  ├─ 支持配置登录 URL、grant_type、org_alias 等字段
│  ├─ 敏感信息加密存储（使用 EncryptUtils）
│  └─ 无需审批，无权限限制
├─ 登录认证
│  ├─ 策略模式实现不同登录方式
│  ├─ 用户通过页面选择登录策略
│  ├─ OAuth2 登录
│  │  ├─ 支持密码流程（password）
│  │  ├─ 支持客户端凭证流程（client_credentials）
│  │  ├─ 支持授权码流程（authorization_code）
│  │  ├─ 支持刷新 Session
│  │  └─ 支持登出操作
│  ├─ Session ID 登录
│  │  ├─ 使用已有的 Salesforce Session ID 进行登录
│  │  ├─ 通过 Identity API 验证 Session ID
│  │  ├─ 支持登出操作
│  │  └─ 不支持刷新 Session
│  ├─ Salesforce CLI 登录
│  │  ├─ 使用 Salesforce CLI 进行登录
│  │  ├─ 通过 CLI 命令获取 Session ID
│  │  ├─ 支持登出操作
│  │  └─ 不支持刷新 Session
│  └─ Legacy Credential 登录
│     ├─ 使用遗留凭证进行登录
│     ├─ 支持登出操作
│     └─ 不支持刷新 Session
├─ 登录历史
│  ├─ 记录登录时间
│  ├─ 记录登录用户
│  ├─ 记录登录结果
│  ├─ 记录登录 IP
│  ├─ 记录审计信息（设备信息、浏览器信息、地理位置等）
│  ├─ 支持查询登录历史
│  ├─ 支持分页查询
│  ├─ 支持导出登录历史为 Excel 文件
│  └─ 支持选择历史登录成功信息快速登录
├─ 配置回写
│  ├─ 回写 Session ID（Access Token，由 Salesforce 登录后返回）
│  ├─ 回写 Server URL（Instance URL）
│  ├─ 回写用户信息（用户 ID、用户名等）
│  └─ 回写组织信息（组织 ID、组织名称等）
├─ 缓存优化
│  ├─ 缓存 Session ID（Access Token）
│  ├─ 缓存 Server URL（Instance URL）
│  ├─ 缓存用户信息
│  ├─ 缓存组织信息
│  ├─ 使用时校验有效性
│  ├─ 登录成功后刷新 org 配置名称加 org 类型的缓存
│  ├─ 过期时 Redis 自动清理，或者登出接口清除当前缓存
│  ├─ 结构化缓存键设计（CURRENT_SOURCE_ORG_RESULT、CURRENT_TARGET_ORG_RESULT）
│  └─ 支持会话管理（datai_sf_login_session 表）
├─ 会话管理
│  ├─ 获取当前 Salesforce 会话信息（按 org 类型）
│  ├─ 会话失效时自动重新登录
│  ├─ 获取当前 Session ID
│  ├─ 获取当前 Instance URL
│  ├─ 判断会话是否有效
│  ├─ 支持会话信息的增删改查
│  ├─ 支持查询最近一条活跃的会话信息
│  ├─ 支持根据 ORG 类型查询最近一条活跃的会话信息
│  ├─ 支持会话状态（active/inactive）和最后活动时间管理
│  └─ 支持自动重新登录
├─ 登录状态查询
│  ├─ 提供查询接口返回当前所有系统的登录状态
│  ├─ 显示每个系统的登录状态（已登录/未登录/已过期）
│  ├─ 显示每个系统的 Session ID（脱敏处理）
│  ├─ 显示每个系统的过期时间
│  ├─ 支持按 org 类型筛选查询结果
│  ├─ 支持按系统 ID 查询特定系统的登录状态
│  └─ 支持会话信息管理
└─ 错误码映射
   ├─ 在 datai-salesforce-common 模块中生成错误码映射枚举类
   ├─ 映射 Salesforce 错误码到系统错误码
   ├─ 提供友好的错误提示
   ├─ 支持错误级别（ERROR=错误 WARN=警告 INFO=信息）
   ├─ 支持是否可重试（true=可重试 false=不可重试）
   ├─ 支持建议重试次数、建议重试间隔（毫秒）
   └─ 根据枚举类中的配置决定是否重试及重试次数
```

### 应用场景
1. **多环境管理**：管理生产环境、沙盒环境、自定义环境等多个 Salesforce 系统
2. **登录审计**：审计所有 Salesforce 登录操作，包含详细的审计信息
3. **性能优化**：使用 Redis 缓存减少重复登录，使用时校验有效性
4. **灵活配置**：用户可以自定义系统类型，无需审批和权限限制
5. **快速登录**：用户可以选择历史登录成功信息快速登录为源 org 或目标 org
6. **会话管理**：自动管理会话，会话失效时自动重新登录，提升用户体验

## 功能需求

### 核心功能

#### 功能 1：多系统配置
- **描述**：支持配置多个不同类型的 Salesforce 系统
- **验收标准**：
  1. 支持配置多个 Salesforce 系统
  2. 支持用户自定义系统类型（不限于 production/sandbox/developer）
  3. 支持区分源 org 和目标 org
  4. 支持同一系统既是源 org 又是目标 org
  5. 支持配置系统名称、自定义类型、登录方式等
  6. 支持配置登录 URL、grant_type、org_alias 等字段
  7. 支持启用/停用系统
  8. 系统配置变更无需审批流程
  9. 系统配置无权限限制
  10. 密码、安全令牌等敏感信息使用 EncryptUtils 加密存储
- **优先级**：高
- **依赖关系**：依赖数据库表设计

#### 功能 2：策略模式登录
- **描述**：使用策略模式实现不同类型的 Salesforce 系统登录，用户通过页面选择登录策略
- **验收标准**：
  1. 支持 OAuth2 登录策略
  2. 支持 Session ID 登录策略
  3. 支持 Salesforce CLI 登录策略
  4. 支持 Legacy Credential 登录策略
  5. 支持用户通过页面选择登录策略
  6. 支持扩展新的登录策略（预留接口）
  7. 根据用户选择的策略执行登录
  8. OAuth2 登录支持三种授权流程：
     - 密码流程（password）
     - 客户端凭证流程（client_credentials）
     - 授权码流程（authorization_code）
  9. Session ID 登录使用已有的 Salesforce Session ID 进行登录
  10. Session ID 登录通过 Identity API 验证 Session ID 并获取用户信息
  11. Salesforce CLI 登录使用 CLI 命令获取 Session ID
  12. Legacy Credential 登录使用遗留凭证进行登录
  13. 登录策略工厂使用工厂方法模式进行依赖注入
- **优先级**：高
- **依赖关系**：依赖多系统配置功能

#### 功能 3：源目标区分
- **描述**：划分 SF 系统为源 org 和目标 org，支持同一系统既是源 org 又是目标 org
- **验收标准**：
  1. 支持标记系统为源 org 或目标 org
  2. 支持同一系统既是源 org 又是目标 org
  3. 支持查询所有源 org
  4. 支持查询所有目标 org
  5. 支持根据类型筛选系统
- **优先级**：高
- **依赖关系**：依赖多系统配置功能

#### 功能 4：登录历史
- **描述**：记录所有登录历史信息，包含审计信息
- **验收标准**：
  1. 记录登录时间
  2. 记录登录用户
  3. 记录登录结果（成功/失败）
  4. 记录登录 IP
  5. 记录失败原因
  6. 记录审计信息（设备信息、浏览器信息、地理位置等）
  7. 支持查询登录历史
  8. 支持分页查询
  9. 支持导出登录历史为 Excel 文件
  10. 支持选择历史登录成功信息快速登录为源 org 或目标 org
- **优先级**：高
- **依赖关系**：依赖策略模式登录功能

#### 功能 5：配置回写
- **描述**：登录成功后回写 SF 返回的信息到系统配置表
- **验收标准**：
  1. 回写 Session ID（Access Token，由 Salesforce 登录后返回）
  2. 回写 Server URL（Instance URL）
  3. 回写用户信息（用户 ID、用户名等）
  4. 回写组织信息（组织 ID、组织名称等）
  5. 回写访问令牌（Access Token）
  6. 支持定时刷新令牌（OAuth2 登录支持）
- **优先级**：高
- **依赖关系**：依赖策略模式登录功能

#### 功能 6：缓存优化
- **描述**：登录成功后将 SF 登录信息保存到 Redis 缓存，使用时校验有效性
- **验收标准**：
  1. 缓存 Session ID（Access Token）
  2. 缓存 Server URL（Instance URL）
  3. 缓存用户信息
  4. 缓存组织信息
  5. 缓存 Access Token 和过期时间戳
  6. 设置合理的缓存过期时间（2 小时）
  7. 使用缓存时校验有效性（检查过期时间戳）
  8. 缓存失效时自动重新登录
  9. Session ID 的有效期通过成功登录后存入缓存中，设置过期时间
  10. 若是过期了，Redis 则没有 Session ID
  11. 在缓存中存储过期时间戳，使用前进行校验
  12. 并发登录使用 Salesforce 用户 ID + 系统 ID 存储缓存
  13. 设计结构化的缓存键：`sf:auth:{userId}:{systemId}:{orgType}`
  14. 支持会话管理（datai_sf_login_session 表）
  15. 支持会话状态（active/inactive）和最后活动时间管理
  16. 支持自动重新登录
- **优先级**：高
- **依赖关系**：依赖 datai-cache-redis 模块

#### 功能 7：缓存刷新
- **描述**：Salesforce 登录成功后，刷新当前系统中对于 org 配置名称加 org 类型的缓存
- **验收标准**：
  1. 登录成功后自动刷新 org 配置名称加 org 类型的缓存
  2. 缓存刷新失败后的处理机制
  3. 缓存刷新的日志记录
- **优先级**：高
- **依赖关系**：依赖缓存优化功能

#### 功能 8：缓存清理
- **描述**：过期时 Redis 自动清理，或者登出接口清除当前缓存
- **验收标准**：
  1. 过期时 Redis 自动清理缓存
  2. 提供登出接口清除当前缓存
  3. 缓存清理失败后的处理机制
  4. 缓存清理的日志记录
- **优先级**：高
- **依赖关系**：依赖缓存优化功能

#### 功能 9：历史登录快速使用
- **描述**：支持选择历史登录成功信息快速登录为源 org 或目标 org
- **验收标准**：
  1. 支持查询历史登录成功的记录
  2. 支持选择历史登录成功信息
  3. 支持将历史登录成功信息快速设置为源 org
  4. 支持将历史登录成功信息快速设置为目标 org
  5. 支持验证历史登录信息的有效性
- **优先级**：高
- **依赖关系**：依赖登录历史功能

#### 功能 10：会话管理
- **描述**：支持会话管理，会话失效时自动重新登录
- **验收标准**：
  1. 获取当前 Salesforce 会话信息（按 org 类型）
  2. 会话失效时自动重新登录
  3. 获取当前 Session ID
  4. 获取当前 Instance URL
  5. 判断会话是否有效
  6. 支持按 org 类型（source/target）管理会话
  7. 支持自动登录（基于历史登录记录）
  8. 支持会话信息的增删改查
  9. 支持查询最近一条活跃的会话信息
  10. 支持根据 ORG 类型查询最近一条活跃的会话信息
  11. 支持会话状态（active/inactive）和最后活动时间管理
- **优先级**：高
- **依赖关系**：依赖缓存优化功能、登录历史功能

#### 功能 11：登录状态查询
- **描述**：提供登录状态查询接口，用户可以查看当前所有系统的登录状态
- **验收标准**：
  1. 提供查询接口返回当前所有系统的登录状态
  2. 显示每个系统的登录状态（已登录/未登录/已过期）
  3. 显示每个系统的 Session ID（脱敏处理）
  4. 显示每个系统的过期时间
  5. 支持按 org 类型筛选查询结果
  6. 支持按系统 ID 查询特定系统的登录状态
  7. 支持会话信息管理
- **优先级**：高
- **依赖关系**：依赖缓存优化功能、会话管理功能

#### 功能 12：错误码映射
- **描述**：在 datai-salesforce-common 模块中生成错误码映射枚举类，提供友好的错误提示
- **验收标准**：
  1. 在 datai-salesforce-common 模块中生成错误码映射枚举类
  2. 枚举类包含 Salesforce 错误码
  3. 枚举类包含系统错误码
  4. 枚举类包含系统错误信息（友好的错误提示）
  5. 枚举类包含错误级别（ERROR=错误 WARN=警告 INFO=信息）
  6. 枚举类包含是否可重试（true=可重试 false=不可重试）
  7. 枚举类包含建议重试次数
  8. 枚举类包含建议重试间隔（毫秒）
  9. 枚举类包含错误描述
  10. 支持根据 Salesforce 错误码查询系统错误码
  11. 支持根据系统错误码查询 Salesforce 错误码
  12. 支持获取所有错误码映射
  13. 支持判断错误是否可重试
  14. 支持获取重试次数和重试间隔
- **优先级**：高
- **依赖关系**：依赖 datai-salesforce-common 模块

## 非功能需求

### 性能需求
- **登录时间**：登录响应时间 < 3 秒
- **缓存时间**：缓存读取时间 < 10ms
- **缓存校验时间**：缓存有效性校验时间 < 5ms
- **并发用户数**：支持 100+ 并发用户

### 安全需求
- **认证方式**：使用现有的 Spring Security 认证机制
- **数据安全**：密码、安全令牌等敏感信息使用 EncryptUtils 加密存储
- **审计日志**：记录所有登录操作和审计信息

### 可用性需求
- **系统可用性**：99.9%
- **容错机制**：登录失败时自动重试
- **灾备方案**：缓存失效时自动重新登录

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

## 数据需求

### 数据模型

#### datai_sf_system_config（Salesforce 系统配置表）
```
datai_sf_system_config (Salesforce 系统配置表)
├─ id (BIGINT) - 主键ID
├─ system_name (VARCHAR) - 系统名称（唯一）
├─ system_type (VARCHAR) - 系统类型（用户自定义）
├─ org_type (VARCHAR) - 组织类型（S=源 org T=目标 org ST=源和目标 org，可同时选中）
├─ login_type (VARCHAR) - 登录类型（oauth2/session_id/cli/legacy_credential）
├─ login_url (VARCHAR) - 登录 URL
├─ grant_type (VARCHAR) - OAuth2 授权类型（password/client_credentials/authorization_code）
├─ org_alias (VARCHAR) - 组织别名
├─ client_id (VARCHAR) - OAuth 客户端 ID
├─ client_secret (VARCHAR) - OAuth 客户端密钥（使用 EncryptUtils 加密存储）
├─ username (VARCHAR) - 用户名
├─ password (VARCHAR) - 密码（使用 EncryptUtils 加密存储）
├─ security_token (VARCHAR) - 安全令牌（使用 EncryptUtils 加密存储）
├─ session_id (VARCHAR) - Session ID（由 Salesforce 登录后返回）
├─ server_url (VARCHAR) - 服务器 URL（Instance URL）
├─ refresh_token (VARCHAR) - 刷新令牌
├─ token_expires_at (DATETIME) - 令牌过期时间
├─ sf_user_id (VARCHAR) - Salesforce 用户 ID（由 Salesforce 登录后返回，用于缓存键）
├─ user_id (VARCHAR) - 用户 ID（由 Salesforce 登录后返回）
├─ org_id (VARCHAR) - 组织 ID（由 Salesforce 登录后返回）
├─ org_name (VARCHAR) - 组织名称（由 Salesforce 登录后返回）
├─ status (CHAR) - 状态（0正常 1停用）
├─ sort_order (INT) - 排序
├─ create_by (VARCHAR) - 创建者
├─ create_time (DATETIME) - 创建时间
├─ update_by (VARCHAR) - 更新者
└─ update_time (DATETIME) - 更新时间
```

#### datai_sf_login_history（Salesforce 登录历史表）
```
datai_sf_login_history (Salesforce 登录历史表)
├─ id (BIGINT) - 主键ID
├─ system_id (BIGINT) - 系统配置 ID
├─ login_type (VARCHAR) - 登录类型（oauth2/session_id/cli/legacy_credential）
├─ username (VARCHAR) - 登录用户名
├─ login_result (CHAR) - 登录结果（S=成功 F=失败）
├─ failure_reason (VARCHAR) - 失败原因
├─ login_ip (VARCHAR) - 登录 IP
├─ device_info (VARCHAR) - 设备信息（审计信息）
├─ browser_info (VARCHAR) - 浏览器信息（审计信息）
├─ location_info (VARCHAR) - 地理位置（审计信息）
├─ session_id (VARCHAR) - Session ID（仅成功登录时记录，由 Salesforce 登录后返回）
├─ server_url (VARCHAR) - 服务器 URL（Instance URL，仅成功登录时记录）
├─ user_id (VARCHAR) - 用户 ID（仅成功登录时记录，由 Salesforce 登录后返回）
├─ org_id (VARCHAR) - 组织 ID（仅成功登录时记录，由 Salesforce 登录后返回）
├─ org_name (VARCHAR) - 组织名称（仅成功登录时记录，由 Salesforce 登录后返回）
├─ token_expires_at (DATETIME) - 令牌过期时间（仅成功登录时记录）
├─ login_time (DATETIME) - 登录时间
└─ create_time (DATETIME) - 创建时间
```

#### datai_sf_login_session（Salesforce 登录会话表）
```
datai_sf_login_session (Salesforce 登录会话表)
├─ id (BIGINT) - 主键ID
├─ system_id (BIGINT) - 系统配置 ID
├─ org_type (VARCHAR) - 组织类型（source/target）
├─ session_id (VARCHAR) - Session ID（由 Salesforce 登录后返回）
├─ server_url (VARCHAR) - 服务器 URL（Instance URL）
├─ user_id (VARCHAR) - 用户 ID（由 Salesforce 登录后返回）
├─ org_id (VARCHAR) - 组织 ID（由 Salesforce 登录后返回）
├─ org_name (VARCHAR) - 组织名称（由 Salesforce 登录后返回）
├─ session_status (VARCHAR) - 会话状态（active/inactive）
├─ last_activity_time (DATETIME) - 最后活动时间
├─ token_expires_at (DATETIME) - 令牌过期时间
├─ create_time (DATETIME) - 创建时间
├─ update_time (DATETIME) - 更新时间
└─ create_by (VARCHAR) - 创建者
```

#### 错误码映射枚举类（datai-salesforce-common 模块）
```
SalesforceErrorCode 枚举类
├─ 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) - 错误描述

ErrorLevel 枚举类
├─ ERROR ("E", "错误")
├─ WARN ("W", "警告")
└─ INFO ("I", "信息")
```

### 数据存储需求
- **数据库类型**：MySQL 8.3.0
- **存储容量**：单表支持 1000 万+ 数据
- **数据备份策略**：每日备份，保留 7 天

### 数据流转需求
```
系统配置
  └─ 管理员添加/编辑/删除 Salesforce 系统
  └─ 更新数据库中的系统配置
  └─ 支持配置登录 URL、grant_type、org_alias 等字段
  └─ 密码、安全令牌等敏感信息使用 EncryptUtils 加密存储
  └─ 无需审批流程
  └─ 无权限限制

登录认证
  └─ 读取系统配置
  └─ 使用 EncryptUtils 解密敏感信息
  └─ 用户通过页面选择登录策略
  └─ 根据登录类型选择对应的策略
     ├─ OAuth2 登录
     │  ├─ 支持三种授权流程（password、client_credentials、authorization_code）
     │  ├─ 支持刷新 Session
     │  └─ 支持登出操作
     ├─ Session ID 登录
     │  ├─ 使用已有的 Salesforce Session ID 进行登录
     │  ├─ 通过 Identity API 验证 Session ID 并获取用户信息
     │  ├─ 支持登出操作
     │  └─ 不支持刷新 Session
     ├─ Salesforce CLI 登录
     │  ├─ 使用 Salesforce CLI 进行登录
     │  ├─ 通过 CLI 命令获取 Session ID
     │  ├─ 支持登出操作
     │  └─ 不支持刷新 Session
     └─ Legacy Credential 登录
        ├─ 使用遗留凭证进行登录
        ├─ 支持登出操作
        └─ 不支持刷新 Session
  └─ Session ID 由 Salesforce 登录后返回
  └─ 记录登录历史（包含审计信息）
  └─ 回写 SF 返回信息到系统配置
  └─ 保存登录信息到 Redis 缓存
  └─ 设置缓存过期时间为 2 小时
  └─ 刷新当前系统中对于 org 配置名称加 org 类型的缓存

会话管理
  └─ 获取当前 Salesforce 会话信息（按 org 类型）
  └─ 判断会话是否有效
  └─ 会话失效时自动重新登录
  └─ 基于历史登录记录进行自动登录
  └─ 获取当前 Session ID
  └─ 获取当前 Instance URL
  └─ 支持会话信息的增删改查
  └─ 支持查询最近一条活跃的会话信息
  └─ 支持根据 ORG 类型查询最近一条活跃的会话信息
  └─ 支持会话状态（active/inactive）和最后活动时间管理

使用缓存
  └─ 从 Redis 读取登录信息
  └─ 校验缓存有效性（检查过期时间）
  └─ 有效则直接使用
  └─ 无效则重新登录

缓存清理
  └─ 过期时 Redis 自动清理缓存
  └─ 或者通过登出接口清除当前缓存

历史登录快速使用
  └─ 查询历史登录成功的记录
  └─ 选择历史登录成功信息
  └─ 验证历史登录信息的有效性
  └─ 将历史登录成功信息快速设置为源 org 或目标 org

错误码映射
  └─ 在 datai-salesforce-common 模块中维护枚举类
  └─ 枚举类包含 Salesforce 错误码、系统错误码、错误级别、重试配置
  └─ 提供友好的错误提示
  └─ 捕获 Salesforce 错误
  └─ 根据枚举类查找对应的系统错误码
  └─ 返回友好的错误提示
  └─ 根据枚举类中的配置决定是否重试
  └─ 根据枚举类中的配置决定重试次数和重试间隔
```

## 业务规则
1. **系统名称唯一性**：系统名称（system_name）必须唯一
2. **用户自定义类型**：系统类型（system_type）由用户自定义，不限制为固定值
3. **源目标区分**：每个系统可以标记为源 org 或目标 org，支持同一系统既是源 org 又是目标 org
4. **登录策略选择**：用户通过页面选择登录策略，系统不自动选择
5. **登录历史记录**：每次登录都必须记录历史，包含审计信息
6. **配置回写**：登录成功后必须回写 SF 返回的信息
7. **缓存策略**：登录信息必须缓存到 Redis，设置过期时间为 2 小时
8. **缓存有效性校验**：使用缓存时必须校验有效性（检查 token_expires_at）
9. **敏感信息加密**：密码、安全令牌等敏感信息必须使用 EncryptUtils 加密存储
10. **Access Token 等同 Session ID**：对于 Salesforce 来说，Access Token 就是 Session ID，两者是同一个概念
11. **Session ID 获取方式**：Session ID 由 Salesforce 登录后返回给到
12. **Session ID 有效期**：通过成功登录后存入缓存中，设置过期时间，若是过期了，Redis 则没有 Session ID
13. **用户选择登录策略**：用户通过在页面上选择对应的登录策略
14. **缓存刷新**：Salesforce 登录成功后，刷新当前系统中对于 org 配置名称加 org 类型的缓存
15. **缓存清理**：过期时 Redis 自动清理，或者登出接口清除当前缓存
16. **OAuth2 登录支持**：OAuth2 登录支持三种授权流程（password、client_credentials、authorization_code）
17. **OAuth2 刷新 Session**：OAuth2 登录支持刷新 Session
18. **OAuth2 登出**：OAuth2 登录支持登出操作
19. **Session ID 登录验证**：Session ID 登录通过 Identity API 验证 Session ID 并获取用户信息
20. **Session ID 登出不支持刷新**：Session ID 登录不支持刷新 Session
21. **Session ID 登出**：Session ID 登录支持登出操作
22. **Salesforce CLI 登录**：Salesforce CLI 登录使用 CLI 命令获取 Session ID
23. **Salesforce CLI 登出不支持刷新**：Salesforce CLI 登录不支持刷新 Session
24. **Salesforce CLI 登出**：Salesforce CLI 登录支持登出操作
25. **Legacy Credential 登录**：Legacy Credential 登录使用遗留凭证进行登录
26. **Legacy Credential 登出不支持刷新**：Legacy Credential 登录不支持刷新 Session
27. **Legacy Credential 登出**：Legacy Credential 登录支持登出操作
28. **会话管理**：支持会话管理，会话失效时自动重新登录
29. **会话有效性判断**：判断会话是否有效（会话信息不为 null、登录状态为成功、Session ID 不为空、Session 未过期）
30. **简化实现**：先实现最简单的登录模式（OAuth2、Session ID），数据同步功能后续处理
31. **历史登录快速使用**：支持选择历史登录成功信息快速登录为源 org 或目标 org
32. **缓存过期时间戳校验**：在缓存中存储过期时间戳，使用前必须校验
33. **并发登录缓存键**：并发登录使用 Salesforce 用户 ID + 系统 ID 存储缓存
34. **结构化缓存键设计**：缓存键格式为 `sf:auth:{sf_user_id}:{systemId}:{orgType}`，其中 sf_user_id 为 Salesforce 用户 ID（由 Salesforce 登录后返回）
35. **登录策略工厂模式**：登录策略工厂使用工厂方法模式进行依赖注入
36. **错误码映射**：所有 Salesforce 错误码必须在枚举类中映射到系统错误码，提供友好的错误提示
37. **错误重试机制**：根据枚举类中的配置决定是否重试及重试次数
38. **错误级别**：支持错误级别（ERROR=错误 WARN=警告 INFO=信息）
39. **可重试配置**：支持是否可重试（true=可重试 false=不可重试）
40. **枚举类维护**：在 `datai-salesforce-common` 模块中维护枚举类
41. **登录状态查询**：提供登录状态查询接口，显示所有系统的登录状态（已登录/未登录/已过期）
42. **会话状态管理**：支持会话状态（active/inactive）和最后活动时间管理
43. **会话信息查询**：支持查询最近一条活跃的会话信息
44. **会话信息查询**：支持根据 ORG 类型查询最近一条活跃的会话信息
45. **登录历史导出**：支持导出登录历史为 Excel 文件
46. **登录历史分页**：支持分页查询登录历史

## 技术约束
1. **Spring Boot 版本**：3.5.7
2. **Java 版本**：21
3. **数据库**：MySQL 8.3.0
4. **ORM 框架**：MyBatis 3.5.16
5. **缓存**：Redis（使用 datai-cache-redis 模块）
6. **Salesforce API**：使用 datai-salesforce-common 模块
7. **加密工具**：使用 datai-common 模块的 EncryptUtils 加密敏感信息
8. **必须使用现有的认证授权机制**：不能引入新的认证方式
9. **策略模式**：使用策略模式实现不同登录方式
10. **会话管理**：使用会话管理类管理会话，会话失效时自动重新登录

## 成功标准
1. 支持配置多个 Salesforce 系统
2. 支持用户自定义系统类型
3. 支持策略模式登录（OAuth2、Session ID、Salesforce CLI、Legacy Credential），用户通过页面选择登录策略
4. 支持区分源 org 和目标 org，支持同一系统既是源 org 又是目标 org
5. 记录所有登录历史信息，包含审计信息
6. 登录成功后回写 SF 返回信息到系统配置表
7. 登录成功后将 SF 登录信息保存到 Redis 缓存
8. 使用缓存时校验有效性（检查过期时间）
9. 密码、安全令牌等敏感信息使用 EncryptUtils 加密存储
10. Access Token 等同 Session ID，两者是同一个概念
11. Session ID 由 Salesforce 登录后返回给到
12. Session ID 的有效期通过成功登录后存入缓存中，设置过期时间，若是过期了，Redis 则没有 Session ID
13. 用户通过在页面上选择对应的登录策略
14. Salesforce 登录成功后，刷新当前系统中对于 org 配置名称加 org 类型的缓存
15. 过期时 Redis 自动清理，或者登出接口清除当前缓存
16. OAuth2 登录支持三种授权流程（password、client_credentials、authorization_code）
17. OAuth2 登录支持刷新 Session
18. OAuth2 登录支持登出操作
19. Session ID 登录通过 Identity API 验证 Session ID 并获取用户信息
20. Session ID 登录不支持刷新 Session
21. Session ID 登录支持登出操作
22. Salesforce CLI 登录使用 CLI 命令获取 Session ID
23. Salesforce CLI 登录不支持刷新 Session
24. Salesforce CLI 登录支持登出操作
25. Legacy Credential 登录使用遗留凭证进行登录
26. Legacy Credential 登录不支持刷新 Session
27. Legacy Credential 登录支持登出操作
28. 支持会话管理，会话失效时自动重新登录
29. 支持获取当前 Session ID
30. 支持获取当前 Instance URL
31. 支持判断会话是否有效
32. 支持选择历史登录成功信息快速登录为源 org 或目标 org
33. 支持会话信息的增删改查
34. 支持查询最近一条活跃的会话信息
35. 支持根据 ORG 类型查询最近一条活跃的会话信息
36. 支持会话状态（active/inactive）和最后活动时间管理
37. 支持登录状态查询接口，显示所有系统的登录状态（已登录/未登录/已过期）
38. 支持导出登录历史为 Excel 文件
39. 支持分页查询登录历史
40. 在 datai-salesforce-common 模块中生成错误码映射枚举类
41. 支持错误级别（ERROR=错误 WARN=警告 INFO=信息）
42. 支持是否可重试（true=可重试 false=不可重试）
43. 支持建议重试次数、建议重试间隔（毫秒）
44. 登录响应时间 < 3 秒
45. 单元测试覆盖率 ≥ 80%

## 风险评估
| 风险 | 影响程度 | 发生概率 | 缓解措施 |
| ---- | ------ | ------ | ------ |
| 登录策略扩展复杂度高 | 中 | 低 | 使用策略模式，提供清晰的扩展接口 |
| 缓存失效导致性能下降 | 中 | 中 | 实现自动重新登录机制 |
| 令牌过期导致登录失败 | 中 | 中 | 实现缓存有效性校验，自动重新登录 |
| 敏感信息泄露 | 高 | 低 | 使用 EncryptUtils 加密存储敏感信息，限制访问权限 |
| 历史登录信息过期 | 中 | 中 | 实现历史登录信息有效性校验机制 |
| 缓存刷新失败 | 中 | 低 | 实现缓存刷新失败后的重试机制 |
| 缓存清理失败 | 低 | 低 | 实现缓存清理失败后的日志记录和告警 |
| 会话管理复杂度高 | 中 | 中 | 使用会话管理类封装会话逻辑，提供清晰的接口 |
| 自动登录失败 | 中 | 中 | 实现自动登录失败后的重试机制和错误提示 |

## 依赖关系
- 依赖 datai-salesforce-common 模块（Salesforce API、错误码映射枚举类）
- 依赖 datai-cache-redis 模块（Redis 缓存）
- 依赖 datai-common 模块（EncryptUtils 加密工具）
- 依赖现有的 Spring Boot 框架
- 依赖现有的 MyBatis 框架
- 依赖现有的认证授权机制

## 后续扩展
1. **数据同步功能**：未来实现从源 org 拉取数据并推送到目标 org
2. **更多登录策略**：未来支持 JWT 登录等
3. **系统配置审批**：未来可选支持系统配置审批流程
4. **系统配置权限**：未来可选支持按用户/角色控制对特定系统的访问权限
5. **登录历史统计**：未来支持登录成功率、失败率等统计分析
6. **审计信息增强**：未来支持更多审计信息（如操作日志、行为分析）
7. **OAuth2 PKCE 支持**：未来支持 OAuth2 PKCE（Proof Key for Code Exchange）增强安全性

## 相关文档
- [设计文档](../design/2026-01-21-003-salesforce-multi-system-auth-design.md)（待创建）
- [实施方案](../implementation/salesforce-multi-system-auth-solution.md)（待创建）
- [数据库脚本](../sql/2026-01-21-003-salesforce-multi-system-auth.sql)（待创建）