datai/docs/requirements/2026-01-21-003-04-salesforce-cache-optimization.md

# 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：错误码映射