329 lines
12 KiB
Markdown
329 lines
12 KiB
Markdown
# Salesforce 会话管理需求
|
||
|
||
## 元数据
|
||
- 需求编号：2026-01-21-003-05
|
||
- 父需求编号：2026-01-21-003
|
||
- 创建时间：2026-01-21
|
||
- 创建人：SSOT 架构师
|
||
- 状态：待开始
|
||
- 优先级：高
|
||
|
||
## 需求概述
|
||
支持会话管理，会话失效时自动重新登录。获取当前 Salesforce 会话信息（按 org 类型），会话失效时自动重新登录，获取当前 Session ID，获取当前 Instance URL，判断会话是否有效。支持按 org 类型（source/target）管理会话，支持自动登录（基于历史登录记录）。
|
||
|
||
## 目标
|
||
1. **会话管理**：支持会话管理，会话失效时自动重新登录
|
||
2. **会话信息获取**：获取当前 Salesforce 会话信息（按 org 类型）
|
||
3. **会话失效处理**：会话失效时自动重新登录
|
||
4. **Session ID 获取**：获取当前 Session ID
|
||
5. **Instance URL 获取**：获取当前 Instance URL
|
||
6. **会话有效性判断**：判断会话是否有效
|
||
7. **按 org 类型管理**：支持按 org 类型（source/target）管理会话
|
||
8. **自动登录**：支持自动登录（基于历史登录记录）
|
||
|
||
## 业务上下文
|
||
|
||
### 当前问题
|
||
- 缺乏会话管理功能
|
||
- 缺乏会话失效时自动重新登录机制
|
||
|
||
### 业务场景
|
||
```
|
||
Salesforce 会话管理
|
||
├─ 获取当前 Salesforce 会话信息
|
||
├─ 会话失效时自动重新登录
|
||
├─ 获取当前 Session ID
|
||
├─ 获取当前 Instance URL
|
||
└─ 判断会话是否有效
|
||
```
|
||
|
||
### 应用场景
|
||
1. **会话管理**：自动管理会话，会话失效时自动重新登录，提升用户体验
|
||
2. **自动登录**：基于历史登录记录进行自动登录
|
||
|
||
## 功能需求
|
||
|
||
### 核心功能
|
||
|
||
#### 功能 1：获取会话信息
|
||
- **描述**：获取当前 Salesforce 会话信息（按 org 类型）
|
||
- **验收标准**：
|
||
1. 支持获取当前 Salesforce 会话信息
|
||
2. 支持按 org 类型（source/target）获取会话信息
|
||
3. 支持获取当前 Session ID
|
||
4. 支持获取当前 Instance URL
|
||
5. 支持获取用户信息
|
||
6. 支持获取组织信息
|
||
7. 支持获取令牌过期时间
|
||
- **优先级**：高
|
||
- **依赖关系**：依赖缓存优化功能（2026-01-21-003-04）
|
||
|
||
#### 功能 2：会话有效性判断
|
||
- **描述**：判断会话是否有效
|
||
- **验收标准**：
|
||
1. 判断会话信息是否为 null
|
||
2. 判断登录状态是否为成功
|
||
3. 判断 Session ID 是否为空
|
||
4. 判断 Session 是否过期
|
||
5. 返回会话有效性状态（有效/无效）
|
||
- **优先级**：高
|
||
- **依赖关系**：依赖获取会话信息功能
|
||
|
||
#### 功能 3：会话失效处理
|
||
- **描述**：会话失效时自动重新登录
|
||
- **验收标准**：
|
||
1. 会话失效时自动重新登录
|
||
2. 基于历史登录记录进行自动登录
|
||
3. 自动登录失败时返回错误信息
|
||
4. 自动登录成功后更新缓存
|
||
5. 记录会话状态日志（会话为 null、登录状态为失败、Session 已过期）
|
||
- **优先级**：高
|
||
- **依赖关系**：依赖会话有效性判断功能、登录历史功能（2026-01-21-003-03）
|
||
|
||
#### 功能 4：按 org 类型管理会话
|
||
- **描述**：支持按 org 类型（source/target）管理会话
|
||
- **验收标准**：
|
||
1. 支持按 org 类型（source）管理会话
|
||
2. 支持按 org 类型（target）管理会话
|
||
3. 支持同时管理源 org 和目标 org 的会话
|
||
4. 支持查询指定 org 类型的会话信息
|
||
- **优先级**：高
|
||
- **依赖关系**：依赖获取会话信息功能
|
||
|
||
#### 功能 5：自动登录
|
||
- **描述**：支持自动登录（基于历史登录记录）
|
||
- **验收标准**：
|
||
1. 基于历史登录记录进行自动登录
|
||
2. 选择最近一次成功的登录记录
|
||
3. 验证历史登录信息的有效性
|
||
4. 使用历史登录信息进行登录
|
||
5. 自动登录成功后更新缓存
|
||
6. 自动登录失败时返回错误信息
|
||
7. 自动登录失败时抛出异常
|
||
8. 记录自动登录的日志
|
||
- **优先级**：高
|
||
- **依赖关系**：依赖会话失效处理功能、登录历史功能（2026-01-21-003-03）
|
||
|
||
#### 功能 6：会话信息管理
|
||
- **描述**：支持会话信息的增删改查
|
||
- **验收标准**：
|
||
1. 支持查询会话信息列表
|
||
2. 支持查询会话信息详情
|
||
3. 支持新增会话信息
|
||
4. 支持修改会话信息
|
||
5. 支持删除会话信息
|
||
6. 支持批量删除会话信息
|
||
7. 支持根据 Session ID 查询会话信息
|
||
8. 支持查询最近一条活跃的会话信息
|
||
9. 支持根据 ORG 类型查询最近一条活跃的会话信息
|
||
10. 支持导出会话信息列表为 Excel 文件
|
||
- **优先级**：高
|
||
- **依赖关系**：依赖获取会话信息功能
|
||
|
||
## 非功能需求
|
||
|
||
### 性能需求
|
||
- **会话查询时间**：会话查询响应时间 < 10ms
|
||
- **会话校验时间**：会话有效性校验时间 < 5ms
|
||
- **并发用户数**：支持 100+ 并发用户
|
||
|
||
### 安全需求
|
||
- **会话安全**：会话信息使用加密存储
|
||
- **会话过期**：会话过期后自动失效
|
||
|
||
### 可用性需求
|
||
- **系统可用性**：99.9%
|
||
- **容错机制**：会话失效时自动重新登录
|
||
|
||
### 可维护性需求
|
||
- **代码可读性**：代码符合项目编码规范，注释完整
|
||
- **测试覆盖率**：单元测试覆盖率 ≥ 80%
|
||
|
||
## 数据需求
|
||
|
||
### 数据模型
|
||
|
||
#### datai_sf_login_session（Salesforce 登录会话表）
|
||
```
|
||
datai_sf_login_session (Salesforce 登录会话表)
|
||
├─ id (BIGINT) - 主键ID
|
||
├─ username (VARCHAR) - 用户名
|
||
├─ login_type (VARCHAR) - 登录类型（oauth2/session_id/cli/legacy_credential）
|
||
├─ status (VARCHAR) - 会话状态（active/inactive）
|
||
├─ login_time (DATETIME) - 登录时间
|
||
├─ expire_time (DATETIME) - 过期时间
|
||
├─ last_activity_time (DATETIME) - 最后活动时间
|
||
├─ login_ip (VARCHAR) - 登录 IP
|
||
├─ device_info (VARCHAR) - 设备信息
|
||
├─ browser_info (VARCHAR) - 浏览器信息
|
||
├─ session_id (VARCHAR) - 会话 ID
|
||
├─ dept_id (BIGINT) - 部门 ID
|
||
├─ sf_user_id (VARCHAR) - Salesforce 用户 ID
|
||
├─ sf_organization_id (VARCHAR) - Salesforce 组织 ID
|
||
├─ instance_url (VARCHAR) - 实例 URL（Instance URL）
|
||
├─ org_type (VARCHAR) - ORG 类型（S=源 org T=目标 org ST=源和目标 org）
|
||
├─ create_by (VARCHAR) - 创建者
|
||
├─ create_time (DATETIME) - 创建时间
|
||
├─ update_by (VARCHAR) - 更新者
|
||
└─ update_time (DATETIME) - 更新时间
|
||
```
|
||
|
||
#### Redis 缓存结构（复用缓存优化需求的缓存结构）
|
||
```
|
||
缓存键：
|
||
- 源 org：CURRENT_SOURCE_ORG_RESULT
|
||
- 目标 org：CURRENT_TARGET_ORG_RESULT
|
||
|
||
说明：
|
||
- 缓存键通过 orgType（source/target）动态获取
|
||
- 源 org 和目标 org 使用不同的缓存键
|
||
- 支持同时管理源 org 和目标 org 的会话
|
||
|
||
缓存值（SalesforceLoginResult 对象，JSON 序列化）：
|
||
{
|
||
"success": true/false,
|
||
"errorCode": "错误代码",
|
||
"errorMessage": "错误信息",
|
||
"sessionId": "Session ID",
|
||
"refreshToken": "刷新令牌（仅 OAuth 流程中存在）",
|
||
"tokenType": "Bearer",
|
||
"expiresIn": "过期时间（秒）",
|
||
"loginTimestamp": "登录时间戳",
|
||
"expirationTimestamp": "过期时间戳（登录时间 + 过期时长）",
|
||
"instanceUrl": "实例 URL（Instance URL）",
|
||
"metadataServerUrl": "元数据服务器 URL",
|
||
"sandbox": true/false,
|
||
"passwordExpired": true/false,
|
||
"userId": "用户 ID（由 Salesforce 登录后返回）",
|
||
"organizationId": "组织 ID（由 Salesforce 登录后返回）",
|
||
"orgType": "组织类型（source/target）",
|
||
"userFullName": "用户全名",
|
||
"userEmail": "用户邮箱",
|
||
"organizationName": "组织名称（由 Salesforce 登录后返回）",
|
||
"language": "语言",
|
||
"timeZone": "时区"
|
||
}
|
||
|
||
缓存过期时间：2 小时（7200 秒）
|
||
```
|
||
|
||
### 数据存储需求
|
||
- **缓存类型**：Redis
|
||
- **存储容量**：支持 1000 万+ 缓存键
|
||
- **缓存过期策略**：TTL（Time To Live）自动过期
|
||
|
||
### 数据流转需求
|
||
```
|
||
会话管理
|
||
└─ 获取当前 Salesforce 会话信息（按 org 类型）
|
||
└─ 判断会话是否有效
|
||
└─ 会话失效时自动重新登录
|
||
└─ 基于历史登录记录进行自动登录
|
||
└─ 获取当前 Session ID
|
||
└─ 获取当前 Instance URL
|
||
└─ 记录会话状态日志（会话为 null、登录状态为失败、Session 已过期）
|
||
|
||
会话信息管理
|
||
└─ 查询会话信息列表
|
||
└─ 查询会话信息详情
|
||
└─ 新增会话信息
|
||
└─ 修改会话信息
|
||
└─ 删除会话信息
|
||
└─ 批量删除会话信息
|
||
└─ 根据 Session ID 查询会话信息
|
||
└─ 查询最近一条活跃的会话信息
|
||
└─ 根据 ORG 类型查询最近一条活跃的会话信息
|
||
└─ 导出会话信息列表为 Excel 文件
|
||
```
|
||
|
||
## 业务规则
|
||
1. **会话管理**：支持会话管理，会话失效时自动重新登录
|
||
2. **会话有效性判断**：判断会话是否有效（会话信息不为 null、登录状态为成功、Session ID 不为空、Session 未过期）
|
||
3. **会话失效处理**：会话失效时自动重新登录
|
||
4. **按 org 类型管理**：支持按 org 类型（source/target）管理会话
|
||
5. **自动登录**：支持自动登录（基于历史登录记录）
|
||
6. **会话状态日志**：记录会话状态日志（会话为 null、登录状态为失败、Session 已过期）
|
||
7. **自动登录失败处理**：自动登录失败时返回错误信息并抛出异常
|
||
8. **会话信息管理**：支持会话信息的增删改查
|
||
9. **会话状态管理**：支持会话状态（active/inactive）和最后活动时间管理
|
||
|
||
## 接口需求
|
||
|
||
### 会话管理接口
|
||
1. **获取会话信息**
|
||
- 接口路径：GET /api/salesforce/session/info
|
||
- 请求参数：orgType（必填，source/target）
|
||
- 响应：会话信息（SalesforceLoginResult）
|
||
|
||
2. **获取当前 Session ID**
|
||
- 接口路径：GET /api/salesforce/session/session-id
|
||
- 请求参数：orgType（必填，source/target）
|
||
- 响应：Session ID
|
||
|
||
3. **获取当前 Instance URL**
|
||
- 接口路径：GET /api/salesforce/session/instance-url
|
||
- 请求参数：orgType（必填，source/target）
|
||
- 响应：Instance URL
|
||
|
||
4. **判断会话是否有效**
|
||
- 接口路径：GET /api/salesforce/session/valid
|
||
- 请求参数：orgType（必填，source/target）
|
||
- 响应：会话有效性状态（true/false）
|
||
|
||
5. **自动登录**
|
||
- 接口路径：POST /api/salesforce/session/auto-login
|
||
- 请求参数：orgType（必填，source/target）
|
||
- 响应：登录结果（SalesforceLoginResult）
|
||
|
||
6. **查询会话信息列表**
|
||
- 接口路径：GET /api/salesforce/session/list
|
||
- 请求参数：分页参数、筛选参数
|
||
- 响应：会话信息列表
|
||
|
||
7. **导出会话信息列表**
|
||
- 接口路径：POST /api/salesforce/session/export
|
||
- 请求参数：筛选参数
|
||
- 响应：Excel 文件
|
||
|
||
8. **查询会话信息详情**
|
||
- 接口路径：GET /api/salesforce/session/{id}
|
||
- 响应：会话信息详情
|
||
|
||
9. **新增会话信息**
|
||
- 接口路径：POST /api/salesforce/session
|
||
- 请求参数：会话信息
|
||
- 响应：成功/失败
|
||
|
||
10. **修改会话信息**
|
||
- 接口路径：PUT /api/salesforce/session
|
||
- 请求参数：会话信息
|
||
- 响应：成功/失败
|
||
|
||
11. **删除会话信息**
|
||
- 接口路径：DELETE /api/salesforce/session/{ids}
|
||
- 请求参数：会话 ID 数组
|
||
- 响应：成功/失败
|
||
|
||
12. **根据 Session ID 查询会话信息**
|
||
- 接口路径：GET /api/salesforce/session/by-session-id/{sessionId}
|
||
- 响应：会话信息
|
||
|
||
13. **查询最近一条活跃的会话信息**
|
||
- 接口路径：GET /api/salesforce/session/latest-active
|
||
- 响应：会话信息
|
||
|
||
14. **根据 ORG 类型查询最近一条活跃的会话信息**
|
||
- 接口路径：GET /api/salesforce/session/latest-active/{orgType}
|
||
- 请求参数：orgType（S/T/ST）
|
||
- 响应：会话信息
|
||
|
||
## 依赖关系
|
||
- 依赖 `2026-01-21-003-03`：登录历史
|
||
- 依赖 `2026-01-21-003-04`：缓存优化
|
||
- 依赖 `datai-cache-redis` 模块
|
||
- 依赖 `datai-salesforce-common` 模块的 Salesforce API 封装
|
||
|
||
## 后续需求
|
||
- 2026-01-21-003-06：登录状态查询
|
||
- 2026-01-21-003-07：错误码映射
|