新增接口文档

mini-program/docs/api.md

@@ -0,0 +1,166 @@
+# 接口文档
+
+本地 Base URL：
+
+```
+http://127.0.0.1:8001
+```
+
+自动生成文档：
+
+- Swagger UI：`/docs`
+- ReDoc：`/redoc`
+
+## 1. 健康检查
+
+### `GET /health`
+
+用途：
+
+- 检查服务是否存活。
+
+响应示例：
+
+```json
+{
+  "status": "ok"
+}
+```
+
+## 2. 发送消息
+
+### `POST /messages`
+
+用途：
+
+- 保存单聊消息。
+- 服务端会根据 `sender_user_id` 和 `peer_user_id` 自动查找或创建会话。
+- `client_msg_id` 用于幂等控制。
+
+请求体：
+
+```json
+{
+  "sender_user_id": 1,
+  "peer_user_id": 2,
+  "client_msg_id": "msg-20260326-0001",
+  "content_type": 1,
+  "content_text": "hello"
+}
+```
+
+字段规则：
+
+- `sender_user_id`：`int > 0`
+- `peer_user_id`：`int > 0`，且不能与 `sender_user_id` 相同
+- `client_msg_id`：`string`，长度 `1-64`
+- `content_type`：`1=text 2=audio 3=image 4=json`
+- `content_text`：`content_type=1` 时必填
+- `content_json`：`content_type=4` 时必填
+- `media_file_key`：`content_type=2` 或 `3` 时必填
+- `media_duration_ms`：媒体时长（可选，毫秒）
+
+成功响应（首次入库，`201`）：
+
+```json
+{
+  "idempotent": false,
+  "message": {
+    "id": 1006,
+    "conversation_id": 1,
+    "seq": 6,
+    "sender_user_id": 1,
+    "role": 1,
+    "content_type": 1,
+    "content_text": "hello",
+    "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"
+  }
+}
+```
+
+成功响应（幂等命中，`200`）：
+
+```json
+{
+  "idempotent": true,
+  "message": {
+    "id": 1006,
+    "conversation_id": 1,
+    "seq": 6,
+    "sender_user_id": 1,
+    "role": 1,
+    "content_type": 1,
+    "content_text": "hello",
+    "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"
+  }
+}
+```
+
+常见错误码：
+
+- `404`：发送人或接收人不存在/不可用
+- `409`：会话不是激活状态
+- `422`：请求参数校验失败
+
+## 3. 查询消息
+
+### `GET /messages`
+
+用途：
+
+- 按会话分页读取消息。
+- 返回结果按 `seq` 正序排列。
+
+Query 参数：
+
+- `conversation_id`（必填）：`int > 0`
+- `cursor_seq`（可选）：`int >= 1`，用于向前翻页
+- `limit`（可选）：默认 `20`，最大 `100`
+
+请求示例：
+
+```
+GET /messages?conversation_id=1&limit=20
+GET /messages?conversation_id=1&cursor_seq=50&limit=20
+```
+
+响应示例：
+
+```json
+{
+  "conversation_id": 1,
+  "has_more": false,
+  "next_cursor_seq": null,
+  "items": [
+    {
+      "id": 1001,
+      "conversation_id": 1,
+      "seq": 1,
+      "sender_user_id": 1,
+      "role": 1,
+      "content_type": 1,
+      "content_text": "Hi, did you finish homework?",
+      "content_json": {
+        "lang": "en"
+      },
+      "media_file_key": null,
+      "media_duration_ms": null,
+      "client_msg_id": "c1-m1",
+      "created_at": "2026-03-25T10:00:05"
+    }
+  ]
+}
+```
+
+常见错误码：
+
+- `404`：会话不存在
+- `422`：请求参数校验失败