# 架构决策记录 (ADR) - 基础设施和枚举定义

## 背景

REQ-011-1 需求要求在 datai-salesforce-common 模块定义文件上传下载所需的基础设施，包括：
- 文件对象类型枚举（FileObjectType）
- 文件上传下载参数类（DTO/VO）
- 文件上传下载异常类
- 文件验证工具类

这些基础设施将被后续的文件上传下载功能（REQ-011-2/3/4/5/6）使用，需要确保设计的合理性和可扩展性。

**约束条件**：
- 必须基于现有的 Spring Boot 3 技术栈
- 必须遵循 Authentication.canvas 中定义的架构和调用关系
- 必须在 datai-salesforce-common 模块下实现
- 必须遵循 SSOT 方法论

**业务需求**：
- 支持 Attachment、ContentDocument、Document 三种文件对象类型
- 提供统一的参数验证和响应封装
- 提供完善的异常处理机制
- 支持文件大小和类型验证

## 决策

采用**策略模式 + 枚举 + 统一异常处理**的架构设计方案：

1. **文件对象类型枚举（FileObjectType）**：
   - 使用 Java 枚举定义 ATTACHMENT、CONTENT_DOCUMENT、DOCUMENT 三个枚举值
   - 每个枚举值包含：描述、文件大小限制、推荐等级、API 类型、必填字段等元数据
   - 提供静态方法进行枚举值与字符串的转换
   - 提供获取文件大小限制和推荐等级的方法

2. **参数类设计**：
   - FileUploadRequest：包含组织配置 ID、文件对象类型、文件、关联记录 ID、文件名、描述等字段
   - FileDownloadRequest：包含组织配置 ID、文件对象类型、文件 ID、保存路径等字段
   - FileUploadResponse：包含文件 ID、文件名、文件大小、文件类型、上传时间、操作状态等字段
   - FileDownloadResponse：包含文件名、文件大小、保存路径、下载时间、操作状态等字段
   - 使用 Lombok 注解简化代码（@Data、@Builder、@NoArgsConstructor、@AllArgsConstructor）
   - 使用 JSR-303 验证注解（@NotNull、@NotBlank、@Size、@Valid）

3. **异常类设计**：
   - 继承自 datai-salesforce-common 模块的 RuntimeException 基类
   - 提供错误代码枚举（FileErrorCode）
   - 每个异常类包含：错误代码、错误消息、异常链（cause）
   - 异常类包括：FileUploadException、FileDownloadException、FileSizeExceededException、FileTypeNotSupportedException、FileObjectNotFoundException、OrgConfigNotFoundException、FileValidationException

4. **验证工具类设计**：
   - FileValidationUtils：提供文件大小验证、文件类型验证、文件名验证、文件扩展名获取、文件 MIME 类型获取等静态方法
   - 使用 Apache Tika 获取文件 MIME 类型
   - 提供可配置的文件大小限制和文件类型白名单

## 备选方案

### 方案一：策略模式 + 枚举 + 统一异常处理（已选择）

**优点**：
- 枚举提供类型安全和编译时检查
- 策略模式易于扩展新的文件对象类型
- 统一异常处理机制便于维护
- 参数类使用 Lombok 和 JSR-303 注解，代码简洁
- 验证工具类提供可复用的验证逻辑

**缺点**：
- 需要引入 Apache Tika 依赖
- 枚举扩展需要修改代码

### 方案二：配置文件 + 反射 + 动态验证

**优点**：
- 文件对象类型配置化，无需修改代码即可扩展
- 验证规则可配置，灵活性高

**缺点**：
- 失去编译时类型安全
- 反射影响性能
- 配置复杂度增加
- 维护成本高

### 方案三：继承体系 + 抽象类

**优点**：
- 面向对象设计，符合 OOP 原则
- 可以通过继承扩展功能

**缺点**：
- 类层次结构复杂
- 三种文件对象类型差异较大，难以抽象
- 违反"组合优于继承"原则

