264 lines
12 KiB
Markdown
264 lines
12 KiB
Markdown
# 架构决策记录 - 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](../../Authentication.canvas) - 相关架构图
|
||
- **具体节点**: [SessionManager](node_session_manager_detail) - 会话管理，提供登录服务
|
||
- **具体节点**: [集成核心](node_integration_core) - 提供与Salesforce的各种连接方式
|
||
|
||
### Status
|
||
|
||
- [x] Draft
|
||
- [ ] Accepted
|
||
- [ ] Superceded
|
||
|
||
## 参考资料
|
||
|
||
列出与该决策相关的参考资料，包括文档、文章或其他资源：
|
||
|
||
- [REQ-010-3.md](../../requirements/REQ-010-3.md) - Salesforce组织配置管理需求文档
|
||
- [REQ-010-1.md](../../requirements/REQ-010-1.md) - 数据库表结构设计和创建
|
||
- [REQ-010-2.md](../../requirements/REQ-010-2.md) - 基础实体类和Mapper创建
|
||
- [Authentication.canvas](../../Authentication.canvas) - 项目架构视觉化展示
|
||
- [MyBatis Plus 官方文档](https://baomidou.com/) - MyBatis Plus 框架文档
|
||
- [Java Cryptography Architecture](https://docs.oracle.com/javase/8/docs/technotes/guides/security/crypto/CryptoSpec.html) - Java 加密架构文档
|