datai/datai-scenes/datai-scene-salesforce/docs/decisions/adr/0012-org-config-management.md

架构决策记录 - Salesforce组织配置管理

背景

REQ-010-3 需要实现 Salesforce 组织配置的完整管理功能，包括：

1. 组织配置 CRUD 功能 - 支持多环境配置、分页查询、条件查询
2. OAuth 认证信息加密存储 - 使用 AES 加密算法，确保安全性
3. 环境类型管理 - 支持 Sandbox/Production 环境类型
4. 存储根路径配置 - 支持 OSS 和本地文件系统
5. 连接状态管理 - 支持 Active/Inactive/Auth_Invalid 状态
6. 配置验证功能 - 验证 OAuth 认证信息和连接可用性

这些功能需要基于现有的 Spring Boot 3 + Vue 3 技术栈，遵循 Authentication.canvas 中定义的架构和调用关系，使用 MyBatis Plus 作为持久层框架，使用现有的认证模块和 SessionManager 进行会话管理。

决策

1. 组织配置 CRUD 功能方案

决策: 使用 MyBatis Plus 的 BaseMapper 实现 CRUD，使用 @Valid 注解进行参数验证，使用 RESTful API 设计接口。

理由:

• MyBatis Plus 的 BaseMapper 提供了基础的 CRUD 方法，简化了开发
• @Valid 注解可以自动验证参数，提高代码质量和安全性
• RESTful API 设计符合业界标准，易于使用和扩展
• 支持分页查询和条件查询，满足业务需求

实现方案:

• 使用 MyBatis Plus 的 BaseMapper 提供基础的 CRUD 方法
• 使用 @Valid 注解进行参数验证
• 使用 RESTful API 设计接口，包括 GET、POST、PUT、DELETE 方法
• 使用 MyBatis Plus 的 QueryWrapper 实现条件查询
• 使用 MyBatis Plus 的分页插件实现分页查询

2. OAuth 认证信息加密存储方案

决策: 使用 Java Cryptography API 实现 AES 加密，使用 Base64 编码存储，使用配置文件存储加密密钥。

理由:

• Java Cryptography API 是 Java 标准库的一部分，无需引入额外依赖
• AES 加密算法是业界标准，安全性高，性能好
• Base64 编码可以将加密后的二进制数据转换为字符串，便于存储
• 使用配置文件存储加密密钥，便于管理和维护

实现方案:

• 使用 Java Cryptography API 实现 AES 加密
• 使用 AES/CBC/PKCS5Padding 加密模式
• 使用 256 位密钥，提高加密强度
• 使用 Base64 编码存储加密后的数据
• 使用配置文件存储加密密钥，密钥长度为 32 字节
• 创建 EncryptionUtil 工具类，提供加密和解密方法

3. 环境类型管理方案

决策: 使用 Java 枚举类型管理环境类型，使用 @EnumValue 注解映射数据库值。

理由:

• Java 枚举类型可以提供类型安全，避免使用魔法值
• @EnumValue 注解可以自动映射枚举值和数据库值
• 枚举类型可以提供友好的显示名称，提高用户体验

实现方案:

• 创建 EnvironmentType 枚举类，包含 SANDBOX 和 PRODUCTION 两个值
• 使用 @EnumValue 注解映射枚举值和数据库值
• 提供 getDisplayName() 方法，返回友好的显示名称
• 提供 fromCode() 方法，根据数据库值转换为枚举类型

4. 存储根路径配置方案

决策: 使用正则表达式验证路径格式，使用 File API 检查路径存在性，支持相对路径和绝对路径。

理由:

• 正则表达式可以灵活验证路径格式，支持多种路径格式
• File API 可以检查路径存在性，避免配置无效路径
• 支持相对路径和绝对路径，提高灵活性

实现方案:

