全部 API，一处查阅

01 · 快速接入

1. Base URL 为当前服务器根地址，不要重复拼接 /api。生产环境请配置 HTTPS。
2. 管理员调用 POST /api/admin/login；审核员调用 POST /api/reviewer/login；普通用户调用 POST /api/client/users/login。
3. 登录结果中的 data.token 用于对应身份的 Authorization: Bearer <TOKEN>，四类会话令牌不能混用。
4. 卡密授权流程：签名上报设备 → 管理员启用设备 → validate-card → 卡密 login → heartbeat。validate-card 会激活卡密并增加使用次数，不是纯查询。
5. 预设流程：注册/登录用户 → multipart 上传 → 审核员 preview / decision → published 与 publicVisible 均为 true 时公开可见。
6. JSON 响应须同时检查 HTTP 状态与 code === 0；data 允许 null。图片和 .mnd 下载返回二进制，不能调用 response.json()。

{"code":0,"message":"ok","data":null,"timestamp":1788609600000}

timestamp 是 Unix 毫秒；签名 X-Timestamp 是 Unix 秒。大部分日期字段为无时区偏移的服务器本地 ISO 字符串，不要假设 UTC。账号 accountId 是九位字符串，管理路径 id 通常为内部数字主键。

02 · 鉴权与签名

HMAC-SHA256 规范

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

METHOD 必须大写；requestURI 只包含路径，不含域名、查询字符串和请求体；末尾不添加换行。每次重试重新生成 nonce。服务端密钥由管理员单独安全分发，文档不包含真实密钥。

03 · WebSocket / STOMP 实时聊天

连接 ，使用 STOMP 1.2（不是 SockJS，也不是直接 JSON WebSocket）。连接后订阅 /topic/chat，收到 MESSAGE 后将 body 解析为 ChatItem。发送消息走 POST /api/client/chat/messages，服务器没有实现 /app 下的发送接口。

CONNECT
accept-version:1.2
host:当前主机
heart-beat:0,0

\0

# 收到 CONNECTED 后发送
SUBSCRIBE
id:chat-0
destination:/topic/chat
ack:auto

\0

上面的 \0 表示真实 NUL 字节。消息创建和置顶会广播；删除/清空消息当前不广播。断线重连后先订阅，再通过 after 游标补拉历史，按消息 id 去重；同一 id 的置顶事件要合并更新。

兼容/安全提示：当前后端 WebSocket 握手和订阅没有用户鉴权，Origin 允许 *；不要通过此通道发布私密内容。HTTP 聊天接口仍需要用户令牌。本次静态 WebUI 更新不改变该行为。

04 · 错误处理与现有边界

• 400：业务失败/参数不合法；普通用户会话过期也可能为400。401：管理员/审核员会话无效、客户端签名失败或权限拒绝。
• 404：路由不存在或头像不存在。部分缺少参数、错误方法、上传超限等旧异常可能被统一包装为500，不能假设全部是400/405/413。
• 多数列表无服务端分页；WebUI 是本地筛选与每页20条。聊天用户历史100条、增量最多200条；管理聊天最近300条。
• 头像业务上限200KB；预设业务上限2MB，但 Spring 默认单文件1MB限制可能先执行，建议上传控制在1MB以内。
• 公开下载计数、卡密验证、设备上报有副作用；写请求不要自动重试。头像缓存7天，更新后客户端可追加缓存版本参数。
• 旧 /api/overview、/api/dashboard 未做后台鉴权；新接入应使用受保护的 /api/admin/stats 系列。
• 授予社区角色的旧接口直接返回用户实体，可能包含密码哈希等敏感字段，禁止记录整个响应。建议后续独立改为脱敏 DTO。
• HTTP API 未配置通用 CORS：推荐同源或由自己的后端代理；不要把服务器签名密钥放入公开网页。
• 当前线上没有免打扰修改路由、用户退出路由或预设独立驳回状态，不要沿用其他分支的接口定义。