DP/tempdocs/认证接口文档.md

认证接口文档

概述

• 基础地址：http://localhost:8000
• 版本前缀：/api/v1
• 认证方式：Bearer JWT（登录或注册成功后返回的 access_token）
• 单设备限制：同一账号仅允许一个设备同时在线（依据 device_id）

注册

• 方法与路径：POST /api/v1/auth/register
• 请求体：

{
  "username": "alice",
  "password": "secret123",
  "confirm_password": "secret123"
}

• 成功响应：

{
  "access_token": "<JWT>",
  "token_type": "bearer",
  "username": "alice"
}

• 失败响应示例：
  • 400：Passwords do not match
  • 400：Username already registered
• 调用示例（curl）：

curl -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username":"alice","password":"secret123","confirm_password":"secret123"}'

登录

• 方法与路径：POST /api/v1/auth/login
• 请求体：

{
  "username": "alice",
  "password": "secret123",
  "device_id": "devA"
}

• 成功响应：

{
  "access_token": "<JWT>",
  "token_type": "bearer",
  "username": "alice"
}

• 失败响应示例：
  • 401：用户名或密码错误
  • 403：该账号已在其他设备在线
• 调用示例（curl）：

curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"alice","password":"secret123","device_id":"devA"}'

登出

• 方法与路径：POST /api/v1/auth/logout
• 请求体：

{
  "username": "alice",
  "device_id": "devA"
}

• 成功响应：

{ "detail": "已退出登录" }

• 用途：释放当前设备的会话，便于其他设备登录同账号

在线时长统计

• 方法与路径：GET /api/v1/auth/online-time/{username}
• 返回体：

{
  "username": "alice",
  "total_seconds": 1234,   // 已登出会话累计时长（秒）
  "active_seconds": 56     // 当前活跃会话的实时在线时长（秒）
}

• 说明：
  • 登录时会记录 login_at，登出时写入 logout_at 并计算 duration_seconds
  • total_seconds 为历史累计；active_seconds 为当前会话实时值

前端对接建议

• 前端拿到 access_token 后，将其置于请求头：Authorization: Bearer <token>
• 后续接口可以基于该令牌进行身份识别和鉴权
• 登录时必须传入稳定的 device_id，建议由前端根据系统信息生成并持久化（例如用户目录内文件或硬件指纹）