kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
develop
datai/datai-scenes/datai-scene-salesforce/docs/decisions/2026-01-28-004-04-ADR-AI和智能功能技术选型.md

12 KiB
Raw Permalink Blame History

AI 和智能功能技术选型 ADR

元数据

  • 需求编号：004
  • 子需求编号：004-04
  • 子需求名称：AI 和智能功能
  • 阶段：阶段 3：方案决策
  • 创建时间：2026-01-28
  • 创建人：AI Assistant
  • 状态：已接受

相关文档

1. 背景和问题陈述

1.1 背景

Tooling API 提供了丰富的 AI 和智能功能，包括 AI 应用管理、AI 评估配置、AI 创作工具等。这些功能可以帮助开发者更高效地使用 Salesforce 的 AI 能力，包括创建和管理 AI 应用、配置 AI 评估参数、使用 AI 创作工具等。

1.2 问题陈述

在实现 AI 和智能功能时，需要解决以下关键技术问题：

  1. 连接管理：如何高效地管理 Tooling API 连接，避免重复创建连接
  2. 日志记录：如何记录 AI 操作日志，支持操作审计和故障排查
  3. 异常处理：如何统一处理各种异常情况，提供友好的错误信息
  4. SOQL 查询：如何构建 SOQL 查询语句，简化查询逻辑
  5. 性能优化：如何避免日志记录影响主流程性能

1.3 约束条件

  1. 必须复用子需求 004-01 的 ToolingConnectionFactory
  2. 必须使用数据库表记录 AI 操作日志
  3. 必须使用 datai-salesforce-common 模块的异常体系
  4. 必须提供 REST API 接口
  5. 必须支持 AI 应用管理（创建、查询、更新、删除）
  6. 必须支持 AI 评估配置查询
  7. 必须支持 AI 创作工具查询

2. 决策驱动因素

2.1 技术驱动因素

  1. 复用现有基础设施：复用 ToolingConnectionFactory，避免重复实现连接管理逻辑
  2. 性能要求：日志记录不能影响主流程性能
  3. 可维护性：代码结构清晰，易于维护和扩展
  4. 可测试性：易于编写单元测试和集成测试
  5. 可扩展性：预留扩展点，支持未来新增 AI 功能

2.2 业务驱动因素

  1. 操作审计：所有 AI 操作必须记录到数据库，支持审计和故障排查
  2. 用户体验：提供友好的错误信息，便于用户理解和排查问题
  3. 功能完整性：支持所有 AI 和智能功能，包括 AI 应用管理、AI 评估配置、AI 创作工具

2.3 团队驱动因素

  1. 开发效率：利用现有基础设施，快速实现功能
  2. 学习成本：使用熟悉的技术栈，降低学习成本
  3. 协作效率：与项目现有架构保持一致，便于团队协作

3. 考虑的方案

方案 1：Service + ToolingConnectionFactory + 异步日志记录

描述：

  • 复用 ToolingConnectionFactory 获取连接
  • 使用 CompletableFuture 异步记录操作日志
  • 使用 SoqlBuilder 构建 SOQL 查询
  • 提供完整的 REST API 接口

优点：

  1. 复用现有基础设施，开发效率高
  2. 异步日志记录不影响主流程性能
  3. 统一异常处理，错误信息友好
  4. SOQL 查询构建简单，易于维护
  5. 与项目现有架构保持一致

缺点：

  1. 需要管理异步线程池
  2. 日志记录失败不影响主流程，可能丢失日志

适用场景：

  • 需要高性能的场景
  • 日志记录不是关键业务的场景

方案 2：Service + ToolingConnectionFactory + 同步日志记录

描述：

  • 复用 ToolingConnectionFactory 获取连接
  • 同步记录操作日志到数据库
  • 使用 SoqlBuilder 构建 SOQL 查询
  • 提供完整的 REST API 接口

优点：

  1. 实现简单，易于理解
  2. 日志记录可靠，不会丢失
  3. 与项目现有架构保持一致

缺点：

  1. 日志记录影响主流程性能
  2. 数据库故障可能导致主流程失败
  3. 并发场景下性能较差

适用场景：

  • 日志记录是关键业务的场景
  • 性能要求不高的场景

