kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
develop
datai/datai-scenes/datai-scene-salesforce/docs/sessions/2026-02-02-002-01-session.md

18 KiB
Raw Permalink Blame History

会话记录 - Apex 连接管理（完整会话）

会话元数据

  • 需求编号：002-01
  • 需求名称：Apex 连接管理
  • 开始时间：2026-02-02
  • 结束时间：2026-02-02
  • 当前阶段：阶段 9：闭环复盘和接口文档
  • 状态：已完成

需求描述

实现 Salesforce Apex API 连接管理功能，包括：

  1. 连接工厂：创建和管理 SoapConnection 实例
  2. 会话头管理：设置和更新 SessionHeader
  3. 调用选项：配置 CallOptions 头部
  4. 调试头部：配置 DebuggingHeader 用于调试
  5. 字段截断头：配置 AllowFieldTruncationHeader
  6. 包版本头：配置 PackageVersionHeader
  7. 连接缓存：使用 AbstractConnectionFactory 提供的缓存机制

核心要求：

  • 固定使用 source org 类型
  • 继承 AbstractConnectionFactory
  • 集成 SessionManager 获取会话信息
  • 提供 RESTful API 接口

执行阶段

阶段 2：方案设计

  • 状态：已完成
  • 生成文档：设计文档
  • 关键决策：
    1. 连接工厂模式：继承 AbstractConnectionFactory，复用缓存机制
    2. 固定使用 source org：所有方法固定使用 source org 类型
    3. API 版本：使用 Salesforce API 65.0 版本
    4. 异常处理：使用 datai-salesforce-common 模块的现有异常类
    5. 缓存策略：使用 AbstractConnectionFactory 提供的 ConcurrentHashMap + ReentrantLock

阶段 3：方案决策（ADR）

  • 状态：已完成
  • 生成文档：决策记录
  • 关键决策：
    1. 选择方案 1：使用 AbstractConnectionFactory + SessionManager
    2. 与 Partner 模块保持一致
    3. 复用现有基础设施
    4. 开发效率高，维护成本低

阶段 4：数据库结构生成

  • 状态：跳过
  • 原因：本需求不涉及数据库变更
  • 分析结果：
    1. Apex 连接管理功能主要依赖 Salesforce 的外部 API，不需要本地数据库存储
    2. 会话信息通过 SessionManager 管理，存储在现有表中
    3. 连接信息通过 AbstractConnectionFactory 的内存缓存管理，不需要持久化
    4. 所有配置信息（如 API 版本、超时时间）通过代码或配置文件管理

阶段 5：提示词生成

  • 状态：已完成
  • 生成文档：提示词文档
  • 关键决策：
    1. 引用真源：需求文档、设计文档、决策记录
    2. 详细的需求描述：7 个核心功能点
    3. 完整的设计方案：模块结构、技术选型、包结构
    4. 明确的输出格式要求：必须包含的文件清单、REST API 接口列表
    5. 严格的代码规范要求：命名规范、注释规范、日志规范、异常处理
    6. 完整的测试要求：覆盖率、测试场景、测试框架
    7. 实现要点：代码示例、注意事项

阶段 6：执行代码生成

  • 状态：已完成
  • 生成代码文件：10 个 Java 文件
  • 关键决策：
    1. 不涉及数据库表新增，跳过代码生成器确认步骤
    2. 按照提示词要求生成所有代码文件
    3. 代码符合 Spring Boot 最佳实践
    4. 代码符合若依框架规范
    5. 代码包含完整的异常处理和日志记录

阶段 7：记录当前会话

  • 状态：已完成
  • 生成文档：无
  • 关键决策：完整记录了当前会话的所有信息

阶段 8：变更记录与归档

  • 状态：已完成
  • 生成文档：变更日志
  • 关键决策：
    1. 创建了完整的变更日志文档，记录所有变更内容
    2. 更新了根目录 CHANGELOG.md，添加了 Apex 连接管理的变更记录
    3. 更新了索引文件 docs/index.md，添加了变更日志链接
    4. 更新了需求文档，添加了变更日志引用
    5. 更新了会话记录，标记当前阶段为阶段 8

阶段 9：闭环复盘和接口文档

  • 状态：已完成
  • 生成文档：
  • 关键决策：
    1. 创建了完整的复盘文档，总结了成功经验、改进点、问题分析和行动计划
    2. 提取了 3 条有效的 Prompt 技巧和 3 个避免的坑
    3. 进行了模板迭代，明确了提示词模板的改进方向
    4. 创建了详细的 API 文档，包含 7 个接口的完整说明
    5. 更新了索引文件 docs/index.md，添加了复盘和 API 文档链接
    6. 更新了需求文档，添加了复盘和 API 文档引用

