kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
2e6f087732
datai/datai-scenes/datai-scene-salesforce/docs/decisions/adr/0012-org-config-management.md
Kris 2e6f087732 docs: 完成REQ-010-17和REQ-010-2的文档创建 
- 完成REQ-010-17（性能优化和限流处理）的所有6个阶段
  - 创建ADR文档：0026-performance-optimization.md
  - 创建Prompt文档：027-performance-optimization.md
  - 创建会话记录：20260119-performance-optimization.md
  - 创建变更记录：20260119-performance-optimization.md
  - 创建复盘报告：20260119-performance-optimization-retro.md
  - 更新index.md和CHANGELOG.md

- 完成REQ-010-2（基础实体类和Mapper创建）的前3个阶段
  - 更新ADR文档：0011-entity-mapper-create.md
  - 创建Prompt文档：002-entity-mapper-create.md
  - 更新index.md

所有文档均按照SSOT方法论创建，包括需求定义、架构决策、提示词资产化、执行会话、变更记录和闭环复盘。
2026-01-19 10:06:09 +08:00

7.5 KiB
Raw Blame History

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 的具体节点或快照：

Status

  • Draft
  • Accepted
  • Superceded

参考资料

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