zhibo/模块文档/13-文件上传模块.md

# 文件上传模块

## 模块概述
文件上传模块负责处理图片、视频等媒体文件的上传功能，为用户头像、作品发布、消息图片等功能提供支持。

## 相关文件
- `FileUploadResponse.java` - 文件上传响应模型
- `PublishWorkActivity.java` - 作品发布界面（使用文件上传）
- `EditProfileActivity.java` - 编辑资料界面（使用头像上传）

---

## 接口列表

### 1. 上传图片
**接口地址**: `POST /api/front/user/upload/image`

**请求方式**: `multipart/form-data`

**请求参数**:
```
file: File          // 图片文件（必填）
model: string       // 模块标识（必填）
pid: integer        // 关联ID（必填）
```

**model参数说明**:
- `avatar` - 用户头像
- `work` - 作品图片
- `message` - 聊天图片
- `cover` - 封面图片

**返回数据** (FileUploadResponse):
```json
{
  "code": 200,
  "msg": "上传成功",
  "data": {
    "url": "string",           // 文件访问URL
    "fileName": "string",      // 文件名
    "fileSize": "long",        // 文件大小（字节）
    "fileType": "string",      // 文件类型
    "uploadTime": "long"       // 上传时间戳
  }
}
```

---

### 2. 上传视频
**接口地址**: `POST /api/front/upload/work/video`

**请求方式**: `multipart/form-data`

**请求参数**:
```
file: File          // 视频文件（必填）
model: string       // 模块标识（必填）
pid: integer        // 关联ID（必填）
```

**model参数说明**:
- `work` - 作品视频
- `message` - 聊天视频

**返回数据** (FileUploadResponse):
```json
{
  "code": 200,
  "msg": "上传成功",
  "data": {
    "url": "string",           // 文件访问URL
    "fileName": "string",      // 文件名
    "fileSize": "long",        // 文件大小（字节）
    "fileType": "string",      // 文件类型
    "duration": "integer",     // 视频时长（秒）
    "width": "integer",        // 视频宽度
    "height": "integer",       // 视频高度
    "uploadTime": "long"       // 上传时间戳
  }
}
```

---

## 功能说明

### 支持的文件类型

**图片格式**:
- JPG/JPEG
- PNG
- GIF
- WEBP

**视频格式**:
- MP4
- AVI
- MOV
- FLV

### 文件大小限制
- 图片：最大 10MB
- 视频：最大 100MB

### 上传流程
1. 选择文件
2. 构建 multipart/form-data 请求
3. 调用上传接口
4. 获取返回的文件URL
5. 使用URL进行后续操作（如发布作品、更新头像等）

---

## 使用示例

### Android代码示例

#### 上传图片
```java
// 创建文件部分
File imageFile = new File(imagePath);
RequestBody fileBody = RequestBody.create(
    MediaType.parse("image/*"), 
    imageFile
);
MultipartBody.Part filePart = MultipartBody.Part.createFormData(
    "file", 
    imageFile.getName(), 
    fileBody
);

// 创建其他参数
RequestBody model = RequestBody.create(
    MediaType.parse("text/plain"), 
    "avatar"
);
RequestBody pid = RequestBody.create(
    MediaType.parse("text/plain"), 
    String.valueOf(userId)
);

// 调用接口
ApiService apiService = ApiClient.getService(context);
Call<ApiResponse<FileUploadResponse>> call = 
    apiService.uploadImage(filePart, model, pid);

call.enqueue(new Callback<ApiResponse<FileUploadResponse>>() {
    @Override
    public void onResponse(Call<ApiResponse<FileUploadResponse>> call, 
                         Response<ApiResponse<FileUploadResponse>> response) {
        if (response.isSuccessful() && response.body() != null) {
            ApiResponse<FileUploadResponse> apiResponse = response.body();
            if (apiResponse.getCode() == 200) {
                String imageUrl = apiResponse.getData().getUrl();
                // 使用图片URL
            }
        }
    }

    @Override
    public void onFailure(Call<ApiResponse<FileUploadResponse>> call, Throwable t) {
        // 处理错误
    }
});
```

#### 上传视频
```java
// 创建文件部分
File videoFile = new File(videoPath);
RequestBody fileBody = RequestBody.create(
    MediaType.parse("video/*"), 
    videoFile
);
MultipartBody.Part filePart = MultipartBody.Part.createFormData(
    "file", 
    videoFile.getName(), 
    fileBody
);

// 创建其他参数
RequestBody model = RequestBody.create(
    MediaType.parse("text/plain"), 
    "work"
);
RequestBody pid = RequestBody.create(
    MediaType.parse("text/plain"), 
    String.valueOf(userId)
);

// 调用接口
ApiService apiService = ApiClient.getService(context);
Call<ApiResponse<FileUploadResponse>> call = 
    apiService.uploadVideo(filePart, model, pid);

call.enqueue(new Callback<ApiResponse<FileUploadResponse>>() {
    @Override
    public void onResponse(Call<ApiResponse<FileUploadResponse>> call, 
                         Response<ApiResponse<FileUploadResponse>> response) {
        if (response.isSuccessful() && response.body() != null) {
            ApiResponse<FileUploadResponse> apiResponse = response.body();
            if (apiResponse.getCode() == 200) {
                String videoUrl = apiResponse.getData().getUrl();
                int duration = apiResponse.getData().getDuration();
                // 使用视频URL和时长
            }
        }
    }

    @Override
    public void onFailure(Call<ApiResponse<FileUploadResponse>> call, Throwable t) {
        // 处理错误
    }
});
```

---

## 错误处理

| 错误码 | 说明 |
|--------|------|
| 400 | 参数错误或文件格式不支持 |
| 401 | 未登录 |
| 413 | 文件过大 |
| 415 | 不支持的文件类型 |
| 500 | 服务器错误 |

---

## 注意事项
1. 所有上传接口都需要登录认证
2. 上传前建议先压缩图片以提高上传速度
3. 视频上传时间较长，建议显示进度条
4. 上传失败时可以重试
5. model和pid参数用于后端文件管理和关联
6. 返回的URL是完整的访问地址，可直接使用
7. 建议在上传前检查文件大小和格式