datai/docs/requirements/2026-01-21-003-02-salesforce-strategy-login.md

# Salesforce 策略模式登录需求

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

## 需求概述
使用策略模式实现不同类型的 Salesforce 系统登录，用户通过页面选择登录策略。支持 OAuth2 登录策略（最简单模式）、Session ID 登录策略（最简单模式）、Salesforce CLI 登录策略、Legacy Credential 登录策略（传统账密凭证），支持扩展新的登录策略（预留接口）。OAuth2 登录支持三种授权流程：密码流程（password）、客户端凭证流程（client_credentials）、授权码流程（authorization_code）。Session ID 登录使用已有的 Salesforce Session ID 进行登录，通过 Identity API 验证 Session ID 并获取用户信息。Legacy Credential 登录使用 SOAP API 进行传统账密凭证登录。Salesforce CLI 登录通过 Salesforce CLI 命令行工具获取 Session 信息。登录策略工厂使用工厂方法模式进行依赖注入。

## 目标
1. **策略模式实现**：使用策略模式实现不同类型的 Salesforce 系统登录
2. **用户选择策略**：用户通过页面选择登录策略
3. **OAuth2 登录**：支持 OAuth2 登录策略（最简单模式）
4. **Session ID 登录**：支持 Session ID 登录策略（最简单模式）
5. **Salesforce CLI 登录**：支持 Salesforce CLI 登录策略
6. **Legacy Credential 登录**：支持 Legacy Credential 登录策略（传统账密凭证）
7. **扩展性**：支持扩展新的登录策略（预留接口）
8. **OAuth2 授权流程**：OAuth2 登录支持三种授权流程
9. **Session ID 验证**：Session ID 登录通过 Identity API 验证 Session ID 并获取用户信息
10. **Legacy Credential SOAP**：Legacy Credential 登录使用 SOAP API
11. **Salesforce CLI 命令**：Salesforce CLI 登录通过命令行工具获取 Session
12. **工厂方法模式**：登录策略工厂使用工厂方法模式进行依赖注入

## 业务上下文

### 当前问题
- 缺乏对不同类型 Salesforce 系统登录的支持
- 缺乏策略模式实现登录方式
- 缺乏用户选择登录策略的功能

### 业务场景
```
Salesforce 策略模式登录
├─ 策略模式实现不同登录方式
├─ 用户通过页面选择登录策略
├─ OAuth2 登录（最简单模式）
│  ├─ 支持密码流程（password）
│  ├─ 支持客户端凭证流程（client_credentials）
│  ├─ 支持授权码流程（authorization_code）
│  ├─ 支持刷新 Session
│  └─ 支持登出操作
├─ Session ID 登录（最简单模式）
│  ├─ 使用已有的 Salesforce Session ID 进行登录
│  ├─ 通过 Identity API 验证 Session ID
│  ├─ 支持登出操作
│  └─ 不支持刷新 Session
├─ Salesforce CLI 登录
│  ├─ 通过 Salesforce CLI 命令行工具获取 Session
│  ├─ 支持组织别名（org_alias）
│  ├─ 支持刷新 Session（重新获取）
│  └─ 支持登出操作
└─ Legacy Credential 登录（传统账密凭证）
   ├─ 使用 SOAP API 进行登录
   ├─ 支持用户名、密码、安全令牌
   ├─ 不支持刷新 Session
   └─ 支持登出操作
```

### 应用场景
1. **灵活登录**：用户可以选择不同的登录策略进行登录
2. **OAuth2 登录**：使用 OAuth2 方式登录 Salesforce
3. **Session ID 登录**：使用已有的 Session ID 快速登录 Salesforce
4. **Salesforce CLI 登录**：使用 Salesforce CLI 命令行工具获取 Session
5. **Legacy Credential 登录**：使用传统账密凭证方式登录 Salesforce

## 功能需求

### 核心功能