• 使用正则表达式验证路径格式，支持 Windows 和 Unix 路径格式
• 使用 File API 检查路径存在性，如果路径不存在则创建
• 提供路径格式验证方法，返回详细的错误信息
• 支持相对路径和绝对路径，自动转换为绝对路径

5. 连接状态管理方案

决策: 使用 Java 枚举类型管理连接状态，使用状态机管理连接状态转移。

理由:

• Java 枚举类型可以提供类型安全，避免使用魔法值
• 状态机可以管理连接状态转移，确保状态一致性
• 枚举类型可以提供友好的显示名称，提高用户体验

实现方案:

• 创建 ConnectionStatus 枚举类，包含 ACTIVE、INACTIVE、AUTH_INVALID 三个值
• 使用 @EnumValue 注解映射枚举值和数据库值
• 提供 getDisplayName() 方法，返回友好的显示名称
• 提供 fromCode() 方法，根据数据库值转换为枚举类型
• 创建 ConnectionStateManager 类，使用状态机管理连接状态转移

6. 配置验证功能方案

决策: 使用 SessionManager 验证连接，使用正则表达式验证 OAuth 信息格式，使用异步验证提高性能。

理由:

• SessionManager 提供了连接验证功能，可以直接复用
• 正则表达式可以灵活验证 OAuth 信息格式
• 异步验证可以提高性能，避免阻塞主线程

实现方案:

• 使用 SessionManager 的连接验证功能，验证 OAuth 认证信息
• 使用正则表达式验证 OAuth 信息格式，包括 client_id、client_secret、username、password
• 提供异步验证方法，使用 @Async 注解实现异步执行
• 提供详细的验证错误信息，包括错误类型和错误位置
• 提供验证结果缓存，避免重复验证

备选方案

1. OAuth 认证信息加密存储备选方案

方案 A: 使用 Jasypt 加密库

• 优点: Jasypt 提供了简单易用的 API，支持多种加密算法
• 缺点: 需要引入额外依赖，增加了项目复杂度
• 不选择原因: Java Cryptography API 已经足够，无需引入额外依赖

方案 B: 使用 Spring Security Crypto 模块

• 优点: Spring Security Crypto 模块提供了简单的加密 API
• 缺点: 需要引入 Spring Security 依赖，增加了项目复杂度
• 不选择原因: Java Cryptography API 已经足够，无需引入额外依赖

2. 连接状态管理备选方案

方案 A: 使用数据库字段存储连接状态

• 优点: 简单直接，易于实现
• 缺点: 无法管理状态转移，可能导致状态不一致
• 不选择原因: 无法满足状态管理需求

方案 B: 使用 Redis 存储连接状态

• 优点: Redis 提供了高性能的键值存储，支持分布式部署
• 缺点: 需要引入 Redis 依赖，增加了项目复杂度
• 不选择原因: 当前项目不需要分布式部署，数据库存储足够

影响

系统架构影响

• 新增 EncryptionUtil 工具类，提供加密和解密方法
• 新增 EnvironmentType 枚举类，管理环境类型
• 新增 ConnectionStatus 枚举类，管理连接状态
• 新增 ConnectionStateManager 类，管理连接状态转移
• 新增 OrgConfigController 控制器，提供 RESTful API 接口
• 新增 IOrgConfigService 服务接口，定义组织配置服务接口
• 新增 OrgConfigServiceImpl 服务实现，实现组织配置服务
• 新增 IOrgConfigValidationService 服务接口，定义配置验证服务接口
• 新增 OrgConfigValidationServiceImpl 服务实现，实现配置验证服务

开发流程影响

• 需要编写单元测试，测试加密和解密功能
• 需要编写单元测试，测试枚举类型转换功能
• 需要编写单元测试，测试路径验证功能
• 需要编写单元测试，测试连接状态转移功能
• 需要编写单元测试，测试配置验证功能
• 需要编写集成测试，测试组织配置 CRUD 功能
• 需要编写集成测试，测试配置验证功能

运维管理影响

