285 lines
11 KiB
Markdown
285 lines
11 KiB
Markdown
# 架构决策记录 - 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) 进行操作
|
||
|
||
### 面临的问题
|
||
|
||
1. **API 方式选择**: 需要选择合适的 API 方式，考虑 Document 对象的特殊性和官方推荐
|
||
2. **文件编码方式选择**: 需要选择合适的文件编码方式，考虑文件大小限制和性能
|
||
3. **架构设计**: 需要设计合理的架构，支持多种文件对象类型的上传下载功能
|
||
4. **依赖管理**: 需要合理管理依赖关系，确保与现有系统的兼容性
|
||
|
||
### 约束条件
|
||
|
||
1. **技术栈限制**: 必须基于现有的 Spring Boot 3 技术栈
|
||
2. **架构约束**: 必须遵循 Authentication.canvas 中定义的架构和调用关系
|
||
3. **模块约束**: 必须在 datai-salesforce-integration 模块下实现
|
||
4. **认证约束**: 必须使用 SessionManager 进行会话管理和自动重新登录
|
||
5. **API约束**: 必须使用 Salesforce Partner API (SOAP)
|
||
6. **文件大小约束**: 单个文件大小建议不超过 20-30MB
|
||
7. **内存约束**: 必须使用流式处理避免内存溢出
|
||
8. **设计模式约束**: 必须使用策略模式封装上传下载逻辑
|
||
|
||
## 决策
|
||
|
||
### 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 调用逻辑，开发复杂度较高
|
||
- **测试复杂度**: 需要测试大文件上传下载功能，测试复杂度较高
|
||
|
||
### 对运维管理的影响
|
||
|
||
- **性能监控**: 需要监控大文件上传下载的性能
|
||
- **日志要求**: 需要记录详细的日志，便于问题排查
|
||
|
||
## 风险
|
||
|
||
### 技术风险
|
||
|
||
1. **SOAP API 复杂度风险**: SOAP API 复杂度高，实现难度大
|
||
- **缓解措施**: 参考官方文档和示例代码，使用成熟的 SOAP 客户端库
|
||
2. **文件大小风险**: 大文件上传下载可能导致内存溢出
|
||
- **缓解措施**: 使用流式处理，限制文件大小
|
||
3. **Base64 编码风险**: Base64 编码会导致文件大小增加约 33%
|
||
- **缓解措施**: 限制文件大小，建议不超过 20-30MB
|
||
4. **API 限流风险**: 频繁的 API 调用可能导致 Salesforce API 限流
|
||
- **缓解措施**: 实现重试机制，监控 API 调用频率
|
||
|
||
### 业务风险
|
||
|
||
1. **功能受限风险**: Document 功能受限，仅适用于特定场景
|
||
- **缓解措施**: 提供迁移方案，建议用户使用 ContentDocument
|
||
2. **兼容性风险**: 旧系统可能依赖 Document 对象
|
||
- **缓解措施**: 保持 Document 对象的兼容性，提供迁移指南
|
||
3. **弃用风险**: Document 可能被 Salesforce 弃用
|
||
- **缓解措施**: 提供迁移方案，建议用户使用 ContentDocument
|
||
|
||
### 实施风险
|
||
|
||
1. **开发风险**: 开发过程中可能遇到技术难题
|
||
- **缓解措施**: 提前进行技术调研，参考官方文档和示例代码
|
||
2. **测试风险**: 测试过程中可能发现性能问题
|
||
- **缓解措施**: 提前进行性能测试，优化代码性能
|
||
|
||
## 回滚策略
|
||
|
||
如果决策实施后出现问题，可以采取以下回滚策略：
|
||
|
||
1. **SOAP API 问题**: 如果 SOAP API 调用出现问题，可以：
|
||
- 检查 PartnerV1Connection 的配置和实现
|
||
- 检查 Session ID 的获取和有效性
|
||
- 检查 SOAP 请求的格式和参数
|
||
|
||
2. **Base64 编码问题**: 如果 Base64 编码出现问题，可以：
|
||
- 检查 Base64 编码和解码的实现
|
||
- 检查文件内容的完整性
|
||
- 使用更成熟的 Base64 编码库
|
||
|
||
3. **性能问题**: 如果大文件上传下载性能不佳，可以：
|
||
- 优化缓冲区大小
|
||
- 使用更高效的流式处理方式
|
||
- 限制文件大小，避免处理超大文件
|
||
|
||
4. **功能不满足需求**: 如果实现的功能不满足需求，可以：
|
||
- 检查需求文档和实现的一致性
|
||
- 调整实现方案，满足需求
|
||
- 与用户沟通，确认需求的合理性
|
||
|
||
## 验收标准
|
||
|
||
定义验证该决策有效性的具体标准和测试方法：
|
||
|
||
1. **功能验收标准**:
|
||
- 能够成功上传本地文件到 Salesforce Document 对象
|
||
- 能够成功从 Salesforce Document 对象下载文件到本地
|
||
- 支持指定组织配置 ID
|
||
- 支持指定 FolderId（必填）
|
||
- 支持指定文件名和 DeveloperName
|
||
- 上传成功返回 Document ID
|
||
- 下载成功返回文件信息
|
||
|
||
2. **性能验收标准**:
|
||
- 大文件上传下载不影响系统响应
|
||
- 流式处理有效避免内存溢出
|
||
- 20-30MB 文件上传下载性能良好
|
||
|
||
3. **代码质量验收标准**:
|
||
- 代码符合项目编码规范
|
||
- 使用策略模式封装上传下载逻辑
|
||
- 遵循单一职责原则和开闭原则
|
||
- 通过 IDE 诊断检查，无编译错误或警告
|
||
|
||
4. **测试验收标准**:
|
||
- 单元测试覆盖率 ≥ 90%
|
||
- 集成测试覆盖所有场景
|
||
- 性能测试验证大文件上传下载性能
|
||
|
||
## 视觉锚点
|
||
|
||
### Visual Reference
|
||
|
||
引用 Canvas 的具体节点或快照：
|
||
- [Authentication.canvas](../../Authentication.canvas) - 相关架构图
|
||
- **具体节点**: [集成核心](node_integration_core) - 提供与Salesforce的各种连接方式
|
||
- **具体节点**: [SessionManager](node_session_manager_detail) - 会话管理，提供登录服务
|
||
- **具体节点**: [PartnerV1Connection](node_partner_v1_connection) - Partner API 连接
|
||
|
||
### Status
|
||
|
||
- [x] Draft
|
||
- [ ] Accepted
|
||
- [ ] Superceded
|
||
|
||
## 参考资料
|
||
|
||
列出与该决策相关的参考资料，包括文档、文章或其他资源：
|
||
|
||
- [REQ-011.md](../requirements/REQ-011.md) - Salesforce文件上传下载功能
|
||
- [REQ-011-4.md](../requirements/REQ-011-4.md) - Document 文件上传下载功能
|
||
- [Document上传下载.md](../reference-code/data-dump/Document上传下载.md) - Salesforce Document 上传下载实现逻辑
|
||
- [0028-attachment-upload-download.md](./0028-attachment-upload-download.md) - Attachment 文件上传下载架构决策
|
||
- [0029-contentdocument-upload-download.md](./0029-contentdocument-upload-download.md) - ContentDocument 文件上传下载架构决策
|
||
- [Salesforce Partner API 文档](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/) - Salesforce Partner API 官方文档
|
||
- [Salesforce Document 对象文档](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources/sobject_document.htm) - Salesforce Document 对象官方文档
|