datai/docs/archive/prompts/031-document-upload-download.md

# Prompt - Document 文件上传下载功能实现

## 输入引用

引用相关的 docs 文档链接：

- [REQ-011.md](../requirements/REQ-011.md) - 父需求文档
- [REQ-011-4.md](../requirements/REQ-011-4.md) - 子需求文档
- [0030-document-upload-download.md](./0030-document-upload-download.md) - 架构决策记录 (ADR)
- [Authentication.canvas](../Authentication.canvas) - 项目架构视觉化展示

## Context Maps

强制列出本次 Prompt 依赖的 Canvas 文件：

- [Authentication.canvas](../Authentication.canvas) - 项目架构视觉化展示
- **相关节点**: [集成核心](node_integration_core) - 提供与Salesforce的各种连接方式
- **相关节点**: [SessionManager](node_session_manager_detail) - 会话管理，提供登录服务
- **相关节点**: [PartnerV1Connection](node_partner_v1_connection) - Partner API 连接

## 目标

本提示词的目标是指导 AI 实现 REQ-011-4 需求，在 datai-salesforce-integration 模块实现 Salesforce Document 对象的文件上传下载功能，使用 Partner API (SOAP) 方式，支持最大 20-30MB 文件。

预期效果：
- DocumentUploadStrategy 类能够成功上传本地文件到 Salesforce Document 对象
- DocumentDownloadStrategy 类能够成功从 Salesforce Document 对象下载文件到本地
- DocumentFileService 接口和实现类能够封装上传下载逻辑
- 使用策略模式封装上传下载逻辑，符合开闭原则
- 使用流式处理避免内存溢出
- 代码符合项目编码规范，有清晰的注释
- 代码结构清晰，易于扩展和维护
- 代码易于单元测试

## 输出格式

### 代码输出格式

**语言**：Java 22

**代码结构**：
```
datai-salesforce-integration/src/main/java/com/datai/integration/
├── strategy/
│   ├── impl/
│   │   ├── DocumentUploadStrategy.java
│   │   └── DocumentDownloadStrategy.java
└── service/
    ├── DocumentFileService.java
    └── impl/
        └── DocumentFileServiceImpl.java
```

**代码要求**：
- 使用 Lombok 注解简化代码（@Data、@Builder、@NoArgsConstructor、@AllArgsConstructor、@Slf4j）
- 使用 JSR-303 验证注解（@NotNull、@NotBlank、@Size、@Valid）
- 使用 Spring 注解（@Service、@Autowired、@Component）
- 使用 Javadoc 注释，包含参数说明、返回值说明、异常说明
- 遵循阿里巴巴 Java 开发手册
- 代码行数不超过 200 行/文件
- 使用策略模式封装上传下载逻辑
- 使用流式处理避免内存溢出

### 单元测试输出格式

**语言**：Java 22 + JUnit 5 + Mockito

**测试结构**：
```
datai-salesforce-integration/src/test/java/com/datai/integration/
├── strategy/
│   └── impl/
│       ├── DocumentUploadStrategyTest.java
│       └── DocumentDownloadStrategyTest.java
└── service/
    └── impl/
        └── DocumentFileServiceImplTest.java
```

**测试要求**：
- 使用 JUnit 5 的 @Test、@ParameterizedTest、@Nested 等注解
- 使用 Mockito 的 @Mock、@InjectMocks 等注解
- 测试覆盖率 ≥ 90%
- 测试用例包含：正常场景、边界场景、异常场景

### 文档输出格式

**格式**：Markdown

**文档要求**：
- 为每个类提供 Javadoc 注释
- 为每个公共方法提供 Javadoc 注释
- 为每个策略类提供使用示例

## 约束

### 技术栈限制
- 必须基于现有的 Spring Boot 3 技术栈
- 必须使用 Java 22
- 必须使用 Lombok（如果项目已引入）
- 必须使用 JSR-303 Bean Validation
- 必须使用 JUnit 5
- 必须使用 Mockito

### 架构约束
- 必须遵循 Authentication.canvas 中定义的架构和调用关系
- 必须在 datai-salesforce-integration 模块下实现
- 必须使用 SessionManager 进行会话管理和自动重新登录
- 必须使用 PartnerV1Connection 处理 SOAP API 调用
- 必须使用策略模式封装上传下载逻辑

### 依赖约束
- 必须依赖 REQ-011-1 的基础设施（FileObjectType、FileErrorCode、FileUploadRequest、FileDownloadRequest、FileUploadResponse、FileDownloadResponse、FileValidationUtils）
- 必须依赖 datai-salesforce-integration 模块的 SessionManager
- 必须依赖 datai-salesforce-integration 模块的 PartnerV1Connection
- 不能引入与项目现有依赖冲突的依赖

### 性能约束
- 文件上传方法必须在合理时间内完成（20-30MB 文件）
- 文件下载方法必须在合理时间内完成（20-30MB 文件）
- 流式处理必须有效避免内存溢出
- 文件验证方法必须在 100ms 内完成

### 安全性约束
- 文件类型验证必须使用白名单机制
- 文件名验证必须防止路径遍历攻击
- 文件大小验证必须防止 DoS 攻击
- 必须使用 SessionManager 进行认证，防止未授权访问

### 兼容性约束
- 必须兼容 Windows、Linux、macOS 操作系统
- 必须兼容 UTF-8 编码
- 必须兼容 Salesforce API v58.0+
- 必须兼容 Partner API (SOAP)

## Rule Set

