datai/docs/archive/sessions/2026-01-24-003-session.md

会话记录：从库数据源注解实现

元数据

• 需求编号：2026-01-24-003
• 创建时间：2026-01-24
• 创建人：SSOT 架构师
• 状态：进行中

阶段执行记录

阶段 1：需求定义

• 状态：已完成
• 需求文档：2026-01-24-003-从库数据源注解实现.md
• 关键决策：
  • 使用现有的 @DataSource 注解和 DataSourceType.SLAVE 枚举
  • 在 DataSourceAspect 切面中添加简单的路由逻辑
  • 从 SalesforceConfigCacheManager 获取当前激活环境
  • 根据当前激活环境的编码，构造从库数据源名称（如 slave_dev）
  • 如果从库数据源不存在，回退到主库数据源
  • 为 4 个 public 方法添加 @DataSource(DataSourceType.SLAVE) 注解

阶段 2：方案设计

• 状态：已完成
• 设计文档：2026-01-24-003-从库数据源注解实现.md
• 关键设计决策：
  • 系统架构：使用现有的 @DataSource 注解和 DataSourceAspect 切面，通过简单的路由逻辑实现从库数据源的自动切换
  • 模块架构：涉及 datai-common、datai-framework、datai-scenes-datai-scene-salesforce-datai-salesforce-setting、datai-scenes-datai-scene-salesforce-datai-salesforce-integration 四个模块
  • 数据流：Controller → Service → DataSourceAspect → SalesforceConfigCacheManager → DataSourceManager → Database
  • 技术选型：Spring AOP、Spring Framework、AspectJ、MyBatis Plus、Druid、Lombok
  • 核心算法：数据源路由算法，时间复杂度 O(1)，空间复杂度 O(1)
  • 集成方案：与 SalesforceConfigCacheManager、DataSourceManager、DynamicDataSourceContextHolder 集成
  • 异常处理：所有异常都应该被捕获并记录日志，从库数据源切换失败时，自动回退到主库数据源
  • 性能优化：利用 SalesforceConfigCacheManager 和 DataSourceManager 的缓存机制，避免频繁的数据源切换
  • 安全设计：确保从库数据源的访问权限正确配置，防止数据源切换导致的数据泄露
  • 需要添加注解的方法：8 个 public 方法，涵盖表结构创建、元数据同步、对象数据写入、实时同步

阶段 3：方案决策

• 状态：已完成
• 决策文档：2026-01-24-003-从库数据源注解实现-技术选型.md
• 关键决策：
  • 采用方案：扩展 @DataSource 注解 + DataSourceAspect 动态路由
  • 技术方案：修改 DataSourceAspect 切面，添加动态路由逻辑，从 SalesforceConfigCacheManager 获取当前激活环境编码，构造从库数据源名称，检查从库是否存在，存在则切换到从库，不存在则回退到主库
  • 备选方案：
    • 方案一：扩展 @DataSource 注解 + DataSourceAspect 动态路由（已选择）
    • 方案二：创建新的 @EnvironmentSlave 注解（未选择）
    • 方案三：在 Service 层手动切换数据源（未选择）
    • 方案四：使用自定义注解 + 自定义数据源路由器（未选择）
  • 影响分析：系统架构、开发流程、运维管理、性能等方面的影响分析
  • 风险评估：技术风险、业务风险、实施风险的识别和缓解措施
  • 验收标准：功能验收、性能验收、日志验收、测试验收

阶段 4：数据库结构

• 状态：已完成
• 关键决策：
  • 本需求不涉及数据库表结构的修改，不需要创建新的数据表
  • 不需要生成 SQL 脚本

阶段 5：提示词生成

• 状态：已完成
• 提示词文档：2026-01-24-003-prompt-从库数据源注解实现.md
• 关键内容：
  • 目标：基于现有的 @DataSource 注解和 DataSourceAspect 切面，实现从库数据源的动态切换功能
  • 输出格式：Java 代码、代码文件路径和文件名、修改说明、测试建议
  • 约束：技术栈限制、性能要求、安全性要求、兼容性要求、代码规范、异常处理
  • Rule Set：必须使用 Canvas 中定义的类名和方法名、必须遵循 Canvas 中定义的调用关系、必须参考 Canvas 中的流程图逻辑等 18 条具体规则
  • 验收标准：功能完整性、代码正确性、文档准确性、性能指标
  • 风险：输出质量风险、技术实现风险、时间成本风险、其他潜在风险