#### 功能 1：策略模式实现
- **描述**：使用策略模式实现不同类型的 Salesforce 系统登录
- **验收标准**：
  1. 定义登录策略接口（LoginStrategy）
  2. 实现 OAuth2 登录策略（OAuth2LoginStrategy）
  3. 实现 Session ID 登录策略（SessionIdLoginStrategy）
  4. 实现 Salesforce CLI 登录策略（SalesforceCliLoginStrategy）
  5. 实现 Legacy Credential 登录策略（LegacyCredentialLoginStrategy）
  6. 支持扩展新的登录策略（预留接口）
  7. 策略接口包含 login、refreshToken、logout、getLoginType 方法
- **优先级**：高
- **依赖关系**：依赖多系统配置功能（2026-01-21-003-01）

#### 功能 2：登录策略工厂
- **描述**：登录策略工厂使用工厂方法模式进行依赖注入
- **验收标准**：
  1. 创建登录策略工厂（LoginStrategyFactory）
  2. 使用工厂方法模式进行依赖注入
  3. 根据登录类型返回对应的策略实例
  4. 支持获取所有支持的登录类型
  5. 支持动态注册新的登录策略
- **优先级**：高
- **依赖关系**：依赖策略模式实现功能

#### 功能 3：OAuth2 登录
- **描述**：支持 OAuth2 登录策略（最简单模式）
- **验收标准**：
  1. 支持密码流程（password）
  2. 支持客户端凭证流程（client_credentials）
  3. 支持授权码流程（authorization_code）
  4. 支持刷新 Session
  5. 支持登出操作
  6. 登录成功后返回 Session ID（Access Token）、Server URL（Instance URL）、用户信息、组织信息
  7. 登录失败时返回错误信息
  8. 支持自定义登录 URL（login_url）
  9. 授权码流程支持 state 参数（防止 CSRF 攻击）
- **优先级**：高
- **依赖关系**：依赖登录策略工厂功能

#### 功能 4：Session ID 登录
- **描述**：支持 Session ID 登录策略（最简单模式）
- **验收标准**：
  1. 使用已有的 Salesforce Session ID 进行登录
  2. 通过 Identity API 验证 Session ID
  3. 获取用户信息
  4. 支持登出操作
  5. 不支持刷新 Session
  6. 登录成功后返回 Session ID、Server URL、用户信息、组织信息
  7. 登录失败时返回错误信息
- **优先级**：高
- **依赖关系**：依赖登录策略工厂功能

#### 功能 5：Salesforce CLI 登录
- **描述**：支持 Salesforce CLI 登录策略
- **验收标准**：
  1. 通过 Salesforce CLI 命令行工具获取 Session
  2. 支持组织别名（org_alias）参数
  3. 支持刷新 Session（重新获取）
  4. 支持登出操作
  5. 登录成功后返回 Session ID、Instance URL、用户信息、组织信息
  6. 登录失败时返回错误信息
  7. 检查 Salesforce CLI 是否已安装
- **优先级**：高
- **依赖关系**：依赖登录策略工厂功能

#### 功能 6：Legacy Credential 登录
- **描述**：支持 Legacy Credential 登录策略（传统账密凭证）
- **验收标准**：
  1. 使用 SOAP API 进行登录
  2. 支持用户名、密码、安全令牌参数
  3. 不支持刷新 Session
  4. 支持登出操作
  5. 登录成功后返回 Session ID、Server URL、用户信息、组织信息
  6. 登录失败时返回错误信息
  7. 支持自定义登录 URL（login_url）
  8. 提供友好的错误消息（中文）
- **优先级**：高
- **依赖关系**：依赖登录策略工厂功能

#### 功能 7：用户选择登录策略
- **描述**：用户通过页面选择登录策略
- **验收标准**：
  1. 提供登录策略选择界面
  2. 显示所有支持的登录策略
  3. 用户选择登录策略后执行登录
  4. 根据选择的策略显示对应的登录表单
  5. OAuth2 登录表单包含 login_url、client_id、client_secret、grant_type、username、password、security_token、code、state
  6. Session ID 登录表单包含 login_url、session_id、server_url
  7. Salesforce CLI 登录表单包含 org_alias
  8. Legacy Credential 登录表单包含 login_url、username、password、security_token
