11 KiB
11 KiB
架构决策记录 - Document 文件上传下载功能
背景
REQ-011-4 需求要求实现 Salesforce Document 对象的文件上传下载功能。Document 是 Salesforce 的传统文档对象（用于存储 Email 模板 Logo、Classic 模式附件等），使用 Partner API (SOAP) 方式进行文件上传下载，最大支持 20-30MB 文件。
与 Attachment 和 ContentDocument/ContentVersion 相比，Document 对象具有以下特点：
- 仅适用于特定遗留功能（Email 模板 Logo、Classic 附件）
- 不支持版本管理（只能覆盖）
- 存储在 DocumentFolder 中
- 必填字段：FolderId, Name, Body
- 使用 Partner API (SOAP) 进行操作
面临的问题
- API 方式选择: 需要选择合适的 API 方式，考虑 Document 对象的特殊性和官方推荐
- 文件编码方式选择: 需要选择合适的文件编码方式，考虑文件大小限制和性能
- 架构设计: 需要设计合理的架构，支持多种文件对象类型的上传下载功能
- 依赖管理: 需要合理管理依赖关系，确保与现有系统的兼容性
约束条件
- 技术栈限制: 必须基于现有的 Spring Boot 3 技术栈
- 架构约束: 必须遵循 Authentication.canvas 中定义的架构和调用关系
- 模块约束: 必须在 datai-salesforce-integration 模块下实现
- 认证约束: 必须使用 SessionManager 进行会话管理和自动重新登录
- API约束: 必须使用 Salesforce Partner API (SOAP)
- 文件大小约束: 单个文件大小建议不超过 20-30MB
- 内存约束: 必须使用流式处理避免内存溢出
- 设计模式约束: 必须使用策略模式封装上传下载逻辑
决策
1. API 方式选择
决策: 使用 Partner API (SOAP) 进行文件上传下载
理由:
- Document 对象的官方推荐 API 方式是 Partner API (SOAP)
- Document 对象是传统对象，主要使用 SOAP API 进行操作
- Partner API (SOAP) 提供完整的 CRUD 操作
- REST API 对 Document 对象的支持有限
实现方案:
- 使用 PartnerV1Connection 进行 SOAP API 调用
- 使用 SessionManager 获取 Session ID
- 使用 Partner API 的 create() 方法创建 Document 对象
- 使用 Partner API 的 query() 方法查询 Document 对象
2. 文件编码方式选择
决策: 使用 Base64 编码进行文件上传下载
理由:
- Document 对象的 Body 字段使用 Base64 编码
- Base64 编码方式简单易实现，兼容性好
- 20-30MB 文件大小限制适合 Base64 编码方式
- 与 SOAP API 的实现方式一致
实现方案:
- 上传时使用 Base64 编码文件内容
- 下载时使用 Base64 解码文件内容
- 使用 Java 的 Base64 工具类进行编码解码
- 使用流式处理避免内存溢出
3. 流式处理决策
决策: 使用流式处理避免内存溢出
理由:
- Document 对象支持最大 20-30MB 文件，建议使用流式处理
- 流式处理可以有效控制内存使用
- 流式处理可以提高大文件上传下载的性能
实现方案:
- 上传时使用 FileInputStream 读取文件内容
- 使用 BufferedInputStream 提高性能
- 使用固定大小的缓冲区（如 8KB）
- 下载时使用 InputStream 读取 Body 字段内容
- 使用 FileOutputStream 保存文件到本地
4. 架构设计决策
决策: 使用策略模式封装上传下载逻辑
理由:
- 策略模式可以很好地支持多种文件对象类型的上传下载功能
- 符合开闭原则，易于扩展新的文件对象类型
- 代码结构清晰，易于维护
- 符合单一职责原则
实现方案:
- 复用 FileUploadStrategy 接口，定义 upload() 方法
- 复用 FileDownloadStrategy 接口，定义 download() 方法
- 实现 DocumentUploadStrategy 类，实现 FileUploadStrategy 接口
- 实现 DocumentDownloadStrategy 类，实现 FileDownloadStrategy 接口
- 定义 DocumentFileService 接口，封装上传下载逻辑
- 定义 DocumentFileServiceImpl 实现类，使用策略模式调用上传下载逻辑
5. 依赖管理决策
决策: 依赖 REQ-011-1 的基础设施和 datai-salesforce-integration 模块的 SessionManager、PartnerV1Connection
理由:
- REQ-011-1 提供了完整的基础设施，包括枚举、异常、参数、验证等
- SessionManager 提供了会话管理和自动重新登录功能
- PartnerV1Connection 提供了 SOAP API 调用功能
- 避免重复造轮子，提高代码复用性
实现方案:
- 使用 @Autowired 注入 SessionManager
- 使用 @Autowired 注入 PartnerV1Connection
- 使用 REQ-011-1 提供的 FileObjectType、FileErrorCode、FileUploadRequest、FileDownloadRequest、FileUploadResponse、FileDownloadResponse、FileValidationUtils
备选方案
方案 1：使用 Partner API (SOAP) + Base64 编码（推荐）
优点:
- Document 对象的官方推荐 API 方式
- Base64 编码方式简单易实现，兼容性好
- 20-30MB 文件大小限制适合 Base64 编码方式
- 与 SOAP API 的实现方式一致
缺点:
- SOAP 协议复杂，实现难度高
- Base64 编码会导致文件大小增加约 33%
- 不支持流式处理，大文件可能导致内存溢出
评估: 推荐使用
方案 2：使用 REST API + Base64 编码
优点:
- REST API 简单易用
- 实现复杂度低
缺点:
- REST API 对 Document 对象的支持有限
- 不符合 Document 对象的官方推荐方式
- 可能存在功能限制
评估: 不推荐使用
方案 3：使用 REST API + Multipart/form-data
优点:
- Multipart/form-data 方式不需要 Base64 编码，减少内存开销
- 支持流式处理，避免大文件导致内存溢出
缺点:
- REST API 对 Document 对象的支持有限
- 不符合 Document 对象的官方推荐方式
- 可能存在功能限制
评估: 不推荐使用
影响
对系统架构的影响
- 新增类: 需要新增 DocumentUploadStrategy、DocumentDownloadStrategy、DocumentFileService、DocumentFileServiceImpl 类
- 复用接口: 复用 FileUploadStrategy 和 FileDownloadStrategy 接口
- 复用依赖: 复用 SessionManager 和 PartnerV1Connection
对开发流程的影响
- 开发复杂度: 需要实现 SOAP API 调用逻辑，开发复杂度较高
- 测试复杂度: 需要测试大文件上传下载功能，测试复杂度较高
对运维管理的影响
- 性能监控: 需要监控大文件上传下载的性能
- 日志要求: 需要记录详细的日志，便于问题排查
风险
技术风险
- SOAP API 复杂度风险: SOAP API 复杂度高，实现难度大
- 缓解措施: 参考官方文档和示例代码，使用成熟的 SOAP 客户端库
- 文件大小风险: 大文件上传下载可能导致内存溢出
- 缓解措施: 使用流式处理，限制文件大小
- Base64 编码风险: Base64 编码会导致文件大小增加约 33%
- 缓解措施: 限制文件大小，建议不超过 20-30MB
- API 限流风险: 频繁的 API 调用可能导致 Salesforce API 限流
- 缓解措施: 实现重试机制，监控 API 调用频率
业务风险
- 功能受限风险: Document 功能受限，仅适用于特定场景
- 缓解措施: 提供迁移方案，建议用户使用 ContentDocument
- 兼容性风险: 旧系统可能依赖 Document 对象
- 缓解措施: 保持 Document 对象的兼容性，提供迁移指南
- 弃用风险: Document 可能被 Salesforce 弃用
- 缓解措施: 提供迁移方案，建议用户使用 ContentDocument
实施风险
- 开发风险: 开发过程中可能遇到技术难题
- 缓解措施: 提前进行技术调研，参考官方文档和示例代码
- 测试风险: 测试过程中可能发现性能问题
- 缓解措施: 提前进行性能测试，优化代码性能
回滚策略
如果决策实施后出现问题，可以采取以下回滚策略：
-
SOAP API 问题: 如果 SOAP API 调用出现问题，可以：
- 检查 PartnerV1Connection 的配置和实现
- 检查 Session ID 的获取和有效性
- 检查 SOAP 请求的格式和参数
-
Base64 编码问题: 如果 Base64 编码出现问题，可以：
- 检查 Base64 编码和解码的实现
- 检查文件内容的完整性
- 使用更成熟的 Base64 编码库
-
性能问题: 如果大文件上传下载性能不佳，可以：
- 优化缓冲区大小
- 使用更高效的流式处理方式
- 限制文件大小，避免处理超大文件
-
功能不满足需求: 如果实现的功能不满足需求，可以：
- 检查需求文档和实现的一致性
- 调整实现方案，满足需求
- 与用户沟通，确认需求的合理性
验收标准
定义验证该决策有效性的具体标准和测试方法：
-
功能验收标准:
- 能够成功上传本地文件到 Salesforce Document 对象
- 能够成功从 Salesforce Document 对象下载文件到本地
- 支持指定组织配置 ID
- 支持指定 FolderId（必填）
- 支持指定文件名和 DeveloperName
- 上传成功返回 Document ID
- 下载成功返回文件信息
-
性能验收标准:
- 大文件上传下载不影响系统响应
- 流式处理有效避免内存溢出
- 20-30MB 文件上传下载性能良好
-
代码质量验收标准:
- 代码符合项目编码规范
- 使用策略模式封装上传下载逻辑
- 遵循单一职责原则和开闭原则
- 通过 IDE 诊断检查，无编译错误或警告
-
测试验收标准:
- 单元测试覆盖率 ≥ 90%
- 集成测试覆盖所有场景
- 性能测试验证大文件上传下载性能
视觉锚点
Visual Reference
引用 Canvas 的具体节点或快照：
- Authentication.canvas - 相关架构图
- 具体节点: 集成核心 - 提供与Salesforce的各种连接方式
- 具体节点: SessionManager - 会话管理，提供登录服务
- 具体节点: PartnerV1Connection - Partner API 连接
Status
- Draft
- Accepted
- Superceded
参考资料
列出与该决策相关的参考资料，包括文档、文章或其他资源：
- REQ-011.md - Salesforce文件上传下载功能
- REQ-011-4.md - Document 文件上传下载功能
- Document上传下载.md - Salesforce Document 上传下载实现逻辑
- 0028-attachment-upload-download.md - Attachment 文件上传下载架构决策
- 0029-contentdocument-upload-download.md - ContentDocument 文件上传下载架构决策
- Salesforce Partner API 文档 - Salesforce Partner API 官方文档
- Salesforce Document 对象文档 - Salesforce Document 对象官方文档