datai/docs/archive/sessions/2026-01-26-010-3-session.md

会话记录

元数据

• 需求编号：010-3
• 开始时间：2026-01-26 16:30:00
• 结束时间：2026-01-26 17:00:00
• 当前阶段：阶段 2：方案设计

需求澄清记录

需求分析 (REQ-010-3)

用户要求对 REQ-010-3 进入阶段 2：方案设计。

需求分析

通过阅读 REQ-010-3.md 需求文档，确认了以下核心需求：

1. 组织配置CRUD功能：实现Salesforce组织配置的增删改查，支持多环境配置。
2. OAuth认证信息加密存储：使用AES加密算法加密OAuth认证信息，确保安全性。
3. 环境类型管理：支持Sandbox/Production环境类型选择和管理。
4. 存储配置：支持多种存储渠道（local/minio/oss）的灵活配置。
5. 连接状态管理：实现连接状态管理（Active/Inactive/Auth_Invalid）。
6. 配置验证功能：验证OAuth认证信息和连接可用性。

技术约束分析

• 技术栈限制：必须基于现有的Spring Boot 3 + Vue 3技术栈
• 架构约束：必须遵循Authentication.canvas中定义的架构和调用关系
• 模块约束：必须在datai-salesforce-metadata模块下实现
• 数据库约束：必须使用MyBatis Plus作为持久层框架
• 认证约束：必须使用现有的认证模块和SessionManager进行会话管理
• 安全约束：OAuth认证信息必须加密存储，不存明文密码；存储配置中的敏感信息必须加密存储
• API约束：必须使用现有的集成核心功能进行Salesforce API调用
• 存储约束：必须使用datai-scene-file模块提供的StorageBucket抽象接口和StorageUtils工具类

阶段 1：需求定义

• 状态：已完成
• 输出文档：
  • REQ-010-3.md - Salesforce组织配置管理需求文档

阶段 2：方案设计

• 状态：已完成
• 设计内容：
  • 系统架构设计：设计了包含Controller、Service、Mapper、Entity的分层架构，以及与StorageBucket接口、SessionManager的集成关系
  • 技术方案设计：
    • OAuth认证信息加密方案：使用AES-256-CBC算法，密钥长度256位，填充模式PKCS5Padding
    • 存储配置方案：集成datai-scene-file模块的StorageBucket接口，支持local/minio/oss三种存储类型
    • 连接验证方案：使用SessionManager验证连接，更新连接状态
  • 数据模型设计：
    • 数据库表设计：datai_meta_org_config表，包含17个字段，5个索引
    • 实体类设计：DataiMetaOrgConfig实体类，使用Lombok注解，继承BaseEntity
    • 枚举类型设计：EnvironmentType、StorageType、ConnectionStatus三个枚举类型
    • 数据字典设计：sf_environment_type、sf_storage_type、sf_connection_status三个字典类型
  • 接口设计：
    • RESTful API设计：8个接口（list、getInfo、add、edit、remove、batchRemove、validate、switchPrimary）
    • 接口权限设计：使用@PreAuthorize注解进行方法级权限控制
    • 接口文档设计：使用Swagger注解自动生成API文档
  • 实现要点设计：
    • 关键实现逻辑：OAuth认证信息加密存储、存储配置验证、连接验证
    • 异常处理设计：CryptoException、StorageConnectionException、ConnectionValidationException、ValidationException
    • 性能优化设计：数据库索引优化、分页查询优化、缓存优化、敏感字段查询优化
    • 安全设计：数据加密、权限控制、防注入（SQL注入、XSS攻击）
• 重要更新：
  • 实体类位置：DataiMetaOrgConfig 位于 datai-salesforce-metadata 模块（与实际实现保持一致）
  • 表名：datai_meta_org_config，遵循元数据模块命名规范
  • 职责说明：与 datai_sf_login_history 表职责不同，不可合并
  • 引用关系：datai_meta_task 表通过 org_config_id 外键引用此表
