datai/docs/archive/prompts/029-attachment-upload-download.md

# 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 | 待生成 | 待反馈 | 待改进 |