初始化2

server/docs/api.md

@@ -2,15 +2,17 @@
 
 > Base URL: `http://localhost:8080/api`
 >
-> 认证方式: `Authorization: Bearer <JWT Token>`
+> 认证方式: 请求头 `token: <JWT Token>`
 >
 > 统一响应格式: `{ "code": 0, "message": "success", "data": ... }`
+>
+> ID 类型: 所有 `id`、`folder_id`、`parent_id`、`file_id` 字段均为**字符串类型**（雪花算法生成的64位整数）
 
 ---
 
 ## 1. 认证 (Auth)
 
-### 1.1 用户登录
+### 1.1 用户登录(密码)
 ```
 POST /api/auth/login
 ```
@@ -26,11 +28,27 @@ POST /api/auth/login
     "token": "eyJhbGci...",
     "username": "admin",
     "nickname": "管理员",
-    "role": "admin"
+    "role": "admin",
+    "must_change_pwd": false
   }
 }
 ```
 
+### 1.2 应用登录(用户名+appId)
+```
+POST /api/auth/app-login
+```
+**请求体:**
+```json
+{ "username": "admin", "app_id": "your_app_id" }
+```
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| username | string | 是 | 用户名 |
+| app_id | string | 是 | 开放平台应用ID, 需在后台创建应用并绑定用户 |
+
+> 校验逻辑: appId 存在且启用 → 用户已绑定该应用 → 生成 Token
+
 ### 1.2 用户注册
 ```
 POST /api/auth/register
@@ -43,13 +61,13 @@ POST /api/auth/register
 ### 1.3 获取当前用户信息
 ```
 GET /api/auth/profile
-Authorization: Bearer <token>
+token: <token>
 ```
 
 ### 1.4 获取当前用户权限
 ```
 GET /api/auth/permissions
-Authorization: Bearer <token>
+token: <token>
 ```
 **响应:**
 ```json
@@ -70,13 +88,13 @@ Authorization: Bearer <token>
 ```
 POST /api/file/upload?folder_id=1&storage_policy_id=1
 Content-Type: multipart/form-data
-Authorization: Bearer <token>
+token: <token>
 ```
 **参数:**
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
 | file | File | 是 | 文件内容 |
-| folder_id | int | 否 | 目标文件夹ID, 0=根目录 |
+| folder_id | string | 否 | 目标文件夹ID, "0"=根目录 |
 | storage_policy_id | int | 否 | 存储策略ID, 0=使用默认策略 |
 
 **响应:**
@@ -84,10 +102,10 @@ Authorization: Bearer <token>
 {
   "code": 0,
   "data": {
-    "id": 1,
+    "id": "170406720000000001",
     "name": "test.txt",
     "extension": "txt",
-    "folder_id": 1,
+    "folder_id": "0",
     "size": 1024,
     "storage_key": "2026/07/02/ab/abcdef123456.txt",
     "storage_policy_id": 1,
@@ -101,7 +119,7 @@ Authorization: Bearer <token>
 **Step 1: 初始化上传**
 ```
 POST /api/file/upload/init
-Authorization: Bearer <token>
+token: <token>
 ```
 **请求体:**
 ```json
@@ -109,7 +127,7 @@ Authorization: Bearer <token>
   "file_name": "large_video.mp4",
   "file_size": 104857600,
   "md5": "d41d8cd98f00b204e9800998ecf8427e",
-  "folder_id": 1,
+  "folder_id": "0",
   "policy_id": 1
 }
 ```
@@ -131,7 +149,7 @@ Authorization: Bearer <token>
 ```
 PUT /api/file/upload/chunk/:uploadId/:index
 Content-Type: multipart/form-data
-Authorization: Bearer <token>
+token: <token>
 X-Checksum: sha256_of_chunk
 ```
 **表单字段:** `chunk` = 分片二进制数据
@@ -139,7 +157,7 @@ X-Checksum: sha256_of_chunk
 **Step 3: 查询进度(断点续传)**
 ```
 GET /api/file/upload/progress/:uploadId
