212 lines
7.5 KiB
Markdown
212 lines
7.5 KiB
Markdown
|
# ADR-0012: Salesforce组织配置管理架构决策
|
|||
|
|
|
|||
|
|
## 背景
|
|||
|
|
|
|||
|
|
REQ-010-3 需求要求实现 Salesforce 组织配置的完整管理功能，包括配置的增删改查、OAuth 认证信息加密存储、环境类型管理、存储路径配置、连接状态管理等。该功能是元数据拉取和部署系统的基础，需要确保配置信息的安全性和可靠性。
|
|||
|
|
|
|||
|
|
## 决策
|
|||
|
|
|
|||
|
|
### 1. 分层架构设计
|
|||
|
|
|
|||
|
|
采用标准的 Controller-Service-Mapper 三层架构：
|
|||
|
|
|
|||
|
|
- **Controller 层**: `DataiMetaOrgConfigController` - 处理 HTTP 请求，参数验证，响应封装
|
|||
|
|
- **Service 层**: `DataiMetaOrgConfigService` 接口 + `DataiMetaOrgConfigServiceImpl` 实现 - 业务逻辑处理
|
|||
|
|
- **Mapper 层**: `DataiMetaOrgConfigMapper` - 数据库操作，继承 MyBatis Plus 的 `BaseMapper`
|
|||
|
|
|
|||
|
|
### 2. OAuth 认证信息加密方案
|
|||
|
|
|
|||
|
|
使用 AES-256-CBC 加密算法：
|
|||
|
|
|
|||
|
|
- **加密算法**: AES-256-CBC
|
|||
|
|
- **密钥管理**: 使用配置文件中的加密密钥，密钥长度 256 位
|
|||
|
|
- **编码方式**: Base64 编码存储加密后的数据
|
|||
|
|
- **加密工具类**: 创建 `EncryptionUtil` 工具类，提供加密和解密方法
|
|||
|
|
- **加密字段**: `auth_config` 字段中的 OAuth 认证信息（client_id、client_secret、refresh_token 等）
|
|||
|
|
|
|||
|
|
### 3. 环境类型和连接状态管理
|
|||
|
|
|
|||
|
|
使用 Java 枚举类型：
|
|||
|
|
|
|||
|
|
- **环境类型枚举**: `EnvironmentType` (SANDBOX, PRODUCTION)
|
|||
|
|
- **连接状态枚举**: `ConnectionStatus` (ACTIVE, INACTIVE, AUTH_INVALID)
|
|||
|
|
- **数据库映射**: 使用 MyBatis Plus 的 `@EnumValue` 注解映射枚举值到数据库
|
|||
|
|
|
|||
|
|
### 4. 存储路径配置和验证
|
|||
|
|
|
|||
|
|
- **路径格式验证**: 使用正则表达式验证路径格式
|
|||
|
|
- **路径存在性检查**: 使用 Java `File` API 检查本地路径是否存在
|
|||
|
|
- **OSS 配置**: 支持 OSS 存储配置，使用 `@TableField` 注解处理 JSON 字段
|
|||
|
|
- **路径类型**: 支持相对路径和绝对路径
|
|||
|
|
|
|||
|
|
### 5. 配置验证功能
|
|||
|
|
|
|||
|
|
- **验证时机**: 在创建和更新配置时进行验证
|
|||
|
|
- **验证内容**:
|
|||
|
|
- OAuth 认证信息格式验证
|
|||
|
|
- 存储路径存在性验证
|
|||
|
|
- 连接可用性验证（使用 SessionManager）
|
|||
|
|
- **验证结果**: 返回详细的验证错误信息
|
|||
|
|
|
|||
|
|
### 6. API 接口设计
|
|||
|
|
|
|||
|
|
遵循 RESTful API 设计规范：
|
|||
|
|
|
|||
|
|
- `POST /api/metadata/org-config` - 创建组织配置
|
|||
|
|
- `PUT /api/metadata/org-config/{id}` - 更新组织配置
|
|||
|
|
- `DELETE /api/metadata/org-config/{id}` - 删除组织配置
|
|||
|
|
- `GET /api/metadata/org-config/{id}` - 查询组织配置详情
|
|||
|
|
- `GET /api/metadata/org-config` - 查询组织配置列表（支持分页和条件查询）
|
|||
|
|
- `POST /api/metadata/org-config/{id}/validate` - 验证组织配置
|
|||
|
|
|
|||
|
|
## 备选方案
|
|||
|
|
|
|||
|
|
### 方案 1: 使用 JPA/Hibernate
|
|||
|
|
|
|||
|
|
**优点**:
|
|||
|
|
- 标准 JPA 规范，可移植性好
|
|||
|
|
- 自动生成 DDL
|
|||
|
|
- 强类型查询
|
|||
|
|
|
|||
|
|
**缺点**:
|
|||
|
|
- 学习曲线较陡
|
|||
|
|
- 性能不如 MyBatis Plus
|
|||
|
|
- 与现有技术栈不一致
|
|||
|
|
|
|||
|
|
**选择原因**: 不选择，因为项目已经使用 MyBatis Plus，保持技术栈一致性更重要。
|
|||
|
|
|
|||
|
|
### 方案 2: 使用 RSA 加密算法
|
|||
|
|
|
|||
|
|
**优点**:
|
|||
|
|
- 非对称加密，安全性更高
|
|||
|
|
- 密钥管理更灵活
|
|||
|
|
|
|||
|
|
**缺点**:
|
|||
|
|
- 加密解密性能较差
|
|||
|
|
- 密钥管理复杂
|
|||
|
|
- 对于配置信息存储来说，安全性要求不需要这么高
|
|||
|
|
|
|||
|
|
**选择原因**: 不选择，AES-256 加密已经足够安全，且性能更好。
|
|||
|
|
|
|||
|
|
### 方案 3: 使用数据库加密函数
|
|||
|
|
|
|||
|
|
**优点**:
|
|||
|
|
- 加密解密在数据库层完成
|
|||
|
|
- 应用层无需处理加密逻辑
|
|||
|
|
|
|||
|
|
**缺点**:
|
|||
|
|
- 依赖数据库特定功能
|
|||
|
|
- 可移植性差
|
|||
|
|
- 密钥管理复杂
|
|||
|
|
|
|||
|
|
**选择原因**: 不选择，应用层加密更灵活，不依赖数据库特定功能。
|
|||
|
|
|
|||
|
|
## 影响
|
|||
|
|
|
|||
|
|
### 架构影响
|
|||
|
|
|
|||
|
|
- 引入新的 Controller、Service、Mapper 层
|
|||
|
|
- 引入加密工具类
|
|||
|
|
- 引入枚举类型管理环境类型和连接状态
|
|||
|
|
- 遵循现有的三层架构模式
|
|||
|
|
|
|||
|
|
### 开发影响
|
|||
|
|
|
|||
|
|
- 需要实现 6 个 API 接口
|
|||
|
|
- 需要实现配置验证逻辑
|
|||
|
|
- 需要实现加密解密功能
|
|||
|
|
- 需要编写单元测试和集成测试
|
|||
|
|
|
|||
|
|
### 运维影响
|
|||
|
|
|
|||
|
|
- 需要配置加密密钥
|
|||
|
|
- 需要配置存储路径
|
|||
|
|
- 需要监控连接状态
|
|||
|
|
- 需要定期审计配置信息
|
|||
|
|
|
|||
|
|
## 风险
|
|||
|
|
|
|||
|
|
### 技术风险
|
|||
|
|
|
|||
|
|
- **加密密钥泄露**: 如果加密密钥泄露，可能导致 OAuth 认证信息泄露
|
|||
|
|
- **缓解措施**: 加密密钥存储在配置文件中，使用环境变量或密钥管理服务
|
|||
|
|
|
|||
|
|
- **连接状态同步**: 连接状态可能因为网络问题或 Salesforce API 限制而变化
|
|||
|
|
- **缓解措施**: 定期检查连接状态，使用 SessionManager 自动重新登录
|
|||
|
|
|
|||
|
|
- **路径验证失败**: 路径验证可能因为权限问题或网络问题而失败
|
|||
|
|
- **缓解措施**: 提供详细的错误信息，支持手动配置路径
|
|||
|
|
|
|||
|
|
### 业务风险
|
|||
|
|
|
|||
|
|
- **配置错误**: 配置错误可能导致元数据拉取和部署失败
|
|||
|
|
- **缓解措施**: 提供配置验证功能，确保配置正确
|
|||
|
|
|
|||
|
|
- **多环境配置混乱**: 多环境配置可能导致配置混乱
|
|||
|
|
- **缓解措施**: 使用环境类型枚举管理，提供清晰的配置界面
|
|||
|
|
|
|||
|
|
## 回滚策略
|
|||
|
|
|
|||
|
|
如果架构决策实施后出现问题，可以采取以下回滚策略：
|
|||
|
|
|
|||
|
|
1. **回滚到明文存储**: 如果加密功能出现问题，可以暂时回滚到明文存储 OAuth 认证信息
|
|||
|
|
2. **回滚到简单验证**: 如果配置验证功能出现问题，可以暂时简化验证逻辑
|
|||
|
|
3. **回滚到基础 CRUD**: 如果复杂功能出现问题，可以暂时只提供基础的 CRUD 功能
|
|||
|
|
|
|||
|
|
## 验收标准
|
|||
|
|
|
|||
|
|
### 功能验收标准
|
|||
|
|
|
|||
|
|
- [ ] 能够成功创建、编辑、删除、查询组织配置
|
|||
|
|
- [ ] OAuth 认证信息加密存储成功，解密功能正常工作
|
|||
|
|
- [ ] 环境类型和连接状态枚举管理正确
|
|||
|
|
- [ ] 存储路径配置和验证功能正常工作
|
|||
|
|
- [ ] 配置验证功能正常工作，返回详细的错误信息
|
|||
|
|
- [ ] API 接口符合 RESTful 规范，支持分页和条件查询
|
|||
|
|
|
|||
|
|
### 性能验收标准
|
|||
|
|
|
|||
|
|
- [ ] 加密解密性能满足要求，不影响系统响应
|
|||
|
|
- [ ] 配置查询性能满足要求，支持分页查询
|
|||
|
|
- [ ] 配置验证性能满足要求，不影响用户体验
|
|||
|
|
|
|||
|
|
### 安全验收标准
|
|||
|
|
|
|||
|
|
- [ ] OAuth 认证信息加密存储，符合安全标准
|
|||
|
|
- [ ] 加密密钥安全存储，不泄露
|
|||
|
|
- [ ] 配置信息访问权限控制正确
|
|||
|
|
|
|||
|
|
### 代码质量验收标准
|
|||
|
|
|
|||
|
|
- [ ] 代码符合项目编码规范，有清晰的注释
|
|||
|
|
- [ ] 代码结构清晰，易于扩展和维护
|
|||
|
|
- [ ] 单元测试覆盖率 >= 80%
|
|||
|
|
- [ ] 集成测试覆盖主要业务场景
|
|||
|
|
|
|||
|
|
## 视觉锚点
|
|||
|
|
|
|||
|
|
### 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创建
|
|||
|
|
- [010-metadata-retrieve-deploy-sub-requirements.md](../requirements/010-metadata-retrieve-deploy-sub-requirements.md) - REQ-010子需求拆分文档
|
|||
|
|
- [0011-entity-mapper-create.md](./0011-entity-mapper-create.md) - 基础实体类和Mapper创建架构决策
|
|||
|
|
- [Java Cryptography Architecture (JCA) Reference Guide](https://docs.oracle.com/javase/8/docs/technotes/guides/security/crypto/CryptoSpec.html) - Java 加密架构参考指南
|
|||
|
|
- [MyBatis Plus 官方文档](https://baomidou.com/) - MyBatis Plus 框架文档
|