datai/docs/archive/changelog/0013-attachment-upload-download.md

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

变更信息

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

变更摘要

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

详细变更

特性更新

• FileUploadStrategy接口 - 定义了文件上传策略接口，包含upload()方法，接收FileUploadRequest参数，返回FileUploadResponse响应
• FileDownloadStrategy接口 - 定义了文件下载策略接口，包含download()方法，接收FileDownloadRequest参数，返回FileDownloadResponse响应
• AttachmentUploadStrategy类 - 实现了Attachment上传策略，使用REST API + Base64编码方式上传文件，支持最大50MB文件大小，包含文件验证、会话管理、错误处理等功能
• AttachmentDownloadStrategy类 - 实现了Attachment下载策略，使用REST API + 流式处理方式下载文件，使用BufferedInputStream和ByteArrayOutputStream避免内存溢出，包含会话管理、错误处理等功能
• AttachmentFileService接口 - 定义了Attachment文件服务接口，包含uploadAttachment()和downloadAttachment()方法
• AttachmentFileServiceImpl类 - 实现了Attachment文件服务，使用策略模式封装上传下载逻辑，通过@Autowired注入FileUploadStrategy和FileDownloadStrategy

技术实现

• REST API集成 - 使用HttpURLConnection进行REST API调用，设置Authorization、Content-Type等请求头
• Base64编码 - 使用Java内置的Base64.getEncoder().encodeToString()方法进行文件内容编码
• 流式处理 - 下载时使用BufferedInputStream和ByteArrayOutputStream进行流式处理，避免大文件导致内存溢出
• 会话管理 - 使用SessionManager获取Access Token和Instance URL，支持自动重新登录
• 异常处理 - 实现了完善的异常处理机制，包括FileSizeExceededException、FileTypeNotSupportedException、FileValidationException、OrgConfigNotFoundException、FileUploadException、FileDownloadException等
• 日志记录 - 使用@Slf4j注解记录关键操作日志，包括上传下载开始、成功、失败等

影响范围

受影响的模块

• datai-salesforce-integration模块 - 新增文件上传下载策略和服务
• 策略包 - 新增FileUploadStrategy接口、FileDownloadStrategy接口、AttachmentUploadStrategy类、AttachmentDownloadStrategy类
• 服务包 - 新增AttachmentFileService接口、AttachmentFileServiceImpl类

兼容性说明

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

升级指南

升级步骤

1. 引入依赖 - 确保项目已引入Lombok和Spring Boot 3.5.7（包含JSR-303验证）
2. 代码集成 - 在需要使用Attachment文件上传下载功能的模块中引入新增的策略和服务类
3. 配置验证 - 确保SessionManager已正确配置，能够获取Access Token和Instance URL

使用示例

@Autowired
private AttachmentFileService attachmentFileService;

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

public void downloadFile() {
    FileDownloadRequest request = FileDownloadRequest.builder()
            .orgConfigId("org-config-id")
            .fileType(FileObjectType.ATTACHMENT)
            .fileId("attachment-id")
            .fileName("example.pdf")
            .build();
    
    FileDownloadResponse response = attachmentFileService.downloadAttachment(request);
    System.out.println("文件下载成功: " + response.getFileSize());
}

注意事项

• 文件大小限制 - Attachment对象的文件大小限制是50MB
• Base64编码开销 - Base64编码会增加约33%的文件大小
• 流式处理 - 下载时使用流式处理避免内存溢出，适合大文件下载
• 会话管理 - 确保SessionManager已正确配置，能够获取Access Token和Instance URL
• 错误处理 - 建议调用方捕获并处理可能的异常，如FileUploadException、FileDownloadException等

测试信息

测试环境

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

测试结果

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

相关链接

• 需求文档 - Salesforce文件上传下载功能
• 子需求文档 - Attachment 文件上传下载功能
• 架构决策 - Attachment 文件上传下载架构决策
• 执行提示词 - Attachment 文件上传下载执行提示词
• 会话记录 - REQ-011-2执行会话记录
• 参考代码 - Salesforce Attachment 上传实现逻辑
• 参考代码 - Salesforce Attachment 下载实现逻辑

发布人员

• 开发人员 - SSOT架构师

审核信息

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