# 认证接口文档

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

## 注册
- 方法与路径：`POST /api/v1/auth/register`
- 请求体：
```json
{
  "username": "alice",
  "password": "secret123",
  "confirm_password": "secret123"
}
```
- 成功响应：
```json
{
  "access_token": "<JWT>",
  "token_type": "bearer",
  "username": "alice"
}
```
- 失败响应示例：
  - 400：`Passwords do not match`
  - 400：`Username already registered`
- 调用示例（curl）：
```bash
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`
- 请求体：
```json
{
  "username": "alice",
  "password": "secret123",
  "device_id": "devA"
}
```
- 成功响应：
```json
{
  "access_token": "<JWT>",
  "token_type": "bearer",
  "username": "alice"
}
```
- 失败响应示例：
  - 401：`用户名或密码错误`
  - 403：`该账号已在其他设备在线`
- 调用示例（curl）：
```bash
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`
- 请求体：
```json
{
  "username": "alice",
  "device_id": "devA"
}
```
- 成功响应：
```json
{ "detail": "已退出登录" }
```
- 用途：释放当前设备的会话，便于其他设备登录同账号

## 在线时长统计
- 方法与路径：`GET /api/v1/auth/online-time/{username}`
- 返回体：
```json
{
  "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`，建议由前端根据系统信息生成并持久化（例如用户目录内文件或硬件指纹）