# 初始化分片上传

## 接口信息

- **接口名称**: 初始化分片上传
- **接口路径**: /file/initUpload
- **请求方法**: POST
- **模块归属**: file
- **版本号**: v1.0.0
- **创建日期**: 2026-01-18
- **最后更新**: 2026-01-18

## 功能描述

初始化分片上传，生成上传 ID 和文件路径，用于后续的分片上传操作。支持大文件分片上传，提高上传效率和可靠性。

## 请求参数

### 表单参数

| 参数名 | 类型 | 必填 | 描述 | 示例 |
|--------|------|------|------|------|
| fileName | String | 是 | 文件名 | large-file.zip |
| fileSize | Long | 是 | 文件大小（字节） | 1073741824 |

## 响应数据

### 成功响应

**HTTP 状态码**: 200 OK

```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "uploadId": "1234567890abcdef",
    "filePath": "/upload/2026/01/18/1234567890_large-file.zip",
    "fileName": "large-file.zip"
  }
}
```

| 字段名 | 类型 | 描述 | 示例 |
|--------|------|------|------|
| uploadId | String | 上传 ID，用于后续分片上传和合并 | 1234567890abcdef |
| filePath | String | 文件存储路径 | /upload/2026/01/18/1234567890_large-file.zip |
| fileName | String | 文件名 | large-file.zip |

### 失败响应

**HTTP 状态码**: 500 Internal Server Error

```json
{
  "code": 500,
  "message": "文件名或文件大小不能为空",
  "data": null
}
```

## 接口示例

### 请求示例

```bash
curl -X POST "http://localhost:8080/file/initUpload" \
  -H "Authorization: Bearer [token]" \
  -F "fileName=large-file.zip" \
  -F "fileSize=1073741824"
```

### 响应示例

**成功**:

```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "uploadId": "1234567890abcdef",
    "filePath": "/upload/2026/01/18/1234567890_large-file.zip",
    "fileName": "large-file.zip"
  }
}
```

## 错误处理

- 文件名为空时返回错误
- 文件大小为空或小于等于 0 时返回错误
- 初始化上传失败时返回错误

## 注意事项

- 文件路径格式为：/upload/{yyyy}/{MM}/{dd}/{timestamp}_{fileName}
- 使用系统配置的默认存储
- 上传 ID 用于后续的分片上传和合并操作
- 分片上传适用于大文件（通常大于 100MB）
- 初始化成功后需要调用上传分片接口上传各个分片

## 相关接口

- [上传文件分片](./0007-upload-chunk.md) - 上传文件分片
- [完成分片上传](./0008-complete-upload.md) - 完成分片上传并合并文件
- [统一上传接口](./0002-upload.md) - 普通文件上传（非分片）

## 实现细节

- 使用 `StorageService.initMultipartUpload()` 初始化分片上传
- 文件路径包含日期目录：yyyy/MM/dd
- 文件名前缀使用时间戳避免冲突
- 使用系统配置的默认存储桶
- 返回的 uploadId 必须妥善保存，用于后续操作