-Authorization: Bearer <token>
+token: <token>
 ```
 **响应:**
 ```json
@@ -159,25 +177,25 @@ Authorization: Bearer <token>
 **Step 4: 合并完成**
 ```
 POST /api/file/upload/merge/:uploadId
-Authorization: Bearer <token>
+token: <token>
 ```
 
 **Step 5: 取消上传**
 ```
 DELETE /api/file/upload/:uploadId
-Authorization: Bearer <token>
+token: <token>
 ```
 
 ### 2.3 获取文件信息
 ```
 GET /api/file/:id
-Authorization: Bearer <token>
+token: <token>
 ```
 
 ### 2.3 根据 fileKey 查询文件信息
 ```
 GET /api/file/info?key=2026/07/02/ab/abcdef123456.txt
-Authorization: Bearer <token>
+token: <token>
 ```
 **参数:**
 | 参数 | 类型 | 必填 | 说明 |
@@ -187,14 +205,14 @@ Authorization: Bearer <token>
 ### 2.4 直接下载文件流
 ```
 GET /api/file/:id/download
-Authorization: Bearer <token>
+token: <token>
 ```
 **响应:** 文件二进制流, Content-Disposition: attachment
 
 ### 2.5 获取下载链接
 ```
 GET /api/file/:id/download-url
-Authorization: Bearer <token>
+token: <token>
 ```
 **响应:**
 ```json
@@ -210,14 +228,14 @@ Authorization: Bearer <token>
 ### 2.6 预览文件流
 ```
 GET /api/file/:id/preview
-Authorization: Bearer <token>
+token: <token>
 ```
 **响应:** 文件二进制流, Content-Disposition: inline
 
 ### 2.7 获取预览链接
 ```
 GET /api/file/:id/preview-url
-Authorization: Bearer <token>
+token: <token>
 ```
 **响应:**
 ```json
@@ -232,7 +250,7 @@ Authorization: Bearer <token>
 ### 2.8 重命名文件
 ```
 PUT /api/file/:id/rename
-Authorization: Bearer <token>
+token: <token>
 ```
 **请求体:**
 ```json
@@ -242,7 +260,7 @@ Authorization: Bearer <token>
 ### 2.9 移动文件
 ```
 POST /api/file/:id/move
-Authorization: Bearer <token>
+token: <token>
 ```
 **请求体:**
 ```json
@@ -252,33 +270,138 @@ Authorization: Bearer <token>
 ### 2.10 删除文件(移入回收站)
 ```
 DELETE /api/file/:id
-Authorization: Bearer <token>
+token: <token>
 ```
 
 ### 2.11 恢复文件
 ```
 POST /api/file/:id/restore
-Authorization: Bearer <token>
+token: <token>
 ```
 
 ### 2.12 永久删除文件
 ```
 DELETE /api/file/:id/permanent
-Authorization: Bearer <token>
+token: <token>
 ```
 
 ### 2.13 搜索文件
 ```
 GET /api/file/search?keyword=报告
-Authorization: Bearer <token>
+GET /api/file/search?type=image
+token: <token>
 ```