对话记录

2026-02-02 用户：继续 2026-02-02 AI：进入阶段 2：方案设计。基于需求文档 2026-01-28-002-01-连接管理.md 创建了详细的设计文档。 2026-02-02 AI：设计文档已创建：[链接]。内容是否达标？是否进入下一阶段？ 2026-02-02 用户：继续 2026-02-02 AI：进入阶段 3：方案决策。分析了 4 种技术方案，创建了 ADR 记录。 2026-02-02 AI：决策记录已创建：[链接]。决策是否合理？是否进入下一阶段？ 2026-02-02 用户：继续 2026-02-02 AI：进入阶段 4：数据库结构生成。分析需求是否涉及数据库变更。 2026-02-02 AI：本需求不涉及数据库变更，跳过阶段 4，直接进入阶段 5：提示词生成。 2026-02-02 AI：由于本需求不涉及数据库变更，是否直接进入下一阶段（阶段 5：提示词生成）？ 2026-02-02 用户：继续 2026-02-02 AI：进入阶段 5：提示词生成。基于需求文档、设计文档和决策记录创建了详细的提示词。 2026-02-02 AI：提示词已生成：[链接]。提示词是否合适？是否进入下一阶段（阶段 6：代码生成）？ 2026-02-02 用户：继续 2026-02-02 AI：进入阶段 6：执行代码生成。基于提示词生成了 10 个 Java 文件。 2026-02-02 AI：代码已生成：[文件列表]。代码是否正确？是否进入下一阶段（阶段 7：会话记录）？ 2026-02-02 用户：进入下一阶段（阶段 7：会话记录） 2026-02-02 AI：进入阶段 7：记录当前会话。完整记录当前会话的所有信息。 2026-02-02 用户：继续 2026-02-02 AI：进入阶段 8：变更记录与归档。基于会话记录创建了完整的变更日志。 2026-02-02 AI：变更日志已创建：docs/changelog/2026-02-02-002-01-changelog.md 2026-02-02 AI：CHANGELOG.md 已更新：CHANGELOG.md 2026-02-02 AI：索引已更新：docs/index.md 2026-02-02 AI：需求文档已更新：docs/requirements/sub/2026-01-28-002-01-连接管理.md 2026-02-02 AI：变更日志是否准确？是否进入下一阶段（阶段 9：闭环复盘和接口文档）？ 2026-02-02 用户：进入下一阶段（阶段 9：闭环复盘和接口文档） 2026-02-02 AI：进入阶段 9：闭环复盘和接口文档。基于变更记录创建了复盘文档和 API 文档。 2026-02-02 AI：复盘文档已创建：docs/retros/2026-02-02-002-01-retro.md 2026-02-02 AI：API 文档已创建：docs/api-docs/2026-02-02-002-01-api.md 2026-02-02 AI：索引已更新：docs/index.md 2026-02-02 AI：需求文档已更新：docs/requirements/sub/2026-01-28-002-01-连接管理.md 2026-02-02 AI：复盘和 API 文档是否完整？是否进入下一阶段（阶段 10：代码提交）？

生成的文档

阶段 2：方案设计

  1. 设计文档：docs/design/2026-02-02-002-01-连接管理-设计.md
    • 元数据
    • 设计概述
    • 架构设计（系统架构、模块架构、数据流设计）
    • 技术方案（技术选型、核心算法、集成方案）
    • 数据模型（DTO、VO 设计）
    • 接口设计（RESTful API、权限设计、接口文档）
    • 实现要点（关键实现逻辑、异常处理、性能优化、安全设计）

阶段 3：方案决策（ADR）

  1. 决策记录：docs/decisions/2026-02-02-002-01-ADR-Apex连接管理技术选型.md
    • 状态：已接受
    • 分析了 4 种技术方案：
      • 方案 1：使用 AbstractConnectionFactory + SessionManager（已选择）
      • 方案 2：自定义工厂模式
      • 方案 3：每次调用创建新连接
      • 方案 4：使用 Spring 的 Connection Pool
    • 详细记录了决策理由和后果

阶段 5：提示词生成

  1. 提示词文档：docs/prompts/2026-02-02-002-01-prompt-Apex连接管理.md
    • 引用真源（需求文档、设计文档、决策记录）
    • 详细的需求描述
    • 完整的设计方案
    • 明确的输出格式要求
    • 严格的代码规范要求
    • 完整的测试要求
    • 实现要点和代码示例

