datai/datai-scenes/datai-scene-salesforce/docs/decisions/adr/0027-file-infrastructure-enums.md

架构决策记录 (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 - 相关架构图
• 具体节点: 通用常量 - 定义Salesforce相关的常量
• 具体节点: 通用异常 - 定义Salesforce相关的异常类

Status

• Draft
• Accepted
• Superceded

参考资料

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

1. REQ-011.md - 父需求文档
2. REQ-011-1.md - 子需求文档
3. Authentication.canvas - 项目架构视觉化展示
4. Attachment文件上传.md - Salesforce Attachment 上传实现逻辑
5. Attachment文件下载.md - Salesforce Attachment 下载实现逻辑
6. Document上传下载.md - Salesforce Document 上传下载实现逻辑
7. ContentVersion上传下载.md - Salesforce ContentVersion 上传下载实现逻辑
8. 大文件上传下载.md - 大文件上传下载实现逻辑
9. CommonServiceImpl.java - 现有的文件上传下载实现逻辑
10. DataImportNewServiceImpl.java - 现有的文件上传下载实现逻辑
11. Java 枚举最佳实践 - Oracle 官方文档
12. JSR-303 Bean Validation - Bean Validation 规范
13. Apache Tika 文档 - Apache Tika 官方文档
14. Lombok 文档 - Lombok 官方文档