SeeyonFileSystem/server/docs/api.md

# 文件管理系统 OpenAPI 接口文档

> Base URL: `http://localhost:8080/api`
>
> 认证方式: 请求头 `token: <JWT Token>`
>
> 统一响应格式: `{ "code": 0, "message": "success", "data": ... }`
>
> ID 类型: 所有 `id`、`folder_id`、`parent_id`、`file_id` 字段均为**字符串类型**（雪花算法生成的64位整数）

---

## 1. 认证 (Auth)

### 1.1 用户登录(密码)
```
POST /api/auth/login
```
**请求体:**
```json
{ "username": "admin", "password": "admin123" }
```
**响应:**
```json
{
  "code": 0,
  "data": {
    "token": "eyJhbGci...",
    "username": "admin",
    "nickname": "管理员",
    "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
```
**请求体:**
```json
{ "username": "user1", "password": "123456", "nickname": "用户1", "email": "user1@example.com" }
```

### 1.3 获取当前用户信息
```
GET /api/auth/profile
token: <token>
```

### 1.4 获取当前用户权限
```
GET /api/auth/permissions
token: <token>
```
**响应:**
```json
{
  "code": 0,
  "data": {
    "roles": [{ "id": 1, "name": "admin", "display_name": "管理员" }],
    "permissions": ["file:create", "file:read", "file:update", "file:delete", "file:upload", "share:create"]
  }
}
```

---

## 2. 文件管理 (File)

### 2.1 上传文件(简单上传)
```
POST /api/file/upload?folder_id=1&storage_policy_id=1
Content-Type: multipart/form-data
token: <token>
```
**参数:**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| file | File | 是 | 文件内容 |
| folder_id | string | 否 | 目标文件夹ID, "0"=根目录 |
| storage_policy_id | int | 否 | 存储策略ID, 0=使用默认策略 |

**响应:**
```json
{
  "code": 0,
  "data": {
    "id": "170406720000000001",
    "name": "test.txt",
    "extension": "txt",
    "folder_id": "0",
    "size": 1024,
    "storage_key": "2026/07/02/ab/abcdef123456.txt",
    "storage_policy_id": 1,
    "mime_type": "text/plain"
  }
}
```

### 2.2 分片上传(大文件/断点续传)

**Step 1: 初始化上传**
```
POST /api/file/upload/init
token: <token>
```
**请求体:**
```json
{
  "file_name": "large_video.mp4",
  "file_size": 104857600,
  "md5": "d41d8cd98f00b204e9800998ecf8427e",
  "folder_id": "0",
  "policy_id": 1
}
```
**响应:**
```json
{
  "code": 0,
  "data": {
    "upload_id": "uuid-xxx",
    "instant": false,
    "chunk_size": 5242880,
    "total": 20
  }
}
```
> 如果 `instant: true`, 表示文件已存在(秒传), 直接使用 `file_id`

**Step 2: 逐片上传**
```
PUT /api/file/upload/chunk/:uploadId/:index
Content-Type: multipart/form-data
token: <token>
X-Checksum: sha256_of_chunk
```
**表单字段:** `chunk` = 分片二进制数据

**Step 3: 查询进度(断点续传)**
```
GET /api/file/upload/progress/:uploadId
token: <token>
```
**响应:**
```json
{
  "code": 0,
  "data": {
    "upload_id": "uuid-xxx",
    "total_chunks": 20,
    "uploaded": 15,
    "missing": [15, 16, 17, 18, 19],
    "status": 1
  }
}
```
> `missing` 数组列出未上传的分片索引, 客户端只需重传这些分片

**Step 4: 合并完成**
```
POST /api/file/upload/merge/:uploadId
token: <token>
```

**Step 5: 取消上传**
```
DELETE /api/file/upload/:uploadId
token: <token>
```

### 2.3 获取文件信息
```
GET /api/file/:id
token: <token>
```

### 2.3 根据 fileKey 查询文件信息
```
GET /api/file/info?key=2026/07/02/ab/abcdef123456.txt
token: <token>
```
**参数:**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| key | string | 是 | 文件的 storage_key |

### 2.4 直接下载文件流
```
GET /api/file/:id/download
token: <token>
```
**响应:** 文件二进制流, Content-Disposition: attachment

### 2.5 获取下载链接
```
GET /api/file/:id/download-url
token: <token>
```
**响应:**
```json
{
  "code": 0,
  "data": {
    "download_url": "http://localhost:9000/seeyon-fs/2026/07/02/...?X-Amz-..."
  }
}
```
> MinIO存储返回预签名URL(24小时有效), 本地存储返回API路径