+**参数:**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| keyword | string | 与type二选一 | 搜索关键词, 支持 `\|` 分隔多关键词(OR匹配) |
+| type | string | 与keyword二选一 | 按文件类型搜索 |
+
+**支持的 type 值:**
+| type | 匹配扩展名 |
+|------|-----------|
+| image | jpg, jpeg, png, gif, bmp, webp, svg, ico |
+| video | mp4, avi, mov, wmv, flv, mkv, webm |
+| audio | mp3, wav, ogg, aac, flac, wma |
+| document | pdf, doc, docx, xls, xlsx, ppt, pptx, txt, md, csv |
+| archive | zip, rar, 7z, tar, gz, bz2 |
+| code | js, ts, py, go, java, c, cpp, h, css, html, sql, json, xml, yaml, yml |
+
+**响应:**
+```json
+{
+  "code": 0,
+  "data": [
+    {
+      "id": "170406720000000007",
+      "name": "pic.jpg",
+      "extension": "jpg",
+      "folder_id": "0",
+      "size": 6770,
+      "storage_key": "2026/07/03/be/be2f5ef653f22a3f.jpg",
+      "storage_policy_id": 8,
+      "mime_type": "image/jpeg",
+      "is_favorite": 0,
+      "download_count": 2,
+      "version": 1,
+      "download_url": "/api/file/170406720000000007/download",
+      "preview_url": "/api/file/170406720000000007/preview",
+      "created_at": "2026-07-03T18:30:50.496+08:00",
+      "updated_at": "2026-07-03T22:19:14.916+08:00"
+    }
+  ]
+}
+```
+> 管理员可搜到所有文件, 非管理员只能搜到自己创建的 + 被授权的。最多返回200条。
 
 ### 2.14 获取回收站列表
 ```
 GET /api/file/trash
-Authorization: Bearer <token>
+token: <token>
 ```
 
+### 2.15 查看文件授权列表
+```
+GET /api/file/:id/grant
+token: <token>
+```
+**响应:**
+```json
+{
+  "code": 0,
+  "data": [
+    {
+      "id": 1,
+      "file_id": "170406720000000005",
+      "user_id": 3,
+      "user_name": "张三",
+      "perm_level": "read",
+      "grant_by": 1,
+      "grant_by_name": "管理员",
+      "created_at": "2026-07-03 12:00:00"
+    },
+    {
+      "id": 2,
+      "file_id": "170406720000000005",
+      "role_id": 5,
+      "role_name": "内部员工",
+      "perm_level": "write",
+      "grant_by": 1,
+      "grant_by_name": "管理员",
+      "created_at": "2026-07-03 12:00:00"
+    }
+  ]
+}
+```
+
+### 2.16 授权文件权限
+```
+POST /api/file/:id/grant
+token: <token>
+```
+**请求体(授权给用户):**
+```json
+{ "user_id": 3, "perm_level": "read" }
+```
+**请求体(授权给角色):**
+```json
+{ "role_id": 5, "perm_level": "write" }
+```
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| user_id | int | 与role_id二选一 | 授权给指定用户 |
+| role_id | int | 与user_id二选一 | 授权给指定角色 |
+| perm_level | string | 是 | read / write / admin |
+
+> 需要 `file:grant` 权限。同一文件+同一用户/角色重复授权会更新权限级别。
+
+### 2.17 撤销文件权限
+```
+DELETE /api/file/:id/grant/:permId
+token: <token>
+```
+> 需要 `file:grant` 权限。只能撤销自己授权的或管理员可撤销任意。
+
 ---
 
 ## 3. 文件夹管理 (Folder)
@@ -286,52 +409,82 @@ Authorization: Bearer <token>
 ### 3.1 创建文件夹
 ```
 POST /api/folder
-Authorization: Bearer <token>
+token: <token>
 ```
 **请求体:**
 ```json
-{ "name": "项目文档", "parent_id": 0 }
+{ "name": "项目文档", "parent_id": "0", "biz_id": "ext_001" }
 ```
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| name | string | 是 | 文件夹名称 |
+| parent_id | string | 否 | 父文件夹ID, "0"=根目录 |
+| biz_id | string | 否 | 业务ID, 用于外部系统关联 |
+
 **响应:**
 ```json
 {
   "code": 0,
-  "data": { "id": 1, "name": "项目文档", "parent_id": 0, "path": "/1/" }
+  "data": { "id": "170406720000000001", "biz_id": "ext_001", "name": "项目文档", "parent_id": "0", "path": "/170406720000000001/" }
 }
 ```
 
