131 lines
6.4 KiB
Markdown
131 lines
6.4 KiB
Markdown
# 变更记录：ContentDocument/ContentVersion 文件上传下载功能实现
|
||
|
||
## 变更信息
|
||
|
||
- **版本号**: v1.0.2
|
||
- **发布日期**: 2026-01-19
|
||
- **变更类型**: [特性更新]
|
||
|
||
## 变更摘要
|
||
|
||
本次变更实现了Salesforce ContentDocument/ContentVersion对象的文件上传下载功能，使用REST API + Multipart/form-data方式进行文件上传，使用REST API + 流式处理方式进行文件下载。引入了Apache HttpClient依赖，支持最大2GB文件，使用流式处理避免内存溢出。
|
||
|
||
## 详细变更
|
||
|
||
### 特性更新
|
||
|
||
- **Apache HttpClient依赖** - 在datai-salesforce-integration模块的pom.xml中引入Apache HttpClient依赖
|
||
- httpclient依赖（版本4.5.13）- 提供HTTP客户端功能
|
||
- httpmime依赖（版本4.5.13）- 提供Multipart/form-data支持
|
||
- **ContentVersionUploadStrategy类** - 实现了ContentVersion上传策略，使用REST API + Multipart/form-data方式上传文件，支持最大2GB文件大小，包含文件验证、会话管理、错误处理等功能
|
||
- **ContentVersionDownloadStrategy类** - 实现了ContentVersion下载策略，使用REST API + 流式处理方式下载文件，使用BufferedInputStream和ByteArrayOutputStream避免内存溢出，包含会话管理、错误处理等功能
|
||
- **ContentVersionFileService接口** - 定义了ContentVersion文件服务接口，包含uploadContentVersion()和downloadContentVersion()方法
|
||
- **ContentVersionFileServiceImpl类** - 实现了ContentVersion文件服务，使用策略模式封装上传下载逻辑，通过@Autowired注入FileUploadStrategy和FileDownloadStrategy
|
||
|
||
### 技术实现
|
||
|
||
- **REST API集成** - 使用Apache HttpClient进行REST API调用，设置Authorization、Content-Type等请求头
|
||
- **Multipart/form-data上传** - 使用MultipartEntityBuilder构建Multipart/form-data请求，支持Title、PathOnClient、FirstPublishLocationId、Description等字段
|
||
- **流式处理** - 上传时使用FileInputStream读取文件内容，下载时使用BufferedInputStream和ByteArrayOutputStream进行流式处理，避免大文件导致内存溢出
|
||
- **会话管理** - 使用SessionManager获取Access Token和Instance URL，支持自动重新登录
|
||
- **异常处理** - 实现了完善的异常处理机制，包括FileSizeExceededException、FileTypeNotSupportedException、FileValidationException、OrgConfigNotFoundException、FileUploadException、FileDownloadException等
|
||
- **日志记录** - 使用@Slf4j注解记录关键操作日志，包括上传下载开始、成功、失败等
|
||
|
||
## 影响范围
|
||
|
||
### 受影响的模块
|
||
|
||
- **datai-salesforce-integration模块** - 新增文件上传下载策略和服务，引入Apache HttpClient依赖
|
||
- **策略包** - 新增ContentVersionUploadStrategy类、ContentVersionDownloadStrategy类
|
||
- **服务包** - 新增ContentVersionFileService接口、ContentVersionFileServiceImpl类
|
||
|
||
### 兼容性说明
|
||
|
||
- **向后兼容** - 本次变更不影响现有功能
|
||
- **API兼容性** - 新增的策略和服务提供独立的API接口
|
||
- **依赖兼容性** - Apache HttpClient 4.5.13与Spring Boot 3兼容
|
||
|
||
## 升级指南
|
||
|
||
### 升级步骤
|
||
|
||
1. **引入依赖** - 确保项目已引入Apache HttpClient依赖（httpclient 4.5.13、httpmime 4.5.13）
|
||
2. **代码集成** - 在需要使用ContentVersion文件上传下载功能的模块中引入新增的策略和服务类
|
||
3. **配置验证** - 确保SessionManager已正确配置，能够获取Access Token和Instance URL
|
||
|
||
### 使用示例
|
||
|
||
```java
|
||
@Autowired
|
||
private ContentVersionFileService contentVersionFileService;
|
||
|
||
public void uploadFile() {
|
||
FileUploadRequest request = FileUploadRequest.builder()
|
||
.orgConfigId("org-config-id")
|
||
.fileType(FileObjectType.CONTENT_DOCUMENT)
|
||
.file(multipartFile)
|
||
.relatedRecordId("record-id")
|
||
.fileName("example.pdf")
|
||
.description("示例文件")
|
||
.build();
|
||
|
||
FileUploadResponse response = contentVersionFileService.uploadContentVersion(request);
|
||
System.out.println("文件上传成功: " + response.getFileId());
|
||
}
|
||
|
||
public void downloadFile() {
|
||
FileDownloadRequest request = FileDownloadRequest.builder()
|
||
.orgConfigId("org-config-id")
|
||
.fileType(FileObjectType.CONTENT_DOCUMENT)
|
||
.fileId("content-version-id")
|
||
.fileName("example.pdf")
|
||
.build();
|
||
|
||
FileDownloadResponse response = contentVersionFileService.downloadContentVersion(request);
|
||
System.out.println("文件下载成功: " + response.getFileSize());
|
||
}
|
||
```
|
||
|
||
### 注意事项
|
||
|
||
- **文件大小限制** - ContentVersion对象的文件大小限制是2GB
|
||
- **Multipart/form-data上传** - 使用Multipart/form-data方式上传，不需要Base64编码，减少内存开销
|
||
- **流式处理** - 上传下载时使用流式处理避免内存溢出，适合大文件处理
|
||
- **会话管理** - 确保SessionManager已正确配置，能够获取Access Token和Instance URL
|
||
- **错误处理** - 建议调用方捕获并处理可能的异常，如FileUploadException、FileDownloadException等
|
||
- **临时文件清理** - 上传时会创建临时文件，上传完成后会自动删除
|
||
|
||
## 测试信息
|
||
|
||
### 测试环境
|
||
|
||
- **开发环境** - 本地开发环境
|
||
- **测试环境** - 待定
|
||
|
||
### 测试结果
|
||
|
||
- **编译检查** - 通过IDE诊断检查，无编译错误或警告
|
||
- **单元测试** - 待完成（目标测试覆盖率 ≥ 90%）
|
||
- **代码质量检查** - 待完成（SonarQube、Checkstyle、SpotBugs）
|
||
|
||
## 相关链接
|
||
|
||
- [需求文档](../requirements/REQ-011.md) - Salesforce文件上传下载功能
|
||
- [子需求文档](../requirements/REQ-011-3.md) - ContentDocument/ContentVersion 文件上传下载功能
|
||
- [架构决策](../decisions/adr/0029-contentdocument-upload-download.md) - ContentDocument/ContentVersion 文件上传下载架构决策
|
||
- [执行提示词](../prompts/030-contentdocument-upload-download.md) - ContentDocument/ContentVersion 文件上传下载执行提示词
|
||
- [会话记录](../sessions/20260119-req-011-3-contentdocument-upload-download.md) - REQ-011-3执行会话记录
|
||
- [参考代码](../reference-code/data-dump/ContentVersion上传下载.md) - Salesforce ContentVersion 上传实现逻辑
|
||
- [参考代码](../reference-code/data-dump/大文件上传下载.md) - 大文件上传下载实现逻辑（Multipart/form-data）
|
||
|
||
## 发布人员
|
||
|
||
- **开发人员** - SSOT架构师
|
||
|
||
## 审核信息
|
||
|
||
- **审核人员**: 待定
|
||
- **审核日期**: 待定
|
||
- **审核状态**: [待审核]
|
||
- **审核意见**: 待审核
|