阶段 6：代码生成

• 状态：已完成

• 代码修改：

  • DataSourceAspect.java：

    • 文件路径：d:\idea_demo\datai\datai-framework\src\main\java\com\datai\framework\aspectj\DataSourceAspect.java
    • 修改内容：
      • 修改 around 方法，当检测到 DataSourceType.SLAVE 时，调用 getCurrentEnvironmentSlaveDataSourceName() 方法
      • 添加 getCurrentEnvironmentSlaveDataSourceName() 方法，实现动态路由逻辑
      • 添加 getCurrentEnvironmentCode() 方法，通过反射从 SalesforceConfigCacheManager Bean 中获取当前激活环境编码
      • 实现逻辑：通过反射调用 SalesforceConfigCacheManager.getCurrentEnvironmentCode() 方法获取当前激活环境编码，构造从库数据源名称，检查从库是否存在，存在则切换到从库，不存在则回退到主库

  • DataiIntegrationObjectServiceImpl.java：

    • 文件路径：d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-integration\src\main\java\com\datai\integration\service\impl\DataiIntegrationObjectServiceImpl.java
    • 修改内容：
      • 添加 @DataSource 和 DataSourceType 导入
      • 为 createObjectStructure(Integer id) 方法添加 @DataSource(DataSourceType.SLAVE) 注解
      • 为 syncSingleObjectData(Integer id) 方法添加 @DataSource(DataSourceType.SLAVE) 注解
      • 为 syncMultipleObjectData(Integer[] ids) 方法添加 @DataSource(DataSourceType.SLAVE) 注解

  • DataiIntegrationBatchServiceImpl.java：

    • 文件路径：d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-integration\src\main\java\com\datai\integration\service\impl\DataiIntegrationBatchServiceImpl.java
    • 修改内容：
      • 添加 @DataSource 和 DataSourceType 导入
      • 为 syncBatchData(Integer id) 方法添加 @DataSource(DataSourceType.SLAVE) 注解

  • DataiIntegrationMetadataChangeServiceImpl.java：

    • 文件路径：d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-integration\src\main\java\com\datai\integration\service\impl\DataiIntegrationMetadataChangeServiceImpl.java
    • 修改内容：
      • 添加 @DataSource 和 DataSourceType 导入
      • 为 syncToLocalDatabase(Long id) 方法添加 @DataSource(DataSourceType.SLAVE) 注解
      • 为 syncBatchToLocalDatabase(Long[] ids) 方法添加 @DataSource(DataSourceType.SLAVE) 注解

  • DataSynchronizerImpl.java：

    • 文件路径：d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-integration\src\main\java\com\datai\integration\realtime\impl\DataSynchronizerImpl.java
    • 修改内容：
      • 添加 @DataSource 和 DataSourceType 导入
      • 为 synchronizeData(String objectType, String recordId, String changeType, Map<String, Object> changeData, Date changeDate) 方法添加 @DataSource(DataSourceType.SLAVE) 注解
      • 为 batchSynchronizeData(List<SyncData> syncDataList) 方法添加 @DataSource(DataSourceType.SLAVE) 注解

• 测试建议：

  • 测试从库数据源存在时，成功切换到从库数据源
  • 测试从库数据源不存在时，成功回退到主库数据源
  • 测试环境编码为空时，成功回退到主库数据源
  • 测试数据源切换时间 < 10ms
  • 测试不影响业务方法的执行时间

阶段 7：会话记录

• 状态：已完成
• 记录内容：
  • 记录了从库数据源注解实现的完整开发过程
  • 记录了代码修改的详细信息和测试建议
  • 记录了技术实现的关键决策和优化过程
  • 记录了反射调用 SalesforceConfigCacheManager 的实现方式
  • 记录了性能优化的具体措施（缓存 Bean 和 Method 对象）

阶段 8：变更日志

• 状态：已完成
• 变更日志文档：2026-01-24-003-changelog.md
• 关键内容：
  • 记录了从库数据源注解实现的完整变更信息
  • 记录了 DataSourceAspect 动态路由的实现细节
  • 记录了 8 个方法的注解添加情况
  • 记录了技术特性、测试建议、兼容性说明、风险评估和后续优化建议

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

