datai/docs/archive/prompts/032-file-controller-api.md

# Prompt First - REQ-011-5 文件上传下载 Controller 和 API 接口

## 输入引用

引用相关的 docs 文档链接：

- [REQ-011.md](../requirements/REQ-011.md) - Salesforce文件上传下载功能总需求
- [REQ-011-5.md](../requirements/REQ-011-5.md) - 文件上传下载 Controller 和 API 接口需求
- [0027-file-infrastructure-enums.md](../decisions/adr/0027-file-infrastructure-enums.md) - 文件上传下载基础设施架构决策
- [0028-attachment-upload-download.md](../decisions/adr/0028-attachment-upload-download.md) - Attachment 文件上传下载架构决策
- [0029-contentdocument-upload-download.md](../decisions/adr/0029-contentdocument-upload-download.md) - ContentDocument 文件上传下载架构决策
- [0030-document-upload-download.md](../decisions/adr/0030-document-upload-download.md) - Document 文件上传下载架构决策
- [0031-file-controller-api.md](../decisions/adr/0031-file-controller-api.md) - 文件上传下载 Controller 和 API 接口架构决策

## Context Maps

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

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

## 目标

实现 FileController，提供文件上传下载的 RESTful API 接口，支持 Attachment、ContentDocument、Document 三种文件对象类型。用户可以通过 HTTP 请求上传和下载 Salesforce 的三种文件对象，支持指定组织配置 ID。

### 具体目标

1. 创建 FileController，使用 @RestController 和 @RequestMapping("/files") 注解
2. 实现文件上传接口 POST /files/upload，支持三种文件对象类型
3. 实现文件下载接口 GET /files/download，支持三种文件对象类型
4. 使用 JSR-303 验证注解进行参数验证
5. 使用统一的响应格式
6. 使用策略模式根据文件对象类型调用不同的 Service
7. 使用 Swagger/OpenAPI 注解生成 API 文档

## 输出格式

### 代码文件

**文件路径**: `d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-integration\src\main\java\com\datai\integration\controller\FileController.java`

**代码语言**: Java 17

**代码框架**: Spring Boot 3.5.7

**依赖注解**:
- @RestController
- @RequestMapping("/files")
- @Slf4j
- @Tag(name = "文件管理", description = "文件上传下载 API")
- @RequiredArgsConstructor
- @Autowired

**必需导入**:
```java
import com.datai.integration.dto.*;
import com.datai.integration.enums.FileObjectType;
import com.datai.integration.service.*;
import io.swagger.v3.oas.annotations.*;
import io.swagger.v3.oas.annotations.parameters.*;
import io.swagger.v3.oas.annotations.responses.*;
import io.swagger.v3.oas.annotations.media.*;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.http.*;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.multipart.MultipartFile;
import jakarta.validation.Valid;
import jakarta.validation.constraints.*;
```

### API 接口定义

#### 1. 文件上传接口

**接口路径**: POST /files/upload

**请求参数**:
```java
@Parameter(description = "文件对象类型", required = true, example = "ATTACHMENT")
@RequestParam("fileObjectType") FileObjectType fileObjectType,

@Parameter(description = "组织配置 ID", required = true, example = "org001")
@RequestParam("orgConfigId") @NotBlank String orgConfigId,

@Parameter(description = "关联记录 ID", required = false, example = "001xx000003DGp2AAG")
@RequestParam(value = "relatedRecordId", required = false) String relatedRecordId,

@Parameter(description = "文件", required = true)
@RequestPart("file") MultipartFile file,

@Parameter(description = "文件描述", required = false)
@RequestParam(value = "description", required = false) String description
```

**响应格式**:
```java
@ApiResponse(responseCode = "200", description = "上传成功",
    content = @Content(schema = @Schema(implementation = ApiResponse.class)))
@ApiResponse(responseCode = "400", description = "请求参数错误",
    content = @Content(schema = @Schema(implementation = ApiResponse.class)))
@ApiResponse(responseCode = "500", description = "服务器内部错误",
    content = @Content(schema = @Schema(implementation = ApiResponse.class)))
```

**实现逻辑**:
```java
@PostMapping("/upload")
public ResponseEntity<ApiResponse<FileUploadResponse>> uploadFile(
        @RequestParam("fileObjectType") FileObjectType fileObjectType,
        @RequestParam("orgConfigId") @NotBlank String orgConfigId,
        @RequestParam(value = "relatedRecordId", required = false) String relatedRecordId,
        @RequestPart("file") MultipartFile file,
        @RequestParam(value = "description", required = false) String description) {

    log.info("收到文件上传请求: fileObjectType={}, orgConfigId={}, fileName={}",
            fileObjectType, orgConfigId, file.getOriginalFilename());

    FileUploadRequest request = FileUploadRequest.builder()
            .fileObjectType(fileObjectType)
            .orgConfigId(orgConfigId)
            .relatedRecordId(relatedRecordId)
            .file(file)
            .description(description)
            .build();

    FileUploadResponse response = switch (fileObjectType) {
        case ATTACHMENT -> attachmentFileService.upload(request);
        case CONTENT_DOCUMENT -> contentVersionFileService.upload(request);
        case DOCUMENT -> documentFileService.upload(request);
    };

    log.info("文件上传成功: fileId={}, fileName={}", response.getFileId(), response.getFileName());

    return ResponseEntity.ok(ApiResponse.success(response));
}
```

