# 喵喵助手 API 接入指南

接口目录以同目录 `openapi.json` 为准，当前覆盖 **86 个 HTTP 操作、74 个路径、1 个 WebSocket 通道**。WebUI `/api-docs.html` 提供全量字段表、搜索、cURL / JavaScript 示例与全量 Markdown 导出。

## 基本约定

- Base URL：服务器根地址，例如 `http://154.40.35.176`；生产环境推荐 HTTPS。
- JSON 成功：`{"code":0,"message":"ok","data":null,"timestamp":1788609600000}`。
- 同时判断 HTTP 状态与业务 code；data 可以是对象、数组或 null。
- timestamp 为 Unix 毫秒；X-Timestamp 为 Unix 秒。
- xxxAt 日期多为服务器本地 ISO 时间，不携带时区；不得默认 UTC。
- accountId 是九位字符串账号ID；管理路由 id 通常是数据库内部数字主键。
- 二进制接口（头像、MND下载）直接返回字节，不使用 JSON 外壳。

## 四类会话

|身份|登录地址|后续传递|
|---|---|---|
|管理员|POST /api/admin/login|Authorization: Bearer <ADMIN_TOKEN>|
|审核员|POST /api/reviewer/login|Authorization: Bearer <REVIEWER_TOKEN>，12小时|
|用户账号|POST /api/client/users/login|Authorization: Bearer <USER_TOKEN>，3天|
|卡密授权|POST /api/client/login|heartbeat 请求体 token；仍须客户端签名，默认24小时|

令牌不可混用。用户和审核员新登录会撤销旧会话。用户改密码当前不撤销会话；管理员重置用户密码会撤销会话。密码/令牌只通过安全渠道保存，不记录到日志。

## 客户端签名

须签名的接口见每个操作的 security：device-status、validate-card、卡密login、heartbeat、monitor、preset-api-status、runtime-config、sponsors。

```
raw = timestamp + "\n" + nonce + "\n" + METHOD + "\n" + requestURI
signature = lowercase_hex(HMAC_SHA256(UTF8(CLIENT_SECRET), UTF8(raw)))
```

- METHOD 大写；URI 仅路径，不含域名、查询串、请求体；末尾无换行。
- X-Timestamp 为当前秒，误差不超过300秒。
- X-Nonce 至少16字符，建议 UUID hex；重试必须生成新的nonce。
- X-Signature 为十六进制摘要。
- 密钥由管理员单独安全提供，不在文档或公开网页中发布。

Python（标准库）：

```python
import os, time, uuid, hmac, hashlib, json, urllib.request
base = os.environ['API_BASE_URL']
path = '/api/client/runtime-config'
method = 'GET'
ts = str(int(time.time()))
nonce = uuid.uuid4().hex
raw = '\n'.join([ts, nonce, method, path])
signature = hmac.new(os.environ['CLIENT_SECRET'].encode(), raw.encode(), hashlib.sha256).hexdigest()
req = urllib.request.Request(base + path, method=method, headers={
    'X-Timestamp': ts, 'X-Nonce': nonce, 'X-Signature': signature
})
with urllib.request.urlopen(req, timeout=20) as response:
    result = json.load(response)
    if result['code'] != 0:
        raise RuntimeError(result['message'])
    print(result['data'])
```

## 业务流程

1. 卡密：签名登记设备 → 管理员启用设备 → validate-card → 卡密 login → heartbeat。
   - validate-card 会增加使用次数、首次激活计算到期，不是只读查询。
   - login 不替代 validate-card 的次数/云端设备授权校验。
   - 云端关闭卡密验证时，login 返回 bypass=true、token为空；正常登录可能不包含 bypass。
2. 用户：multipart 注册 → 用户登录 → me / 修改个人资料 / 聊天 / 上传。
   - 注册不自动登录；username 2–20位文字/数字/_/-；密码6–64位。
   - 当前设备字段兼容接收但不绑定用户。
3. 预设：上传 .mnd → 审核预览 → 审核决定 → 公开列表/下载。
   - published 和 publicVisible 均为true才能公开；本人可查看自己的全部上传。
   - 管理/审核 preview 只返回解密字段，不导入、不应用、不增加下载次数。
   - 头像≤200KB；预设业务限制2MB，但默认Spring单文件1MB限制可能先执行，建议≤1MB。
   - multipart 由客户端库生成boundary，不手动写不带boundary的Content-Type。
4. 版本：GET version 返回最高已发布版本或null，不在服务端比较传入的versionCode；客户端自行按版本策略判断。

## WebSocket / STOMP

- ws://主机/ws/chat（HTTPS时使用wss）。原生WebSocket + STOMP 1.2，不是SockJS。
- CONNECT 后等待 CONNECTED，再订阅 `/topic/chat`，MESSAGE body 为 ChatItem JSON。
- STOMP帧以真实NUL字节结束。
- 无 /app 发送处理器；发送走HTTP POST /api/client/chat/messages。
- 消息创建/置顶广播；删除/清空不广播。
- 重连后先订阅，再以 after 游标补拉HTTP历史，按id去重，同id置顶事件合并更新。
- 现有握手/订阅未做用户鉴权，Origin允许*，不能当作私密通道。HTTP聊天仍需用户token。

## 错误、分页和兼容边界

- 400：业务/参数错误，普通用户令牌失效也可能为400。
- 401：后台/审核令牌、客户端签名或角色权限错误。
- 404：路由/头像不存在。缺参、错误方法、上传超限可能被旧异常处理器包装为500。
- 不对有副作用的请求自动重试；服务端未提供幂等键机制。
- 多数列表返回全量；WebUI为本地20条分页，不表示接口支持page/size。
- 用户聊天：初次最近100条，增量最多200条；管理聊天最近300条。
- 头像缓存7天；更新后可在URL附加版本参数绕过旧缓存。
- /api/overview、/api/dashboard 为未保护的旧兼容接口，新接入使用 /api/admin/stats 系列。
- 旧授予角色接口直接序列化UserAccount，可能返回passwordHash等敏感字段，不记录完整响应；建议后续单独改为脱敏DTO。
- HTTP未配置通用CORS；使用同源部署或可信后端代理。
- 当前无免打扰修改、普通用户退出、独立预设驳回状态接口，以线上规范为准。

## 导入第三方工具

下载 `/openapi.json`，导入 Apifox / Postman 等支持 OpenAPI 3.0 的工具；将相对服务器地址 `/` 改为自己的 Base URL，按接口身份单独设置认证。导入只创建接口定义，不应批量运行写操作。