-### 3.2 获取文件夹内容(文件+子文件夹)
+### 3.2 获取文件夹内容(支持分页)
 ```
-GET /api/folder/:id/children
-Authorization: Bearer <token>
+GET /api/folder/:id/children?page=1&page_size=50
+token: <token>
 ```
 > `:id` 为 `root` 时获取根目录
 
+**参数:**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| page | int | 否 | 页码, 默认1 |
+| page_size | int | 否 | 每页大小, 默认50, 最大200 |
+
 **响应:**
 ```json
 {
   "code": 0,
   "data": {
-    "folders": [{ "id": 2, "name": "子文件夹", "parent_id": 1 }],
-    "files": [{ "id": 1, "name": "test.txt", "size": 1024 }]
+    "folders": [{ "id": "170406720000000002", "name": "子文件夹", "parent_id": "170406720000000001" }],
+    "files": [{ "id": "170406720000000003", "name": "test.txt", "size": 1024, "storage_key": "2026/...", "storage_policy_id": 8 }],
+    "total_files": 25,
+    "total_folders": 3,
+    "page": 1,
+    "page_size": 50
   }
 }
 ```
+> 文件夹不分页(通常数量较少), 仅文件分页
 
-### 3.3 重命名文件夹
+### 3.3 根据业务ID获取文件夹
+```
+GET /api/folder/by-bizid/:bizid
+token: <token>
+```
+**响应:**
+```json
+{
+  "code": 0,
+  "data": { "id": "170406720000000001", "biz_id": "ext_001", "name": "项目文档", "parent_id": "0", "path": "/170406720000000001/" }
+}
+```
+
+### 3.4 重命名文件夹
 ```
 PUT /api/folder/:id/rename
-Authorization: Bearer <token>
+token: <token>
 ```
 **请求体:**
 ```json
 { "new_name": "新名称" }
 ```
 
-### 3.4 删除文件夹
+### 3.5 删除文件夹
 ```
 DELETE /api/folder/:id
-Authorization: Bearer <token>
+token: <token>
 ```
 
 ---
@@ -341,12 +494,12 @@ Authorization: Bearer <token>
 ### 4.1 创建分享链接
 ```
 POST /api/share
-Authorization: Bearer <token>
+token: <token>
 ```
 **请求体:**
 ```json
 {
-  "file_id": 1,
+  "file_id": "170406720000000001",
   "password": "123456",
   "expire_hours": 24,
   "max_download": 10
@@ -357,7 +510,7 @@ Authorization: Bearer <token>
 {
   "code": 0,
   "data": {
-    "id": 1,
+    "id": "170406720000000010",
     "share_code": "a1b2c3d4e5f6g7h8",
     "share_url": "/s/a1b2c3d4e5f6g7h8",
     "has_password": true,
@@ -371,13 +524,13 @@ Authorization: Bearer <token>
 ### 4.2 获取我的分享列表
 ```
 GET /api/share
-Authorization: Bearer <token>
+token: <token>
 ```
 
 ### 4.3 取消分享
 ```
 DELETE /api/share/:id
-Authorization: Bearer <token>
+token: <token>
 ```
 
 ### 4.4 获取分享信息(公开)
@@ -474,13 +627,13 @@ POST /api/sso/callback
 ### 5.5 获取SSO提供商详情(管理员)
 ```
 GET /api/admin/sso/providers/:id
-Authorization: Bearer <token>
+token: <token>
 ```
 
 ### 5.6 创建SSO提供商(管理员)
 ```
 POST /api/admin/sso/providers
-Authorization: Bearer <token>
+token: <token>
 ```
 **请求体:**
 ```json