阶段 6：执行代码生成

  1. 代码文件：10 个 Java 文件
文件类型 文件路径 说明
Factory datai-salesforce-apex/src/main/java/com/datai/apex/factory/ApexConnectionFactory.java 连接工厂，继承 AbstractConnectionFactory
Service Interface datai-salesforce-apex/src/main/java/com/datai/apex/service/IApexConnectionService.java 服务接口，定义 7 个方法
Service Impl 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 个接口
DTO datai-salesforce-apex/src/main/java/com/datai/apex/model/dto/SetSessionHeaderDto.java 设置会话头请求参数
DTO datai-salesforce-apex/src/main/java/com/datai/apex/model/dto/SetCallOptionsDto.java 设置调用选项请求参数
DTO datai-salesforce-apex/src/main/java/com/datai/apex/model/dto/SetDebuggingHeaderDto.java 设置调试头部请求参数
DTO datai-salesforce-apex/src/main/java/com/datai/apex/model/dto/SetFieldTruncationHeaderDto.java 设置字段截断头请求参数
DTO datai-salesforce-apex/src/main/java/com/datai/apex/model/dto/SetPackageVersionHeaderDto.java 设置包版本头请求参数
VO datai-salesforce-apex/src/main/java/com/datai/apex/model/vo/ConnectionInfoVo.java 连接信息响应
  1. 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 - 清除连接缓存

生成的代码文件

Factory 层

  1. ApexConnectionFactory.java
    • 路径：datai-salesforce-apex/src/main/java/com/datai/apex/factory/ApexConnectionFactory.java
    • 功能：创建和管理 SoapConnection 实例
    • 特点：
      • 继承 AbstractConnectionFactory<SoapConnection>
      • 实现 createConnection() 方法
      • 实现 getConnectionType() 方法，返回 "apex"
      • 实现 isConnectionValid() 方法，验证连接有效性
      • 集成 SessionManager 获取会话信息
      • 使用 Salesforce API 65.0 版本
      • 连接超时 60 秒，读取超时 60 秒

Service 层

  1. IApexConnectionService.java

    • 路径：datai-salesforce-apex/src/main/java/com/datai/apex/service/IApexConnectionService.java
    • 功能：定义 7 个服务方法
    • 方法：
      • ConnectionInfoVo getConnection() - 获取连接信息
      • void setSessionHeader(SetSessionHeaderDto dto) - 设置会话头
      • void setCallOptions(SetCallOptionsDto dto) - 设置调用选项
      • void setDebuggingHeader(SetDebuggingHeaderDto dto) - 设置调试头部
      • void setFieldTruncationHeader(SetFieldTruncationHeaderDto dto) - 设置字段截断头
      • void setPackageVersionHeader(SetPackageVersionHeaderDto dto) - 设置包版本头
      • void clearConnection() - 清除连接缓存

  2. ApexConnectionServiceImpl.java

    • 路径：datai-salesforce-apex/src/main/java/com/datai/apex/service/impl/ApexConnectionServiceImpl.java
    • 功能：实现所有服务方法
    • 特点：
      • 固定使用 source org 类型
      • 注入 ApexConnectionFactory 和 SessionManager
      • 完整的异常处理
      • 详细的日志记录
      • 参数校验

Controller 层

  1. ApexConnectionController.java
    • 路径：datai-salesforce-apex/src/main/java/com/datai/apex/controller/ApexConnectionController.java
    • 功能：提供 7 个 REST API 接口
    • 特点：
      • 使用 @RestController 注解
      • 使用 @RequestMapping("/api/apex/connection") 定义基础路径
      • 使用 @Tag 注解定义 Swagger 文档
      • 使用 @Operation 注解定义接口文档
      • 使用 @PreAuthorize 注解进行权限控制
      • 使用 @Valid 注解进行参数校验
      • 统一的异常处理
      • 返回 AjaxResult 格式的响应