方案 3：Service + ToolingConnectionFactory + 消息队列日志记录

描述：

  • 复用 ToolingConnectionFactory 获取连接
  • 使用消息队列（如 RabbitMQ、Kafka）异步记录操作日志
  • 使用 SoqlBuilder 构建 SOQL 查询
  • 提供完整的 REST API 接口

优点：

  1. 异步日志记录不影响主流程性能
  2. 消息队列保证日志记录的可靠性
  3. 支持高并发场景
  4. 可以扩展为分布式架构

缺点：

  1. 需要部署和维护消息队列
  2. 增加系统复杂度
  3. 需要额外的监控和运维成本
  4. 开发成本较高

适用场景：

  • 高并发场景
  • 日志记录可靠性要求极高的场景
  • 分布式架构场景

方案 4：Service + ToolingConnectionFactory + 仅记录失败日志

描述：

  • 复用 ToolingConnectionFactory 获取连接
  • 仅记录失败的操作日志到数据库
  • 使用 SoqlBuilder 构建 SOQL 查询
  • 提供完整的 REST API 接口

优点：

  1. 减少数据库写入量，提高性能
  2. 实现简单，易于理解
  3. 与项目现有架构保持一致

缺点：

  1. 无法完整审计所有操作
  2. 无法统计操作成功率
  3. 无法追踪成功操作的历史记录

适用场景：

  • 性能要求极高的场景
  • 只需要追踪失败操作的场景

方案 5：Service + ToolingConnectionFactory + 文件日志记录

描述：

  • 复用 ToolingConnectionFactory 获取连接
  • 将操作日志写入文件（如 JSON、CSV）
  • 使用 SoqlBuilder 构建 SOQL 查询
  • 提供完整的 REST API 接口

优点：

  1. 文件写入性能高
  2. 不占用数据库资源
  3. 实现简单，易于理解

缺点：

  1. 文件日志不便于查询和分析
  2. 文件管理复杂，需要定期清理
  3. 不支持分布式架构
  4. 无法与其他系统集成

适用场景：

  • 日志记录主要用于故障排查的场景
  • 不需要查询和分析日志的场景

4. 决策结果

4.1 选定方案

选择方案 1：Service + ToolingConnectionFactory + 异步日志记录

4.2 决策理由

  1. 复用现有基础设施：复用子需求 004-01 的 ToolingConnectionFactory 获取连接，避免重复实现连接管理逻辑

  2. 异步日志记录：使用 CompletableFuture 异步记录操作日志，不影响主流程性能

  3. 统一异常处理：使用 datai-salesforce-common 模块的异常体系，统一处理各种异常情况

  4. SOQL 查询支持：使用 SoqlBuilder 构建 SOQL 查询语句，简化查询逻辑

  5. 开发效率高：利用现有的基础设施，可以快速实现 AI 和智能功能

  6. 维护成本低：与项目现有架构保持一致，与 Partner API、Apex API、Metadata API 的实现方式一致

  7. 性能优秀：异步日志记录不影响主流程性能，连接复用提高性能

  8. 审计追溯完善：所有 AI 操作记录到数据库，便于审计和故障排查

  9. 可扩展性强：预留扩展点，支持未来新增 AI 功能

  10. 符合团队习惯：使用熟悉的技术栈，降低学习成本

5. 正面后果

5.1 技术方面

  1. 性能优秀：异步日志记录不影响主流程性能，连接复用提高性能
  2. 可维护性强：代码结构清晰，易于维护和扩展
  3. 可测试性好：易于编写单元测试和集成测试
  4. 可扩展性强：预留扩展点，支持未来新增 AI 功能

5.2 业务方面

  1. 操作审计完善：所有 AI 操作记录到数据库，支持审计和故障排查
  2. 用户体验良好：提供友好的错误信息，便于用户理解和排查问题
  3. 功能完整：支持所有 AI 和智能功能，包括 AI 应用管理、AI 评估配置、AI 创作工具

5.3 团队方面

  1. 开发效率高：利用现有基础设施，快速实现功能
  2. 学习成本低：使用熟悉的技术栈，降低学习成本
  3. 协作效率高：与项目现有架构保持一致，便于团队协作

6. 负面后果

