93 lines
4.8 KiB
Markdown
93 lines
4.8 KiB
Markdown
# 变更记录：文件上传下载基础设施实现
|
||
|
||
## 变更信息
|
||
|
||
- **版本号**: v1.0.0
|
||
- **发布日期**: 2026-01-19
|
||
- **变更类型**: [特性更新]
|
||
|
||
## 变更摘要
|
||
|
||
本次变更实现了Salesforce文件上传下载的基础设施，包括文件对象类型枚举、错误代码枚举、异常类、参数类、响应类和验证工具类。这些基础设施为后续实现Attachment、ContentDocument、Document三种文件对象类型的上传下载功能提供了统一的架构支持。
|
||
|
||
## 详细变更
|
||
|
||
### 特性更新
|
||
|
||
- **FileObjectType枚举** - 定义了Attachment、ContentDocument、Document三种文件对象类型，包含API名称、描述、文件大小限制、推荐等级、上传方式和必填字段等元数据
|
||
- **FileErrorCode枚举** - 定义了10个文件相关的错误代码，包括FILE_UPLOAD_FAILED、FILE_DOWNLOAD_FAILED、FILE_SIZE_EXCEEDED、FILE_TYPE_NOT_SUPPORTED等
|
||
- **FileUploadException异常类** - 文件上传异常，继承自RuntimeException，包含错误代码和错误消息
|
||
- **FileDownloadException异常类** - 文件下载异常，继承自RuntimeException，包含错误代码和错误消息
|
||
- **FileSizeExceededException异常类** - 文件大小超限异常，包含实际大小和最大限制
|
||
- **FileTypeNotSupportedException异常类** - 文件类型不支持异常，包含实际类型和支持的类型列表
|
||
- **FileObjectNotFoundException异常类** - 文件对象不存在异常，包含对象ID和对象类型
|
||
- **OrgConfigNotFoundException异常类** - 组织配置不存在异常，包含配置ID
|
||
- **FileValidationException异常类** - 文件验证异常，包含验证类型
|
||
- **FileUploadRequest参数类** - 文件上传请求参数，包含组织配置ID、文件对象类型、文件、关联记录ID、文件名和描述，使用Lombok注解和JSR-303验证注解
|
||
- **FileDownloadRequest参数类** - 文件下载请求参数，包含组织配置ID、文件对象类型、文件ID和保存路径，使用Lombok注解和JSR-303验证注解
|
||
- **FileUploadResponse响应类** - 文件上传响应，包含文件ID、文件名、文件大小、文件类型、上传时间、状态和消息
|
||
- **FileDownloadResponse响应类** - 文件下载响应，包含文件名、文件大小、保存路径、下载时间、状态和消息
|
||
- **FileValidationUtils工具类** - 文件验证工具类，提供文件大小验证、文件类型验证、文件名验证、文件扩展名获取、文件MIME类型获取等功能，支持13种文件类型白名单和13种危险扩展名黑名单
|
||
|
||
## 影响范围
|
||
|
||
### 受影响的模块
|
||
|
||
- **datai-salesforce-common模块** - 新增文件上传下载基础设施
|
||
- **枚举包** - 新增FileObjectType枚举
|
||
- **异常包** - 新增8个文件相关异常类
|
||
- **参数包** - 新增2个文件请求参数类和2个文件响应类
|
||
- **工具包** - 新增FileValidationUtils验证工具类
|
||
|
||
### 兼容性说明
|
||
|
||
- **向后兼容** - 本次变更不影响现有功能
|
||
- **API兼容性** - 新增的基础设施提供独立的API接口
|
||
|
||
## 升级指南
|
||
|
||
### 升级步骤
|
||
|
||
1. **引入依赖** - 确保项目已引入Lombok和Spring Boot 3.5.7（包含JSR-303验证）
|
||
2. **代码集成** - 在需要使用文件上传下载功能的模块中引入新增的基础设施类
|
||
3. **配置验证** - 根据实际需求调整FileValidationUtils中的ALLOWED_FILE_TYPES和DANGEROUS_EXTENSIONS
|
||
|
||
### 注意事项
|
||
|
||
- **文件大小限制** - 不同文件对象类型有不同的文件大小限制（Attachment: 50MB、ContentDocument: 2048MB、Document: 25MB）
|
||
- **文件类型限制** - 默认支持13种文件类型，可根据实际需求调整ALLOWED_FILE_TYPES
|
||
- **安全考虑** - 已实现路径遍历攻击防护和危险文件上传防护
|
||
- **MIME类型检测** - 使用Java内置的Files.probeContentType()方法，不依赖Apache Tika
|
||
|
||
## 测试信息
|
||
|
||
### 测试环境
|
||
|
||
- **开发环境** - 本地开发环境
|
||
- **测试环境** - 待定
|
||
|
||
### 测试结果
|
||
|
||
- **编译检查** - 通过IDE诊断检查，无编译错误
|
||
- **单元测试** - 待完成（目标测试覆盖率 ≥ 90%）
|
||
- **代码质量检查** - 待完成（SonarQube、Checkstyle、SpotBugs）
|
||
|
||
## 相关链接
|
||
|
||
- [需求文档](../requirements/REQ-011.md) - Salesforce文件上传下载功能
|
||
- [子需求文档](../requirements/REQ-011-1.md) - 基础设施和枚举定义
|
||
- [架构决策](../decisions/adr/0027-file-infrastructure-enums.md) - 文件上传下载基础设施架构决策
|
||
- [执行提示词](../prompts/028-file-infrastructure-enums.md) - 文件上传下载基础设施执行提示词
|
||
- [会话记录](../sessions/20260119-req-011-1-file-infrastructure-enums.md) - REQ-011-1执行会话记录
|
||
|
||
## 发布人员
|
||
|
||
- **开发人员** - SSOT架构师
|
||
|
||
## 审核信息
|
||
|
||
- **审核人员**: 待定
|
||
- **审核日期**: 待定
|
||
- **审核状态**: [待审核]
|
||
- **审核意见**: 待审核
|