## 影响

### 系统架构影响

1. **datai-salesforce-common 模块**：
   - 新增枚举类：FileObjectType
   - 新增参数类：FileUploadRequest、FileDownloadRequest、FileUploadResponse、FileDownloadResponse
   - 新增异常类：FileUploadException、FileDownloadException、FileSizeExceededException、FileTypeNotSupportedException、FileObjectNotFoundException、OrgConfigNotFoundException、FileValidationException
   - 新增错误代码枚举：FileErrorCode
   - 新增工具类：FileValidationUtils

2. **依赖管理**：
   - 需要引入 Apache Tika 依赖（用于文件 MIME 类型检测）
   - 需要引入 Lombok 依赖（如果尚未引入）
   - 需要引入 Spring Validation 依赖（如果尚未引入）

### 开发流程影响

1. **后续子需求开发**：
   - REQ-011-2/3/4 可以直接使用 FileObjectType 枚举
   - REQ-011-2/3/4 可以直接使用 FileUploadRequest 和 FileDownloadRequest
   - REQ-011-2/3/4 可以直接使用 FileUploadResponse 和 FileDownloadResponse
   - REQ-011-2/3/4 可以直接使用异常类和验证工具类

2. **测试流程**：
   - 需要为枚举类编写单元测试
   - 需要为参数类编写单元测试
   - 需要为异常类编写单元测试
   - 需要为验证工具类编写单元测试

### 运维管理影响

1. **配置管理**：
   - 文件大小限制和文件类型白名单可以通过配置文件管理
   - 无需修改代码即可调整验证规则

2. **日志管理**：
   - 异常类提供详细的错误信息和错误代码
   - 便于日志分析和问题排查

## 风险

### 技术风险

1. **Apache Tika 依赖冲突**：
   - 风险描述：Apache Tika 可能与项目现有依赖冲突
   - 影响程度：中
   - 缓解措施：使用 Maven 依赖树检查冲突，必要时使用 exclusions

2. **枚举扩展性**：
   - 风险描述：未来可能需要支持更多文件对象类型，需要修改枚举
   - 影响程度：低
   - 缓解措施：枚举设计时考虑扩展性，提供清晰的扩展文档

### 业务风险

1. **文件大小限制调整**：
   - 风险描述：Salesforce 可能调整文件大小限制
   - 影响程度：低
   - 缓解措施：文件大小限制配置化，便于调整

2. **文件类型白名单维护**：
   - 风险描述：文件类型白名单需要定期维护
   - 影响程度：低
   - 缓解措施：提供配置文件，便于运维人员维护

### 实施风险

1. **参数验证复杂性**：
   - 风险描述：参数验证逻辑可能过于复杂
   - 影响程度：中
   - 缓解措施：使用 JSR-303 验证注解，简化验证逻辑

2. **异常类设计不完善**：
   - 风险描述：异常类设计可能不够完善，遗漏某些异常场景
   - 影响程度：中
   - 缓解措施：参考现有的异常类定义，提供详细的错误代码

## 回滚策略

如果决策实施后出现问题，可以采用以下回滚策略：

1. **Apache Tika 依赖冲突**：
   - 回滚方案：移除 Apache Tika 依赖，使用 Java 内置的 Files.probeContentType() 方法
   - 回滚步骤：
     1. 在 pom.xml 中移除 Apache Tika 依赖
     2. 修改 FileValidationUtils，使用 Files.probeContentType() 方法
     3. 重新编译和测试

2. **枚举扩展性不足**：
   - 回滚方案：将枚举改为配置文件 + 反射
   - 回滚步骤：
     1. 创建 file-object-types.yml 配置文件
     2. 修改 FileObjectType 为配置类
     3. 使用反射动态加载配置
     4. 重新编译和测试

3. **参数验证逻辑复杂**：
   - 回滚方案：简化参数验证，只保留核心验证逻辑
   - 回滚步骤：
     1. 移除复杂的自定义验证注解
     2. 只保留 JSR-303 基础验证注解
     3. 重新编译和测试

