# 架构决策记录：文件上传下载 Controller 和 API 接口

## 背景

REQ-011-5 需求要求创建 FileController，提供文件上传下载的 RESTful API 接口，支持 Attachment、ContentDocument、Document 三种文件对象类型。用户可以通过 HTTP 请求上传和下载 Salesforce 的三种文件对象，支持指定组织配置 ID。

### 面临的问题

1. **Controller 设计**: 需要设计合理的 Controller，支持三种文件对象类型的上传下载功能
2. **API 设计**: 需要设计符合 RESTful 规范的 API 接口
3. **参数验证**: 需要设计合理的参数验证机制，确保 API 接口的健壮性
4. **响应封装**: 需要设计统一的响应格式，提高 API 接口的一致性
5. **策略模式应用**: 需要使用策略模式根据文件对象类型调用不同的 Service
6. **文档生成**: 需要生成清晰的 API 文档，提高 API 接口的可用性

### 约束条件

1. **技术栈限制**: 必须基于现有的 Spring Boot 3 技术栈
2. **架构约束**: 必须遵循 Authentication.canvas 中定义的架构和调用关系
3. **模块约束**: 必须在 datai-salesforce-integration 模块下实现
4. **认证约束**: 必须使用 SessionManager 进行会话管理和自动重新登录
5. **API约束**: 必须遵循 RESTful 设计规范
6. **文档约束**: 必须遵循 SSOT 方法论
7. **设计模式约束**: 必须使用策略模式封装三种文件对象的上传下载逻辑
8. **验证约束**: 必须使用 JSR-303 验证注解进行参数验证
9. **文档约束**: 必须使用 Swagger/OpenAPI 注解生成 API 文档

## 决策

### 1. Controller 设计

**决策**: 创建 FileController，使用 @RestController 和 @RequestMapping 注解

**理由**:
- @RestController 是 Spring Boot 推荐的 RESTful Controller 注解
- @RequestMapping 可以指定基础路径，便于 API 管理
- 符合 Spring Boot 最佳实践
- 代码简洁，易于维护

**实现方案**:
- 使用 @RestController 注解标记 FileController
- 使用 @RequestMapping("/files") 注解指定基础路径
- 使用 @Slf4j 注解记录日志
- 使用 @Autowired 注入 AttachmentFileService、ContentVersionFileService、DocumentFileService

### 2. API 设计

**决策**: 设计符合 RESTful 规范的 API 接口

**理由**:
- RESTful 是业界公认的 API 设计规范
- 提高 API 接口的一致性和可维护性
- 便于前端调用和集成
- 符合业界最佳实践

**实现方案**:
- 文件上传接口：POST /files/upload
- 文件下载接口：GET /files/download
- 使用 @PostMapping 和 @GetMapping 注解
- 使用 @RequestParam 和 @RequestPart 注解接收参数
- 使用 @Valid 注解进行参数验证
- 返回统一的响应格式

### 3. 参数验证

**决策**: 使用 JSR-303 验证注解进行参数验证

**理由**:
- JSR-303 是 Java 标准的验证规范
- Spring Boot 3.5.7 内置 JSR-303 支持
- 提供丰富的验证注解，如 @NotNull、@NotBlank、@Size 等
- 可以自定义验证注解
- 提高代码的可读性和可维护性

**实现方案**:
- 使用 @Valid 注解进行参数验证
- 使用 @NotNull、@NotBlank、@Size 等验证注解
- 自定义验证注解（如果需要）
- 提供详细的错误信息

### 4. 响应封装

**决策**: 使用统一的响应格式

**理由**:
- 提高 API 接口的一致性
- 便于前端处理响应
- 便于错误处理和日志记录
- 符合业界最佳实践

**实现方案**:
- 定义统一的响应格式，包含 code、message、data 字段
- 成功响应返回 200 状态码
- 失败响应返回 4xx 或 5xx 状态码
- 提供详细的错误信息

### 5. 策略模式应用

**决策**: 使用策略模式根据文件对象类型调用不同的 Service

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

**实现方案**:
- 使用 switch-case 语句根据 FileObjectType 调用不同的 Service
- Attachment 类型调用 AttachmentFileService
- ContentDocument 类型调用 ContentVersionFileService
- Document 类型调用 DocumentFileService

### 6. 文档生成

**决策**: 使用 Swagger/OpenAPI 注解生成 API 文档

**理由**:
- Swagger/OpenAPI 是业界标准的 API 文档规范
- 自动生成 API 文档，减少维护成本
- 提供在线 API 测试功能
- 提高开发效率和用户体验

**实现方案**:
- 使用 @Tag 注解标记 Controller
- 使用 @Operation 注解标记方法
- 使用 @Parameter 注解标记参数
- 使用 @ApiResponse 注解标记响应
- 配置 Swagger UI

## 备选方案

### 方案 1: 使用 GraphQL API

**优点**:
- GraphQL API 灵活强大
- 可以一次性获取多个数据
- 减少网络请求次数

**缺点**:
- GraphQL API 对文件上传下载支持有限
- 实现复杂度高
- 不符合 RESTful 规范
- 前端需要学习 GraphQL