#### 2. 文件下载接口

**接口路径**: GET /files/download

**请求参数**:
```java
@Parameter(description = "文件对象类型", required = true, example = "ATTACHMENT")
@RequestParam("fileObjectType") FileObjectType fileObjectType,

@Parameter(description = "组织配置 ID", required = true, example = "org001")
@RequestParam("orgConfigId") @NotBlank String orgConfigId,

@Parameter(description = "文件 ID", required = true, example = "00Pxx0000016u0HEAQ")
@RequestParam("fileId") @NotBlank String fileId
```

**响应格式**:
```java
@ApiResponse(responseCode = "200", description = "下载成功",
    content = @Content(schema = @Schema(implementation = ApiResponse.class)))
@ApiResponse(responseCode = "400", description = "请求参数错误",
    content = @Content(schema = @Schema(implementation = ApiResponse.class)))
@ApiResponse(responseCode = "404", description = "文件不存在",
    content = @Content(schema = @Schema(implementation = ApiResponse.class)))
@ApiResponse(responseCode = "500", description = "服务器内部错误",
    content = @Content(schema = @Schema(implementation = ApiResponse.class)))
```

**实现逻辑**:
```java
@GetMapping("/download")
public ResponseEntity<ApiResponse<FileDownloadResponse>> downloadFile(
        @RequestParam("fileObjectType") FileObjectType fileObjectType,
        @RequestParam("orgConfigId") @NotBlank String orgConfigId,
        @RequestParam("fileId") @NotBlank String fileId) {

    log.info("收到文件下载请求: fileObjectType={}, orgConfigId={}, fileId={}",
            fileObjectType, orgConfigId, fileId);

    FileDownloadRequest request = FileDownloadRequest.builder()
            .fileObjectType(fileObjectType)
            .orgConfigId(orgConfigId)
            .fileId(fileId)
            .build();

    FileDownloadResponse response = switch (fileObjectType) {
        case ATTACHMENT -> attachmentFileService.download(request);
        case CONTENT_DOCUMENT -> contentVersionFileService.download(request);
        case DOCUMENT -> documentFileService.download(request);
    };

    log.info("文件下载成功: fileId={}, fileName={}", response.getFileId(), response.getFileName());

    return ResponseEntity.ok(ApiResponse.success(response));
}
```

### 统一响应格式

**响应类定义**:
```java
@Data
@Builder
@AllArgsConstructor
@NoArgsConstructor
public class ApiResponse<T> {
    private Integer code;
    private String message;
    private T data;

    public static <T> ApiResponse<T> success(T data) {
        return ApiResponse.<T>builder()
                .code(200)
                .message("success")
                .data(data)
                .build();
    }

    public static <T> ApiResponse<T> error(Integer code, String message) {
        return ApiResponse.<T>builder()
                .code(code)
                .message(message)
                .data(null)
                .build();
    }
}
```

## 约束

### 技术栈约束

1. **Java 版本**: 必须使用 Java 17
2. **Spring Boot 版本**: 必须使用 Spring Boot 3.5.7
3. **Lombok**: 必须使用 Lombok 注解简化代码
4. **Swagger**: 必须使用 Swagger/OpenAPI 3.0 注解生成 API 文档
5. **JSR-303**: 必须使用 JSR-303 验证注解进行参数验证

### 架构约束

1. **模块约束**: 必须在 datai-salesforce-integration 模块下实现
2. **包路径**: 必须在 com.datai.integration.controller 包下
3. **依赖注入**: 必须使用 @Autowired 或构造函数注入
4. **策略模式**: 必须使用策略模式根据文件对象类型调用不同的 Service
5. **统一响应**: 必须使用统一的响应格式

### 认证约束

1. **会话管理**: 必须使用 SessionManager 进行会话管理
2. **自动重新登录**: 必须支持自动重新登录机制
3. **组织配置**: 必须支持指定组织配置 ID

### API 设计约束

1. **RESTful 规范**: 必须遵循 RESTful 设计规范
2. **HTTP 方法**: 必须使用正确的 HTTP 方法（POST 用于上传，GET 用于下载）
3. **参数传递**: 必须使用 @RequestParam 和 @RequestPart 注解接收参数
4. **响应状态码**: 必须返回正确的 HTTP 状态码

### 文档约束

1. **Swagger 注解**: 必须使用 Swagger/OpenAPI 注解生成 API 文档
2. **参数描述**: 必须为每个参数提供详细的描述
3. **响应描述**: 必须为每个响应提供详细的描述
4. **示例数据**: 必须为每个参数和响应提供示例数据

### 代码质量约束

1. **代码规范**: 必须遵循项目编码规范
2. **日志记录**: 必须使用 @Slf4j 注解记录日志
3. **异常处理**: 必须正确处理异常，提供详细的错误信息
4. **单元测试**: 必须编写单元测试，确保测试覆盖率 ≥ 90%

