kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
3d290a8dd1
datai/docs/archive/REQ-011-1.md

7.3 KiB
Raw Blame History

Requirements - 基础设施和枚举定义

需求信息

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

输入引用

引用相关的 docs 文档链接：

Context Maps

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

需求目标

在 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 拆分 系统管理员 - 待审核

相关人员

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

评审信息

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