@@ -514,14 +667,14 @@ Authorization: Bearer <token>
 ### 5.7 更新SSO提供商(管理员)
 ```
 PUT /api/admin/sso/providers/:id
-Authorization: Bearer <token>
+token: <token>
 ```
 > 请求体同创建, 字段可选(只传需要修改的字段)
 
 ### 5.8 启用/禁用SSO提供商(管理员)
 ```
 PUT /api/admin/sso/providers/:id/toggle
-Authorization: Bearer <token>
+token: <token>
 ```
 **请求体:**
 ```json
@@ -531,7 +684,7 @@ Authorization: Bearer <token>
 ### 5.9 删除SSO提供商(管理员)
 ```
 DELETE /api/admin/sso/providers/:id
-Authorization: Bearer <token>
+token: <token>
 ```
 
 ---
@@ -541,13 +694,13 @@ Authorization: Bearer <token>
 ### 6.1 用户列表
 ```
 GET /api/admin/users?page=1&size=20
-Authorization: Bearer <token>
+token: <token>
 ```
 
 ### 6.2 创建用户
 ```
 POST /api/admin/users
-Authorization: Bearer <token>
+token: <token>
 ```
 **请求体:**
 ```json
@@ -564,19 +717,19 @@ Authorization: Bearer <token>
 ### 6.3 更新用户
 ```
 PUT /api/admin/users/:id
-Authorization: Bearer <token>
+token: <token>
 ```
 
 ### 6.4 删除用户
 ```
 DELETE /api/admin/users/:id
-Authorization: Bearer <token>
+token: <token>
 ```
 
 ### 6.5 重置密码
 ```
 PUT /api/admin/users/:id/password
-Authorization: Bearer <token>
+token: <token>
 ```
 **请求体:**
 ```json
@@ -586,7 +739,7 @@ Authorization: Bearer <token>
 ### 6.6 设置用户角色
 ```
 PUT /api/admin/users/:id/roles
-Authorization: Bearer <token>
+token: <token>
 ```
 **请求体:**
 ```json
@@ -600,13 +753,13 @@ Authorization: Bearer <token>
 ### 7.1 角色列表
 ```
 GET /api/admin/roles
-Authorization: Bearer <token>
+token: <token>
 ```
 
 ### 7.2 创建角色
 ```
 POST /api/admin/roles
-Authorization: Bearer <token>
+token: <token>
 ```
 **请求体:**
 ```json
@@ -616,19 +769,19 @@ Authorization: Bearer <token>
 ### 7.3 更新角色
 ```
 PUT /api/admin/roles/:id
-Authorization: Bearer <token>
+token: <token>
 ```
 
 ### 7.4 删除角色
 ```
 DELETE /api/admin/roles/:id
-Authorization: Bearer <token>
+token: <token>
 ```
 
 ### 7.5 设置角色权限
 ```
 PUT /api/admin/roles/:id/permissions
-Authorization: Bearer <token>
+token: <token>
 ```
 **请求体:**
 ```json
@@ -638,13 +791,13 @@ Authorization: Bearer <token>
 ### 7.6 权限列表
 ```
 GET /api/admin/permissions
-Authorization: Bearer <token>
+token: <token>
 ```
 
 ### 7.7 创建权限
 ```
 POST /api/admin/permissions
-Authorization: Bearer <token>
+token: <token>
 ```
 **请求体:**
 ```json
@@ -654,7 +807,7 @@ Authorization: Bearer <token>
 ### 7.8 删除权限
 ```
 DELETE /api/admin/permissions/:id
-Authorization: Bearer <token>
+token: <token>
 ```
 
 ---
@@ -664,13 +817,13 @@ Authorization: Bearer <token>
 ### 8.1 存储策略列表
 ```
 GET /api/admin/storage-policies
-Authorization: Bearer <token>
+token: <token>
 ```
 
 ### 8.2 创建存储策略
 ```
 POST /api/admin/storage-policies
-Authorization: Bearer <token>
+token: <token>
 ```
 **请求体 (本地存储):**
 ```json