## Rule Set

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

**具体规则**：
- 必须使用 Canvas 中定义的类名和方法名
- 必须遵循 Canvas 中定义的调用关系
- 必须参考 Canvas 中的流程图逻辑

**代码规范规则**：
- 必须使用 Lombok 注解（@Data、@Builder、@Slf4j、@RequiredArgsConstructor 等）
- 必须使用 JSR-303 验证注解（@NotNull、@NotBlank、@Size 等）
- 必须使用 Swagger/OpenAPI 注解（@Tag、@Operation、@Parameter、@ApiResponse 等）
- 必须使用策略模式（switch-case 语句）根据文件对象类型调用不同的 Service
- 必须使用统一的响应格式（ApiResponse）
- 必须使用构造函数注入（@RequiredArgsConstructor）
- 必须使用 @Valid 注解进行参数验证

**API 设计规则**：
- 必须遵循 RESTful 设计规范
- 必须使用正确的 HTTP 方法（POST 用于上传，GET 用于下载）
- 必须使用 @RequestParam 和 @RequestPart 注解接收参数
- 必须返回正确的 HTTP 状态码
- 必须提供详细的参数描述和示例数据
- 必须提供详细的响应描述和示例数据

**异常处理规则**：
- 必须正确处理异常，提供详细的错误信息
- 必须使用 try-catch 块捕获异常
- 必须记录详细的日志，便于问题排查
- 必须返回统一的错误响应格式

**日志记录规则**：
- 必须使用 @Slf4j 注解记录日志
- 必须记录关键操作的开始和结束
- 必须记录异常信息
- 必须记录请求参数和响应结果

## 验收标准

### 功能完整性验收标准

1. **上传功能**: 能够成功上传本地文件到 Salesforce Attachment、ContentDocument、Document 对象
2. **下载功能**: 能够成功从 Salesforce Attachment、ContentDocument、Document 对象下载文件到本地
3. **参数验证**: 能够正确验证参数，提供详细的错误信息
4. **异常处理**: 能够正确处理异常，提供详细的错误信息
5. **日志记录**: 能够记录详细的日志，便于问题排查
6. **API 文档**: 能够生成清晰的 API 文档，便于前端调用和集成

### 代码质量验收标准

1. **代码规范**: 代码符合项目编码规范，有清晰的注释
2. **设计模式**: 使用策略模式封装三种文件对象的上传下载逻辑
3. **单一职责**: 遵循单一职责原则和开闭原则
4. **测试覆盖**: 测试覆盖率 ≥ 90%

### API 设计验收标准

1. **RESTful 规范**: 遵循 RESTful 设计规范
2. **HTTP 方法**: 使用正确的 HTTP 方法（POST 用于上传，GET 用于下载）
3. **参数传递**: 使用 @RequestParam 和 @RequestPart 注解接收参数
4. **响应状态码**: 返回正确的 HTTP 状态码
5. **统一响应**: 使用统一的响应格式

### 文档质量验收标准

1. **Swagger 注解**: 使用 Swagger/OpenAPI 注解生成 API 文档
2. **参数描述**: 为每个参数提供详细的描述
3. **响应描述**: 为每个响应提供详细的描述
4. **示例数据**: 为每个参数和响应提供示例数据

### 性能验收标准

1. **上传性能**: 文件上传性能良好，不影响系统响应
2. **下载性能**: 文件下载性能良好，不影响系统响应
3. **并发性能**: 并发上传下载性能良好，不出现资源竞争

## 风险

### 输出质量风险

1. **API 设计风险**: API 接口设计可能不够完善
   - **缓解措施**: 提前进行 API 设计评审，参考业界最佳实践
2. **参数验证风险**: 参数验证可能不够严格
   - **缓解措施**: 使用 JSR-303 验证注解，提供详细的错误信息
3. **响应封装风险**: 响应封装可能不够统一
   - **缓解措施**: 定义统一的响应格式，使用统一的响应封装逻辑

### 技术实现风险

1. **并发风险**: 并发上传下载可能导致资源竞争
   - **缓解措施**: 使用线程池，限制并发数，监控并发性能
2. **性能风险**: API 接口性能可能不达标
   - **缓解措施**: 提前进行性能测试，优化代码性能
3. **兼容性风险**: 前端可能不兼容新的 API 接口
   - **缓解措施**: 提供详细的 API 文档，提供前端集成指南

### 时间成本风险

1. **开发时间风险**: 开发时间可能超出预期
   - **缓解措施**: 提前进行技术调研，参考官方文档和示例代码
2. **测试时间风险**: 测试时间可能超出预期
   - **缓解措施**: 提前进行性能测试，优化代码性能

## 使用记录

| 日期 | 使用场景 | 输入参数 | 输出结果 | 反馈 | 改进措施 |
|------|---------|---------|---------|------|----------|
| 2026-01-19 | REQ-011-5 阶段 4 执行 | REQ-011-5 需求文档、架构决策文档、提示词文档 | FileController 代码实现 | 待评估 | 待改进 |