413 lines
7.4 KiB
Markdown
413 lines
7.4 KiB
Markdown
# Server API 全量文档
|
||
|
||
## 概述
|
||
|
||
- **基础地址**：`http://localhost:8000`
|
||
- **版本前缀**：`/api/v1`
|
||
- **认证方式**：
|
||
- Header: `Authorization: Bearer <access_token>` (用于普通用户接口)
|
||
- Header: `x-admin-token: admin-secret-token` (用于管理员接口)
|
||
- Header: `x-api-key: <key>` (用于部分工具接口)
|
||
|
||
---
|
||
|
||
## 📚 1. 认证模块 (Auth)
|
||
|
||
**Base Path**: `/api/v1/auth`
|
||
|
||
### 1.1 注册
|
||
|
||
- **URL**: `POST /register`
|
||
- **功能**: 用户注册
|
||
- **请求体**:
|
||
|
||
```json
|
||
{
|
||
"username": "user1",
|
||
"password": "password123",
|
||
"confirm_password": "password123",
|
||
"email": "user1@example.com", // 可选
|
||
"code": "123456", // 验证码(可选)
|
||
"device_id": "device_001" // 可选，默认 unknown_device
|
||
}
|
||
```
|
||
|
||
- **响应**:
|
||
|
||
```json
|
||
{
|
||
"access_token": "eyJhbG...",
|
||
"token_type": "bearer",
|
||
"username": "user1"
|
||
}
|
||
```
|
||
|
||
### 1.2 登录
|
||
|
||
- **URL**: `POST /login`
|
||
- **功能**: 用户登录，获取 Token
|
||
- **请求体**:
|
||
|
||
```json
|
||
{
|
||
"username": "user1",
|
||
"password": "password123",
|
||
"device_id": "device_001"
|
||
}
|
||
```
|
||
|
||
- **响应**: 同注册接口
|
||
|
||
### 1.3 发送验证码
|
||
|
||
- **URL**: `POST /send-verification-code`
|
||
- **功能**: 发送注册/验证邮件验证码
|
||
- **请求体**:
|
||
|
||
```json
|
||
{
|
||
"email": "user1@example.com"
|
||
}
|
||
```
|
||
|
||
### 1.4 验证邮箱
|
||
|
||
- **URL**: `POST /verify-email`
|
||
- **功能**: 验证邮箱验证码
|
||
- **请求体**:
|
||
|
||
```json
|
||
{
|
||
"username": "user1",
|
||
"code": "123456"
|
||
}
|
||
```
|
||
|
||
### 1.5 忘记密码
|
||
|
||
- **URL**: `POST /forgot-password`
|
||
- **功能**: 发送重置密码邮件
|
||
- **请求体**:
|
||
|
||
```json
|
||
{
|
||
"email": "user1@example.com"
|
||
}
|
||
```
|
||
|
||
### 1.6 重置密码
|
||
|
||
- **URL**: `POST /reset-password`
|
||
- **功能**: 使用 Token 重置密码
|
||
- **请求体**:
|
||
|
||
```json
|
||
{
|
||
"email": "user1@example.com",
|
||
"token": "123456",
|
||
"new_password": "newpassword123",
|
||
"confirm_password": "newpassword123"
|
||
}
|
||
```
|
||
|
||
### 1.7 登出
|
||
|
||
- **URL**: `POST /logout`
|
||
- **功能**: 退出当前设备登录
|
||
- **请求体**:
|
||
|
||
```json
|
||
{
|
||
"username": "user1",
|
||
"device_id": "device_001"
|
||
}
|
||
```
|
||
|
||
### 1.8 许可证验证 (Verify)
|
||
|
||
- **URL**: `POST /verify`
|
||
- **功能**: 验证当前 Token 和会话是否有效（用于应用启动检查）
|
||
- **Headers**: `Authorization: Bearer <token>`
|
||
- **请求体**:
|
||
|
||
```json
|
||
{
|
||
"username": "user1",
|
||
"device_id": "device_001"
|
||
}
|
||
```
|
||
|
||
- **响应**:
|
||
|
||
```json
|
||
{
|
||
"valid": true,
|
||
"username": "user1",
|
||
"expire_date": "2025-12-31T23:59:59" // 若有过期时间
|
||
}
|
||
```
|
||
|
||
### 1.9 心跳 (Heartbeat)
|
||
|
||
- **URL**: `POST /heartbeat`
|
||
- **功能**: 维持会话活跃状态
|
||
- **请求体**:
|
||
|
||
```json
|
||
{
|
||
"username": "user1",
|
||
"device_id": "device_001"
|
||
}
|
||
```
|
||
|
||
### 1.10 获取在线时长
|
||
|
||
- **URL**: `GET /online-time/{username}`
|
||
- **功能**: 获取用户累计在线时长
|
||
- **响应**:
|
||
|
||
```json
|
||
{
|
||
"username": "user1",
|
||
"total_seconds": 3600, // 历史累计
|
||
"active_seconds": 120 // 当前会话
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🖥️ 2. 客户端模块 (Client)
|
||
|
||
**Base Path**: `/api/v1/client`
|
||
|
||
### 2.1 检查更新
|
||
|
||
- **URL**: `POST /check_update`
|
||
- **功能**: 检查插件是否有新版本
|
||
- **请求体**:
|
||
|
||
```json
|
||
{
|
||
"username": "user1" // 用于检查用户所在组的特定版本
|
||
}
|
||
```
|
||
|
||
### 2.2 客户端登录
|
||
|
||
- **URL**: `POST /login`
|
||
- **功能**: 客户端专用登录，返回更多用户信息
|
||
- **请求体**: 同 Auth 登录
|
||
- **响应**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"token": "eyJ...",
|
||
"username": "user1",
|
||
"expire_date": "2025-12-31",
|
||
"permissions": ["plugin.use"]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 👤 3. 用户资料 (User Profile)
|
||
|
||
**Base Path**: `/api/v1`
|
||
|
||
### 3.1 获取资料
|
||
|
||
- **URL**: `GET /user/profile?username=user1`
|
||
- **功能**: 获取用户详细资料（积分、VIP 状态、签到信息等）
|
||
- **Headers**: `Authorization: Bearer <token>`
|
||
|
||
### 3.2 更新资料
|
||
|
||
- **URL**: `PUT /user/profile`
|
||
- **功能**: 更新昵称、头像等
|
||
- **请求体**:
|
||
|
||
```json
|
||
{
|
||
"username": "user1",
|
||
"nickname": "New Nickname",
|
||
"avatar": "http://example.com/avatar.jpg"
|
||
}
|
||
```
|
||
|
||
### 3.3 积分历史
|
||
|
||
- **URL**: `GET /points/history`
|
||
- **功能**: 分页获取积分变动记录
|
||
- **Query Params**: `username`, `type` (可选: checkin/consume/reward), `page`, `limit`
|
||
|
||
---
|
||
|
||
## 📅 4. 签到模块 (Check-In)
|
||
|
||
**Base Path**: `/api/v1/checkin`
|
||
|
||
### 4.1 每日签到
|
||
|
||
- **URL**: `POST /daily`
|
||
- **功能**: 执行每日签到
|
||
- **请求体**: `{"username": "user1"}`
|
||
- **响应**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"success": true,
|
||
"points_earned": 10,
|
||
"consecutive_days": 5,
|
||
"message": "签到成功..."
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4.2 签到状态
|
||
|
||
- **URL**: `GET /status?username=user1`
|
||
- **功能**: 检查今日是否已签到
|
||
|
||
### 4.3 签到日历
|
||
|
||
- **URL**: `GET /calendar/{year}/{month}`
|
||
- **功能**: 获取指定月份的签到日期列表
|
||
- **Query Params**: `username`
|
||
|
||
### 4.4 签到记录 (列表)
|
||
|
||
- **URL**: `GET /history?username=user1&page=1`
|
||
- **功能**: 分页获取签到记录
|
||
|
||
### 4.5 获取签到规则
|
||
|
||
- **URL**: `GET /config`
|
||
- **功能**: 获取签到奖励规则（公开接口，无需 Admin Token）
|
||
- **响应**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": [
|
||
{
|
||
"consecutive_days": 1,
|
||
"base_points": 10,
|
||
"bonus_points": 0,
|
||
"total_points": 10
|
||
},
|
||
{
|
||
"consecutive_days": 7,
|
||
"base_points": 10,
|
||
"bonus_points": 20,
|
||
"total_points": 30
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🛠️ 5. 功能使用 (Feature)
|
||
|
||
**Base Path**: `/api/v1/feature`
|
||
|
||
### 5.1 使用功能的 (扣费接口)
|
||
|
||
- **URL**: `POST /use`
|
||
- **功能**: 记录功能使用，扣除积分或 VIP 配额
|
||
- **请求体**:
|
||
|
||
```json
|
||
{
|
||
"username": "user1",
|
||
"feature_key": "ai_remove_bg",
|
||
"device_id": "device_001"
|
||
}
|
||
```
|
||
|
||
- **响应**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"success": true,
|
||
"cost_type": "points", // 或 vip_quota, free
|
||
"points_cost": 10,
|
||
"message": "消耗10积分"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🧮 6. 工具演示 (JSX Demo)
|
||
|
||
**Base Path**: `/api/v1/jsx_demo`
|
||
|
||
### 6.1 计算表达式
|
||
|
||
- **URL**: `POST /calculate`
|
||
- **Headers**: `x-api-key: <optional>`
|
||
- **请求体**: `{"expression": "1+1"}`
|
||
|
||
---
|
||
|
||
## 📊 7. 统计与日志 (Analytics & Stats)
|
||
|
||
**Base Path**: `/api/v1`
|
||
|
||
### 7.1 上报日志
|
||
|
||
- **URL**: `POST /analytics/log`
|
||
- **功能**: 客户端上报行为日志
|
||
- **请求体**:
|
||
|
||
```json
|
||
{
|
||
"username": "user1",
|
||
"device_id": "dev1",
|
||
"action": "click_button",
|
||
"timestamp": 1234567890
|
||
}
|
||
```
|
||
|
||
### 7.2 获取用户统计
|
||
|
||
- **URL**: `GET /analytics/stats/{username}`
|
||
|
||
---
|
||
|
||
## 👑 8. 管理员后台 (Admin)
|
||
|
||
**Headers**: `x-admin-token: admin-secret-token` (部分接口兼容 Form 表单 token)
|
||
|
||
### 8.1 基础管理 (Base Path: `/api/v1/admin`)
|
||
|
||
- `POST /upload_version`: 上传新版本插件包
|
||
- `GET /archives`: 列出历史版本
|
||
- `POST /groups`: 创建用户组
|
||
- `GET /groups`: 获取用户组列表
|
||
- `PUT /groups/{id}`: 更新用户组
|
||
- `GET /users`: 获取所有用户列表
|
||
- `PUT /users/{id}/group`: 修改用户所属组
|
||
- `PUT /users/{id}/permissions`: 修改用户权限
|
||
|
||
### 8.2 配置管理 (Base Path: `/api/v1/admin/config`)
|
||
|
||
- **功能配置** (`/features`): GET(列表), POST(新增), PUT(/{key} 更新), DELETE(/{key} 删除)
|
||
- **VIP 配置** (`/vip`): GET(列表), PUT(/{type} 更新)
|
||
- **签到配置** (`/checkin`): GET(列表), POST(新增), PUT(/{days} 更新), DELETE(/{days} 删除)
|
||
|
||
### 8.3 数据统计 (Base Path: `/api/v1/admin/stats`)
|
||
|
||
- `GET /today`: 今日概览 (用户数、签到数、功能使用数)
|
||
- `GET /feature-usage`: 功能使用排行 (Top 10)
|
||
- `GET /points-trend`: 积分收支趋势 (近 7 天)
|