@@ -694,13 +847,13 @@ Authorization: Bearer <token>
 ### 8.3 更新存储策略
 ```
 PUT /api/admin/storage-policies/:id
-Authorization: Bearer <token>
+token: <token>
 ```
 
 ### 8.4 删除存储策略
 ```
 DELETE /api/admin/storage-policies/:id
-Authorization: Bearer <token>
+token: <token>
 ```
 
 ---
@@ -710,7 +863,7 @@ Authorization: Bearer <token>
 ### 9.1 部门列表(树形)
 ```
 GET /api/admin/departments
-Authorization: Bearer <token>
+token: <token>
 ```
 **响应:**
 ```json
@@ -731,7 +884,7 @@ Authorization: Bearer <token>
 ### 9.2 创建部门
 ```
 POST /api/admin/departments
-Authorization: Bearer <token>
+token: <token>
 ```
 **请求体:**
 ```json
@@ -741,13 +894,13 @@ Authorization: Bearer <token>
 ### 9.3 更新部门
 ```
 PUT /api/admin/departments/:id
-Authorization: Bearer <token>
+token: <token>
 ```
 
 ### 9.4 删除部门
 ```
 DELETE /api/admin/departments/:id
-Authorization: Bearer <token>
+token: <token>
 ```
 
 ---
@@ -763,7 +916,7 @@ GET /health
 ### 10.2 获取CDN配置(管理员)
 ```
 GET /api/admin/settings/cdn
-Authorization: Bearer <token>
+token: <token>
 ```
 **响应:**
 ```json
@@ -780,7 +933,7 @@ Authorization: Bearer <token>
 ### 10.3 更新CDN配置(管理员)
 ```
 PUT /api/admin/settings/cdn
-Authorization: Bearer <token>
+token: <token>
 ```
 **请求体:**
 ```json
@@ -808,6 +961,193 @@ Authorization: Bearer <token>
 
 ---
 
+## 11. 监控与日志 (Admin)
+
+### 11.1 流量统计
+```
+GET /api/admin/monitor/traffic
+token: <token>
+```
+
+### 11.2 最近请求记录
+```
+GET /api/admin/monitor/requests?limit=50
+token: <token>
+```
+
+### 11.3 存储统计(按策略分组)
+```
+GET /api/admin/monitor/storage
+token: <token>
+```
+**响应:**
+```json
+{
+  "code": 0,
+  "data": {
+    "policies": [
+      { "policy_id": 8, "policy_name": "热存储", "file_count": 10, "total_size": 52428800 }
+    ],
+    "global": {
+      "total_files": 25,
+      "total_size": 104857600,
+      "total_folders": 8,
+      "total_users": 5
+    }
+  }
+}
+```
+
+### 11.4 系统运行日志
+```
+GET /api/admin/monitor/logs?limit=200
+token: <token>
+```
+**响应:**
+```json
+{
+  "code": 0,
+  "data": {
+    "total": 156,
+    "entries": [
+      { "time": "2026-07-03T22:33:09+08:00", "level": "INFO", "message": "数据库连接成功\n" },
+      { "time": "2026-07-03T22:33:09+08:00", "level": "INFO", "message": "存储引擎初始化完成, 已加载 5 个策略\n" }
+    ]
+  }
+}
+```
+> 日志级别: INFO / WARN / ERROR
+
+### 11.5 操作日志列表
+```
+GET /api/admin/logs?page=1&size=20
+token: <token>
+```
+
+### 11.6 操作日志统计
+```
+GET /api/admin/logs/stats
+token: <token>
+```
+
+### 11.7 清理操作日志
+```
+POST /api/admin/logs/clean
+token: <token>
+```
+
+---
+
+## 12. IP黑名单管理 (Admin)
+
+### 12.1 获取黑名单
+```
+GET /api/admin/blacklist
+token: <token>
+```
+
+### 12.2 设置黑名单(全量替换)
+```
+PUT /api/admin/blacklist
+token: <token>
+```
+**请求体:**
+```json
+{ "enabled": true, "ips": ["192.168.1.100", "10.0.0.5"] }
+```
+
+### 12.3 添加封禁IP
+```
+POST /api/admin/blacklist
+token: <token>
+```
+**请求体:**
+```json
+{ "ip": "192.168.1.100" }
+```
+
+### 12.4 移除封禁IP
+```
+DELETE /api/admin/blacklist/:ip
+token: <token>
+```
+
+---
+
+## 13. 备份管理 (Admin)
+
+### 13.1 备份策略列表
+```
+GET /api/admin/backup/policies
+token: <token>
+```
+
+### 13.2 创建备份策略
+```
+POST /api/admin/backup/policies
+token: <token>
+```
+
+### 13.3 执行备份
+```
+POST /api/admin/backup/execute/:id
+token: <token>
+```
+
+### 13.4 备份日志
+```
+GET /api/admin/backup/logs
+token: <token>
+```
+
+### 13.5 恢复备份
+```
+POST /api/admin/backup/restore/:logId
+token: <token>
+```
+
+---
+
+## 14. 存储策略分配 (Admin)
+
+### 14.1 分配列表
+```
+GET /api/admin/storage-assignments
+token: <token>
+```
+
+### 14.2 为角色分配存储策略
+```
+POST /api/admin/storage-assignments/role
+token: <token>
+```
+**请求体:**
+```json
+{ "role_id": 5, "policy_id": 8, "storage_quota": 53687091200, "priority": 10 }
+```
+
+### 14.3 为用户分配存储策略
+```
+POST /api/admin/storage-assignments/user
+token: <token>
+```
+**请求体:**
+```json
+{ "user_id": 3, "policy_id": 8, "storage_quota": 10737418240 }
+```
+
+### 14.4 设置默认存储策略
+```
+POST /api/admin/storage-assignments/default
+token: <token>
+```
+**请求体:**
+```json
+{ "policy_id": 8 }
+```
+
+---
+
 ## 权限标识一览
 
 | 权限标识 | 说明 |
