# FileController 接口文档

## 概述

FileController 提供统一的文件存储服务接口，支持多种存储类型（local、minio、aliyun-oss 等），包括文件上传、下载、预览、分片上传等功能。

## 接口列表

### 基础接口

| 接口名称 | 接口路径 | 请求方法 | 说明 |
|----------|----------|----------|------|
| 获取所有可用存储渠道及其client列表 | /file/client-list | GET | 获取系统可用的存储渠道列表 |
| 统一上传接口 | /file/upload<br>/file/{storageType}/{bucketName}/upload | POST | 上传文件到指定存储 |
| 统一下载接口 | /file/download<br>/file/{storageType}/{bucketName}/download | GET | 从指定存储下载文件 |
| 统一预览接口 | /file/preview<br>/file/{storageType}/{bucketName}/preview | GET | 在线预览文件（支持匿名访问） |
| 本地资源通用下载 | /file/resource | GET | 下载本地资源文件（支持匿名访问） |

### 分片上传接口

| 接口名称 | 接口路径 | 请求方法 | 说明 |
|----------|----------|----------|------|
| 初始化分片上传 | /file/initUpload | POST | 初始化分片上传，获取 uploadId |
| 上传文件分片 | /file/uploadChunk | POST | 上传文件的一个分片 |
| 完成分片上传并合并文件 | /file/completeUpload | POST | 完成分片上传并合并文件 |

## 存储类型

系统支持以下存储类型：

- **local**: 本地文件系统存储
- **minio**: MinIO 对象存储
- **aliyun-oss**: 阿里云 OSS 对象存储

## 使用流程

### 普通文件上传流程

1. 调用 [获取存储渠道列表](./0001-client-list.md) 获取可用的存储渠道
2. 调用 [统一上传接口](./0002-upload.md) 上传文件
3. 使用返回的 URL 进行文件访问

### 分片上传流程

1. 调用 [初始化分片上传](./0006-init-upload.md) 获取 uploadId 和文件路径
2. 循环调用 [上传文件分片](./0007-upload-chunk.md) 上传所有分片
3. 调用 [完成分片上传](./0008-complete-upload.md) 合并所有分片

### 文件下载流程

1. 调用 [统一下载接口](./0003-download.md) 下载文件
2. 浏览器会自动触发文件下载

### 文件预览流程

1. 调用 [统一预览接口](./0004-preview.md) 预览文件
2. 浏览器会根据文件类型进行在线预览

## 权限说明

- 大部分接口需要认证（需要携带 Authorization 头）
- [统一预览接口](./0004-preview.md) 和 [本地资源通用下载](./0005-resource.md) 支持匿名访问

## 注意事项

1. 文件路径格式为：upload/{timestamp}_{originalFilename}
2. 分片上传适用于大文件（通常大于 100MB）
3. 分片序号必须从 1 开始，连续递增
4. 需要妥善保存 uploadId 和所有分片的 ETag
5. 预览接口会自动识别文件类型

## 相关文档

- [SysFileInfoController 接口文档](../SysFileInfoController/index.md) - 文件信息管理接口