docs(api): 后端全部API超详细调用文档(api-reference.md)

Docs/api-client.md

@@ -1,5 +1,7 @@
 # Cyrene v2 客户端 API 文档（用户侧）
 
+> **完整版见 `Docs/api-reference.md`**（后端全部 API（REST + WebSocket）超详细调用文档，字段/鉴权/状态码以代码为准）。本文档为**摘要**，契约如有出入以 `api-reference.md` 为准。
+
 > **面向**: Web 前端 / 移动端原生客户端 / IM 桥接等**跨平台客户端开发者**。
 > **维护铁律**: 每实现/变更一个 API（REST 端点、WS 事件、admin API）**立即更新本文件**；契约变更必须版本化，不破坏既有客户端。
 > **状态**: gateway 已在 M8 落地核心端点；M9 前端按此开发。**`✅` = 已实现**，`🕐` = 规划。
@@ -19,7 +21,7 @@
 
 | # | 端点 | 方法 | 认证 | 状态 | 说明 |
 |---|------|------|------|:---:|------|
-| 1 | `/api/v1/auth/login` | POST | 否 | ✅ | `{username,password}` → `{data:{token,jwt}}`（24h，owner） |
+| 1 | `/api/v1/auth/login` | POST | 否 | ✅ | `{username,password}` → `{data:{token,expiresAt,role}}`（24h，role=owner） |
 | 2 | `/api/v1/health` | GET | 否 | ✅ | 健康检查 `{data:{status:"ok"}}` |
 | 3 | `/api/v1/chat` | POST | JWT | ✅ | `{text,image?,deviceId?,stream?}` → `{data:{reply}}`；`stream:true` 时经 WS 触发流式。`image` 为 base64 data: URI 或 http(s) URL，入视觉路由（design/06）——**真视觉需配 `LLM_VISION_MODEL`/凭据，无凭据时降级为主模型直接看图或视觉·OCR 工具文本描述**；`deviceId` 为**客户端生成的具体端标识**（design/16 §4.5，如 `web:chrome:a1b2c3`，可选），落库到消息、便于主人知道从哪个端发来。**会话编排（design/15）**：非流式且该会话「正忙」时**不阻塞**，返回 `202` `{data:{queued:true,queueDepth}}`（稍后按上下文续接）；待处理队列满时返回 `409` `{error:{code:"chat_busy"}}` |
 | 4 | `/api/v1/sessions` | GET | JWT | ✅ | `{data:[session...]}`。**会话持久化（design/16）**：注入 HistoryStore 后返回持久化会话元数据 `{data:[{id,type("main"|"sub"),title?,createdAt}]}`（主会话 `id="web"` 恒在首位，次级 `web:<uuid>`）；未注入时退化回渠道会话列表 |