# 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 天)