309 lines
9.6 KiB
Markdown
309 lines
9.6 KiB
Markdown
# Prompt First - Attachment 文件上传下载功能实现
|
||
|
||
## 输入引用
|
||
|
||
引用相关的 docs 文档链接：
|
||
|
||
- [REQ-011.md](../requirements/REQ-011.md) - Salesforce文件上传下载功能
|
||
- [REQ-011-1.md](../requirements/REQ-011-1.md) - 基础设施和枚举定义
|
||
- [REQ-011-2.md](../requirements/REQ-011-2.md) - Attachment 文件上传下载功能
|
||
- [0028-attachment-upload-download.md](../decisions/adr/0028-attachment-upload-download.md) - Attachment 文件上传下载架构决策
|
||
- [Attachment文件上传.md](../reference-code/data-dump/Attachment文件上传.md) - Salesforce Attachment 上传实现逻辑
|
||
- [Attachment文件下载.md](../reference-code/data-dump/Attachment文件下载.md) - Salesforce Attachment 下载实现逻辑
|
||
|
||
## Context Maps
|
||
|
||
强制列出本次 Prompt 依赖的 Canvas 文件：
|
||
|
||
- [Authentication.canvas](../Authentication.canvas) - 项目架构视觉化展示
|
||
- **相关节点**: [集成核心](node_integration_core) - 提供与Salesforce的各种连接方式
|
||
- **相关节点**: [SessionManager](node_session_manager_detail) - 会话管理，提供登录服务
|
||
- **相关节点**: [RESTConnection](node_rest_connection) - REST API 连接
|
||
|
||
## 目标
|
||
|
||
实现 Salesforce Attachment 对象的文件上传下载功能，使用 REST API + Base64 编码方式，支持最大 50MB 文件。具体包括：
|
||
|
||
1. **实现 FileUploadStrategy 接口** - 定义文件上传策略接口
|
||
2. **实现 FileDownloadStrategy 接口** - 定义文件下载策略接口
|
||
3. **实现 AttachmentUploadStrategy 类** - 实现 Attachment 上传策略，使用 REST API + Base64 编码
|
||
4. **实现 AttachmentDownloadStrategy 类** - 实现 Attachment 下载策略，使用 REST API + 流式处理
|
||
5. **实现 AttachmentFileService 接口** - 定义 Attachment 文件服务接口
|
||
6. **实现 AttachmentFileServiceImpl 类** - 实现 Attachment 文件服务，封装策略调用逻辑
|
||
|
||
## 输出格式
|
||
|
||
### 代码示例（语言：Java）
|
||
|
||
#### 1. FileUploadStrategy 接口
|
||
|
||
```java
|
||
package com.datai.integration.strategy;
|
||
|
||
import com.datai.common.param.FileUploadRequest;
|
||
import com.datai.common.param.FileUploadResponse;
|
||
|
||
public interface FileUploadStrategy {
|
||
FileUploadResponse upload(FileUploadRequest request);
|
||
}
|
||
```
|
||
|
||
#### 2. FileDownloadStrategy 接口
|
||
|
||
```java
|
||
package com.datai.integration.strategy;
|
||
|
||
import com.datai.common.param.FileDownloadRequest;
|
||
import com.datai.common.param.FileDownloadResponse;
|
||
|
||
public interface FileDownloadStrategy {
|
||
FileDownloadResponse download(FileDownloadRequest request);
|
||
}
|
||
```
|
||
|
||
#### 3. AttachmentUploadStrategy 类
|
||
|
||
```java
|
||
package com.datai.integration.strategy.impl;
|
||
|
||
import com.datai.common.enums.FileObjectType;
|
||
import com.datai.common.exception.*;
|
||
import com.datai.common.param.FileUploadRequest;
|
||
import com.datai.common.param.FileUploadResponse;
|
||
import com.datai.common.utils.FileValidationUtils;
|
||
import com.datai.integration.strategy.FileUploadStrategy;
|
||
import lombok.extern.slf4j.Slf4j;
|
||
import org.springframework.beans.factory.annotation.Autowired;
|
||
import org.springframework.stereotype.Component;
|
||
|
||
@Slf4j
|
||
@Component
|
||
public class AttachmentUploadStrategy implements FileUploadStrategy {
|
||
|
||
@Autowired
|
||
private SessionManager sessionManager;
|
||
|
||
@Autowired
|
||
private RESTConnection restConnection;
|
||
|
||
@Override
|
||
public FileUploadResponse upload(FileUploadRequest request) {
|
||
// 实现上传逻辑
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 4. AttachmentDownloadStrategy 类
|
||
|
||
```java
|
||
package com.datai.integration.strategy.impl;
|
||
|
||
import com.datai.common.enums.FileObjectType;
|
||
import com.datai.common.exception.*;
|
||
import com.datai.common.param.FileDownloadRequest;
|
||
import com.datai.common.param.FileDownloadResponse;
|
||
import com.datai.integration.strategy.FileDownloadStrategy;
|
||
import lombok.extern.slf4j.Slf4j;
|
||
import org.springframework.beans.factory.annotation.Autowired;
|
||
import org.springframework.stereotype.Component;
|
||
|
||
@Slf4j
|
||
@Component
|
||
public class AttachmentDownloadStrategy implements FileDownloadStrategy {
|
||
|
||
@Autowired
|
||
private SessionManager sessionManager;
|
||
|
||
@Autowired
|
||
private RESTConnection restConnection;
|
||
|
||
@Override
|
||
public FileDownloadResponse download(FileDownloadRequest request) {
|
||
// 实现下载逻辑
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 5. AttachmentFileService 接口
|
||
|
||
```java
|
||
package com.datai.integration.service;
|
||
|
||
import com.datai.common.param.FileUploadRequest;
|
||
import com.datai.common.param.FileUploadResponse;
|
||
import com.datai.common.param.FileDownloadRequest;
|
||
import com.datai.common.param.FileDownloadResponse;
|
||
|
||
public interface AttachmentFileService {
|
||
FileUploadResponse uploadAttachment(FileUploadRequest request);
|
||
FileDownloadResponse downloadAttachment(FileDownloadRequest request);
|
||
}
|
||
```
|
||
|
||
#### 6. AttachmentFileServiceImpl 类
|
||
|
||
```java
|
||
package com.datai.integration.service.impl;
|
||
|
||
import com.datai.common.param.FileDownloadRequest;
|
||
import com.datai.common.param.FileDownloadResponse;
|
||
import com.datai.common.param.FileUploadRequest;
|
||
import com.datai.common.param.FileUploadResponse;
|
||
import com.datai.integration.service.AttachmentFileService;
|
||
import com.datai.integration.strategy.FileDownloadStrategy;
|
||
import com.datai.integration.strategy.FileUploadStrategy;
|
||
import lombok.extern.slf4j.Slf4j;
|
||
import org.springframework.beans.factory.annotation.Autowired;
|
||
import org.springframework.stereotype.Service;
|
||
|
||
@Slf4j
|
||
@Service
|
||
public class AttachmentFileServiceImpl implements AttachmentFileService {
|
||
|
||
@Autowired
|
||
private FileUploadStrategy fileUploadStrategy;
|
||
|
||
@Autowired
|
||
private FileDownloadStrategy fileDownloadStrategy;
|
||
|
||
@Override
|
||
public FileUploadResponse uploadAttachment(FileUploadRequest request) {
|
||
// 实现上传逻辑
|
||
}
|
||
|
||
@Override
|
||
public FileDownloadResponse downloadAttachment(FileDownloadRequest request) {
|
||
// 实现下载逻辑
|
||
}
|
||
}
|
||
```
|
||
|
||
### 单元测试
|
||
|
||
为所有类编写单元测试，确保测试覆盖率 ≥ 90%。
|
||
|
||
## 约束
|
||
|
||
### 技术栈限制
|
||
|
||
- 必须基于现有的 Spring Boot 3 技术栈
|
||
- 必须使用 Java 22
|
||
- 必须使用 Lombok 注解
|
||
- 必须使用 JSR-303 验证注解
|
||
- 必须使用 MyBatis Plus
|
||
|
||
### 架构约束
|
||
|
||
- 必须遵循 Authentication.canvas 中定义的架构和调用关系
|
||
- 必须使用策略模式封装上传下载逻辑
|
||
- 必须遵循单一职责原则和开闭原则
|
||
|
||
### 模块约束
|
||
|
||
- 必须在 datai-salesforce-integration 模块下实现
|
||
- 必须在 strategy 包下实现策略类
|
||
- 必须在 service 包下实现服务类
|
||
|
||
### 认证约束
|
||
|
||
- 必须使用 SessionManager 进行会话管理和自动重新登录
|
||
- 必须使用现有的认证模块进行 OAuth 认证
|
||
|
||
### API约束
|
||
|
||
- 必须使用 Salesforce REST API
|
||
- 必须使用 Base64 编码进行文件上传
|
||
- 必须使用流式处理进行文件下载
|
||
|
||
### 文件大小约束
|
||
|
||
- 单个文件大小建议不超过 50MB
|
||
- 必须实现文件大小验证
|
||
|
||
### 内存约束
|
||
|
||
- 必须使用流式处理避免内存溢出
|
||
- 下载时必须使用 InputStream 和 FileOutputStream
|
||
|
||
### 文档约束
|
||
|
||
- 必须遵循 SSOT 方法论
|
||
- 代码必须有清晰的注释
|
||
|
||
## Rule Set
|
||
|
||
"请严格参考 @Authentication.canvas 中的状态机转移逻辑，不要自行发挥。"
|
||
|
||
**具体规则**：
|
||
- 必须使用 Canvas 中定义的类名和方法名
|
||
- 必须遵循 Canvas 中定义的调用关系
|
||
- 必须参考 Canvas 中的流程图逻辑
|
||
- 必须使用 SessionManager 进行会话管理和自动重新登录
|
||
- 必须使用现有的认证模块进行 OAuth 认证
|
||
- 必须遵循现有的异常处理机制
|
||
- 必须遵循现有的日志记录规范
|
||
- 必须使用 RESTConnection 处理 REST API 调用
|
||
- 必须使用策略模式封装上传下载逻辑
|
||
- 必须使用 REQ-011-1 提供的基础设施（FileObjectType、FileErrorCode、FileUploadRequest、FileDownloadRequest、FileUploadResponse、FileDownloadResponse、FileValidationUtils）
|
||
- 必须使用 @Valid 注解进行参数验证
|
||
- 必须使用 @Slf4j 记录日志
|
||
- 必须使用 @Transactional 管理事务
|
||
|
||
## 验收标准
|
||
|
||
### 功能完整性
|
||
|
||
- FileUploadStrategy 接口定义正确
|
||
- FileDownloadStrategy 接口定义正确
|
||
- AttachmentUploadStrategy 类实现正确，能够成功上传文件
|
||
- AttachmentDownloadStrategy 类实现正确，能够成功下载文件
|
||
- AttachmentFileService 接口定义正确
|
||
- AttachmentFileServiceImpl 类实现正确，能够正确调用策略
|
||
|
||
### 代码正确性
|
||
|
||
- 代码符合 Java 22 语法规范
|
||
- 代码符合 Spring Boot 3 规范
|
||
- 代码符合项目编码规范
|
||
- 代码有清晰的注释
|
||
|
||
### 文档准确性
|
||
|
||
- 代码注释准确描述了代码的功能
|
||
- 单元测试准确测试了代码的功能
|
||
|
||
### 性能指标
|
||
|
||
- 文件上传下载不影响系统响应
|
||
- 大文件处理性能良好
|
||
- 流式处理有效避免内存溢出
|
||
|
||
## 风险
|
||
|
||
### 输出质量风险
|
||
|
||
- AI 可能生成不符合项目规范的代码
|
||
- **缓解措施**: 提供详细的约束条件和 Rule Set
|
||
- AI 可能生成不符合架构设计的代码
|
||
- **缓解措施**: 提供详细的架构决策和 Canvas 引用
|
||
|
||
### 技术实现风险
|
||
|
||
- REST API 调用可能失败
|
||
- **缓解措施**: 实现重试机制，提供详细的错误信息
|
||
- Base64 编码可能出错
|
||
- **缓解措施**: 使用 Java 内置的 Base64 编码方法，提供异常处理
|
||
- 流式处理可能出错
|
||
- **缓解措施**: 使用 try-with-resources 确保资源释放，提供异常处理
|
||
|
||
### 时间成本风险
|
||
|
||
- 实现时间可能超出预期
|
||
- **缓解措施**: 提前进行技术调研，参考官方文档和示例代码
|
||
|
||
## 使用记录
|
||
|
||
| 日期 | 使用场景 | 输入参数 | 输出结果 | 反馈 | 改进措施 |
|
||
|------|---------|---------|---------|------|----------|
|
||
| 2026-01-19 | 实现 Attachment 上传下载功能 | REQ-011-2 需求文档、0028-attachment-upload-download.md ADR | 待生成 | 待反馈 | 待改进 |
|