docs: update API design standards

2026-06-08 11:21:32 +08:00
parent 76260b9458
commit 2253ebea92
1 changed files with 98 additions and 1 deletions
@@ -461,7 +461,104 @@ http://localhost:9601/v3/api-docs            # 收银服务 API 文档

 ---

-## 十三、Postman / APIFox 集合规范
+## 十三、文件存储服务（rui-service-storage）
+
+> **服务定位**：独立微服务（9400 端口 / 聚合启动器 9399），所有业务模块共用一个上传入口，通过 `bizType` 区分业务场景。
+> **前端组件**：`<RuiUpload>`（[rui-frontend#5](https://git.dev.vifo.cc/rui/rui-frontend/issues/5)）。
+
+### 13.1 上传文件
+
+```
+POST /storage/upload
+Content-Type: multipart/form-data
+```
+
+**表单参数**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file` | File | ✅ | 文件本体 |
+| `bizType` | string | ✅ | 业务类型，匹配 `^[A-Z][A-Z0-9_]{0,50}$` |
+| `storage` | string | ❌ | `aliyun` / `tencent` / `local`；不传走默认 |
+| `fileName` | string | ❌ | 固定存储名，匹配 `^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$` |
+| `extract` | bool | ❌ | `true` 时若为 .zip 自动解压为多文件入库 |
+
+**响应**：`data: SysFileUploadVO[]`（**统一为数组**，单文件上传也是长度 1）。
+
+```json
+{
+  "code": 0,
+  "message": "ok",
+  "data": [
+    {
+      "id": 1234567890,
+      "name": "abc123.jpg",
+      "originalName": "photo.jpg",
+      "path": "user-avatar/2026/06/abc123.jpg",
+      "url": "https://bucket.oss-cn-shanghai.aliyuncs.com/user-avatar/2026/06/abc123.jpg",
+      "size": 12345,
+      "contentType": "image/jpeg",
+      "storageType": "ALIYUN",
+      "bizType": "USER_AVATAR"
+    }
+  ]
+}
+```
+
+### 13.2 查询文件详情
+
+```
+GET /storage/file/{id}
+```
+
+### 13.3 分页查询
+
+```
+GET /storage/file/page?pageNum=1&pageSize=20&bizType=SYS_APP_CERT
+```
+
+### 13.4 删除文件
+
+```
+DELETE /storage/file/{id}
+```
+
+物理删除对象存储文件 + 软删 `sys_file` 记录。
+
+### 13.5 已知 bizType
+
+| bizType | 限制 | 用途 |
+|---------|------|------|
+| `COMMON` | 10MB | 通用 |
+| `SYS_APP_CERT` | 5MB / pem,crt,key,p12 | 第三方应用证书 |
+| `USER_AVATAR` | 2MB / jpg,jpeg,png,webp | 用户头像 |
+| `CMS_BANNER` | 5MB / jpg,jpeg,png,webp,gif | CMS 轮播图 |
+
+新业务模块直接传新字符串（如 `ORDER_PROOF`），后端 yml 配 `rui.file.biz-types.<新>.max-size` / `allowed-extensions` 即可，**前端不需要等后端发版**。
+
+### 13.6 前端使用示例
+
+```vue
+<script setup>
+import RuiUpload from '@/components/RuiUpload/RuiUpload.vue'
+import type { UploadResult } from '@/service/system/storageService'
+const certFiles = ref<UploadResult[]>([])
+</script>
+
+<template>
+  <RuiUpload
+    v-model="certFiles"
+    biz-type="SYS_APP_CERT"
+    :max-size="20"
+    accept=".pem,.crt,.key,.p12,.zip"
+    :extract="false"
+  />
+</template>
+```
+
+---
+
+## 十四、Postman / APIFox 集合规范

 ### 13.1 目录结构