• 输出文档：
  • 2026-01-26-010-3-Salesforce组织配置管理设计.md - Salesforce组织配置管理设计文档（已更新）

阶段 3：方案决策

• 状态：已完成
• 决策内容：

  • 决策点1：OAuth认证信息加密方案

    • 方案1：AES-256-CBC（推荐方案）
      • 优点：安全性高，使用256位密钥；广泛使用，社区支持好；Java Cryptography API原生支持；性能较好，适合大量数据加密
      • 缺点：密钥管理复杂，需要安全存储；需要处理初始化向量（IV）；填充模式可能影响性能
    • 方案2：RSA非对称加密
      • 优点：密钥管理简单，公钥加密，私钥解密；不需要处理初始化向量；安全性高，基于大数分解难题
      • 缺点：加密速度慢，不适合大量数据；密钥长度较长，占用存储空间大；Java Cryptography API支持相对复杂
    • 最终决策：选择AES-256-CBC算法，与已有ADR-0012记录保持一致

  • 决策点2：存储配置方案

    • 方案1：集成datai-scene-file模块的StorageBucket接口（推荐方案）
      • 优点：复用现有模块，减少重复开发；统一存储抽象，易于扩展；支持多种存储类型（local、minio、oss）；代码复用性高，维护成本低
      • 缺点：依赖外部模块，增加耦合度；需要了解StorageBucket接口的使用方法；可能存在版本兼容性问题
    • 方案2：自定义存储抽象接口
      • 优点：完全自主控制，不受外部模块限制；可以根据项目需求定制接口；减少外部依赖
      • 缺点：需要重新开发和维护存储抽象；增加开发成本和时间；可能与datai-scene-file模块功能重复
    • 最终决策：选择集成datai-scene-file模块的StorageBucket接口，复用现有模块，减少重复开发

  • 决策点3：连接验证方案

    • 方案1：使用SessionManager验证连接（推荐方案）
      • 优点：复用现有SessionManager，减少重复开发；统一会话管理，易于维护；支持多种认证方式
      • 缺点：依赖SessionManager的实现；可能需要修改SessionManager以支持新功能
    • 方案2：自定义连接验证逻辑
      • 优点：完全自主控制，不受外部限制；可以根据项目需求定制验证逻辑；减少外部依赖
      • 缺点：需要重新开发和维护验证逻辑；增加开发成本和时间；可能与SessionManager功能重复
    • 最终决策：选择使用SessionManager验证连接，与已有ADR-0012记录保持一致

  • 冲突检查：搜索已有ADR记录，发现ADR-0012-org-config-management.md已记录OAuth认证信息加密方案和连接验证方案，当前设计是对其细化和补充；存储配置方案与已有ADR记录存在冲突，已创建新的ADR记录记录该决策

  • ADR记录检查结果：

    • ADR-0012-org-config-management.md：记录了OAuth认证信息加密方案（AES-256-CBC）和连接验证方案（使用SessionManager）
    • 2026-01-26-010-3-ADR-Salesforce组织配置管理存储方案.md：记录了存储配置方案（集成datai-scene-file模块的StorageBucket接口）
    • 结论：所有三个关键决策点都已经有对应的ADR记录，且与当前设计文档一致，无需创建新的ADR记录
• 输出文档：
  • ADR-0012-org-config-management.md - Salesforce组织配置管理架构决策
  • 2026-01-26-010-3-ADR-Salesforce组织配置管理存储方案.md - Salesforce组织配置管理存储方案决策记录

阶段 4：数据库结构

• 状态：已完成
• 数据库变更分析：
  • 涉及数据库变更：是
  • 需要创建的表：datai_meta_org_config（Salesforce组织配置表）
  • 需要插入的数据：
    • sys_dict_type：3个字典类型（meta_org_type、meta_auth_type、meta_connection_status）
    • sys_dict_data：8个字典数据（3个组织类型、2个认证类型、3个连接状态）
  • 需要创建的索引：3个索引（1个主键索引、1个唯一索引、1个普通索引）
