11 KiB
11 KiB
变更日志 - Apex 连接管理
元数据
- 需求编号：002-01
- 需求名称：Apex 连接管理
- 创建时间：2026-02-02
- 创建人：AI Assistant
- 版本号：v1.0.0
变更概述
实现 Salesforce Apex API 连接管理功能，包括连接工厂、会话头管理、调用选项配置、调试头部配置、字段截断头配置、包版本头配置和连接缓存管理等功能。
变更内容
新增功能
1. 连接工厂功能
- 创建 ApexConnectionFactory 连接工厂类
- 继承 AbstractConnectionFactory，复用缓存机制
- 实现 createConnection() 方法，从 SessionManager 获取会话信息并创建连接
- 实现 getConnectionType() 方法，返回 "apex"
- 实现 isConnectionValid() 方法，验证连接有效性
- 使用 Salesforce API 65.0 版本
- 连接超时 60 秒，读取超时 60 秒
- 支持连接压缩
2. 连接管理服务
- 实现 IApexConnectionService 服务接口，定义 7 个核心方法
- 实现 ApexConnectionServiceImpl 服务实现类
- 固定使用 source org 类型
- 集成 SessionManager 获取会话信息
- 完整的异常处理和日志记录
- 参数校验和验证
3. 7 个核心服务方法
- getConnection() - 获取 SoapConnection 连接信息
- setSessionHeader() - 设置 SessionHeader
- setCallOptions() - 设置 CallOptions 头部
- setDebuggingHeader() - 设置 DebuggingHeader 用于调试
- setFieldTruncationHeader() - 设置 AllowFieldTruncationHeader
- setPackageVersionHeader() - 设置 PackageVersionHeader
- clearConnection() - 清除连接缓存
4. 7 个 REST API 接口
- GET /api/apex/connection - 获取连接
- POST /api/apex/connection/session-header - 设置会话头
- POST /api/apex/connection/call-options - 设置调用选项
- POST /api/apex/connection/debugging-header - 设置调试头部
- POST /api/apex/connection/field-truncation-header - 设置字段截断头
- POST /api/apex/connection/package-version-header - 设置包版本头
- DELETE /api/apex/connection/cache - 清除连接缓存
5. 数据传输对象（DTO）
- SetSessionHeaderDto - 设置会话头请求参数（sessionId）
- SetCallOptionsDto - 设置调用选项请求参数（client）
- SetDebuggingHeaderDto - 设置调试头部请求参数（logCategories、logType）
- SetFieldTruncationHeaderDto - 设置字段截断头请求参数（allowFieldTruncation）
- SetPackageVersionHeaderDto - 设置包版本头请求参数（packageVersions）
6. 视图对象（VO）
- ConnectionInfoVo - 连接信息响应（sessionId、serverUrl、success、errorMessage）
新增代码文件
Factory 层
datai-salesforce-apex/src/main/java/com/datai/apex/factory/ApexConnectionFactory.java- 连接工厂，继承 AbstractConnectionFactory
- 实现连接创建、验证和类型识别
- 集成 SessionManager 获取会话信息
Service 层
-
datai-salesforce-apex/src/main/java/com/datai/apex/service/IApexConnectionService.java- 服务接口，定义 7 个核心方法
- 使用 @Service 注解标记
-
datai-salesforce-apex/src/main/java/com/datai/apex/service/impl/ApexConnectionServiceImpl.java- 服务实现，实现所有服务方法
- 固定使用 source org 类型
- 完整的异常处理和日志记录
Controller 层
datai-salesforce-apex/src/main/java/com/datai/apex/controller/ApexConnectionController.java- REST API 控制器，提供 7 个接口
- 使用 @RestController、@RequestMapping、@Tag 注解
- 使用 @Operation 注解定义接口文档
- 使用 @PreAuthorize 注解进行权限控制
- 使用 @Valid 注解进行参数校验
- 统一的异常处理和 AjaxResult 响应
DTO 层
-
datai-salesforce-apex/src/main/java/com/datai/apex/model/dto/SetSessionHeaderDto.java- 设置会话头请求参数
- 字段：sessionId（必填）
-
datai-salesforce-apex/src/main/java/com/datai/apex/model/dto/SetCallOptionsDto.java- 设置调用选项请求参数
- 字段：client（可选）
-
datai-salesforce-apex/src/main/java/com/datai/apex/model/dto/SetDebuggingHeaderDto.java- 设置调试头部请求参数
- 字段：logCategories（可选）、logType（可选）
- 内部类：LogInfoDto - 日志信息
-
datai-salesforce-apex/src/main/java/com/datai/apex/model/dto/SetFieldTruncationHeaderDto.java- 设置字段截断头请求参数
- 字段：allowFieldTruncation（可选）
-
datai-salesforce-apex/src/main/java/com/datai/apex/model/dto/SetPackageVersionHeaderDto.java- 设置包版本头请求参数
- 字段：packageVersions（可选）
- 内部类：PackageVersionDto - 包版本信息
VO 层
datai-salesforce-apex/src/main/java/com/datai/apex/model/vo/ConnectionInfoVo.java- 连接信息响应
- 字段：sessionId、serverUrl、success、errorMessage
- 使用 @Builder 注解支持构建器模式
新增文档
设计文档
- 设计文档：docs/design/2026-02-02-002-01-连接管理-设计.md
- 元数据
- 设计概述
- 架构设计（系统架构、模块架构、数据流设计）
- 技术方案（技术选型、核心算法、集成方案）
- 数据模型（DTO、VO 设计）
- 接口设计（RESTful API、权限设计、接口文档）
- 实现要点（关键实现逻辑、异常处理、性能优化、安全设计）
决策记录
- 决策记录：docs/decisions/2026-02-02-002-01-ADR-Apex连接管理技术选型.md
- 状态：已接受
- 分析了 4 种技术方案
- 详细记录了决策理由和后果
提示词文档
- 提示词文档：docs/prompts/2026-02-02-002-01-prompt-Apex连接管理.md
- 引用真源（需求文档、设计文档、决策记录）
- 详细的需求描述
- 完整的设计方案
- 明确的输出格式要求
- 严格的代码规范要求
- 完整的测试要求
- 实现要点和代码示例
会话记录
- 会话记录：docs/sessions/2026-02-02-002-01-session.md
- 完整的会话元数据
- 详细的需求描述
- 所有执行阶段的状态和关键决策
- 完整的对话记录
- 所有生成的文档和代码文件列表
- 关键决策和理由
- 更新的索引文件清单
影响范围
模块级别
- 新增模块：
datai-salesforce-apex- Apex API 连接管理模块 - 依赖模块：
datai-salesforce-common- 使用现有的异常类和工具类datai-salesforce-integration- 使用 SessionManager 进行会话管理
文件级别
- 新增文件：10 个 Java 文件
- 新增文档：4 个 Markdown 文件
功能级别
- 新增功能：Salesforce Apex API 连接管理
- 新增接口：7 个 REST API 接口
相关文档
需求文档
设计文档
决策记录
提示词文档
会话记录
技术选型
核心技术
- 连接工厂模式：AbstractConnectionFactory + SessionManager
- API 版本：Salesforce API 65.0
- 缓存策略：ConcurrentHashMap + ReentrantLock
- 异常处理：使用 datai-salesforce-common 模块的现有异常类
框架和工具
- Spring Boot：应用框架
- Spring Security：权限控制
- Swagger：API 文档生成
- Lombok：代码简化
- SLF4J + Logback：日志记录
关键决策
阶段 2：方案设计
- 连接工厂模式：继承 AbstractConnectionFactory，复用缓存机制
- 固定使用 source org：所有方法固定使用 source org 类型
- API 版本：使用 Salesforce API 65.0 版本
- 异常处理：使用 datai-salesforce-common 模块的现有异常类
- 缓存策略：使用 AbstractConnectionFactory 提供的 ConcurrentHashMap + ReentrantLock
阶段 3：方案决策（ADR）
- 技术选型：选择 AbstractConnectionFactory + SessionManager 方案
- 理由：
- 复用现有基础设施，开发效率高
- 与项目架构保持一致
- 线程安全，性能优秀
- 维护成本低
- 放弃方案：
- 自定义工厂模式：开发成本高，与现有架构不一致
- 每次调用创建新连接：性能差，不符合最佳实践
- Spring Connection Pool：SoapConnection 不完全适用，开发成本高
阶段 4：数据库结构生成
- 决策：跳过此阶段
- 理由：
- 本需求不涉及数据库变更
- 会话信息通过 SessionManager 管理，存储在现有表中
- 连接信息通过内存缓存管理，不需要持久化
阶段 5：提示词生成
- 提示词结构：引用真源、需求描述、设计方案、输出格式、代码规范、测试要求
- 输出格式：明确列出需要生成的文件和接口
- 代码规范：命名规范、注释规范、日志规范、异常处理
- 测试要求：覆盖率不低于 80%，包含正常和异常场景
阶段 6：执行代码生成
- 代码生成策略：不涉及数据库表新增，直接按照提示词生成所有代码
- 代码特点：
- 符合 Spring Boot 最佳实践
- 符合若依框架规范
- 使用 Lombok 简化代码
- 使用 Swagger 注解生成 API 文档
- 使用 Spring Security 进行权限控制
- 完整的异常处理和日志记录
性能优化
连接缓存
- 使用 AbstractConnectionFactory 提供的缓存机制
- 使用 ConcurrentHashMap 保证线程安全
- 使用 ReentrantLock 保证连接创建的原子性
- 连接验证机制，确保缓存连接的有效性
连接复用
- 同一 org 类型的连接复用，减少连接创建开销
- 连接超时配置（60 秒），避免长时间占用资源
安全设计
权限控制
- 使用 Spring Security 进行权限控制
- 使用 @PreAuthorize 注解进行方法级权限控制
- 权限标识：apex:connection:get、apex:connection:session-header、apex:connection:call-options 等
参数校验
- 使用 @Valid 注解进行参数校验
- 使用 @NotNull、@NotBlank 等注解进行字段级校验
异常处理
- 完整的异常处理机制
- 使用统一的异常类（SalesforceAuthException、SalesforceOperationException）
- 详细的错误日志记录
测试要求
单元测试
- 覆盖率不低于 80%
- 包含正常场景和异常场景
- 使用 JUnit 5 + Mockito
集成测试
- 测试与 SessionManager 的集成
- 测试与 Salesforce API 的集成
- 测试 REST API 接口
已知问题
无
后续计划
- 编写单元测试和集成测试
- 编写 API 文档
- 进行性能测试和优化
- 进行安全测试和加固