• 状态：已完成
• 复盘文档：2026-01-24-003-retro.md
• 关键内容：
  • 总结了从库数据源注解实现的完整开发过程
  • 分析了成功经验、改进点和问题
  • 制定了行动计划，旨在提高后续开发的效率和质量
  • 提取了有效的 Prompt 技巧和避免的坑
  • 对比了目标与实际产出，确认所有目标都已实现
• API 文档：2026-01-24-003-api-从库数据源注解实现.md
• 关键内容：
  • 记录了 8 个修改的内部方法
  • 记录了数据源切换逻辑、性能优化和降级机制
  • 记录了数据源命名规则和事务支持
  • 记录了使用示例和注意事项

阶段 10：代码提交

• 状态：已完成
• 提交信息：
  • Commit ID：2d8f9c0aa240aa45dcf47438bcce36dbc13b3b62
  • Commit Message：feat: 实现从库数据源注解功能 (REQ-003)
  • 变更统计：23 files changed, 2036 insertions(+), 307 deletions(-)
• 提交内容：
  • 扩展 @DataSource 注解，支持从库数据源的动态切换
  • 在 DataSourceAspect 切面中添加动态路由逻辑，通过反射调用 SalesforceConfigCacheManager.getCurrentEnvironmentCode() 方法获取当前激活环境编码
  • 构造从库数据源名称（slave_环境编码），检查从库是否存在，存在则切换到从库，不存在则回退到主库
  • 缓存 SalesforceConfigCacheManager Bean 和 getCurrentEnvironmentCode Method 对象，优化性能
  • 为 8 个方法添加 @DataSource(DataSourceType.SLAVE) 注解
  • 创建需求文档、设计文档、决策记录、提示词文档、会话记录、变更日志、复盘文档和 API 文档
  • 更新 CHANGELOG.md 和索引文档

关键技术点

1. @DataSource 注解

• 位置：com.datai.common.annotation.DataSource
• 支持枚举方式：DataSourceType.MASTER 或 DataSourceType.SLAVE
• 支持字符串方式：直接指定数据源名称
• 优先级：方法上的注解优先于类上的注解

2. DataSourceType 枚举

• 位置：com.datai.common.enums.DataSourceType
• 包含：MASTER、SLAVE

3. DataSourceAspect 切面

• 位置：com.datai.framework.aspectj.DataSourceAspect
• 需要修改：添加 SalesforceConfigCacheManager 依赖注入，添加 getCurrentEnvironmentSlaveDataSourceName 方法

4. SalesforceConfigCacheManager

• 位置：com.datai.setting.config.SalesforceConfigCacheManager
• 方法：getCurrentEnvironmentCode() - 获取当前激活环境编码

5. DataSourceManager

• 位置：com.datai.framework.manager.DataSourceManager
• 方法：isDataSourceLoaded(String dsName) - 检查数据源是否已加载

6. DynamicDataSourceContextHolder

• 位置：com.datai.framework.datasource.DynamicDataSourceContextHolder
• 方法：setDataSourceType(String dsType) - 设置数据源类型
• 方法：clearDataSourceType() - 清除数据源类型
• 特性：使用 ThreadLocal 维护数据源变量，支持嵌套数据源切换（使用 Stack 结构）

需要使用从库的方法列表

DataiIntegrationObjectServiceImpl

• createObjectStructure(Integer id) - 创建对象表结构
• syncSingleObjectData(Integer id) - 同步单个对象数据
• syncMultipleObjectData(Integer[] ids) - 同步多个对象数据

DataiIntegrationBatchServiceImpl

• syncBatchData(Integer id) - 同步批次数据

DataiIntegrationMetadataChangeServiceImpl

• syncToLocalDatabase(Long id) - 同步元数据变更到本地数据库
• syncBatchToLocalDatabase(Long[] ids) - 批量同步元数据变更到本地数据库

DataSynchronizerImpl

• synchronizeData(String objectType, String recordId, String changeType, Map<String, Object> changeData, Date changeDate) - 同步实时数据
• batchSynchronizeData(List<SyncData> syncDataList) - 批量同步实时数据

相关文档

• 需求文档
• 设计文档