zuowei/DP

Fork 0

Files

zuowei1216 1b19ff1b92 20251222

2025-12-22 21:06:29 +08:00

7.4 KiB

Raw Blame History

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
功能: 用户注册
请求体:

{
  "username": "user1",
  "password": "password123",
  "confirm_password": "password123",
  "email": "user1@example.com", // 可选
  "code": "123456", // 验证码(可选)
  "device_id": "device_001" // 可选，默认 unknown_device
}

响应:

{
  "access_token": "eyJhbG...",
  "token_type": "bearer",
  "username": "user1"
}

1.2 登录

URL: POST /login
功能: 用户登录，获取 Token
请求体:

{
  "username": "user1",
  "password": "password123",
  "device_id": "device_001"
}

响应: 同注册接口

1.3 发送验证码

URL: POST /send-verification-code
功能: 发送注册/验证邮件验证码
请求体:

{
  "email": "user1@example.com"
}

1.4 验证邮箱

URL: POST /verify-email
功能: 验证邮箱验证码
请求体:

{
  "username": "user1",
  "code": "123456"
}

1.5 忘记密码

URL: POST /forgot-password
功能: 发送重置密码邮件
请求体:

{
  "email": "user1@example.com"
}

1.6 重置密码

URL: POST /reset-password
功能: 使用 Token 重置密码
请求体:

{
  "email": "user1@example.com",
  "token": "123456",
  "new_password": "newpassword123",
  "confirm_password": "newpassword123"
}

1.7 登出

URL: POST /logout
功能: 退出当前设备登录
请求体:

{
  "username": "user1",
  "device_id": "device_001"
}

1.8 许可证验证 (Verify)

URL: POST /verify
功能: 验证当前 Token 和会话是否有效（用于应用启动检查）
Headers: Authorization: Bearer <token>
请求体:

{
  "username": "user1",
  "device_id": "device_001"
}

响应:

{
  "valid": true,
  "username": "user1",
  "expire_date": "2025-12-31T23:59:59" // 若有过期时间
}

1.9 心跳 (Heartbeat)

URL: POST /heartbeat
功能: 维持会话活跃状态
请求体:

{
  "username": "user1",
  "device_id": "device_001"
}

1.10 获取在线时长

URL: GET /online-time/{username}
功能: 获取用户累计在线时长
响应:

{
  "username": "user1",
  "total_seconds": 3600, // 历史累计
  "active_seconds": 120 // 当前会话
}

🖥️ 2. 客户端模块 (Client)

Base Path: /api/v1/client

2.1 检查更新

URL: POST /check_update
功能: 检查插件是否有新版本
请求体:

{
  "username": "user1" // 用于检查用户所在组的特定版本
}

2.2 客户端登录

URL: POST /login
功能: 客户端专用登录，返回更多用户信息
请求体: 同 Auth 登录
响应:

{
  "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
功能: 更新昵称、头像等
请求体:

{
  "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"}
响应:

{
  "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）
响应:

{
  "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 配额
请求体:

{
  "username": "user1",
  "feature_key": "ai_remove_bg",
  "device_id": "device_001"
}

响应:

{
  "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)