# 变更记录：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接口

## 升级指南

### 升级步骤

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

### 使用示例

```java
@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）

## 相关链接

- [需求文档](../requirements/REQ-011.md) - Salesforce文件上传下载功能
- [子需求文档](../requirements/REQ-011-4.md) - Document 文件上传下载功能
- [架构决策](../decisions/adr/0030-document-upload-download.md) - Document 文件上传下载架构决策
- [执行提示词](../prompts/031-document-upload-download.md) - Document 文件上传下载执行提示词
- [会话记录](../sessions/20260119-req-011-4-document-upload-download.md) - REQ-011-4执行会话记录
- [参考代码](../reference-code/data-dump/Document上传下载.md) - Salesforce Document 上传下载实现逻辑

## 发布人员

- **开发人员** - SSOT架构师

## 审核信息

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