"请严格参考 @Authentication.canvas 中的状态机转移逻辑，不要自行发挥。"

**具体规则**：
- 必须使用 Canvas 中定义的类名和方法名
- 必须遵循 Canvas 中定义的调用关系
- 必须参考 Canvas 中的流程图逻辑
- 必须使用 SessionManager 进行会话管理和自动重新登录
- 必须使用 PartnerV1Connection 处理 SOAP API 调用
- 必须遵循现有的异常处理机制
- 必须遵循现有的日志记录规范
- 必须使用策略模式封装上传下载逻辑
- 必须使用流式处理避免内存溢出
- 必须遵循项目编码规范
- 必须使用 Lombok 注解简化代码
- 必须使用 JSR-303 验证注解
- 必须提供完整的 Javadoc 注释

## 验收标准

### 功能完整性
- [ ] DocumentUploadStrategy 类实现 FileUploadStrategy 接口
- [ ] DocumentUploadStrategy 类能够成功上传本地文件到 Salesforce Document 对象
- [ ] DocumentUploadStrategy 类支持指定组织配置 ID
- [ ] DocumentUploadStrategy 类支持指定 FolderId（必填）
- [ ] DocumentUploadStrategy 类支持指定文件名和 DeveloperName
- [ ] DocumentUploadStrategy 类使用 Base64 编码文件内容
- [ ] DocumentUploadStrategy 类上传成功返回 Document ID
- [ ] DocumentUploadStrategy 类支持文件大小验证（建议不超过 20-30MB）
- [ ] DocumentUploadStrategy 类支持文件类型验证
- [ ] DocumentUploadStrategy 类提供详细的错误信息
- [ ] DocumentDownloadStrategy 类实现 FileDownloadStrategy 接口
- [ ] DocumentDownloadStrategy 类能够成功从 Salesforce Document 对象下载文件到本地
- [ ] DocumentDownloadStrategy 类支持指定组织配置 ID
- [ ] DocumentDownloadStrategy 类支持指定 Document ID
- [ ] DocumentDownloadStrategy 类支持指定保存路径
- [ ] DocumentDownloadStrategy 类使用流式处理避免内存溢出
- [ ] DocumentDownloadStrategy 类下载成功返回文件信息
- [ ] DocumentDownloadStrategy 类支持大文件下载
- [ ] DocumentDownloadStrategy 类提供详细的错误信息
- [ ] DocumentFileService 接口定义 uploadDocument 方法
- [ ] DocumentFileService 接口定义 downloadDocument 方法
- [ ] DocumentFileServiceImpl 实现类使用策略模式封装上传下载逻辑
- [ ] DocumentFileServiceImpl 实现类提供参数验证
- [ ] DocumentFileServiceImpl 实现类提供异常处理
- [ ] DocumentFileServiceImpl 实现类提供日志记录

### 代码正确性
- [ ] 代码符合项目编码规范
- [ ] 代码有清晰的注释
- [ ] 代码通过 IDE 诊断检查，无编译错误或警告
- [ ] 代码通过 SonarQube 静态代码分析
- [ ] 代码通过 Checkstyle 检查
- [ ] 代码通过 SpotBugs 检查

### 文档准确性
- [ ] 每个类提供 Javadoc 注释
- [ ] 每个公共方法提供 Javadoc 注释
- [ ] 每个策略类提供使用示例

### 性能指标
- [ ] 文件上传性能良好，不影响系统响应
- [ ] 文件下载性能良好，不影响系统响应
- [ ] 流式处理有效避免内存溢出
- [ ] 20-30MB 文件上传下载性能良好
- [ ] 单元测试覆盖率 ≥ 90%

## 风险

### 输出质量风险
- **风险描述**：AI 可能生成不符合项目规范的代码
- **影响程度**：中
- **缓解措施**：
  1. 严格遵循项目编码规范
  2. 参考现有代码风格
  3. 使用 Lombok 注解简化代码
  4. 提供完整的 Javadoc 注释

### 技术实现风险
- **风险描述**：SOAP API 调用复杂度高，可能增加实现难度
- **影响程度**：高
- **缓解措施**：
  1. 参考官方文档和示例代码
  2. 使用成熟的 SOAP 客户端库
  3. 参考 Attachment 和 ContentDocument 的实现方式
  4. 提供详细的错误处理和日志记录

### 性能风险
- **风险描述**：Base64 编码可能导致文件大小增加约 33%
- **影响程度**：中
- **缓解措施**：
  1. 限制文件大小，建议不超过 20-30MB
  2. 使用流式处理避免内存溢出
  3. 优化 Base64 编码和解码性能

### 时间成本风险
- **风险描述**：实现所有类可能需要较长时间
- **影响程度**：低
- **缓解措施**：
  1. 优先实现核心类（DocumentUploadStrategy、DocumentDownloadStrategy）
  2. 逐步实现 Service 接口和实现类
  3. 分批进行单元测试

### 其他潜在风险
- **风险描述**：Document 功能受限，仅适用于特定场景
- **影响程度**：低
- **缓解措施**：
  1. 提供清晰的文档说明
  2. 提供迁移方案，建议用户使用 ContentDocument
  3. 保持 Document 对象的兼容性

## 使用记录

| 日期 | 使用场景 | 输入参数 | 输出结果 | 反馈 | 改进措施 |
|------|---------|---------|---------|------|----------|
| 2026-01-19 | 初始实现 | REQ-011-4 需求文档 | 待执行 | - | - |