393 lines
16 KiB
Markdown
393 lines
16 KiB
Markdown
# Salesforce 缓存优化需求
|
||
|
||
## 元数据
|
||
- 需求编号：2026-01-21-003-04
|
||
- 父需求编号：2026-01-21-003
|
||
- 创建时间：2026-01-21
|
||
- 创建人：SSOT 架构师
|
||
- 状态：待开始
|
||
- 优先级：高
|
||
|
||
## 需求概述
|
||
登录成功后将 SF 登录信息保存到 Redis 缓存，使用时校验有效性。缓存 Session ID（Access Token）、Server URL（Instance URL）、用户信息、组织信息、Access Token 和过期时间戳。设置合理的缓存过期时间（2 小时），使用缓存时校验有效性（检查过期时间戳），缓存失效时自动重新登录。Session ID 的有效期通过成功登录后存入缓存中，设置过期时间，若是过期了，Redis 则没有 Session ID。在缓存中存储过期时间戳，使用前进行校验。并发登录使用 Salesforce 用户 ID + 系统 ID 存储缓存。设计结构化的缓存键：`sf:auth:{userId}:{systemId}:{orgType}`。Salesforce 登录成功后，刷新当前系统中对于 org 配置名称加 org 类型的缓存。过期时 Redis 自动清理，或者登出接口清除当前缓存。
|
||
|
||
## 目标
|
||
1. **缓存登录信息**：登录成功后将 SF 登录信息保存到 Redis 缓存
|
||
2. **缓存有效性校验**：使用时校验有效性（检查过期时间戳）
|
||
3. **缓存失效处理**：缓存失效时自动重新登录
|
||
4. **结构化缓存键**：设计结构化的缓存键：`CURRENT_SOURCE_ORG_RESULT`（源 org）、`CURRENT_TARGET_ORG_RESULT`（目标 org）
|
||
5. **并发登录支持**：并发登录使用不同的缓存键区分源 org 和目标 org
|
||
6. **缓存刷新**：Salesforce 登录成功后，刷新当前系统中对于 org 配置名称加 org 类型的缓存
|
||
7. **缓存清理**：过期时 Redis 自动清理，或者登出接口清除当前缓存
|
||
8. **会话管理**：使用数据库表 `datai_sf_login_session` 管理会话信息
|
||
9. **自动重新登录**：会话失效时自动重新登录
|
||
10. **会话状态管理**：支持会话状态（active/inactive）和最后活动时间管理
|
||
|
||
## 业务上下文
|
||
|
||
### 当前问题
|
||
- 缺乏登录信息缓存机制
|
||
- 缺乏缓存有效性校验
|
||
- 缺乏缓存刷新机制
|
||
- 缺乏缓存清理机制
|
||
|
||
### 业务场景
|
||
```
|
||
Salesforce 缓存优化
|
||
├─ 缓存 Session ID（Access Token）
|
||
├─ 缓存 Server URL（Instance URL）
|
||
├─ 缓存用户信息
|
||
├─ 缓存组织信息
|
||
├─ 使用时校验有效性
|
||
├─ 登录成功后刷新 org 配置名称加 org 类型的缓存
|
||
├─ 过期时 Redis 自动清理，或者登出接口清除当前缓存
|
||
├─ 使用数据库表 datai_sf_login_session 管理会话信息
|
||
├─ 支持会话状态（active/inactive）和最后活动时间管理
|
||
└─ 会话失效时自动重新登录
|
||
```
|
||
|
||
### 应用场景
|
||
1. **性能优化**：使用 Redis 缓存减少重复登录，使用时校验有效性
|
||
2. **并发登录**：支持多个用户同时登录不同的 Salesforce 系统
|
||
3. **缓存管理**：自动管理缓存的生命周期
|
||
|
||
## 功能需求
|
||
|
||
### 核心功能
|
||
|
||
#### 功能 1：缓存登录信息
|
||
- **描述**：登录成功后将 SF 登录信息保存到 Redis 缓存
|
||
- **验收标准**：
|
||
1. 缓存 Session ID（Access Token）
|
||
2. 缓存 Server URL（Instance URL）
|
||
3. 缓存用户信息
|
||
4. 缓存组织信息
|
||
5. 缓存 Access Token 和过期时间戳
|
||
6. 设置合理的缓存过期时间（2 小时）
|
||
7. Session ID 的有效期通过成功登录后存入缓存中，设置过期时间
|
||
8. 若是过期了，Redis 则没有 Session ID
|
||
9. 在缓存中存储过期时间戳，使用前进行校验
|
||
10. 并发登录使用不同的缓存键区分源 org 和目标 org
|
||
11. 设计结构化的缓存键：`CURRENT_SOURCE_ORG_RESULT`（源 org）、`CURRENT_TARGET_ORG_RESULT`（目标 org）
|
||
- **优先级**：高
|
||
- **依赖关系**：依赖策略模式登录功能（2026-01-21-003-02）
|
||
|
||
#### 功能 2：缓存有效性校验
|
||
- **描述**：使用缓存时校验有效性（检查过期时间戳）
|
||
- **验收标准**：
|
||
1. 使用缓存时校验有效性（检查过期时间戳）
|
||
2. 有效则直接使用
|
||
3. 无效则重新登录
|
||
4. 缓存校验时间 < 5ms
|
||
5. 检查会话信息是否为 null
|
||
6. 检查登录状态是否为成功
|
||
7. 检查 Session ID 是否为空
|
||
8. 检查 Session 是否过期
|
||
- **优先级**：高
|
||
- **依赖关系**：依赖缓存登录信息功能
|
||
|
||
#### 功能 3：缓存失效处理
|
||
- **描述**：缓存失效时自动重新登录
|
||
- **验收标准**：
|
||
1. 缓存失效时自动重新登录
|
||
2. 基于历史登录记录进行自动登录
|
||
3. 自动登录失败时返回错误信息
|
||
4. 记录会话状态日志（会话为 null、登录状态为失败、Session 已过期）
|
||
- **优先级**：高
|
||
- **依赖关系**：依赖缓存有效性校验功能、登录历史功能（2026-01-21-003-03）
|
||
|
||
#### 功能 4：缓存刷新
|
||
- **描述**：Salesforce 登录成功后，刷新当前系统中对于 org 配置名称加 org 类型的缓存
|
||
- **验收标准**：
|
||
1. 登录成功后自动刷新 org 配置名称加 org 类型的缓存
|
||
2. 缓存刷新失败后的处理机制
|
||
3. 缓存刷新的日志记录
|
||
- **优先级**：高
|
||
- **依赖关系**：依赖缓存登录信息功能
|
||
|
||
#### 功能 5：缓存清理
|
||
- **描述**：过期时 Redis 自动清理，或者登出接口清除当前缓存
|
||
- **验收标准**：
|
||
1. 过期时 Redis 自动清理缓存
|
||
2. 提供登出接口清除当前缓存
|
||
3. 缓存清理失败后的处理机制
|
||
4. 缓存清理的日志记录
|
||
- **优先级**：高
|
||
- **依赖关系**：依赖缓存登录信息功能
|
||
|
||
#### 功能 6：会话管理
|
||
- **描述**：使用数据库表 `datai_sf_login_session` 管理会话信息
|
||
- **验收标准**：
|
||
1. 记录会话信息（用户名、登录类型、会话状态）
|
||
2. 记录登录时间、过期时间、最后活动时间
|
||
3. 记录登录 IP、设备信息、浏览器信息
|
||
4. 记录会话 ID、Salesforce 用户 ID、Salesforce 组织 ID
|
||
5. 记录实例 URL、ORG 类型
|
||
6. 支持会话状态（active/inactive）
|
||
7. 支持查询会话信息列表
|
||
8. 支持查询会话信息详情
|
||
9. 支持新增会话信息
|
||
10. 支持修改会话信息
|
||
11. 支持删除会话信息
|
||
12. 支持批量删除会话信息
|
||
13. 支持根据 Session ID 查询会话信息
|
||
14. 支持查询最近一条活跃的会话信息
|
||
15. 支持根据 ORG 类型查询最近一条活跃的会话信息
|
||
16. 支持导出会话信息列表为 Excel 文件
|
||
- **优先级**：高
|
||
- **依赖关系**：依赖缓存登录信息功能
|
||
|
||
#### 功能 7：自动重新登录
|
||
- **描述**：会话失效时自动重新登录
|
||
- **验收标准**：
|
||
1. 会话失效时自动重新登录
|
||
2. 基于历史登录记录进行自动登录
|
||
3. 自动登录失败时返回错误信息
|
||
4. 自动登录成功后更新缓存
|
||
5. 自动登录失败时抛出异常
|
||
6. 记录自动登录的日志
|
||
- **优先级**：高
|
||
- **依赖关系**：依赖会话管理功能、登录历史功能（2026-01-21-003-03）
|
||
|
||
## 非功能需求
|
||
|
||
### 性能需求
|
||
- **缓存时间**：缓存读取时间 < 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）自动过期
|
||
|
||
### 数据流转需求
|
||
```
|
||
缓存登录信息
|
||
└─ 登录成功后保存登录信息到 Redis 缓存
|
||
└─ 缓存 Session ID
|
||
└─ 缓存 Server URL（Instance URL）
|
||
└─ 缓存用户信息、组织信息（由 Salesforce 登录后返回）
|
||
└─ 缓存 Access Token 和过期时间戳
|
||
└─ 设置缓存过期时间为 2 小时
|
||
└─ 使用缓存键：CURRENT_SOURCE_ORG_RESULT（源 org）、CURRENT_TARGET_ORG_RESULT（目标 org）
|
||
└─ 源 org 和目标 org 使用不同的缓存键
|
||
|
||
使用缓存
|
||
└─ 从 Redis 读取登录信息
|
||
└─ 校验缓存有效性（检查过期时间）
|
||
└─ 有效则直接使用
|
||
└─ 无效则重新登录
|
||
|
||
缓存刷新
|
||
└─ 登录成功后自动刷新 org 配置名称加 org 类型的缓存
|
||
|
||
缓存清理
|
||
└─ 过期时 Redis 自动清理缓存
|
||
└─ 或者通过登出接口清除当前缓存
|
||
|
||
会话管理
|
||
└─ 使用数据库表 datai_sf_login_session 管理会话信息
|
||
└─ 记录会话信息（用户名、登录类型、会话状态）
|
||
└─ 记录登录时间、过期时间、最后活动时间
|
||
└─ 记录登录 IP、设备信息、浏览器信息
|
||
└─ 记录会话 ID、Salesforce 用户 ID、Salesforce 组织 ID
|
||
└─ 记录实例 URL、ORG 类型
|
||
└─ 支持会话状态（active/inactive）
|
||
|
||
自动重新登录
|
||
└─ 会话失效时自动重新登录
|
||
└─ 基于历史登录记录进行自动登录
|
||
└─ 自动登录成功后更新缓存
|
||
└─ 自动登录失败时抛出异常
|
||
└─ 记录自动登录的日志
|
||
```
|
||
|
||
## 业务规则
|
||
1. **缓存策略**：登录信息必须缓存到 Redis，设置过期时间为 2 小时
|
||
2. **缓存有效性校验**：使用缓存时必须校验有效性（检查 expirationTimestamp）
|
||
3. **Session ID 有效期**：通过成功登录后存入缓存中，设置过期时间，若是过期了，Redis 则没有 Session ID
|
||
4. **缓存过期时间戳**：在缓存中存储过期时间戳，使用前进行校验
|
||
5. **并发登录缓存键**：并发登录使用不同的缓存键区分源 org 和目标 org
|
||
6. **结构化缓存键**：缓存键格式为 `CURRENT_SOURCE_ORG_RESULT`（源 org）、`CURRENT_TARGET_ORG_RESULT`（目标 org）
|
||
7. **缓存刷新**：Salesforce 登录成功后，刷新当前系统中对于 org 配置名称加 org 类型的缓存
|
||
8. **缓存清理**：过期时 Redis 自动清理，或者登出接口清除当前缓存
|
||
9. **会话管理**：使用数据库表 `datai_sf_login_session` 管理会话信息
|
||
10. **会话状态**：支持会话状态（active/inactive）和最后活动时间管理
|
||
11. **会话有效性检查**：检查会话信息是否为 null、登录状态是否为成功、Session ID 是否为空、Session 是否过期
|
||
12. **自动重新登录**：会话失效时自动重新登录，基于历史登录记录进行自动登录
|
||
13. **自动登录失败处理**：自动登录失败时返回错误信息并抛出异常
|
||
14. **会话状态日志**：记录会话状态日志（会话为 null、登录状态为失败、Session 已过期）
|
||
|
||
## 接口需求
|
||
|
||
### 缓存管理接口
|
||
1. **获取缓存信息**
|
||
- 接口路径：GET /api/salesforce/cache/info
|
||
- 请求参数：userId、systemId、orgType
|
||
- 响应：缓存信息
|
||
|
||
2. **清除缓存**
|
||
- 接口路径：DELETE /api/salesforce/cache
|
||
- 请求参数：userId、systemId、orgType
|
||
- 响应：成功/失败
|
||
|
||
3. **刷新缓存**
|
||
- 接口路径：POST /api/salesforce/cache/refresh
|
||
- 请求参数：systemId、orgType
|
||
- 响应：成功/失败
|
||
|
||
### 会话管理接口
|
||
1. **查询会话信息列表**
|
||
- 接口路径：GET /api/salesforce/session/list
|
||
- 请求参数：分页参数、筛选参数
|
||
- 响应：会话信息列表
|
||
|
||
2. **导出会话信息列表**
|
||
- 接口路径：POST /api/salesforce/session/export
|
||
- 请求参数：筛选参数
|
||
- 响应：Excel 文件
|
||
|
||
3. **查询会话信息详情**
|
||
- 接口路径：GET /api/salesforce/session/{id}
|
||
- 响应：会话信息详情
|
||
|
||
4. **新增会话信息**
|
||
- 接口路径：POST /api/salesforce/session
|
||
- 请求参数：会话信息
|
||
- 响应：成功/失败
|
||
|
||
5. **修改会话信息**
|
||
- 接口路径：PUT /api/salesforce/session
|
||
- 请求参数：会话信息
|
||
- 响应：成功/失败
|
||
|
||
6. **删除会话信息**
|
||
- 接口路径：DELETE /api/salesforce/session/{ids}
|
||
- 请求参数：会话 ID 数组
|
||
- 响应：成功/失败
|
||
|
||
7. **根据 Session ID 查询会话信息**
|
||
- 接口路径：GET /api/salesforce/session/by-session-id/{sessionId}
|
||
- 响应：会话信息
|
||
|
||
8. **查询最近一条活跃的会话信息**
|
||
- 接口路径：GET /api/salesforce/session/latest-active
|
||
- 响应：会话信息
|
||
|
||
9. **根据 ORG 类型查询最近一条活跃的会话信息**
|
||
- 接口路径：GET /api/salesforce/session/latest-active/{orgType}
|
||
- 请求参数：orgType（S/T/ST）
|
||
- 响应：会话信息
|
||
|
||
### SessionManager 接口
|
||
1. **获取当前登录结果**
|
||
- 接口路径：GET /api/salesforce/session/current-login-result/{orgType}
|
||
- 请求参数：orgType（source/target）
|
||
- 响应：SalesforceLoginResult 会话信息
|
||
|
||
2. **获取当前 Session ID**
|
||
- 接口路径：GET /api/salesforce/session/current-session/{orgType}
|
||
- 请求参数：orgType（source/target）
|
||
- 响应：访问令牌
|
||
|
||
3. **获取实例 URL**
|
||
- 接口路径：GET /api/salesforce/session/instance-url/{orgType}
|
||
- 请求参数：orgType（source/target）
|
||
- 响应：实例 URL
|
||
|
||
4. **检查会话有效性**
|
||
- 接口路径：GET /api/salesforce/session/is-valid/{orgType}
|
||
- 请求参数：orgType（source/target）
|
||
- 响应：会话是否有效（true/false）
|
||
|
||
## 依赖关系
|
||
- 依赖 `2026-01-21-003-02`：策略模式登录
|
||
- 依赖 `2026-01-21-003-03`：登录历史
|
||
- 依赖 `datai-cache-redis` 模块
|
||
- 依赖 `datai-salesforce-common` 模块的 Salesforce API 封装
|
||
|
||
## 后续需求
|
||
- 2026-01-21-003-05：会话管理
|
||
- 2026-01-21-003-06：登录状态查询
|
||
- 2026-01-21-003-07：错误码映射
|