• 重要更新：
  • 表名：datai_meta_org_config，遵循元数据模块命名规范，与实际实现保持一致
  • 字段调整：移除了storage_type、storage_config、connection_status、is_primary字段，因为这些字段不在实际实现中
  • 字典类型：移除了meta_storage_type，因为实际实现中不涉及存储类型配置
  • 版本：v4.0（更新：表名从 datai_sf_org_config 改为 datai_meta_org_config，与实际实现保持一致）
• 输出文档：
  • 2026-01-26-010-3-Salesforce组织配置管理.sql - Salesforce组织配置管理SQL脚本（v4.0）

阶段 5：提示词生成

• 状态：已完成
• 提示词内容摘要：
  • 引用真源：需求文档、设计文档、决策记录、SQL脚本
  • 需求描述：组织配置CRUD功能、OAuth认证信息加密存储、组织类型管理、认证类型管理、连接状态管理、配置验证功能、令牌管理
  • 设计方案：Spring Boot 3 + MyBatis Plus + Spring Security 6 + Lombok + Swagger；AES-256-CBC加密算法；使用SessionManager验证连接；实体类位于 datai-salesforce-metadata 模块
  • 输出格式要求：必须包含Entity、Mapper、Service、Controller、DTO、VO、枚举类型、工具类；必须包含单元测试；必须符合Spring Boot最佳实践；必须遵循若依框架规范；必须使用MyBatis Plus进行数据库操作
  • 代码规范要求：类命名、方法命名、变量命名、常量命名、注释规范、代码格式、导入规范
  • 测试要求：单元测试覆盖率不低于80%；测试用例包含CRUD功能、OAuth认证信息加密、连接验证、异常场景；使用JUnit 5和Mockito进行测试；测试用例命名规范
  • 注意事项：实体类必须位于 datai-salesforce-metadata 模块；表名必须使用 datai_meta_org_config；使用SessionManager进行连接验证；使用AES-256-CBC算法加密OAuth认证信息；使用@TableField(select = false)注解避免敏感字段被查询；使用@PreAuthorize注解进行方法级权限控制；使用@Valid注解进行参数验证；使用@Log注解记录操作日志；遵循若依框架规范；处理异常情况；使用枚举类型管理组织类型、认证类型、连接状态；使用MyBatis Plus的BaseMapper提供的CRUD方法；使用QueryWrapper实现条件查询；使用Page实现分页查询；使用Lombok注解简化代码；使用Swagger注解自动生成API文档
• 重要更新：
  • 实体类位置：DataiMetaOrgConfig 位于 datai-salesforce-metadata 模块，与实际实现保持一致
  • 表名：datai_meta_org_config，遵循元数据模块命名规范
  • 移除内容：移除了存储配置相关内容（storage_type、storage_config、StorageType枚举），因为实际实现中不涉及存储配置
  • 决策记录更新：引用了 ADR-0012-org-config-management.md，而不是 2026-01-26-010-3-ADR-Salesforce组织配置管理存储方案.md
• 输出文档：
  • 2026-01-26-010-3-prompt-Salesforce组织配置管理.md - Salesforce组织配置管理实现提示词（已更新）

阶段 5.5：架构重构决策

• 状态：已完成
• 重构原因：
  • 问题发现：DataiMetaOrgConfig 实体类位于 datai-salesforce-metadata 模块，但 setting 和 auth 模块需要使用该实体类，会造成循环依赖（metadata → auth → setting → metadata）
  • 模块依赖关系：datai-salesforce-setting（基础配置模块）→ datai-salesforce-auth（认证模块）→ datai-salesforce-metadata（元数据模块）
  • 架构原则：遵循模块依赖关系，避免循环依赖，确保模块职责清晰