## 验收标准

定义验证该决策有效性的具体标准和测试方法：

1. **功能验证**：
   - [ ] FileObjectType 枚举包含 ATTACHMENT、CONTENT_DOCUMENT、DOCUMENT 三个枚举值
   - [ ] FileObjectType 枚举提供描述、文件大小限制、推荐等级等元数据
   - [ ] FileObjectType 枚举提供枚举值与字符串的转换方法
   - [ ] FileUploadRequest 包含所有必需字段
   - [ ] FileDownloadRequest 包含所有必需字段
   - [ ] FileUploadResponse 包含所有必需字段
   - [ ] FileDownloadResponse 包含所有必需字段
   - [ ] 所有异常类继承自 RuntimeException
   - [ ] 所有异常类提供错误代码和错误消息
   - [ ] FileValidationUtils 提供所有必需的验证方法

2. **代码质量验证**：
   - [ ] 代码符合项目编码规范
   - [ ] 代码有清晰的注释
   - [ ] 代码通过 SonarQube 静态代码分析
   - [ ] 代码通过 Checkstyle 检查

3. **单元测试验证**：
   - [ ] FileObjectType 枚举单元测试覆盖率 ≥ 90%
   - [ ] 参数类单元测试覆盖率 ≥ 90%
   - [ ] 异常类单元测试覆盖率 ≥ 90%
   - [ ] FileValidationUtils 单元测试覆盖率 ≥ 90%

4. **集成测试验证**：
   - [ ] 后续子需求（REQ-011-2/3/4）能够正常使用这些基础设施
   - [ ] 文件上传下载功能能够正常工作

## 视觉锚点

### Visual Reference

引用 Canvas 的具体节点或快照：
- [Authentication.canvas](../../Authentication.canvas) - 相关架构图
- **具体节点**: [通用常量](node_common_constant) - 定义Salesforce相关的常量
- **具体节点**: [通用异常](node_common_exception) - 定义Salesforce相关的异常类

### Status

- [x] Draft
- [ ] Accepted
- [ ] Superceded

## 参考资料

列出与该决策相关的参考资料，包括文档、文章或其他资源：

1. [REQ-011.md](../requirements/REQ-011.md) - 父需求文档
2. [REQ-011-1.md](../requirements/REQ-011-1.md) - 子需求文档
3. [Authentication.canvas](../Authentication.canvas) - 项目架构视觉化展示
4. [Attachment文件上传.md](../reference-code/data-dump/Attachment文件上传.md) - Salesforce Attachment 上传实现逻辑
5. [Attachment文件下载.md](../reference-code/data-dump/Attachment文件下载.md) - Salesforce Attachment 下载实现逻辑
6. [Document上传下载.md](../reference-code/data-dump/Document上传下载.md) - Salesforce Document 上传下载实现逻辑
7. [ContentVersion上传下载.md](../reference-code/data-dump/ContentVersion上传下载.md) - Salesforce ContentVersion 上传下载实现逻辑
8. [大文件上传下载.md](../reference-code/data-dump/大文件上传下载.md) - 大文件上传下载实现逻辑
9. [CommonServiceImpl.java](../reference-code/data-dump/CommonServiceImpl.java) - 现有的文件上传下载实现逻辑
10. [DataImportNewServiceImpl.java](../reference-code/data-dump/DataImportNewServiceImpl.java) - 现有的文件上传下载实现逻辑
11. [Java 枚举最佳实践](https://docs.oracle.com/javase/tutorial/java/javaOO/enum.html) - Oracle 官方文档
12. [JSR-303 Bean Validation](https://beanvalidation.org/2.0/spec/) - Bean Validation 规范
13. [Apache Tika 文档](https://tika.apache.org/) - Apache Tika 官方文档
14. [Lombok 文档](https://projectlombok.org/) - Lombok 官方文档