kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
3d290a8dd1
datai/docs/archive/decisions/adr/0028-attachment-upload-download.md

9.9 KiB
Raw Blame History

架构决策记录：Attachment 文件上传下载功能

背景

REQ-011-2 需求要求实现 Salesforce Attachment 对象的文件上传下载功能。Attachment 是 Salesforce 的传统附件对象（已弃用，但需兼容旧系统），使用 REST API + Base64 编码方式进行文件上传下载，最大支持 50MB 文件。

面临的问题

  1. 文件上传方式选择: 需要选择合适的文件上传方式，考虑文件大小限制、编码方式、性能等因素
  2. 文件下载方式选择: 需要选择合适的文件下载方式，考虑内存占用、流式处理、性能等因素
  3. 架构设计: 需要设计合理的架构，支持多种文件对象类型的上传下载功能
  4. 依赖管理: 需要合理管理依赖关系，确保与现有系统的兼容性

约束条件

  1. 技术栈限制: 必须基于现有的 Spring Boot 3 技术栈
  2. 架构约束: 必须遵循 Authentication.canvas 中定义的架构和调用关系
  3. 模块约束: 必须在 datai-salesforce-integration 模块下实现
  4. 认证约束: 必须使用 SessionManager 进行会话管理和自动重新登录
  5. API约束: 必须使用 Salesforce REST API
  6. 文件大小约束: 单个文件大小建议不超过 50MB
  7. 内存约束: 必须使用流式处理避免内存溢出
  8. 设计模式约束: 必须使用策略模式封装上传下载逻辑

决策

1. 上传方式选择

决策: 使用 REST API + Base64 编码方式进行文件上传

理由:

  • Attachment 对象的官方推荐上传方式是 REST API + Base64 编码
  • Base64 编码方式简单易实现，兼容性好
  • REST API 是 Salesforce 的标准 API，稳定可靠
  • 50MB 文件大小限制适合 Base64 编码方式

实现方案:

  • 使用 HttpClient 发送 POST 请求到 Salesforce REST API
  • 使用 Base64 编码文件内容
  • 使用 SessionManager 获取 Access Token
  • 上传成功返回 Attachment ID

2. 下载方式选择

决策: 使用 REST API + 流式处理方式进行文件下载

理由:

  • 流式处理可以有效避免内存溢出
  • 适合大文件下载
  • 性能良好，用户体验好
  • 符合 Salesforce 官方推荐做法

实现方案:

  • 使用 HttpClient 发送 GET 请求到 Salesforce REST API
  • 使用 InputStream 流式处理文件内容
  • 使用 FileOutputStream 保存文件到本地

3. 架构设计

决策: 使用策略模式封装上传下载逻辑

理由:

  • 策略模式可以很好地支持多种文件对象类型的上传下载功能
  • 符合开闭原则，易于扩展新的文件对象类型
  • 代码结构清晰，易于维护
  • 符合单一职责原则

实现方案:

  • 定义 FileUploadStrategy 接口，定义 upload() 方法
  • 定义 FileDownloadStrategy 接口，定义 download() 方法
  • 实现 AttachmentUploadStrategy 类，实现 FileUploadStrategy 接口
  • 实现 AttachmentDownloadStrategy 类，实现 FileDownloadStrategy 接口
  • 定义 AttachmentFileService 接口，封装上传下载逻辑
  • 定义 AttachmentFileServiceImpl 实现类，使用策略模式调用上传下载逻辑

4. 依赖管理

决策: 依赖 REQ-011-1 的基础设施和 datai-salesforce-integration 模块的 SessionManager、RESTConnection

理由:

  • REQ-011-1 提供了完整的基础设施，包括枚举、异常、参数、验证等
  • SessionManager 提供了会话管理和自动重新登录功能
  • RESTConnection 提供了 REST API 调用功能
  • 避免重复造轮子，提高代码复用性

实现方案:

  • 使用 @Autowired 注入 SessionManager
  • 使用 @Autowired 注入 RESTConnection
  • 使用 REQ-011-1 提供的 FileObjectType、FileErrorCode、FileUploadRequest、FileDownloadRequest、FileUploadResponse、FileDownloadResponse、FileValidationUtils

备选方案

方案 1: 使用 SOAP API 进行文件上传下载

优点:

  • SOAP API 功能强大，支持更多操作
  • 可以使用 Partner API 进行更灵活的操作

缺点:

  • SOAP API 复杂度高，实现难度大
  • SOAP 协议开销大，性能较差
  • 不符合 Attachment 对象的官方推荐方式

评估: 不推荐使用

方案 2: 使用 Bulk API 进行文件上传下载

优点:

  • Bulk API 适合批量操作
  • 性能较好

