datai/datai-scenes/datai-scene-salesforce/docs/requirements/REQ-011-1.md

# Requirements - 基础设施和枚举定义

## 需求信息

- **需求名称**: 基础设施和枚举定义
- **需求类型**: 功能需求
- **需求编号**: REQ-011-1
- **父需求**: [REQ-011](./REQ-011.md) - Salesforce文件上传下载功能（支持Attachment、ContentDocument、Document）
- **创建日期**: 2026-01-19
- **需求版本**: v1.0.0
- **需求提出人**: 系统管理员
- **需求状态**: 待审核

## 输入引用

引用相关的 docs 文档链接：

- [REQ-011.md](./REQ-011.md) - 父需求文档
- [Authentication.canvas](../Authentication.canvas) - 项目架构视觉化展示

## Context Maps

强制列出本次需求依赖的 Canvas 文件：

- [Authentication.canvas](../Authentication.canvas) - 项目架构视觉化展示
- **相关节点**: [通用常量](node_common_constant) - 定义Salesforce相关的常量
- **相关节点**: [通用异常](node_common_exception) - 定义Salesforce相关的异常类

## 需求目标

在 datai-salesforce-common 模块定义文件上传下载所需的基础设施，包括文件对象类型枚举、参数类、异常类和验证工具类，为后续的文件上传下载功能提供基础支持。

## 需求描述

### 概述

本需求旨在定义文件上传下载所需的基础设施，包括文件对象类型枚举、请求参数类、响应类、异常类和验证工具类。这些基础设施将被后续的文件上传下载功能使用。

### 详细需求

#### 1. 文件对象类型枚举

- **需求描述**: 定义文件对象类型枚举，支持 Attachment、ContentDocument、Document 三种类型
- **优先级**: 高
- **验收标准**: 
  - 定义 FileObjectType 枚举类
  - 包含 ATTACHMENT、CONTENT_DOCUMENT、DOCUMENT 三个枚举值
  - 提供枚举值的描述信息
  - 提供枚举值到字符串的转换方法
  - 提供字符串到枚举值的转换方法
  - 提供获取文件大小限制的方法
  - 提供获取推荐等级的方法
- **依赖关系**: 无
- **实现建议**: 
  - 使用 Java 枚举定义 FileObjectType
  - 添加枚举值的描述字段
  - 添加文件大小限制字段
  - 添加推荐等级字段
  - 添加静态方法进行转换

#### 2. 文件上传请求参数类

- **需求描述**: 定义文件上传请求参数类，包含上传所需的所有参数
- **优先级**: 高
- **验收标准**: 
  - 定义 FileUploadRequest 参数类
  - 包含组织配置 ID 字段
  - 包含文件对象类型字段（FileObjectType）
  - 包含文件字段（MultipartFile）
  - 包含关联记录 ID 字段（ParentId/FirstPublishLocationId/FolderId）
  - 包含文件名字段
  - 包含描述字段（可选）
  - 使用 @Valid 注解进行参数验证
  - 提供参数验证方法
- **依赖关系**: 依赖于 FileObjectType 枚举
- **实现建议**: 
  - 使用 Lombok 注解简化代码
  - 使用 JSR-303 验证注解
  - 提供自定义验证注解

#### 3. 文件下载请求参数类

- **需求描述**: 定义文件下载请求参数类，包含下载所需的所有参数
- **优先级**: 高
- **验收标准**: 
  - 定义 FileDownloadRequest 参数类
  - 包含组织配置 ID 字段
  - 包含文件对象类型字段（FileObjectType）
  - 包含文件 ID 字段（AttachmentId/ContentVersionId/DocumentId）
  - 包含保存路径字段
  - 使用 @Valid 注解进行参数验证
  - 提供参数验证方法
- **依赖关系**: 依赖于 FileObjectType 枚举
- **实现建议**: 
  - 使用 Lombok 注解简化代码
  - 使用 JSR-303 验证注解
  - 提供自定义验证注解

#### 4. 文件上传下载响应类

