212 lines
7.3 KiB
Markdown
212 lines
7.3 KiB
Markdown
# 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 拆分 | 系统管理员 | - | 待审核 |
|
||
|
||
## 相关人员
|
||
|
||
- **需求提出人**: 系统管理员 - 联系方式
|
||
- **需求负责人**: 系统管理员 - 联系方式
|
||
- **技术负责人**: 开发工程师 - 联系方式
|
||
- **测试负责人**: 测试工程师 - 联系方式
|
||
- **其他相关人员**: - 联系方式
|
||
|
||
## 评审信息
|
||
|
||
- **评审日期**: -
|
||
- **评审人员**: -
|
||
- **评审结果**: -
|
||
- **评审意见**: -
|
||
- **修改建议**: -
|