- **优先级**：高
- **依赖关系**：依赖登录策略工厂功能

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

## 非功能需求

### 性能需求
- **登录时间**：登录响应时间 < 3 秒
- **并发用户数**：支持 100+ 并发用户

### 安全需求
- **认证方式**：使用现有的 Spring Security 认证机制
- **数据安全**：登录过程中的敏感信息使用 HTTPS 传输

### 可用性需求
- **系统可用性**：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（如 https://login.salesforce.com）
├─ client_id (VARCHAR) - OAuth 客户端 ID
├─ client_secret (VARCHAR) - OAuth 客户端密钥（使用 EncryptUtils 加密存储）
├─ grant_type (VARCHAR) - OAuth 授权类型（password/client_credentials/authorization_code）
├─ 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) - 令牌过期时间
├─ org_alias (VARCHAR) - Salesforce CLI 组织别名
├─ private_key_path (VARCHAR) - 私有密钥路径
├─ private_key_password (VARCHAR) - 私有密钥密码（使用 EncryptUtils 加密存储）
├─ code (VARCHAR) - OAuth 授权码
├─ state (VARCHAR) - OAuth state 参数，用于防止 CSRF 攻击
├─ 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) - 更新时间
```

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

### 数据流转需求
```
登录认证
  └─ 读取系统配置
  └─ 使用 EncryptUtils 解密敏感信息
  └─ 用户通过页面选择登录策略
  └─ 根据登录类型选择对应的策略（OAuth2/Session ID/Salesforce CLI/Legacy Credential）
  └─ OAuth2 登录支持三种授权流程：
     ├─ 密码流程（password）
     ├─ 客户端凭证流程（client_credentials）
     └─ 授权码流程（authorization_code）
  └─ Session ID 登录使用已有的 Salesforce Session ID 进行登录
  └─ Session ID 登录通过 Identity API 验证 Session ID 并获取用户信息
  └─ Salesforce CLI 登录通过命令行工具获取 Session
  └─ Legacy Credential 登录使用 SOAP API 进行传统账密凭证登录
  └─ Session ID 由 Salesforce 登录后返回
  └─ 回写 SF 返回信息到系统配置