- **需求描述**: 定义文件上传下载响应类，包含操作结果的详细信息
- **优先级**: 高
- **验收标准**: 
  - 定义 FileUploadResponse 响应类
  - 包含文件 ID 字段
  - 包含文件名字段
  - 包含文件大小字段
  - 包含文件类型字段
  - 包含上传时间字段
  - 包含操作状态字段
  - 定义 FileDownloadResponse 响应类
  - 包含文件名字段
  - 包含文件大小字段
  - 包含保存路径字段
  - 包含下载时间字段
  - 包含操作状态字段
- **依赖关系**: 无
- **实现建议**: 
  - 使用 Lombok 注解简化代码
  - 统一响应格式

#### 5. 文件上传下载异常类

- **需求描述**: 定义文件上传下载相关的异常类
- **优先级**: 高
- **验收标准**: 
  - 定义 FileUploadException 异常类
  - 定义 FileDownloadException 异常类
  - 定义 FileSizeExceededException 异常类
  - 定义 FileTypeNotSupportedException 异常类
  - 定义 FileObjectNotFoundException 异常类
  - 定义 OrgConfigNotFoundException 异常类
  - 所有异常类继承自 RuntimeException
  - 提供详细的错误信息和错误代码
- **依赖关系**: 依赖于 datai-salesforce-common 模块的异常类
- **实现建议**: 
  - 参考现有的异常类定义
  - 使用统一的异常处理机制
  - 提供错误代码枚举

#### 6. 文件验证工具类

- **需求描述**: 定义文件验证工具类，提供文件大小和类型的验证方法
- **优先级**: 高
- **验收标准**: 
  - 定义 FileValidationUtils 工具类
  - 提供文件大小验证方法
  - 提供文件类型验证方法
  - 提供文件名验证方法
  - 提供文件扩展名获取方法
  - 提供文件 MIME 类型获取方法
  - 所有方法为静态方法
- **依赖关系**: 依赖于 FileObjectType 枚举
- **实现建议**: 
  - 使用 Apache Tika 获取文件 MIME 类型
  - 提供可配置的文件大小限制
  - 提供可配置的文件类型白名单

## 约束

- **技术栈限制**: 必须基于现有的 Spring Boot 3 技术栈
- **架构约束**: 必须遵循 Authentication.canvas 中定义的架构和调用关系
- **模块约束**: 必须在 datai-salesforce-common 模块下实现
- **文档约束**: 必须遵循 SSOT 方法论
- **代码规范**: 必须遵循项目编码规范

## Rule Set

"请严格参考 @Authentication.canvas 中的状态机转移逻辑，不要自行发挥。"

**具体规则**：
- 必须使用 Canvas 中定义的类名和方法名
- 必须遵循 Canvas 中定义的调用关系
- 必须参考 Canvas 中的流程图逻辑
- 必须遵循现有的异常处理机制
- 必须遵循现有的日志记录规范

## 验收标准

- **功能完整性**: 所有基础设施类能够正常工作，提供完整的枚举、参数、异常和验证功能
- **代码规范性**: 代码符合项目编码规范，有清晰的注释
- **可维护性**: 代码结构清晰，易于扩展和维护
- **可测试性**: 代码易于单元测试

## 风险

- **枚举扩展风险**: 未来可能需要支持更多文件对象类型
- **验证规则风险**: 文件大小和类型验证规则可能需要调整
- **异常处理风险**: 异常类设计可能不够完善

## 需求变更记录

| 日期 | 变更内容 | 变更原因 | 变更人 | 审核人 | 状态 |
|------|---------|---------|--------|--------|------|
| 2026-01-19 | 创建需求文档 | 从 REQ-011 拆分 | 系统管理员 | - | 待审核 |

## 相关人员

- **需求提出人**: 系统管理员 - 联系方式
- **需求负责人**: 系统管理员 - 联系方式
- **技术负责人**: 开发工程师 - 联系方式
- **测试负责人**: 测试工程师 - 联系方式
- **其他相关人员**: - 联系方式

## 评审信息

- **评审日期**: - 
- **评审人员**: - 
- **评审结果**: - 
- **评审意见**: - 
- **修改建议**: -