### 2.6 预览文件流
```
GET /api/file/:id/preview
token: <token>
```
**响应:** 文件二进制流, Content-Disposition: inline

### 2.7 获取预览链接
```
GET /api/file/:id/preview-url
token: <token>
```
**响应:**
```json
{
  "code": 0,
  "data": {
    "preview_url": "http://localhost:9000/seeyon-fs/2026/07/02/..."
  }
}
```

### 2.8 重命名文件
```
PUT /api/file/:id/rename
token: <token>
```
**请求体:**
```json
{ "new_name": "新文件名.txt" }
```

### 2.9 移动文件
```
POST /api/file/:id/move
token: <token>
```
**请求体:**
```json
{ "target_folder_id": 5 }
```

### 2.10 删除文件(移入回收站)
```
DELETE /api/file/:id
token: <token>
```

### 2.11 恢复文件
```
POST /api/file/:id/restore
token: <token>
```

### 2.12 永久删除文件
```
DELETE /api/file/:id/permanent
token: <token>
```

### 2.13 搜索文件
```
GET /api/file/search?keyword=报告
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
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)

### 3.1 创建文件夹
```
POST /api/folder
token: <token>
```
**请求体:**
```json
{ "name": "项目文档", "parent_id": "0", "biz_id": "ext_001" }
```
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 是 | 文件夹名称 |
| parent_id | string | 否 | 父文件夹ID, "0"=根目录 |
| biz_id | string | 否 | 业务ID, 用于外部系统关联 |

**响应:**
```json
{
  "code": 0,
  "data": { "id": "170406720000000001", "biz_id": "ext_001", "name": "项目文档", "parent_id": "0", "path": "/170406720000000001/" }
}
```

### 3.2 获取文件夹内容(支持分页)
```
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": "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 根据业务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
token: <token>
```
**请求体:**
```json
{ "new_name": "新名称" }
```

### 3.5 删除文件夹
```
DELETE /api/folder/:id
token: <token>
```

---

## 4. 分享管理 (Share)

### 4.1 创建分享链接
```
POST /api/share
token: <token>
```
**请求体:**
```json
{
  "file_id": "170406720000000001",
  "password": "123456",
  "expire_hours": 24,
  "max_download": 10
}
```
**响应:**
```json
{
  "code": 0,
  "data": {
    "id": "170406720000000010",
    "share_code": "a1b2c3d4e5f6g7h8",
    "share_url": "/s/a1b2c3d4e5f6g7h8",
    "has_password": true,
    "expire_at": "2026-07-03T15:00:00Z",
    "max_download": 10,
    "download_count": 0
  }
}
```

### 4.2 获取我的分享列表
```
GET /api/share
token: <token>
```

### 4.3 取消分享
```
DELETE /api/share/:id
token: <token>
```

### 4.4 获取分享信息(公开)
```
GET /api/s/:code
```
**响应:**
```json
{
  "code": 0,
  "data": {
    "file": { "name": "test.txt", "size": 1024, "mime_type": "text/plain" },
    "has_password": true,
    "expire_at": "2026-07-03T15:00:00Z"
  }
}
```

### 4.5 验证分享密码
```
POST /api/s/:code/verify
```
**请求体:**
```json
{ "password": "123456" }
```

### 4.6 下载分享文件
```
GET /api/s/:code/download?password=123456
```

---

## 5. SSO 单点登录

### 5.1 获取SSO提供商列表(公开)
```
GET /api/sso/providers
```
**响应:**
```json
{
  "code": 0,
  "data": [
    { "id": 1, "name": "wechat", "display_name": "企业微信", "type": "oauth2", "icon": "" },
    { "id": 2, "name": "dingtalk", "display_name": "钉钉", "type": "oauth2", "icon": "" }
  ]
}
```

### 5.2 获取SSO授权跳转URL
```
GET /api/sso/auth/url?provider_id=1
```
**响应:**
```json
{
  "code": 0,
  "data": {
    "auth_url": "https://open.work.weixin.qq.com/wwopen/sso/qrConnect?...",
    "state": "random_csrf_state"
  }
}
```

### 5.3 SSO回调(重定向)
```
GET /api/sso/callback?provider_id=1&code=AUTH_CODE&state=xxx
```
> 第三方授权后回调, 自动重定向到前端: `/login?sso=success&token=xxx&username=xxx`

### 5.4 SSO回调(JSON)
```
POST /api/sso/callback
```
**请求体:**
```json
{ "provider_id": 1, "code": "AUTH_CODE" }
```
**响应:**
```json
{
  "code": 0,
  "data": {
    "token": "eyJhbGci...",
    "username": "sso_oauth2_zhangsan",
    "nickname": "张三",
    "role": "user"
  }
}
```

### 5.5 获取SSO提供商详情(管理员)
```
GET /api/admin/sso/providers/:id
token: <token>
```

### 5.6 创建SSO提供商(管理员)
```
POST /api/admin/sso/providers
token: <token>
```
**请求体:**
```json
{
  "name": "wechat",
  "type": "oauth2",
  "display_name": "企业微信",
  "icon": "https://example.com/wechat.png",
  "auto_create": 1,
  "default_role": "viewer",
  "config": {
    "client_id": "ww123456",
    "client_secret": "secret_xxx",
    "auth_url": "https://open.work.weixin.qq.com/wwopen/sso/qrConnect",
    "token_url": "https://qyapi.weixin.qq.com/cgi-bin/gettoken",
    "user_info_url": "https://qyapi.weixin.qq.com/cgi-bin/user/getuserinfo",
    "redirect_uri": "http://localhost:8080/api/sso/callback",
    "scopes": "snsapi_userinfo"
  }
}
```

**支持的 SSO 类型:**
| type | 说明 | 必填 config 字段 |
|------|------|------------------|
| oauth2 | OAuth 2.0 | client_id, client_secret, auth_url, token_url, user_info_url, redirect_uri |
| oidc | OpenID Connect | 同 oauth2 + issuer_url |
| cas | CAS | cas_server_url, redirect_uri |
| ldap | LDAP | ldap_server, ldap_port, ldap_base_dn, ldap_bind_user, ldap_bind_pass |

### 5.7 更新SSO提供商(管理员)
```
PUT /api/admin/sso/providers/:id
token: <token>
```
> 请求体同创建, 字段可选(只传需要修改的字段)

### 5.8 启用/禁用SSO提供商(管理员)
```
PUT /api/admin/sso/providers/:id/toggle
token: <token>
```
**请求体:**
```json
{ "status": 1 }
```

### 5.9 删除SSO提供商(管理员)
```
DELETE /api/admin/sso/providers/:id
token: <token>
```

---

## 6. 用户管理 (Admin)

### 6.1 用户列表
```
GET /api/admin/users?page=1&size=20
token: <token>
```

### 6.2 创建用户
```
POST /api/admin/users
token: <token>
```
**请求体:**
```json
{
  "username": "user1",
  "password": "123456",
  "nickname": "用户1",
  "email": "user1@example.com",
  "role_ids": [2],
  "storage_quota": 10737418240
}
```

### 6.3 更新用户
```
PUT /api/admin/users/:id
token: <token>
```

### 6.4 删除用户
```
DELETE /api/admin/users/:id
token: <token>
```

### 6.5 重置密码
```
PUT /api/admin/users/:id/password
token: <token>
```
**请求体:**
```json
{ "password": "new_password" }
```

### 6.6 设置用户角色
```
PUT /api/admin/users/:id/roles
token: <token>
```
**请求体:**
```json
{ "role_ids": [1, 2] }
```

---

## 7. 角色权限管理 (Admin)

### 7.1 角色列表
```
GET /api/admin/roles
token: <token>
```

### 7.2 创建角色
```
POST /api/admin/roles
token: <token>
```
**请求体:**
```json
{ "name": "editor", "display_name": "编辑者", "description": "可编辑文件" }
```

### 7.3 更新角色
```
PUT /api/admin/roles/:id
token: <token>
```

### 7.4 删除角色
```
DELETE /api/admin/roles/:id
token: <token>
```

### 7.5 设置角色权限
```
PUT /api/admin/roles/:id/permissions
token: <token>
```
**请求体:**
```json
{ "permission_ids": [1, 2, 3, 4, 5] }
```

### 7.6 权限列表
```
GET /api/admin/permissions
token: <token>
```

### 7.7 创建权限
```
POST /api/admin/permissions
token: <token>
```
**请求体:**
```json
{ "code": "file:download", "name": "下载文件", "resource": "file", "action": "download" }
```

### 7.8 删除权限
```
DELETE /api/admin/permissions/:id
token: <token>
```

---

## 8. 存储策略管理 (Admin)

### 8.1 存储策略列表
```
GET /api/admin/storage-policies
token: <token>
```

### 8.2 创建存储策略
```
POST /api/admin/storage-policies
token: <token>
```
**请求体 (本地存储):**
```json
{ "name": "本地存储", "type": "local", "config": { "base_path": "./data/storage" } }
```
**请求体 (MinIO):**
```json
{
  "name": "MinIO存储",
  "type": "minio",
  "config": {
    "endpoint": "localhost:9000",
    "access_key": "admin",
    "secret_key": "123456789",
    "bucket": "seeyon-fs",
    "use_ssl": false
  }
}
```

### 8.3 更新存储策略
```
PUT /api/admin/storage-policies/:id
token: <token>
```

### 8.4 删除存储策略
```
DELETE /api/admin/storage-policies/:id
token: <token>
```

---

## 9. 组织架构管理 (Admin)

### 9.1 部门列表(树形)
```
GET /api/admin/departments
token: <token>
```
**响应:**
```json
{
  "code": 0,
  "data": [
    {
      "id": 1, "name": "总公司", "code": "HQ", "parent_id": 0,
      "children": [
        { "id": 2, "name": "技术部", "code": "TECH", "parent_id": 1 },
        { "id": 3, "name": "产品部", "code": "PM", "parent_id": 1 }
      ]
    }
  ]
}
```

### 9.2 创建部门
```
POST /api/admin/departments
token: <token>
```
**请求体:**
```json
{ "name": "技术部", "code": "TECH", "parent_id": 1, "sort_order": 1 }
```

### 9.3 更新部门
```
PUT /api/admin/departments/:id
token: <token>
```

### 9.4 删除部门
```
DELETE /api/admin/departments/:id
token: <token>
```

---

## 10. 系统设置

### 10.1 健康检查
```
GET /health
```
**响应:** `{ "status": "ok" }`

### 10.2 获取CDN配置(管理员)
```
GET /api/admin/settings/cdn
token: <token>
```
**响应:**
```json
{
  "code": 0,
  "data": {
    "cdn_host": "http://localhost:3090",
    "cdn_path_prefix": "/public",
    "local_base_path": "D:/Seeyon/A8/localfile"
  }
}
```

### 10.3 更新CDN配置(管理员)
```
PUT /api/admin/settings/cdn
token: <token>
```
**请求体:**
```json
{
  "cdn_host": "http://localhost:3090",
  "cdn_path_prefix": "/public"
}
```
**响应:**
```json
{
  "code": 0,
  "message": "CDN配置已更新",
  "data": {
    "cdn_host": "http://localhost:3090",
    "cdn_path_prefix": "/public",
    "example_url": "http://localhost:3090/public/2026/07/02/ab/abcdef.txt"
  }
}
```

> 生成的链接格式: `cdn_host + cdn_path_prefix + / + storage_key`
>
> 例如: `http://localhost:3090/public/2026/07/02/30/306d8f65344c19bd.txt`