6.1 技术方面

  1. 需要管理异步线程池：需要配置和管理异步线程池，增加一定的复杂度
  2. 日志记录可能丢失：异步日志记录失败不影响主流程，但可能导致日志丢失

6.2 业务方面

  1. 日志记录不是实时：异步日志记录可能导致日志不是实时写入数据库

6.3 团队方面

  1. 需要监控异步任务：需要监控异步日志记录的任务状态，及时发现和处理问题

7. 替代方案分析

7.1 方案 2：同步日志记录

为什么不选择：

  • 日志记录影响主流程性能
  • 数据库故障可能导致主流程失败
  • 并发场景下性能较差

适用场景：

  • 日志记录是关键业务的场景
  • 性能要求不高的场景

7.2 方案 3：消息队列日志记录

为什么不选择：

  • 需要部署和维护消息队列，增加系统复杂度
  • 需要额外的监控和运维成本
  • 开发成本较高

适用场景：

  • 高并发场景
  • 日志记录可靠性要求极高的场景
  • 分布式架构场景

7.3 方案 4：仅记录失败日志

为什么不选择：

  • 无法完整审计所有操作
  • 无法统计操作成功率
  • 无法追踪成功操作的历史记录

适用场景：

  • 性能要求极高的场景
  • 只需要追踪失败操作的场景

7.4 方案 5：文件日志记录

为什么不选择：

  • 文件日志不便于查询和分析
  • 文件管理复杂，需要定期清理
  • 不支持分布式架构
  • 无法与其他系统集成

适用场景：

  • 日志记录主要用于故障排查的场景
  • 不需要查询和分析日志的场景

8. 实施计划

8.1 阶段 1：数据库设计（已完成）

  • 创建 AI 操作日志表（datai_tooling_ai_operation_log）
  • 设计索引，优化查询性能

8.2 阶段 2：代码生成（待进行）

  • 实现 Service 层（IToolingAIService、ToolingAIServiceImpl）
  • 实现 Controller 层（ToolingAIController）
  • 实现 DTO、VO、Entity、Mapper
  • 实现错误码枚举（ToolingAIErrCode）
  • 编写单元测试

8.3 阶段 3：测试验证（待进行）

  • 单元测试验证
  • 集成测试验证
  • 性能测试验证

8.4 阶段 4：文档更新（待进行）

  • 更新 API 文档
  • 更新变更日志
  • 更新会话记录

9. 风险和缓解措施

9.1 风险 1：异步日志记录失败导致日志丢失

缓解措施：

  • 使用可靠的异步线程池配置
  • 监控异步任务执行状态
  • 定期检查日志记录完整性

9.2 风险 2：异步线程池配置不当导致性能问题

缓解措施：

  • 根据实际负载调整线程池参数
  • 监控线程池使用情况
  • 提供线程池配置接口，支持动态调整

9.3 风险 3：数据库性能瓶颈

缓解措施：

  • 设计合理的索引
  • 定期清理历史日志数据
  • 考虑使用数据库分库分表

10. 监控和运维

10.1 监控指标

  1. 性能指标：

    • API 响应时间
    • 异步日志记录耗时
    • 数据库查询耗时

  2. 业务指标：

    • AI 操作成功率
    • AI 操作失败率
    • 日志记录成功率

  3. 系统指标：

    • 异步线程池使用率
    • 数据库连接数
    • 系统资源使用率

10.2 告警规则

  1. 性能告警：

    • API 响应时间 > 2s
    • 异步日志记录耗时 > 1s
    • 数据库查询耗时 > 500ms

  2. 业务告警：

    • AI 操作失败率 > 5%
    • 日志记录失败率 > 1%

  3. 系统告警：

    • 异步线程池使用率 > 80%
    • 数据库连接数 > 80%

11. 审批记录

角色 姓名 审批意见 审批时间
架构师 - 已接受 2026-01-28
技术负责人 - 已接受 2026-01-28
产品负责人 - 已接受 2026-01-28

12. 附录

12.1 参考资料

  1. Salesforce Tooling API 文档
  2. 项目设计文档
  3. 项目需求文档

12.2 相关 ADR

  1. 连接管理技术选型 ADR
  2. 元数据操作技术选型 ADR
  3. 开发工具功能技术选型 ADR