98 lines
2.5 KiB
Markdown
98 lines
2.5 KiB
Markdown
# 认证接口文档
|
||
|
||
## 概述
|
||
- 基础地址：`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`，建议由前端根据系统信息生成并持久化（例如用户目录内文件或硬件指纹）
|