# 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 框架文档