API 文档

# API 文档

本文档面向外部系统二次对接。所有接口默认返回 JSON，失败时使用合适的 4xx/5xx 状态码，并尽量返回 `success`、`error` 和 `meta` 诊断字段。

## 认证

平台浏览器会话使用 `edgeone_upload_session` HttpOnly Cookie。外部系统如需服务端对接，建议后续扩展专用 API Token；当前已实现接口以 Cookie 会话和公开分享/搜索接口为主。

### 密码登录

`POST /api/auth/login-password`

请求：

```json
{
  "email": "user@example.com",
  "password": "password123"
}
```

成功后写入上传会话 Cookie。

### 邮箱验证码

- `POST /api/auth/send-code` 发送验证码，`purpose` 为 `login` 或 `reset_password`。
- `POST /api/auth/login-code` 使用邮箱验证码登录。
- `POST /api/auth/reset-password` 使用验证码重置密码。
- `POST /api/auth/set-password` 当前登录用户设置密码。
- `POST /api/auth/logout` 退出登录并清除 Cookie。

## 文件上传

### 初始化上传

`POST /api/files/init-upload`

请求：

```json
{
  "name": "example.pdf",
  "size": 1024,
  "type": "application/pdf",
  "recipientEmail": "receiver@example.com",
  "wechatGroupName": "微信群名称",
  "shareTag": "业务标签",
  "checksum": "32位MD5"
}
```

返回 COS 直传 `PUT` 地址和文件元数据。无 Cookie 时按 `Anonymous user` 处理。

### 完成上传

`POST /api/files/{fileId}/complete`

服务端读取 COS 对象信息并更新文件状态、ETag，同时写入上传完成日志。

### 文件预览与下载

- `GET /api/files/{fileId}/preview` 生成当前有效的预览地址。
- `GET /api/files/{fileId}/download` 点击下载时实时重新签名并 302 跳转。

## 分享

### 创建分享

`POST /api/files/{fileId}/share`

请求：

```json
{
  "allowDownload": true,
  "expiresAt": "2026-12-31T00:00:00.000Z",
  "maxViews": 100,
  "password": "optional-password"
}
```

返回 `/shares/{token}` 分享页面 URL。

### 访问分享

- `GET /api/shares/{token}` 获取分享文件预览信息；密码保护分享会返回 HTTP 401 和 `requiresPassword: true`。
- `POST /api/shares/{token}` 使用 `{ "password": "..." }` 解锁密码保护分享，成功后写入短期 HttpOnly 访问 Cookie 并返回预览信息。
- `GET /api/shares/{token}/download` 点击下载时实时重新签名并 302 跳转；密码保护分享需先解锁。

## 公开搜索与取回

### 搜索文件

`POST /api/public/files/search`

支持按 `fileName`、`shareId`、`checksum`、`cosEtag`、`recipientEmail`、`wechatGroupName`、`shareTag` 搜索。

### 取回文件

`POST /api/public/files/{fileId}/retrieve`

请求体使用同搜索条件；条件匹配后实时跳转到下载接口。

## 用户与设置

- `GET /api/users` 列出用户。
- `POST /api/users` 平台管理员添加用户。
- `PATCH /api/users/{userId}` 平台管理员或用户本人更新用户信息。
- `DELETE /api/users/{userId}` 平台管理员删除普通用户。
- `GET /api/users/invitations` 查看邀请。
- `POST /api/users/invitations` 创建邀请。
- `GET /api/settings/registration` 查看注册设置。
- `PATCH /api/settings/registration` 平台管理员修改注册设置。

## 健康检查

`GET /api/health/db`

返回当前元数据存储配置和数据库连接诊断，不返回密码。