• 需要在配置文件中配置加密密钥
• 需要定期更换加密密钥，提高安全性
• 需要监控连接状态，及时发现连接问题
• 需要定期清理无效的配置，避免配置过多

风险

技术风险

• 加密密钥泄露风险: 加密密钥泄露可能导致 OAuth 认证信息泄露

  • 缓解措施: 使用配置文件存储加密密钥，限制配置文件访问权限，定期更换加密密钥

• 加密算法强度不足风险: 加密算法选择不当可能导致加密强度不足

  • 缓解措施: 使用 AES-256 加密算法，定期评估加密算法安全性

• 配置验证不准确风险: 配置验证逻辑复杂可能导致验证不准确

  • 缓解措施: 编写详细的单元测试，覆盖各种验证场景，定期审查验证逻辑

业务风险

• 多环境配置管理复杂风险: 多环境配置管理复杂可能导致配置混乱

  • 缓解措施: 提供清晰的配置管理界面，支持配置分组和标签，定期清理无效配置

• 连接状态管理不当风险: 连接状态管理不当可能导致状态不一致

  • 缓解措施: 使用状态机管理连接状态转移，提供状态转移日志，定期检查状态一致性

实施风险

• 开发周期延长风险: 功能复杂可能导致开发周期延长
  • 缓解措施: 分阶段实施，优先实现核心功能，逐步完善辅助功能

回滚策略

如果决策实施后出现问题，可以采取以下回滚策略：

1. 加密功能回滚: 如果加密功能出现问题，可以暂时关闭加密功能，使用明文存储 OAuth 认证信息，待问题解决后再启用加密功能

2. 连接状态管理回滚: 如果连接状态管理出现问题，可以暂时关闭连接状态管理，使用数据库字段存储连接状态，待问题解决后再启用连接状态管理

3. 配置验证功能回滚: 如果配置验证功能出现问题，可以暂时关闭配置验证功能，待问题解决后再启用配置验证功能

4. 整体回滚: 如果整个功能出现问题，可以删除新增的代码和文档，恢复到功能实现前的状态

验收标准

功能验收标准

• 组织配置 CRUD 功能正常工作，能够成功添加、编辑、删除、查询组织配置
• OAuth 认证信息加密存储成功，加密和解密功能正常工作
• 环境类型管理正常工作，能够正确选择和显示环境类型
• 存储根路径配置正常工作，能够正确配置和验证路径
• 连接状态管理正常工作，能够正确更新和显示连接状态
• 配置验证功能正常工作，能够正确验证 OAuth 认证信息和连接可用性

安全验收标准

• OAuth 认证信息加密存储，不存明文密码
• 加密算法符合安全标准，使用 AES-256 加密算法
• 加密密钥安全存储，限制配置文件访问权限

代码质量验收标准

• 代码符合项目编码规范，有清晰的注释
• 单元测试覆盖率不低于 80%
• 集成测试覆盖率不低于 60%
• 代码审查通过，没有严重的问题

性能验收标准

• 组织配置 CRUD 操作响应时间不超过 500ms
• 配置验证操作响应时间不超过 2s
• 加密和解密操作响应时间不超过 100ms

视觉锚点

Visual Reference

引用 Canvas 的具体节点或快照：

• Authentication.canvas - 相关架构图
• 具体节点: SessionManager - 会话管理，提供登录服务
• 具体节点: 集成核心 - 提供与Salesforce的各种连接方式

Status

• Draft
• Accepted
• Superceded

参考资料

列出与该决策相关的参考资料，包括文档、文章或其他资源：

• REQ-010-3.md - Salesforce组织配置管理需求文档
• REQ-010-1.md - 数据库表结构设计和创建
• REQ-010-2.md - 基础实体类和Mapper创建
• Authentication.canvas - 项目架构视觉化展示
• MyBatis Plus 官方文档 - MyBatis Plus 框架文档
• Java Cryptography Architecture - Java 加密架构文档