缺点:

  • Bulk API 不适合单个文件上传下载
  • 实现复杂度高
  • 不符合 Attachment 对象的官方推荐方式

评估: 不推荐使用

方案 3: 使用 GraphQL API 进行文件上传下载

优点:

  • GraphQL API 灵活强大
  • 可以一次性获取多个数据

缺点:

  • GraphQL API 对文件上传下载支持有限
  • 实现复杂度高
  • 不符合 Attachment 对象的官方推荐方式

评估: 不推荐使用

影响

系统架构影响

  1. 新增模块: 在 datai-salesforce-integration 模块下新增 Attachment 上传下载功能
  2. 新增接口: 新增 FileUploadStrategy、FileDownloadStrategy 接口
  3. 新增实现: 新增 AttachmentUploadStrategy、AttachmentDownloadStrategy 实现
  4. 新增服务: 新增 AttachmentFileService 接口和 AttachmentFileServiceImpl 实现

开发流程影响

  1. 开发流程: 需要按照 SSOT 方法论进行开发，包括需求定义、方案决策、提示词资产化、执行会话、变更记录、闭环复盘
  2. 代码规范: 需要遵循项目编码规范，使用 Lombok 注解、JSR-303 验证注解等
  3. 测试要求: 需要编写单元测试，确保测试覆盖率 ≥ 90%

运维管理影响

  1. 监控要求: 需要监控文件上传下载的性能和错误率
  2. 日志要求: 需要记录详细的日志，便于问题排查
  3. 配置要求: 需要配置文件大小限制、文件类型白名单等

风险

技术风险

  1. 文件大小风险: 大文件上传下载可能导致内存溢出
    • 缓解措施: 使用流式处理，限制文件大小
  2. API 限流风险: 频繁的 API 调用可能导致 Salesforce API 限流
    • 缓解措施: 实现重试机制，监控 API 调用频率
  3. 认证失效风险: Access Token 失效可能导致文件上传下载失败
    • 缓解措施: 使用 SessionManager 进行自动重新登录
  4. 网络异常风险: 网络异常可能导致文件上传下载失败
    • 缓解措施: 实现重试机制，提供详细的错误信息

业务风险

  1. 弃用风险: Attachment 已被 Salesforce 弃用，未来可能被移除
    • 缓解措施: 提供迁移方案，建议用户使用 ContentDocument
  2. 兼容性风险: 旧系统可能依赖 Attachment 对象
    • 缓解措施: 保持 Attachment 对象的兼容性，提供迁移指南

实施风险

  1. 开发风险: 开发过程中可能遇到技术难题
    • 缓解措施: 提前进行技术调研，参考官方文档和示例代码
  2. 测试风险: 测试过程中可能发现性能问题
    • 缓解措施: 提前进行性能测试，优化代码性能

回滚策略

回滚条件

  1. 功能不满足需求: 如果实现的功能不满足需求，可以进行回滚
  2. 性能不达标: 如果性能不达标，可以进行回滚或优化
  3. 严重Bug: 如果发现严重Bug，可以进行回滚或修复

回滚步骤

  1. 代码回滚: 使用 Git 回滚代码到上一个稳定版本
  2. 数据库回滚: 如果有数据库变更，需要回滚数据库
  3. 配置回滚: 如果有配置变更，需要回滚配置
  4. 通知用户: 通知用户回滚的原因和影响

回滚后调整

  1. 问题分析: 分析回滚的原因，找出问题所在
  2. 方案优化: 优化方案，解决存在的问题
  3. 重新实施: 重新实施优化后的方案

验收标准

功能验收标准

  1. 上传功能: 能够成功上传本地文件到 Salesforce Attachment 对象
  2. 下载功能: 能够成功从 Salesforce Attachment 对象下载文件到本地
  3. 参数验证: 能够正确验证参数，提供详细的错误信息
  4. 异常处理: 能够正确处理异常，提供详细的错误信息
  5. 日志记录: 能够记录详细的日志，便于问题排查

性能验收标准

  1. 上传性能: 文件上传性能良好，不影响系统响应
  2. 下载性能: 文件下载性能良好，不影响系统响应
  3. 内存占用: 内存占用合理，不出现内存溢出
  4. 并发性能: 并发上传下载性能良好，不出现资源竞争

代码质量验收标准

  1. 代码规范: 代码符合项目编码规范，有清晰的注释
  2. 设计模式: 使用策略模式封装上传下载逻辑
  3. 单一职责: 遵循单一职责原则和开闭原则
  4. 测试覆盖: 测试覆盖率 ≥ 90%

视觉锚点

Visual Reference

引用 Canvas 的具体节点或快照：

Status

  • Draft
  • Accepted
  • Superceded

参考资料

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