Appearance
接口约定
以下路径相对后端服务根（直接启动为 /；经前端容器反代时，浏览器侧常见前缀 /oars）。
认证
| 操作 | 方法与路径 | 说明 |
|---|---|---|
| 登录 | POST /app/auth/login | 返回 accessToken、refreshToken |
| 刷新 | POST /app/auth/refresh | Body：{ "refreshToken": "..." } |
| 登出 | POST /app/auth/logout | Header 须带 Authorization: Bearer <accessToken>，服务端才会拉黑该令牌 |
| 当前用户 | GET /app/auth/user/info | 需已登录 |
业务请求统一带：
http
Authorization: Bearer <accessToken>成功响应 code 为 200，业务数据在 data。失败时 message 是给操作人看的话术：业务拒绝（如下线模板、未选处理人）会写明原因；系统故障只提示「请稍后重试」，不会返回 SQL 或堆栈。未登录或令牌无效返回 401；触发限流返回 HTTP 429，提示「请求过于频繁，请稍后再试」。限流按客户端 IP 计数，默认每秒 100 次，多节点共用阈值。列表分页每页最多 200 条。同一账号连续登录失败默认 5 次后锁定 15 分钟。
即时通讯 WebSocket 路径：/ws/im（同样相对后端根；经反代时与现场前缀一致）。
联调
- 接口文档：开发/测试环境为
/swagger-ui.html；生产环境默认关闭 - OpenAPI：
/v3/api-docs（同样仅非生产默认开启） - 健康检查：
/actuator/health（不返回组件详情）
文档页本身可打开；在文档里实际调用业务接口仍须带 Bearer。建议先登录取 token，再填入请求头。
生产部署要求：必须提供至少 32 字符的 JWT_SECRET；接口文档默认关闭。跨域时配置 oars.cors.allowed-origin-patterns，不要使用 *。细节见 部署。
权限
功能权限由角色菜单与按钮控制。当前登录用户从服务端会话读取，不要让前端传入的 userId 决定操作对象。列表数据还会叠加数据范围（本人 / 本部门等），有菜单不等于能看到全部行。