变更记录：Document 文件上传下载功能实现

变更信息

版本号: v1.0.0
发布日期: 2026-01-19
变更类型: [特性更新]

变更摘要

本次变更实现了Salesforce Document对象的文件上传下载功能，使用Partner API (SOAP) + Base64编码方式进行文件上传，使用Partner API (SOAP) + 流式处理方式进行文件下载。实现了策略模式封装上传下载逻辑，为Attachment、ContentDocument、Document三种文件对象类型的上传下载功能提供了统一的架构支持。

详细变更

特性更新

DocumentUploadStrategy类 - 实现了Document上传策略，使用Partner API (SOAP) + Base64编码方式上传文件，支持最大20-30MB文件大小，包含文件验证、会话管理、错误处理等功能，支持指定FolderId（必填）、文件名和DeveloperName
DocumentDownloadStrategy类 - 实现了Document下载策略，使用Partner API (SOAP) + 流式处理方式下载文件，使用BufferedInputStream和ByteArrayOutputStream避免内存溢出，包含会话管理、错误处理等功能，支持指定Document ID和保存路径
DocumentFileService接口 - 定义了Document文件服务接口，包含uploadDocument()和downloadDocument()方法
DocumentFileServiceImpl类 - 实现了Document文件服务，使用策略模式封装上传下载逻辑，通过@Autowired注入FileUploadStrategy和FileDownloadStrategy

技术实现

Partner API (SOAP)集成 - 使用PartnerV1Connection进行SOAP API调用，使用create()方法创建Document对象，使用query()方法查询Document对象
Base64编码 - 使用Java内置的Base64.getEncoder().encodeToString()方法进行文件内容编码，将文件内容编码为Base64字符串存储在Document对象的Body字段中
流式处理 - 下载时使用BufferedInputStream和ByteArrayOutputStream进行流式处理，避免大文件导致内存溢出，使用Base64.getDecoder().decode()方法解码文件内容
会话管理 - 使用SessionManager获取Session ID，支持自动重新登录
异常处理 - 实现了完善的异常处理机制，包括FileSizeExceededException、FileTypeNotSupportedException、FileValidationException、FileObjectNotFoundException、OrgConfigNotFoundException、FileUploadException、FileDownloadException等
日志记录 - 使用@Slf4j注解记录关键操作日志，包括上传下载开始、成功、失败等

影响范围

受影响的模块

datai-salesforce-integration模块 - 新增Document文件上传下载策略和服务
策略包 - 新增DocumentUploadStrategy类、DocumentDownloadStrategy类
服务包 - 新增DocumentFileService接口、DocumentFileServiceImpl类

兼容性说明

向后兼容 - 本次变更不影响现有功能
API兼容性 - 新增的策略和服务提供独立的API接口

升级指南

升级步骤

引入依赖 - 确保项目已引入Lombok和Spring Boot 3.5.7（包含JSR-303验证）
代码集成 - 在需要使用Document文件上传下载功能的模块中引入新增的策略和服务类
配置验证 - 确保SessionManager已正确配置，能够获取Session ID
SOAP API配置 - 确保PartnerV1Connection已正确配置，能够进行SOAP API调用

使用示例

@Autowired
private DocumentFileService documentFileService;

public void uploadDocument() {
    FileUploadRequest request = FileUploadRequest.builder()
            .orgConfigId("org-config-id")
            .fileType(FileObjectType.DOCUMENT)
            .file(multipartFile)
            .relatedRecordId("folder-id")
            .fileName("example.pdf")
            .description("示例文件")
            .build();
    
    FileUploadResponse response = documentFileService.uploadDocument(request);
    System.out.println("Document文件上传成功: " + response.getFileId());
}

public void downloadDocument() {
    FileDownloadRequest request = FileDownloadRequest.builder()
            .orgConfigId("org-config-id")
            .fileType(FileObjectType.DOCUMENT)
            .fileId("document-id")
            .fileName("example.pdf")
            .build();
    
    FileDownloadResponse response = documentFileService.downloadDocument(request);
    System.out.println("Document文件下载成功: " + response.getFileSize());
}

注意事项

文件大小限制 - Document对象的文件大小限制是20-30MB
Base64编码开销 - Base64编码会增加约33%的文件大小
流式处理 - 下载时使用流式处理避免内存溢出，适合大文件下载
FolderId必填 - Document对象必须指定FolderId，否则会抛出异常
会话管理 - 确保SessionManager已正确配置，能够获取Session ID
SOAP API配置 - 确保PartnerV1Connection已正确配置，能够进行SOAP API调用
错误处理 - 建议调用方捕获并处理可能的异常，如FileUploadException、FileDownloadException等

测试信息

测试环境

开发环境 - 本地开发环境
测试环境 - 待定

测试结果

编译检查 - 通过IDE诊断检查，无编译错误或警告
单元测试 - 待完成（目标测试覆盖率 ≥ 90%）
代码质量检查 - 待完成（SonarQube、Checkstyle、SpotBugs）

发布人员

开发人员 - SSOT架构师

审核信息

审核人员: 待定
审核日期: 待定
审核状态: [待审核]
审核意见: 待审核

6.0 KiB Raw Permalink Blame History Unescape Escape

变更记录：Document 文件上传下载功能实现

变更信息

变更摘要

详细变更

特性更新

技术实现

影响范围

受影响的模块

兼容性说明

升级指南

升级步骤

使用示例

注意事项

测试信息

测试环境

测试结果

相关链接

发布人员

审核信息

6.0 KiB

Raw Permalink Blame History