```

## 业务规则
1. **用户选择登录策略**：用户通过在页面上选择对应的登录策略
2. **Session ID 获取方式**：Session ID 由 Salesforce 登录后返回给到
3. **Access Token 等同 Session ID**：对于 Salesforce 来说，Access Token 就是 Session ID，两者是同一个概念
4. **OAuth2 登录支持**：OAuth2 登录支持三种授权流程（password、client_credentials、authorization_code）
5. **OAuth2 刷新 Session**：OAuth2 登录支持刷新 Session
6. **OAuth2 登出**：OAuth2 登录支持登出操作
7. **OAuth2 自定义登录 URL**：OAuth2 登录支持自定义登录 URL（login_url）
8. **OAuth2 state 参数**：授权码流程必须使用 state 参数防止 CSRF 攻击
9. **Session ID 登录验证**：Session ID 登录通过 Identity API 验证 Session ID 并获取用户信息
10. **Session ID 登出不支持刷新**：Session ID 登录不支持刷新 Session
11. **Session ID 登出**：Session ID 登录支持登出操作
12. **Salesforce CLI 登录**：Salesforce CLI 登录通过命令行工具获取 Session
13. **Salesforce CLI 组织别名**：Salesforce CLI 登录支持组织别名（org_alias）参数
14. **Salesforce CLI 刷新 Session**：Salesforce CLI 登录支持刷新 Session（重新获取）
15. **Salesforce CLI 登出**：Salesforce CLI 登录支持登出操作
16. **Legacy Credential 登录**：Legacy Credential 登录使用 SOAP API 进行传统账密凭证登录
17. **Legacy Credential 不支持刷新**：Legacy Credential 登录不支持刷新 Session
18. **Legacy Credential 登出**：Legacy Credential 登录支持登出操作
19. **Legacy Credential 自定义登录 URL**：Legacy Credential 登录支持自定义登录 URL（login_url）
20. **Legacy Credential 错误消息**：Legacy Credential 登录提供友好的中文错误消息
21. **配置回写**：登录成功后必须回写 SF 返回的信息

## 接口需求

### 登录接口
1. **OAuth2 登录**
   - 接口路径：POST /api/salesforce/auth/oauth2/login
   - 请求参数：
     - **通用参数**：
       - `login_url`（可选）：登录 URL（如 https://login.salesforce.com）
       - `grant_type`（必填）：授权流程类型（password/client_credentials/authorization_code）
       - `system_id`（必填）：系统配置 ID
     - **密码流程（password）**：
       - `client_id`（必填）：OAuth 客户端 ID
       - `client_secret`（必填）：OAuth 客户端密钥
       - `username`（必填）：用户名
       - `password`（必填）：密码
       - `security_token`（可选）：安全令牌
     - **客户端凭证流程（client_credentials）**：
       - `client_id`（必填）：OAuth 客户端 ID
       - `client_secret`（必填）：OAuth 客户端密钥
     - **授权码流程（authorization_code）**：
       - `client_id`（必填）：OAuth 客户端 ID
       - `client_secret`（必填）：OAuth 客户端密钥
       - `code`（必填）：授权码
       - `redirect_uri`（必填）：重定向 URI
       - `state`（必填）：state 参数，用于防止 CSRF 攻击
   - 响应：Session ID、Server URL、用户信息、组织信息

2. **Session ID 登录**
   - 接口路径：POST /api/salesforce/auth/session/login
   - 请求参数：
     - `login_url`（可选）：登录 URL（如 https://login.salesforce.com）
     - `system_id`（必填）：系统配置 ID
     - `session_id`（必填）：Session ID
     - `server_url`（必填）：服务器 URL
   - 响应：Session ID、Server URL、用户信息、组织信息

3. **Salesforce CLI 登录**
   - 接口路径：POST /api/salesforce/auth/cli/login
   - 请求参数：
     - `system_id`（必填）：系统配置 ID
     - `org_alias`（可选）：组织别名
   - 响应：Session ID、Instance URL、用户信息、组织信息

4. **Legacy Credential 登录**
   - 接口路径：POST /api/salesforce/auth/legacy/login
   - 请求参数：
     - `login_url`（可选）：登录 URL（如 https://login.salesforce.com）
     - `system_id`（必填）：系统配置 ID
     - `username`（必填）：用户名
     - `password`（必填）：密码
     - `security_token`（可选）：安全令牌
   - 响应：Session ID、Server URL、用户信息、组织信息

5. **刷新 Session**
   - 接口路径：POST /api/salesforce/auth/oauth2/refresh
   - 请求参数：
     - `system_id`（必填）：系统配置 ID
     - `refresh_token`（必填）：刷新令牌
   - 响应：新的 Session ID、Server URL

6. **登出**
   - 接口路径：POST /api/salesforce/auth/logout
   - 请求参数：
     - `system_id`（必填）：系统配置 ID
     - `login_type`（必填）：登录类型（oauth2/session_id/cli/legacy_credential）
   - 响应：成功/失败

7. **获取支持的登录类型**
   - 接口路径：GET /api/salesforce/auth/login-types
   - 响应：支持的登录类型列表

## 依赖关系
- 依赖 `2026-01-21-003-01`：多系统配置
- 依赖 `datai-common` 模块的 `EncryptUtils` 工具类
- 依赖 `datai-salesforce-common` 模块的 Salesforce API 封装
- 依赖 `datai-salesforce-auth` 模块的登录策略实现

## 后续需求
- 2026-01-21-003-03：登录历史
- 2026-01-21-003-04：缓存优化
- 2026-01-21-003-05：会话管理
- 2026-01-21-003-06：登录状态查询
- 2026-01-21-003-07：错误码映射