• 重构决策：
  • 删除：删除 metadata 模块中的 DataiMetaOrgConfig 实体类
  • 创建：在 setting 模块中创建 DataiSfOrgConfig 实体类
  • 重命名：将表名从 datai_meta_org_config 改为 datai_sf_org_config
  • 更新：更新设计文档、提示词文档、SQL脚本，反映实体类位置和名称的变化
• 重构内容：
  • 实体类迁移：
    • 删除：datai-salesforce-metadata/src/main/java/com/datai/metadata/model/domain/DataiMetaOrgConfig.java
    • 创建：datai-salesforce-setting/src/main/java/com/datai/setting/model/domain/DataiSfOrgConfig.java
  • SQL脚本更新：
    • 表名：datai_meta_org_config → datai_sf_org_config
    • 版本：v2.0 → v3.0
    • 说明：重构：将表名从 datai_meta_org_config 改为 datai_sf_org_config，实体类从 metadata 模块迁移到 setting 模块
  • 设计文档更新：
    • 模块架构：datai-salesforce-metadata → datai-salesforce-setting
    • 实体类名称：DataiMetaOrgConfig → DataiSfOrgConfig
    • 表名：datai_meta_org_config → datai_sf_org_config
    • 接口路径：/metadata/metaconfig → /setting/sforgconfig
    • 权限标识：metadata:orgconfig → setting:sforgconfig
  • 提示词文档更新：
    • 文件路径：datai-salesforce-metadata → datai-salesforce-setting
    • 类名：DataiMetaOrgConfig → DataiSfOrgConfig
• 架构优势：
  • 避免循环依赖：setting 模块作为基础配置模块，不依赖其他模块
  • 职责清晰：setting 模块负责全局配置管理，auth 模块负责认证，metadata 模块负责元数据管理
  • 易于维护：模块依赖关系清晰，便于后续扩展和维护
  • 符合设计原则：遵循依赖倒置原则，高层模块不依赖低层模块，都依赖抽象
• 输出文档：
  • DataiSfOrgConfig.java - Salesforce组织配置实体类（setting模块）
  • 2026-01-26-010-3-Salesforce组织配置管理.sql - Salesforce组织配置管理SQL脚本（v3.0）
  • 2026-01-26-010-3-Salesforce组织配置管理设计.md - Salesforce组织配置管理设计文档（已更新）
  • 2026-01-26-010-3-prompt-Salesforce组织配置管理.md - Salesforce组织配置管理实现提示词（已更新）

阶段 6：代码生成

• 状态：待开始

阶段 7：会话记录

• 状态：待开始

阶段 8：变更日志

• 状态：待开始

阶段 9：复盘和接口

• 状态：待开始

阶段 10：代码提交

• 状态：待开始

关键设计决策

1. OAuth加密方案：选择AES-256-CBC算法，密钥长度256位，填充模式PKCS5Padding，使用Base64编码存储密文
2. 存储配置方案：集成datai-scene-file模块的StorageBucket接口，支持local/minio/oss三种存储类型，使用StorageUtils工具类管理存储渠道选择和切换
3. 连接验证方案：使用SessionManager验证连接，更新连接状态为Active/Inactive/Auth_Invalid
4. 枚举类型设计：使用Java枚举类型，使用@EnumValue注解映射数据库值，提供友好的描述信息
5. 敏感字段保护：使用@TableField(select = false)注解避免敏感字段被查询，只在需要时才解密敏感字段

遇到的问题

无

解决方案

无

经验教训

1. 设计文档完整性：设计文档必须包含所有必需章节（元数据、设计概述、架构设计、技术方案、数据模型、接口设计、实现要点、相关文档）
2. 技术选型合理性：技术选型必须充分考虑性能、安全性、可维护性等因素，并提供充分的选择理由
3. 接口设计规范性：接口设计必须符合RESTful规范，使用正确的HTTP方法和URL路径
4. 数据模型设计：数据模型设计必须考虑数据库规范，包括字段类型、长度、必填、默认值、索引等
5. 安全设计重要性：安全设计必须贯穿整个设计过程，包括数据加密、权限控制、防注入等