update

2026-10-27 22:55:36 +08:00
parent 1231251ea4
commit 1f6cd63815
5 changed files with 203 additions and 23 deletions
@@ -21,7 +21,61 @@

 ## 3. 接口列表

-### 3.1 `POST /api/admin/files/upload`（后台上传）
+### 3.1 `GET /api/admin/files`（后台文件列表）
+
+分页列出文件，支持按上传者类型/ID 与关键字过滤，供后台「文件管理」栏目使用。
+
+**请求头**：`Authorization: Bearer <JWT>`。
+
+**查询参数**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| `page` | int | 否 | `1` | 页码，从 1 开始。 |
+| `size` | int | 否 | `20` | 每页条数。 |
+| `keyword` | string | 否 | 空 | 模糊匹配 `origin_name` 或 `filename`。 |
+| `uploader_type` | string | 否 | 空 | 按上传者类型过滤：`admin` / `ma`；空表示不限。 |
+| `uploader_id` | uint64 | 否 | `0` | 按上传者主键过滤；`0` 表示不限。 |
+
+**响应**
+
+```json
+{
+  "code": 0,
+  "msg": "ok",
+  "data": {
+    "list": [
+      {
+        "id": 1,
+        "storage_key": "2026/10/27/3f2a...c1.png",
+        "filename": "3f2a...c1.png",
+        "origin_name": "我的图片.png",
+        "mime_type": "image/png",
+        "ext": "png",
+        "size": 12345,
+        "uploader_type": "admin",
+        "uploader_id": 1,
+        "url": "/files/static/2026/10/27/3f2a...c1.png",
+        "created_at": "2026-10-27 22:00:00"
+      }
+    ],
+    "total": 1,
+    "page": 1,
+    "size": 20
+  }
+}
+```
+
+**错误码**：未认证 `40100`；查询失败 `50000`。
+
+**curl 示例**
+
+```bash
+curl "http://localhost:8080/api/admin/files?keyword=png&page=1&size=20" \
+  -H "Authorization: Bearer <JWT>"
+```
+
+### 3.2 `POST /api/admin/files/upload`（后台上传）

 以 `multipart/form-data` 上传单个文件，表单字段名为 `file`。

@@ -60,13 +114,13 @@ curl -X POST http://localhost:8080/api/admin/files/upload \
  -F "file=@/path/to/我的图片.png"
 ```

-### 3.2 `GET /api/admin/files/:id`（后台查询元数据）
+### 3.3 `GET /api/admin/files/:id`（后台查询元数据）

 查询指定文件的元数据记录。

 **路径参数**：`id`（uint64）。**响应**：返回 `File` 对象（见 §4）；不存在返回 `40400`。

-### 3.3 `GET /api/admin/files/:id/raw`（后台获取文件流）
+### 3.4 `GET /api/admin/files/:id/raw`（后台获取文件流）

 以流形式返回文件内容，按 `mime_type` 设置 `Content-Type`，`Content-Disposition: inline`，可用于浏览器预览/下载。

@@ -74,15 +128,15 @@ curl -X POST http://localhost:8080/api/admin/files/upload \

 > 也可直接通过上传返回的 `url` 访问（本地模式由静态目录服务，等效于本接口）。

-### 3.4 `DELETE /api/admin/files/:id`（后台删除）
+### 3.5 `DELETE /api/admin/files/:id`（后台删除）

 删除文件：同时清理存储内容与 `files` 表元数据记录。

 **路径参数**：`id`（uint64）。**响应**：`{ "code": 0, "msg": "ok", "data": { "id": 1 } }`；不存在返回 `40400`。

-### 3.5 `POST /api/ma/files/upload`（小程序上传）
+### 3.6 `POST /api/ma/files/upload`（小程序上传）

-与 3.1 一致，但鉴权为小程序登录态。
+与 3.2 一致，但鉴权为小程序登录态。

 **请求头**：`X-App-ID: <AppID>` + `Authorization: Bearer <token>`（或 `X-Session-Token`）。

@@ -95,17 +149,17 @@ curl -X POST http://localhost:8080/api/ma/files/upload \
  -F "file=@/path/to/photo.jpg"
 ```

-### 3.6 `GET /api/ma/files/:id`（小程序查询元数据）
+### 3.7 `GET /api/ma/files/:id`（小程序查询元数据）

-同 3.2，返回 `File` 对象；不存在 `40400`。
+同 3.3，返回 `File` 对象；不存在 `40400`。

-### 3.7 `GET /api/ma/files/:id/raw`（小程序获取文件流）
+### 3.8 `GET /api/ma/files/:id/raw`（小程序获取文件流）

-同 3.3，返回文件流；不存在 `40400`。
+同 3.4，返回文件流；不存在 `40400`。

-### 3.8 `DELETE /api/ma/files/:id`（小程序删除）
+### 3.9 `DELETE /api/ma/files/:id`（小程序删除）

-同 3.4，删除文件内容与元数据；不存在 `40400`。
+同 3.5，删除文件内容与元数据；不存在 `40400`。

 ## 4. 数据模型

@@ -126,7 +180,7 @@ curl -X POST http://localhost:8080/api/ma/files/upload \
 | `CreatedAt` | time | `created_at` | 创建时间（`Y-m-d H:i:s`）。 |

 > `GET .../raw` 直接返回二进制流，不返回 `File` JSON；`GET .../:id` 返回上述 `File` 对象。
-> 上传成功响应（§3.1）仅返回摘要字段：`id` / `url` / `filename` / `origin_name` / `mime_type` / `size`。
+> 上传成功响应（§3.2）仅返回摘要字段：`id` / `url` / `filename` / `origin_name` / `mime_type` / `size`。

 ## 5. 错误码