添加用户鉴权

mini-program/docs/api.md

@@ -11,6 +11,11 @@ http://127.0.0.1:8001
 - Swagger UI：`/docs`
 - ReDoc：`/redoc`
 
+鉴权说明：
+
+- 除 `GET /health`、`POST /auth/login`、`/docs`、`/redoc`、`/openapi.json` 外，其余接口都需要 Bearer Token。
+- 请求头格式：`Authorization: Bearer <access_token>`
+
 ## 1. 健康检查
 
 ### `GET /health`
@@ -27,23 +32,63 @@ http://127.0.0.1:8001
 }
 ```
 
-## 2. 发送消息
+## 2. 登录
+
+### `POST /auth/login`
+
+用途：
+
+- 用户登录并获取访问令牌（access token）。
+- 当前示例账号：`test1/test2/test3`，密码均为 `123`。
+
+请求体：
+
+```json
+{
+  "username": "test1",
+  "password": "123"
+}
+```
+
+成功响应（`200`）：
+
+```json
+{
+  "access_token": "<jwt-token>",
+  "token_type": "bearer",
+  "expires_in": 3600,
+  "user_id": 1
+}
+```
+
+常见错误码：
+
+- `401`：用户名或密码错误，或账号不可用
+- `422`：请求参数校验失败
+
+## 3. 发送消息
 
 ### `POST /messages`
 
 用途：
 
 - 保存单聊消息。
-- 服务端会根据 `sender_user_id` 和 `peer_user_id` 自动查找或创建会话。
+- 服务端从 token 中识别发送者，不需要传 `sender_user_id`。
+- 服务端根据“当前用户 + peer_user_id”自动查找或创建会话。
 - `client_msg_id` 用于幂等控制。
 
+请求头：
+
+```
+Authorization: Bearer <access_token>
+```
+
 请求体：
 
 ```json
 {
-  "sender_user_id": 1,
   "peer_user_id": 2,
-  "client_msg_id": "msg-20260326-0001",
+  "client_msg_id": "msg-20260326-0002",
   "content_type": 1,
   "content_text": "hello"
 }
@@ -51,8 +96,7 @@ http://127.0.0.1:8001
 
 字段规则：
 
-- `sender_user_id`：`int > 0`
-- `peer_user_id`：`int > 0`，且不能与 `sender_user_id` 相同
+- `peer_user_id`：`int > 0`，且不能与当前登录用户相同
 - `client_msg_id`：`string`，长度 `1-64`
 - `content_type`：`1=text 2=audio 3=image 4=json`
 - `content_text`：`content_type=1` 时必填
@@ -66,9 +110,9 @@ http://127.0.0.1:8001
 {
   "idempotent": false,
   "message": {
-    "id": 1006,
+    "id": 1008,
     "conversation_id": 1,
-    "seq": 6,
+    "seq": 7,
     "sender_user_id": 1,
     "role": 1,
     "content_type": 1,
@@ -76,8 +120,8 @@ http://127.0.0.1:8001
     "content_json": null,
     "media_file_key": null,
     "media_duration_ms": null,
-    "client_msg_id": "msg-20260326-0001",
-    "created_at": "2026-03-26T10:40:00.123000"
+    "client_msg_id": "msg-20260326-0002",
+    "created_at": "2026-03-26T11:20:00.123000"
   }
 }
 ```
@@ -88,9 +132,9 @@ http://127.0.0.1:8001
 {
   "idempotent": true,
   "message": {
-    "id": 1006,
+    "id": 1008,
     "conversation_id": 1,
-    "seq": 6,
+    "seq": 7,
     "sender_user_id": 1,
     "role": 1,
     "content_type": 1,
@@ -98,19 +142,20 @@ http://127.0.0.1:8001
     "content_json": null,
     "media_file_key": null,
     "media_duration_ms": null,
-    "client_msg_id": "msg-20260326-0001",
-    "created_at": "2026-03-26T10:40:00.123000"
+    "client_msg_id": "msg-20260326-0002",
+    "created_at": "2026-03-26T11:20:00.123000"
   }
 }
 ```
 
 常见错误码：
 
-- `404`：发送人或接收人不存在/不可用
+- `401`：未登录或 token 无效
+- `404`：接收人不存在/不可用
 - `409`：会话不是激活状态
 - `422`：请求参数校验失败
 
-## 3. 查询消息
+## 4. 查询消息
 
 ### `GET /messages`
 
@@ -118,6 +163,13 @@ http://127.0.0.1:8001
 
 - 按会话分页读取消息。
 - 返回结果按 `seq` 正序排列。
+- 仅会话参与者可读取。
+
+请求头：
+
+```
+Authorization: Bearer <access_token>
+```
 
 Query 参数：
 
@@ -162,5 +214,7 @@ GET /messages?conversation_id=1&cursor_seq=50&limit=20
 
 常见错误码：
 
+- `401`：未登录或 token 无效
+- `403`：无权限读取该会话
 - `404`：会话不存在
 - `422`：请求参数校验失败