Initial commit - DesignerCEP Project with Caddy deployment

tempdocs/认证接口文档.md

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