DTO 层

  1. SetSessionHeaderDto.java

    • 路径：datai-salesforce-apex/src/main/java/com/datai/apex/model/dto/SetSessionHeaderDto.java
    • 功能：设置会话头请求参数
    • 字段：sessionId（必填）

  2. SetCallOptionsDto.java

    • 路径：datai-salesforce-apex/src/main/java/com/datai/apex/model/dto/SetCallOptionsDto.java
    • 功能：设置调用选项请求参数
    • 字段：client（可选）

  3. SetDebuggingHeaderDto.java

    • 路径：datai-salesforce-apex/src/main/java/com/datai/apex/model/dto/SetDebuggingHeaderDto.java
    • 功能：设置调试头部请求参数
    • 字段：
      • logCategories（可选）- 日志分类数组
      • logType（可选）- 日志类型
    • 内部类：LogInfoDto - 日志信息

  4. SetFieldTruncationHeaderDto.java

    • 路径：datai-salesforce-apex/src/main/java/com/datai/apex/model/dto/SetFieldTruncationHeaderDto.java
    • 功能：设置字段截断头请求参数
    • 字段：allowFieldTruncation（可选）

  5. SetPackageVersionHeaderDto.java

    • 路径：datai-salesforce-apex/src/main/java/com/datai/apex/model/dto/SetPackageVersionHeaderDto.java
    • 功能：设置包版本头请求参数
    • 字段：packageVersions（可选）- 包版本数组
    • 内部类：PackageVersionDto - 包版本信息

VO 层

  1. ConnectionInfoVo.java
    • 路径：datai-salesforce-apex/src/main/java/com/datai/apex/model/vo/ConnectionInfoVo.java
    • 功能：连接信息响应
    • 字段：
      • sessionId - 会话 ID
      • serverUrl - 服务器 URL
      • success - 是否成功
      • errorMessage - 错误信息

关键决策

阶段 2：方案设计

  1. 连接工厂模式：继承 AbstractConnectionFactory，复用缓存机制
  2. 固定使用 source org：所有方法固定使用 source org 类型
  3. API 版本：使用 Salesforce API 65.0 版本
  4. 异常处理：使用 datai-salesforce-common 模块的现有异常类
  5. 缓存策略：使用 AbstractConnectionFactory 提供的 ConcurrentHashMap + ReentrantLock

阶段 3：方案决策（ADR）

  1. 技术选型：选择 AbstractConnectionFactory + SessionManager 方案
  2. 理由：
    • 复用现有基础设施，开发效率高
    • 与项目架构保持一致
    • 线程安全，性能优秀
    • 维护成本低
  3. 放弃方案：
    • 自定义工厂模式：开发成本高，与现有架构不一致
    • 每次调用创建新连接：性能差，不符合最佳实践
    • Spring Connection Pool：SoapConnection 不完全适用，开发成本高

阶段 4：数据库结构生成

  1. 决策：跳过此阶段
  2. 理由：
    • 本需求不涉及数据库变更
    • 会话信息通过 SessionManager 管理，存储在现有表中
    • 连接信息通过内存缓存管理，不需要持久化

阶段 5：提示词生成

  1. 提示词结构：引用真源、需求描述、设计方案、输出格式、代码规范、测试要求
  2. 输出格式：明确列出需要生成的文件和接口
  3. 代码规范：命名规范、注释规范、日志规范、异常处理
  4. 测试要求：覆盖率不低于 80%，包含正常和异常场景

阶段 6：执行代码生成

  1. 代码生成策略：不涉及数据库表新增，直接按照提示词生成所有代码
  2. 代码特点：
    • 符合 Spring Boot 最佳实践
    • 符合若依框架规范
    • 使用 Lombok 简化代码
    • 使用 Swagger 注解生成 API 文档
    • 使用 Spring Security 进行权限控制
    • 完整的异常处理和日志记录

回退记录

无

更新的索引文件

  1. docs/index.md：

    • 添加了设计文档链接
    • 添加了决策记录链接
    • 添加了提示词文档链接
    • 添加了会话记录链接

  2. docs/design/2026-02-02-002-01-连接管理-设计.md：

    • 添加了提示词文档链接
    • 添加了实现状态章节

  3. docs/requirements/sub/2026-01-28-002-01-连接管理.md：

    • 更新了相关文档链接（设计文档、决策记录、提示词文档）

待办事项

  • 创建设计文档
  • 更新索引文件
  • 创建决策记录（ADR）
  • 更新索引文件（ADR）
  • 更新设计文档（ADR 引用）
  • 更新会话记录
  • 分析数据库变更需求
  • 跳过阶段 4（不涉及数据库变更）
  • 创建提示词文档
  • 更新索引文件（提示词）
  • 更新需求文档（提示词引用）
  • 更新会话记录
  • 生成代码文件
  • 更新设计文档（实现状态）
  • 更新会话记录
  • 回顾整个会话过程
  • 识别关键决策和讨论点
  • 整理所有生成的文档和代码
  • 更新会话记录
  • 更新索引文件
  • 等待用户确认
  • 进入阶段 8：变更记录与归档

相关文档