@@ -817,18 +1157,43 @@ Authorization: Bearer <token>
 | file:update | 修改文件 |
 | file:delete | 删除文件 |
 | file:upload | 上传文件 |
+| file:download | 下载文件 |
+| file:grant | 授权文件权限(给其他用户/角色) |
 | share:create | 创建分享 |
 | share:manage | 管理分享 |
+| webdav:access | WebDAV访问 |
 | user:manage | 用户管理 |
 | role:manage | 角色管理 |
 | sso:manage | SSO管理 |
 | system:manage | 系统管理 |
 | * | 所有权限(超级管理员) |
 
+### 默认角色权限
+
+| 角色 | 权限 |
+|------|------|
+| admin | *(全部) |
+| staff | file:create, file:read, file:update, file:delete, file:upload, file:download, file:grant, share:create, webdav:access |
+| user | file:create, file:read, file:update, file:upload, file:download, share:create |
+| guest | file:read |
+
+### 文件可见性规则
+
+| 角色 | 可见范围 |
+|------|----------|
+| admin | 所有文件 |
+| 其他角色 | 自己创建的 + fs_file_permission 中被授权的 |
+
+### 文件操作权限规则
+
+文件操作(删除/重命名/移动/下载/授权等)需要同时满足:
+1. 用户角色拥有对应权限码(如 `file:delete`)
+2. 用户有权操作该具体文件(owner / admin / fs_file_permission 被授权)
+
 ### 2.17 统一文件访问(自动选择模式)
 ```
 GET /api/file/:id/access
-Authorization: Bearer <token>
+token: <token>
 ```
 > 根据存储策略的 `access_mode` 自动选择:
 > - `proxy`: 中转模式, 直接返回文件流
@@ -838,7 +1203,7 @@ Authorization: Bearer <token>
 ### 2.18 获取文件访问URL
 ```
 GET /api/file/:id/access-url
-Authorization: Bearer <token>
+token: <token>
 ```
 **响应:**
 ```json