datai/docs/decisions/2026-01-21-003-01-ADR-salesforce-multi-system-config.md

ADR-003-01: Salesforce 多系统配置架构决策

元数据

• ADR 编号：ADR-003-01
• 需求编号：2026-01-21-003-01
• 创建时间：2026-01-21
• 创建人：SSOT 架构师
• 状态：已采纳
• 优先级：高

上下文

需要实现 Salesforce 多系统配置功能，支持配置多个不同类型的 Salesforce 系统，支持用户自定义系统类型，支持区分源 org 和目标 org（支持同一系统既是源 org 又是目标 org），支持配置系统名称、自定义类型、登录方式等，支持启用/停用系统，系统配置变更无需审批流程，系统配置无权限限制，密码、安全令牌等敏感信息使用 EncryptUtils 加密存储。

决策

采用以下架构决策实现 Salesforce 多系统配置功能：

决策 1：数据库表设计

决策内容：创建 datai_sf_system_config 表存储 Salesforce 系统配置信息

理由：

1. 集中存储所有 Salesforce 系统配置，便于统一管理
2. 支持多系统配置，满足业务需求
3. 使用独立的表存储，避免与其他业务表耦合

影响：

• 需要创建新的数据库表
• 需要创建对应的 Mapper 和 XML 文件
• 需要创建对应的实体类、DTO、VO

决策 2：敏感信息加密策略

决策内容：使用 EncryptUtils 对密码、安全令牌、OAuth 客户端密钥等敏感信息进行加密存储

理由：

1. 保护用户敏感信息，提高系统安全性
2. 符合项目现有的加密规范
3. EncryptUtils 已经在项目中广泛使用，成熟可靠

影响：

• 需要在 Service 层实现加密/解密逻辑
• 需要在读取配置时自动解密
• 需要在保存配置时自动加密

决策 3：系统类型自定义策略

决策内容：系统类型（system_type）使用自由文本字段，不限制为固定值

理由：

1. 支持用户自定义系统类型，提高灵活性
2. 不限制用户的使用场景
3. 满足"用户自定义系统类型"的业务需求

影响：

• 系统类型字段使用 VARCHAR 类型
• 不需要创建枚举或字典表
• 前端需要提供自由输入框

决策 4：源目标区分策略

决策内容：使用 org_type 字段（CHAR 类型）区分源 org 和目标 org，支持同一系统既是源 org 又是目标 org

理由：

1. 使用单个字段存储，简化数据模型
2. 支持 S（源 org）、T（目标 org）两种值
3. 支持同一系统既是源 org 又是目标 org（通过业务逻辑实现）

影响：

• 需要在业务逻辑中处理 org_type 字段
• 需要提供源 org / 目标 org 的筛选查询

决策 5：系统配置管理策略

决策内容：系统配置变更无需审批流程，系统配置无权限限制

理由：

1. 提高配置管理的灵活性
2. 简化配置流程，提高用户体验
3. 满足"系统配置变更无需审批流程，系统配置无权限限制"的业务需求

影响：

• 不需要实现审批流程
• 不需要实现权限控制
• 需要在 Controller 层直接调用 Service 层

决策 6：索引设计策略

决策内容：为关键字段创建索引，提高查询性能

理由：

1. 提高查询性能，满足性能需求（系统列表查询响应时间 < 1 秒）
2. 支持分页查询，避免全表扫描
3. 支持按条件筛选查询

影响：

• 需要创建主键索引
• 需要创建唯一索引（system_name）
• 需要创建普通索引（system_type、org_type、login_type、status）

决策 7：接口设计策略

决策内容：提供 RESTful API 接口，支持 CRUD 操作和特殊查询

理由：

1. 遵循 RESTful 设计规范
2. 提供统一的接口风格
3. 便于前端调用和集成

影响：

• 需要创建 Controller 层接口
• 需要创建 Service 层接口和实现
• 需要创建 Mapper 层接口和实现

决策 8：分层架构策略

决策内容：采用 Controller-Service-Mapper 三层架构

理由：

1. 遵循项目现有的分层架构规范
2. 实现业务逻辑与数据访问的分离
3. 提高代码的可维护性和可测试性

影响：

• 需要创建 Controller 层
• 需要创建 Service 层接口和实现
• 需要创建 Mapper 层接口和 XML 文件

后果

正面影响

1. 灵活性：支持用户自定义系统类型，不限制使用场景
2. 安全性：敏感信息加密存储，保护用户数据
3. 性能：合理的索引设计，提高查询性能
4. 可维护性：清晰的分层架构，便于维护和扩展
5. 易用性：无审批流程和权限限制，简化配置管理

负面影响

1. 开发成本：需要创建多个层次的代码，开发成本较高
2. 测试成本：需要编写单元测试和集成测试，测试成本较高
3. 维护成本：需要维护多个层次的代码，维护成本较高

替代方案

替代方案 1：使用枚举限制系统类型

描述：使用枚举限制系统类型为固定值（production、sandbox、developer）

拒绝理由：

1. 不满足"用户自定义系统类型"的业务需求
2. 限制用户的使用场景
3. 灵活性不足

替代方案 2：使用两个表分别存储源 org 和目标 org

描述：使用 datai_sf_source_org_config 和 datai_sf_target_org_config 两个表分别存储源 org 和目标 org

拒绝理由：

1. 数据模型复杂，增加维护成本
2. 不支持同一系统既是源 org 又是目标 org
3. 查询逻辑复杂

替代方案 3：实现审批流程和权限控制

描述：实现审批流程和权限控制，限制系统配置的变更

拒绝理由：

1. 不满足"系统配置变更无需审批流程，系统配置无权限限制"的业务需求
2. 增加系统复杂度
3. 降低用户体验

相关决策

• 无

相关需求

• 2026-01-21-003-01：Salesforce 多系统配置

相关设计

• 2026-01-21-003-01-salesforce-multi-system-config-design：Salesforce 多系统配置设计

实施计划

1. 创建数据库表 datai_sf_system_config
2. 创建实体类 DataiSfSystemConfig
3. 创建 DTO 和 VO
4. 创建 Mapper 接口和 XML 文件
5. 创建 Service 接口和实现
6. 创建 Controller 接口
7. 编写单元测试
8. 编写集成测试
9. 进行代码审查
10. 部署到测试环境