kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
13c66c20dd
datai/docs/requirements/2026-01-21-003-05-salesforce-session-management.md

12 KiB
Raw Blame History

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