# 文件服务 API 文档

**服务**: `hl-file-service`
**接口总数**: 11

## 目录

- **C端文件上传** (3 个接口)
- **文件管理** (8 个接口)

---

## C端文件上传

### `GET` /mp/file/preview-by-url

**文件在线预览**

返回HTML预览页面，小程序通过web-view打开。支持PDF、图片、Office文档

**查询参数**

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `url` | `string` |  | 文件完整URL |  |

---

### `POST` /mp/file/upload

**上传文件（C端用户）**

小程序端直接上传文件，支持头像、评价图片等场景。groupKey决定存储路径和文件策略，默认为avatar

**查询参数**

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `groupKey` | `string` |  | 文件分组标识 |  |

**响应** `统一响应结果«文件信息»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `文件信息` |  | 响应数据 |
|   `createdAt` | `string` |  | 创建时间 |
|   `fileHash` | `string` |  | 文件MD5哈希 |
|   `fileId` | `string` |  | 文件ID |
|   `fileName` | `string` |  | 文件名 |
|   `fileSize` | `long` |  | 文件大小(字节) |
|   `fileType` | `string` |  | 文件类型 |
|   `groupKey` | `string` |  | 业务分组 |
|   `mimeType` | `string` |  | MIME类型 |
|   `ossUrl` | `string` |  | OSS地址 |
|   `previewUrl` | `string` |  | 预览地址 |
|   `refCount` | `int` |  | 引用次数 |
|   `status` | `string` |  | 文件状态 |
|   `thumbnailUrl` | `string` |  | 缩略图地址 |
| `message` | `string` |  | 响应消息 |

---

### `GET` /mp/file/{fileId}/preview

**文件内容流式预览**

流式输出文件内容，设置正确的Content-Type头。用于小程序端通过web-view直接预览图片和PDF等文件。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `fileId` | `integer` |  | 文件ID |

---

## 文件管理

### `GET` /admin/file/list

**文件列表（分页）**

支持按文件类型、分组、上传者等条件筛选，按上传时间倒序分页返回

**关联字典**：
- file_type：文件类型（列表筛选+显示）
- file_status：文件状态（显示）

**查询参数**

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `endDate` | `string` |  | 结束日期 | 2026-12-31 |
| `fileType` | `string` |  | 文件类型 | image |
| `groupKey` | `string` |  | 业务分组 | scenic |
| `keyword` | `string` |  | 搜索关键词 | 风景 |
| `page` | `integer(int32)` |  | 页码 | 1 |
| `pageSize` | `integer(int32)` |  | 每页条数 | 20 |
| `startDate` | `string` |  | 开始日期 | 2026-01-01 |

**响应** `统一响应结果«IPage«文件信息»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `IPage«文件信息»` |  | 响应数据 |
|   `current` | `long` |  |  |
|   `pages` | `long` |  |  |
|   `records` | `文件信息[]` |  |  |
|     `createdAt` | `string` |  | 创建时间 |
|     `fileHash` | `string` |  | 文件MD5哈希 |
|     `fileId` | `string` |  | 文件ID |
|     `fileName` | `string` |  | 文件名 |
|     `fileSize` | `long` |  | 文件大小(字节) |
|     `fileType` | `string` |  | 文件类型 |
|     `groupKey` | `string` |  | 业务分组 |
|     `mimeType` | `string` |  | MIME类型 |
|     `ossUrl` | `string` |  | OSS地址 |
|     `previewUrl` | `string` |  | 预览地址 |
|     `refCount` | `int` |  | 引用次数 |
|     `status` | `string` |  | 文件状态 |
|     `thumbnailUrl` | `string` |  | 缩略图地址 |
|   `size` | `long` |  |  |
|   `total` | `long` |  |  |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/file/stats

**存储统计**

返回文件总数、总存储空间、各类型文件占比等统计信息

**响应** `统一响应结果«文件统计信息»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `文件统计信息` |  | 响应数据 |
|   `countByGroup` | `object` |  | 按分组统计文件数量 |
|   `countByType` | `object` |  | 按类型统计文件数量 |
|   `sizeByType` | `object` |  | 按类型统计文件大小 |
|   `totalCount` | `long` |  | 文件总数 |
|   `totalSize` | `long` |  | 文件总大小(字节) |
| `message` | `string` |  | 响应消息 |

---

### `POST` /admin/file/upload/confirm

**确认上传完成**

上传流程第二步：前端直传OSS完成后调用此接口，系统验证文件存在性并创建文件记录。支持MD5去重，相同文件不会重复存储

**请求体** `上传确认请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `fileId` | `string` | 是 | 文件ID |

