252 lines
9.9 KiB
Markdown
252 lines
9.9 KiB
Markdown
# 架构决策记录：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 的具体节点或快照：
|
||
- [Authentication.canvas](../../Authentication.canvas) - 项目架构视觉化展示
|
||
- **具体节点**: [集成核心](node_integration_core) - 提供与Salesforce的各种连接方式
|
||
- **具体节点**: [SessionManager](node_session_manager_detail) - 会话管理，提供登录服务
|
||
- **具体节点**: [RESTConnection](node_rest_connection) - REST API 连接
|
||
|
||
### Status
|
||
|
||
- [x] Draft
|
||
- [ ] Accepted
|
||
- [ ] Superceded
|
||
|
||
## 参考资料
|
||
|
||
列出与该决策相关的参考资料，包括文档、文章或其他资源。
|
||
|
||
- [REQ-011.md](../requirements/REQ-011.md) - Salesforce文件上传下载功能
|
||
- [REQ-011-1.md](../requirements/REQ-011-1.md) - 基础设施和枚举定义
|
||
- [REQ-011-2.md](../requirements/REQ-011-2.md) - Attachment 文件上传下载功能
|
||
- [Attachment文件上传.md](../reference-code/data-dump/Attachment文件上传.md) - Salesforce Attachment 上传实现逻辑
|
||
- [Attachment文件下载.md](../reference-code/data-dump/Attachment文件下载.md) - Salesforce Attachment 下载实现逻辑
|
||
- [Salesforce REST API 文档](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/) - Salesforce REST API 官方文档
|
||
- [Salesforce Attachment 对象文档](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources/sobject_attachment.htm) - Salesforce Attachment 对象官方文档
|