# 架构决策记录：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 对象官方文档