SeeyonFileSystem/server/docs/api.md

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

> Base URL: `http://localhost:8080/api`
>
> 认证方式: `Authorization: Bearer <JWT Token>`
>
> 统一响应格式: `{ "code": 0, "message": "success", "data": ... }`

---

## 1. 认证 (Auth)

### 1.1 用户登录
```
POST /api/auth/login
```
**请求体:**
```json
{ "username": "admin", "password": "admin123" }
```
**响应:**
```json
{
  "code": 0,
  "data": {
    "token": "eyJhbGci...",
    "username": "admin",
    "nickname": "管理员",
    "role": "admin"
  }
}
```

### 1.2 用户注册
```
POST /api/auth/register
```
**请求体:**
```json
{ "username": "user1", "password": "123456", "nickname": "用户1", "email": "user1@example.com" }
```

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

### 1.4 获取当前用户权限
```
GET /api/auth/permissions
Authorization: Bearer <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
Authorization: Bearer <token>
```
**参数:**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| file | File | 是 | 文件内容 |
| folder_id | int | 否 | 目标文件夹ID, 0=根目录 |
| storage_policy_id | int | 否 | 存储策略ID, 0=使用默认策略 |

**响应:**
```json
{
  "code": 0,
  "data": {
    "id": 1,
    "name": "test.txt",
    "extension": "txt",
    "folder_id": 1,
    "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
Authorization: Bearer <token>
```
**请求体:**
```json
{
  "file_name": "large_video.mp4",
  "file_size": 104857600,
  "md5": "d41d8cd98f00b204e9800998ecf8427e",
  "folder_id": 1,
  "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
Authorization: Bearer <token>
X-Checksum: sha256_of_chunk
```
**表单字段:** `chunk` = 分片二进制数据

**Step 3: 查询进度(断点续传)**
```
GET /api/file/upload/progress/:uploadId
Authorization: Bearer <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
Authorization: Bearer <token>
```

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

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

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

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

### 2.5 获取下载链接
```
GET /api/file/:id/download-url
Authorization: Bearer <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
Authorization: Bearer <token>
```
**响应:** 文件二进制流, Content-Disposition: inline

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

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

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

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

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

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

### 2.13 搜索文件
```
GET /api/file/search?keyword=报告
Authorization: Bearer <token>
```

### 2.14 获取回收站列表
```
GET /api/file/trash
Authorization: Bearer <token>
```

---

## 3. 文件夹管理 (Folder)

### 3.1 创建文件夹
```
POST /api/folder
Authorization: Bearer <token>
```
**请求体:**
```json
{ "name": "项目文档", "parent_id": 0 }
```
**响应:**
```json
{
  "code": 0,
  "data": { "id": 1, "name": "项目文档", "parent_id": 0, "path": "/1/" }
}
```

### 3.2 获取文件夹内容(文件+子文件夹)
```
GET /api/folder/:id/children
Authorization: Bearer <token>
```
> `:id` 为 `root` 时获取根目录

**响应:**
```json
{
  "code": 0,
  "data": {
    "folders": [{ "id": 2, "name": "子文件夹", "parent_id": 1 }],
    "files": [{ "id": 1, "name": "test.txt", "size": 1024 }]
  }
}
```

### 3.3 重命名文件夹
```
PUT /api/folder/:id/rename
Authorization: Bearer <token>
```
**请求体:**
```json
{ "new_name": "新名称" }
```

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

---

## 4. 分享管理 (Share)

### 4.1 创建分享链接
```
POST /api/share
Authorization: Bearer <token>
```
**请求体:**
```json
{
  "file_id": 1,
  "password": "123456",
  "expire_hours": 24,
  "max_download": 10
}
```
**响应:**
```json
{
  "code": 0,
  "data": {
    "id": 1,
    "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
Authorization: Bearer <token>
```

### 4.3 取消分享
```
DELETE /api/share/:id
Authorization: Bearer <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
Authorization: Bearer <token>
```

### 5.6 创建SSO提供商(管理员)
```
POST /api/admin/sso/providers
Authorization: Bearer <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
Authorization: Bearer <token>
```
> 请求体同创建, 字段可选(只传需要修改的字段)

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

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

---

## 6. 用户管理 (Admin)

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

### 6.2 创建用户
```
POST /api/admin/users
Authorization: Bearer <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
Authorization: Bearer <token>
```

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

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

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

---

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

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

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

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

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

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

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

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

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

---

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

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

### 8.2 创建存储策略
```
POST /api/admin/storage-policies
Authorization: Bearer <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
Authorization: Bearer <token>
```

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

---

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

### 9.1 部门列表(树形)
```
GET /api/admin/departments
Authorization: Bearer <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
Authorization: Bearer <token>
```
**请求体:**
```json
{ "name": "技术部", "code": "TECH", "parent_id": 1, "sort_order": 1 }
```

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

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

---

## 10. 系统设置

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

### 10.2 获取CDN配置(管理员)
```
GET /api/admin/settings/cdn
Authorization: Bearer <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
Authorization: Bearer <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`

---

## 权限标识一览

| 权限标识 | 说明 |
|----------|------|
| file:create | 创建文件/文件夹 |
| file:read | 查看文件 |
| file:update | 修改文件 |
| file:delete | 删除文件 |
| file:upload | 上传文件 |
| share:create | 创建分享 |
| share:manage | 管理分享 |
| user:manage | 用户管理 |
| role:manage | 角色管理 |
| sso:manage | SSO管理 |
| system:manage | 系统管理 |
| * | 所有权限(超级管理员) |

### 2.17 统一文件访问(自动选择模式)
```
GET /api/file/:id/access
Authorization: Bearer <token>
```
> 根据存储策略的 `access_mode` 自动选择:
> - `proxy`: 中转模式, 直接返回文件流
> - `presigned`: 预签名模式, 302重定向到MinIO
> - `cdn`: CDN模式, 302重定向到CDN地址

### 2.18 获取文件访问URL
```
GET /api/file/:id/access-url
Authorization: Bearer <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 |