---

## 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 }
```

---

## 权限标识一览

| 权限标识 | 说明 |
|----------|------|
| file:create | 创建文件/文件夹 |
| file:read | 查看文件 |
| 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
token: <token>
```
> 根据存储策略的 `access_mode` 自动选择:
> - `proxy`: 中转模式, 直接返回文件流
> - `presigned`: 预签名模式, 302重定向到MinIO
> - `cdn`: CDN模式, 302重定向到CDN地址

### 2.18 获取文件访问URL
```
GET /api/file/:id/access-url
token: <token>
```
**响应:**
```json
{
  "code": 0,
  "data": {
    "mode": "presigned",
    "url": "http://files.example.com/minio/seeyon-fs/2026/07/02/...?X-Amz-...",
    "file_name": "test.pdf",
    "file_size": 1024000,
    "content_type": "application/pdf"
  }
}
```

### 2.19 分享文件统一访问(公开)
```
GET /api/s/:code/access?password=xxx
```

---

## 访问模式说明

| 模式 | 适用场景 | 工作原理 |
|------|----------|----------|
| `proxy` | 私有文件、严格权限 | Nginx→Server鉴权→Server从MinIO拉取→返回给用户 |
| `presigned` | 公开分享、大文件 | Server生成预签名URL→用户直连MinIO(经Nginx代理) |
| `cdn` | 静态资源、本地存储 | 返回CDN地址, 用户直接访问 |

**预签名模式配置示例:**
```json
{
  "endpoint": "localhost:9000",
  "bucket": "seeyon-fs",
  "access_key": "admin",
  "secret_key": "123456789",
  "access_mode": "presigned",
  "nginx_endpoint": "http://files.example.com"
}
```
> `nginx_endpoint`: Nginx公网地址, 替换MinIO内部地址, 用户通过Nginx访问MinIO

---

## 存储策略类型

| type | 说明 | config 字段 |
|------|------|-------------|
| local | 本地磁盘 | base_path |
| minio | MinIO | endpoint, access_key, secret_key, bucket, use_ssl |
| s3 | AWS S3 | endpoint, access_key, secret_key, bucket, region, use_ssl |
| oss | 阿里云 OSS | endpoint, access_key, secret_key, bucket, region |