**响应** `统一响应结果«文件信息»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `文件信息` |  | 响应数据 |
|   `createdAt` | `string` |  | 创建时间 |
|   `fileHash` | `string` |  | 文件MD5哈希 |
|   `fileId` | `string` |  | 文件ID |
|   `fileName` | `string` |  | 文件名 |
|   `fileSize` | `long` |  | 文件大小(字节) |
|   `fileType` | `string` |  | 文件类型 |
|   `groupKey` | `string` |  | 业务分组 |
|   `mimeType` | `string` |  | MIME类型 |
|   `ossUrl` | `string` |  | OSS地址 |
|   `previewUrl` | `string` |  | 预览地址 |
|   `refCount` | `int` |  | 引用次数 |
|   `status` | `string` |  | 文件状态 |
|   `thumbnailUrl` | `string` |  | 缩略图地址 |
| `message` | `string` |  | 响应消息 |

---

### `POST` /admin/file/upload/token

**请求上传凭证**

上传流程第一步：前端请求上传凭证 → 获取OSS预签名URL和临时凭证 → 前端直传OSS → 调用确认上传接口。凭证有效期有限，过期需重新请求

**请求体** `上传令牌请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `fileHash` | `string` | 是 | 文件MD5哈希 |
| `fileName` | `string` | 是 | 文件名 |
| `fileSize` | `long` | 是 | 文件大小(字节) |
| `forcePresigned` | `boolean` |  | 强制使用预签名URL（跳过STS分片模式） |
| `groupKey` | `string` |  | 业务分组 |

**响应** `统一响应结果«上传令牌信息»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `上传令牌信息` |  | 响应数据 |
|   `bucket` | `string` |  | OSS Bucket名称 |
|   `contentType` | `string` |  | 上传时必须使用的Content-Type（与预签名URL签名一致） |
|   `expireAt` | `string` |  | 过期时间 |
|   `file` | `文件信息` |  | 秒传文件信息 |
|     `createdAt` | `string` |  | 创建时间 |
|     `fileHash` | `string` |  | 文件MD5哈希 |
|     `fileId` | `string` |  | 文件ID |
|     `fileName` | `string` |  | 文件名 |
|     `fileSize` | `long` |  | 文件大小(字节) |
|     `fileType` | `string` |  | 文件类型 |
|     `groupKey` | `string` |  | 业务分组 |
|     `mimeType` | `string` |  | MIME类型 |
|     `ossUrl` | `string` |  | OSS地址 |
|     `previewUrl` | `string` |  | 预览地址 |
|     `refCount` | `int` |  | 引用次数 |
|     `status` | `string` |  | 文件状态 |
|     `thumbnailUrl` | `string` |  | 缩略图地址 |
|   `fileId` | `string` |  | 文件ID |
|   `ossKey` | `string` |  | OSS对象Key |
|   `presignedUrl` | `string` |  | 预签名上传URL |
|   `region` | `string` |  | OSS Region |
|   `stsToken` | `STS临时凭证信息` |  | STS临时凭证 |
|     `accessKeyId` | `string` |  | AccessKey ID |
|     `accessKeySecret` | `string` |  | AccessKey Secret |
|     `expiration` | `string` |  | 过期时间 |
|     `securityToken` | `string` |  | 安全令牌 |
|   `uploadMode` | `string` |  | 上传模式: PRESIGNED_URL/STS_MULTIPART/INSTANT |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/file/{fileId}

**文件详情**

**关联字典**：
- file_type：文件类型（显示）
- file_status：文件状态（显示）

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `fileId` | `integer` |  | 文件ID |

**响应** `统一响应结果«文件信息»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `文件信息` |  | 响应数据 |
|   `createdAt` | `string` |  | 创建时间 |
|   `fileHash` | `string` |  | 文件MD5哈希 |
|   `fileId` | `string` |  | 文件ID |
|   `fileName` | `string` |  | 文件名 |
|   `fileSize` | `long` |  | 文件大小(字节) |
|   `fileType` | `string` |  | 文件类型 |
|   `groupKey` | `string` |  | 业务分组 |
|   `mimeType` | `string` |  | MIME类型 |
|   `ossUrl` | `string` |  | OSS地址 |
|   `previewUrl` | `string` |  | 预览地址 |
|   `refCount` | `int` |  | 引用次数 |
|   `status` | `string` |  | 文件状态 |
|   `thumbnailUrl` | `string` |  | 缩略图地址 |
| `message` | `string` |  | 响应消息 |

---

### `DELETE` /admin/file/{fileId}

**删除文件**

软删除文件记录，如果文件存在引用关系则不允许删除。OSS上的物理文件由定时任务清理

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `fileId` | `integer` |  | 文件ID |

**响应** `统一响应结果«Void»`

---

### `GET` /admin/file/{fileId}/preview

**文件内容流式预览**

流式输出文件内容，设置正确的Content-Type头，支持浏览器直接预览图片和PDF等文件

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `fileId` | `integer` |  | 文件ID |

---

### `GET` /admin/file/{fileId}/refs

**文件引用列表**

查看文件被哪些业务实体引用（如景区封面、酒店图片等），用于判断文件是否可安全删除

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `fileId` | `integer` |  | 文件ID |

**响应** `统一响应结果«List«文件引用信息»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `文件引用信息[]` |  | 响应数据 |
|   `bizId` | `string` |  | 业务ID |
|   `bizType` | `string` |  | 业务类型 |
|   `createdAt` | `string` |  | 创建时间 |
|   `fileId` | `string` |  | 文件ID |
|   `refId` | `string` |  | 引用ID |
| `message` | `string` |  | 响应消息 |

---