**评估**: 不推荐使用

### 方案 2: 使用 gRPC API

**优点**:
- gRPC 性能优异
- 支持多种语言
- 使用 Protocol Buffers 序列化

**缺点**:
- gRPC 不适合文件上传下载
- 实现复杂度高
- 不符合 RESTful 规范
- 前端需要学习 gRPC

**评估**: 不推荐使用

### 方案 3: 使用自定义验证逻辑

**优点**:
- 可以完全控制验证逻辑
- 不依赖第三方库

**缺点**:
- 代码冗余，不易维护
- 不符合 JSR-303 标准
- 增加开发成本

**评估**: 不推荐使用

### 方案 4: 使用自定义响应格式

**优点**:
- 可以完全控制响应格式
- 不依赖第三方库

**缺点**:
- 代码冗余，不易维护
- 不符合业界最佳实践
- 增加开发成本

**评估**: 不推荐使用

## 影响

### 系统架构影响

1. **新增模块**: 在 datai-salesforce-integration 模块下新增 FileController
2. **新增接口**: 新增文件上传下载 API 接口
3. **新增依赖**: 新增 Swagger/OpenAPI 依赖
4. **新增验证**: 新增 JSR-303 验证注解

### 开发流程影响

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

### 运维管理影响

1. **监控要求**: 需要监控 API 接口的性能和错误率
2. **日志要求**: 需要记录详细的日志，便于问题排查
3. **文档要求**: 需要维护 API 文档，确保文档的准确性和及时性

## 风险

### 技术风险

1. **API 设计风险**: API 接口设计可能不够完善
   - **缓解措施**: 提前进行 API 设计评审，参考业界最佳实践
2. **参数验证风险**: 参数验证可能不够严格
   - **缓解措施**: 使用 JSR-303 验证注解，提供详细的错误信息
3. **响应封装风险**: 响应封装可能不够统一
   - **缓解措施**: 定义统一的响应格式，使用统一的响应封装逻辑
4. **并发风险**: 并发上传下载可能导致资源竞争
   - **缓解措施**: 使用线程池，限制并发数，监控并发性能

### 业务风险

1. **兼容性风险**: 前端可能不兼容新的 API 接口
   - **缓解措施**: 提供详细的 API 文档，提供前端集成指南
2. **性能风险**: API 接口性能可能不达标
   - **缓解措施**: 提前进行性能测试，优化代码性能

### 实施风险

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

## 回滚策略

### 回滚条件

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

### 回滚步骤

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

### 回滚后调整

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

## 验收标准

### 功能验收标准

1. **上传功能**: 能够成功上传本地文件到 Salesforce Attachment、ContentDocument、Document 对象
2. **下载功能**: 能够成功从 Salesforce Attachment、ContentDocument、Document 对象下载文件到本地
3. **参数验证**: 能够正确验证参数，提供详细的错误信息
4. **异常处理**: 能够正确处理异常，提供详细的错误信息
5. **日志记录**: 能够记录详细的日志，便于问题排查
6. **API 文档**: 能够生成清晰的 API 文档，便于前端调用和集成

### 性能验收标准

1. **上传性能**: 文件上传性能良好，不影响系统响应
2. **下载性能**: 文件下载性能良好，不影响系统响应
3. **并发性能**: 并发上传下载性能良好，不出现资源竞争

### 代码质量验收标准

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

### API 文档验收标准

1. **文档完整性**: API 文档包含所有接口的详细信息
2. **文档准确性**: API 文档与实际接口一致
3. **文档可读性**: API 文档清晰易懂，便于前端调用和集成

## 视觉锚点

### Visual Reference

引用 Canvas 的具体节点或快照：
- [Authentication.canvas](../../Authentication.canvas) - 项目架构视觉化展示
- **具体节点**: [集成核心](node_integration_core) - 提供与Salesforce的各种连接方式
- **具体节点**: [SessionManager](node_session_manager_detail) - 会话管理，提供登录服务

### 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 文件上传下载功能
- [REQ-011-3.md](../requirements/REQ-011-3.md) - ContentDocument/ContentVersion 文件上传下载功能
- [REQ-011-4.md](../requirements/REQ-011-4.md) - Document 文件上传下载功能
- [REQ-011-5.md](../requirements/REQ-011-5.md) - 文件上传下载 Controller 和 API 接口
- [0028-attachment-upload-download.md](0028-attachment-upload-download.md) - Attachment 文件上传下载架构决策
- [0029-contentversion-upload-download.md](0029-contentversion-upload-download.md) - ContentVersion 文件上传下载架构决策
- [0030-document-upload-download.md](0030-document-upload-download.md) - Document 文件上传下载架构决策
- [Spring Boot REST API 文档](https://spring.io/guides/gs/rest-service/) - Spring Boot REST API 官方文档
- [Spring Boot Validation 文档](https://spring.io/guides/gs/validating-form-input/) - Spring Boot Validation 官方文档
- [SpringDoc OpenAPI 文档](https://springdoc.org/) - SpringDoc OpenAPI 官方文档