09. 完整路由索引¶
说明：
Auth列含义
Public：无需登录JWT：需要Authorization: Bearer ...JWT+Approved：需要登录且账号审核通过JWT/Discovery：普通 access token 或设备短期发现凭证Admin：管理员Admin/Owner：管理员或群主
1. 认证/公开¶
| Method | Path | Auth | 说明 |
|---|---|---|---|
| POST | /api/auth/login | Public | 账号密码登录 |
| POST | /api/auth/logout | Public | 登出并清 Cookie |
| POST | /api/auth/refresh | Public | 刷新 access token |
| POST | /api/auth/register | Public | 注册 |
| POST | /api/auth/ws-token/clear | Public | 清理 ws_token |
| POST | /api/auth/email-login | Public | 邮箱验证码登录 |
| POST | /api/auth/send-code | Public | 发送邮箱验证码 |
| POST | /api/auth/verify-email | Public | 注册邮箱验证码校验 |
| POST | /api/auth/reset-password | Public | 邮箱重置密码 |
| POST | /api/auth/switch-login/:id | Admin | 直接切换为目标用户登录 |
| GET | /api/captcha | Public | 获取图片验证码 |
| GET | /api/platform/info | Public | 平台信息 |
| GET | /api/platform/totalstats | Public | 平台统计 |
| GET | /api/config/public | Public | 公开站点配置 |
| GET | /healthz | Public | 进程存活检查，返回 status=ok |
| GET | /api/public/relays | Public | 公开中继查询 |
| GET | /api/public/firmware/latest | Public | 查询指定型号最新固件 |
| GET | /api/public/client-resources/manifest | Public | 查询兼容的客户端资源清单 |
| GET | /api/public/client-resources/artifacts/:artifact_id/download | Public | 为仍可发现的资源文件签发短时下载地址 |
2. SSO¶
| Method | Path | Auth | 说明 |
|---|---|---|---|
| GET | /api/sso/login | Public | 获取 SSO 登录 URL |
| GET | /api/sso/callback | Public | SSO 回调 |
| POST | /api/sso/exchange | Public | 一次性交换码换 token |
| GET | /api/sso/status | JWT | 当前用户 SSO 绑定状态 |
| POST | /api/sso/bind | JWT | 发起 SSO 绑定 |
| DELETE | /api/sso/unbind | JWT | 解绑 SSO |
3. 用户资料¶
| Method | Path | Auth | 说明 |
|---|---|---|---|
| POST | /api/auth/ws-token/sync | JWT | 同步 ws_token Cookie |
| GET | /api/me | JWT | 当前用户信息 |
| PUT | /api/me | JWT | 更新个人资料 |
| PUT | /api/me/password | JWT | 修改自己密码 |
| PUT | /api/me/email | JWT | 修改邮箱 |
| PUT | /api/users/:id/password | JWT | 管理员或本人改密码 |
| GET | /api/users/:id/public | JWT | 按 ID 获取用户公开信息 |
| GET | /api/users/name/:username/public | JWT | 按用户名获取用户公开信息 |
| GET | /api/users | Admin | 管理员分页查询用户 |
| PUT | /api/users/:id | Admin | 管理员更新用户资料/角色/状态 |
| DELETE | /api/users/:id | Admin | 删除用户及其级联数据 |
| PUT | /api/users/:id/status | Admin | 更新用户启用状态 |
| GET | /api/users/:id | Admin | 管理员查看用户详情 |
| GET | /api/admin/users/:id/device-password | Admin | 按需读取用户设备准入密码（no-store） |
4. 设备动态码绑定¶
| Method | Path | Auth | 说明 |
|---|---|---|---|
| POST | /api/device/pre-check | Public | 设备预检查 |
| POST | /api/device/request-code | Public | 请求动态码 |
| POST | /api/device/confirm-bind | Public | 轮询绑定状态 |
| POST | /api/device/bind | JWT | Web 端绑定设备 |
| POST | /api/device/submit-config | JWT | 提交绑定配置 |
| POST | /api/device/access-points/token | Public | 使用设备密码签发短期入口发现凭证 |
| GET | /api/access-points | JWT/Discovery | 获取当前主节点设备入口列表；多入口待后续扩展 |
| GET | /api/user/device-password | JWT | 获取设备准入密码 |
| PUT | /api/user/device-password | JWT | 修改设备准入密码 |
| POST | /api/user/device-password/regenerate | JWT | 重新生成设备准入密码 |
5. 设备管理¶
| Method | Path | Auth | 说明 |
|---|---|---|---|
| GET | /api/devices | JWT+Approved | 设备列表 |
| GET | /api/devices/list | JWT+Approved | 兼容旧路径（同上） |
| GET | /api/device/get | JWT+Approved | 设备详情（query id） |
| GET | /api/device/qth | JWT+Approved | 兼容路径（同 device/get） |
| GET | /api/device/qths | JWT+Approved | 设备位置列表 |
| GET | /api/user/device-default-group | JWT+Approved | 获取新普通设备默认群组 |
| PUT | /api/user/device-default-group | JWT+Approved | 设置或清空新普通设备默认群组 |
| PUT | /api/devices/:id | JWT+Approved | 更新设备（含设备级禁发/禁收） |
| DELETE | /api/devices/:id | JWT+Approved | 删除设备 |
| POST | /api/device/changegroup | JWT+Approved | 切换设备群组 |
| PUT | /api/devices/:id/group | JWT+Approved | 切换设备群组（REST 风格） |
| GET | /api/devices/:id/config | JWT+Approved | 读取设备配置 |
| PUT | /api/devices/:id/config | JWT+Approved | 保存设备配置 |
| POST | /api/devices/:id/config/sync | JWT+Approved | 下发设备配置 |
6. 群组¶
| Method | Path | Auth | 说明 |
|---|---|---|---|
| GET | /api/groups | JWT+Approved | 群组列表 |
| GET | /api/group/list | JWT+Approved | 兼容路径 |
| GET | /api/groups/:id | JWT+Approved | 群组详情 |
| GET | /api/groups/:id/devices | JWT+Approved | 群组设备列表 |
| GET | /api/groups/:id/messages | JWT+Approved | 按群组 ACL 获取频道消息历史 |
| GET | /api/groups/:id/messages/:message_id | JWT+Approved | 获取一条频道消息及授权音频地址 |
| POST | /api/groups | JWT+Approved | 创建群组 |
| POST | /api/group/create | JWT+Approved | 兼容路径 |
| POST | /api/groups/search | JWT+Approved | 搜索群组 |
| POST | /api/groups/:id/join | JWT+Approved | 加入私有群组 |
| GET | /api/groups/:id/members | JWT+Approved | 群组成员 |
| POST | /api/groups/:id/leave | JWT+Approved | 退出群组 |
| PUT | /api/groups/:id | Admin/Owner | 更新群组 |
| DELETE | /api/groups/:id | Admin/Owner | 删除群组 |
| DELETE | /api/groups/:id/members/:userId | Admin/Owner | 移除私有群组成员并立即撤销其收发与历史权限 |
| POST | /api/group/update | Admin/Owner | 兼容路径（不建议） |
| POST | /api/group/delete | Admin/Owner | 兼容路径（不建议） |
| DELETE | /api/groups/:id/devices/:deviceId | Admin/Owner | 踢出设备 |
| PUT | /api/groups/:id/devices/:deviceId/comm-control | Admin/Owner | 调整当前组内设备的设备级收发状态 |
| GET | /api/groups/:id/broadcast-context | Admin/Owner | 自动播报互联策略与当前允许状态 |
| GET | /api/groups/:id/broadcast-audios | Admin/Owner | 自动播报音频库 |
| POST | /api/groups/:id/broadcast-audios | Admin/Owner | 上传自动播报音频（multipart） |
| GET | /api/groups/:id/broadcast-audios/:audioId | Admin/Owner | 音频详情和短时试听地址 |
| DELETE | /api/groups/:id/broadcast-audios/:audioId | Admin/Owner | 删除未被计划引用的音频 |
| GET | /api/groups/:id/broadcast-schedules | Admin/Owner | 自动播报计划列表 |
| POST | /api/groups/:id/broadcast-schedules | Admin/Owner | 创建播报计划 |
| PATCH | /api/groups/:id/broadcast-schedules/:scheduleId | Admin/Owner | 更新播报计划 |
| DELETE | /api/groups/:id/broadcast-schedules/:scheduleId | Admin/Owner | 删除播报计划 |
| POST | /api/groups/:id/broadcast-schedules/:scheduleId/run | Admin/Owner | 手动触发一次播报 |
| GET | /api/groups/:id/broadcast-runs | Admin/Owner | 播报执行历史 |
| POST | /api/groups/:id/broadcast-runs/:runId/cancel | Admin/Owner | 停止已认领或播放中的播报 |
7. 虚拟互联组¶
| Method | Path | Auth | 说明 |
|---|---|---|---|
| POST | /api/group-links | Admin | 创建虚拟互联组 |
| GET | /api/group-links | Admin | 互联组列表 |
| GET | /api/group-links/available-targets | Admin | 可关联目标群组 |
| GET | /api/group-links/:id | Admin | 互联组详情 |
| PUT | /api/group-links/:id | Admin | 更新互联组 |
| DELETE | /api/group-links/:id | Admin | 删除互联组 |
| GET | /api/group-links/:id/targets | Admin | 查询关联目标 |
| POST | /api/group-links/:id/targets | Admin | 增加关联目标 |
| DELETE | /api/group-links/:id/targets/:targetId | Admin | 移除关联目标 |
| PUT | /api/group-links/:id/broadcast-policy | Admin | 更新互联期间的自动播报策略 |
8. 在线收发（Radio）¶
| Method | Path | Auth | 说明 |
|---|---|---|---|
| GET | /api/radio/config | JWT+Approved | 在线收发配置 |
| GET | /api/radio/status | JWT+Approved | 幽灵设备状态 |
| GET | /api/radio/sessions | JWT+Approved | 当前账号的幽灵在线 Session 列表 |
| PUT | /api/radio/sessions/:session_id/routing | JWT+Approved | 原子更新指定 Session 的单发/多收路由 |
| DELETE | /api/radio/sessions/:session_id | JWT+Approved | 精确断开当前账号的指定 Session |
| GET | /api/radio/groups/stats | JWT+Approved | 群组实时统计 |
| GET | /api/radio/groups/:id/devices | JWT+Approved | 群组在线设备 |
| GET | /api/admin/radio/sessions | Admin | 全部在线幽灵 Session 摘要 |
| DELETE | /api/admin/radio/sessions/:session_id | Admin | 精确断开任意一个幽灵 Session |
9. 上传与审批¶
| Method | Path | Auth | 说明 |
|---|---|---|---|
| POST | /api/upload/file | JWT | 通用文件上传 |
| POST | /api/upload/operator-certificate | JWT | 上传操作证 |
| GET | /api/operator-certificate | JWT | 查询本人操作证 |
| GET | /api/approvals/pending | Admin | 用户审批列表 |
| PUT | /api/approvals/:id/approve | Admin | 用户审批 |
| GET | /api/certificate-approvals | Admin | 操作证审批列表 |
| PUT | /api/operator-certificates/:id/approve | Admin | 操作证审批 |
| POST | /api/upload/logo | Admin | 上传站点 Logo |
| DELETE | /api/config/logo | Admin | 删除 Logo 配置 |
| POST | /api/upload/favicon | Admin | 上传 Favicon |
| DELETE | /api/config/favicon | Admin | 删除 Favicon 配置 |
| POST | /api/storage/presign-put | JWT/Admin 按类型 | 申请用户绑定的直传上传凭证 |
| PUT | /api/storage/put | Token | local 驱动直传写入 |
| GET | /files/*key | Public | local 驱动文件访问 |
10. 通联日志与通信记录¶
| Method | Path | Auth | 说明 |
|---|---|---|---|
| GET | /api/logbooks | JWT | 我的通联日志列表 |
| GET | /api/logbooks/:id | JWT | 我的通联日志详情 |
| POST | /api/logbooks | JWT | 创建通联日志 |
| PUT | /api/logbooks/:id | JWT | 更新通联日志 |
| DELETE | /api/logbooks/:id | JWT | 删除通联日志 |
| DELETE | /api/logbooks/batch | JWT | 批量删除通联日志 |
| GET | /api/admin/logbooks | Admin | 管理员日志列表 |
| GET | /api/admin/logbooks/:id | Admin | 管理员日志详情 |
| PUT | /api/admin/logbooks/:id | Admin | 管理员更新日志 |
| DELETE | /api/admin/logbooks/:id | Admin | 管理员删除日志 |
| DELETE | /api/admin/logbooks/batch | Admin | 管理员批量删除 |
| GET | /api/comm-records | JWT | 通信记录列表 |
| GET | /api/comm-records/user-stats | JWT | 当前用户通信统计 |
| GET | /api/comm-records/user-trend | JWT | 当前用户通信趋势 |
| GET | /api/comm-records/:id | JWT | 通信记录详情 |
| DELETE | /api/comm-records/:id | Admin | 删除通信记录 |
| GET | /api/comm-records/stats | Admin | 录制器统计 |
| GET | /api/comm-records/system-stats | Admin | 系统通信统计 |
| GET | /api/comm-records/system-trend | Admin | 系统通信趋势 |
11. 预设¶
| Method | Path | Auth | 说明 |
|---|---|---|---|
| GET | /api/user/radio-presets | JWT | 获取预设 |
| POST | /api/user/radio-presets | JWT | 创建预设 |
| PUT | /api/user/radio-presets/:id | JWT | 更新预设 |
| DELETE | /api/user/radio-presets/:id | JWT | 删除预设 |
| PUT | /api/user/radio-presets/reorder | JWT | 重排预设 |
12. 中继台/服务器/日志/缓存/配置¶
| Method | Path | Auth | 说明 |
|---|---|---|---|
| GET | /api/relays | Admin | 中继台列表 |
| GET | /api/relay/list | Admin | 兼容路径 |
| POST | /api/relay/create | Admin | 创建中继台 |
| POST | /api/relay/update | Admin | 更新中继台 |
| POST | /api/relay/delete | Admin | 删除中继台 |
| GET | /api/servers | Admin | 服务器列表 |
| GET | /api/server/list | Admin | 兼容路径 |
| POST | /api/server/create | Admin | 创建服务器 |
| POST | /api/server/update | Admin | 更新服务器 |
| POST | /api/server/delete | Admin | 删除服务器 |
| GET | /api/admin/groups | Admin | 管理员全量群组列表 |
| GET | /api/edge-nodes | Admin | 边缘节点及运行指标列表 |
| POST | /api/edge-nodes | Admin | 创建边缘节点并签发一次性注册凭据 |
| PUT | /api/edge-nodes/:id | Admin | 更新边缘节点和公开入口配置 |
| DELETE | /api/edge-nodes/:id | Admin | 删除边缘节点、断开会话并使凭据失效 |
| POST | /api/edge-nodes/:id/rotate-credential | Admin | 轮换节点长期凭据 |
| POST | /api/edge-nodes/:id/revoke-credential | Admin | 吊销节点全部凭据并断开连接 |
| POST | /api/edge-nodes/:id/disconnect | Admin | 重置节点连接但保留凭据 |
| GET | /api/firmware | Admin | 固件列表 |
| POST | /api/firmware | Admin | 上传固件（multipart） |
| POST | /api/firmware/complete | Admin | 固件直传落库 |
| DELETE | /api/firmware/:id | Admin | 删除固件 |
| GET | /api/client-resources | Admin | 客户端资源定义列表 |
| POST | /api/client-resources | Admin | 创建客户端资源定义 |
| GET | /api/client-resources/:resource_id | Admin | 客户端资源详情 |
| PATCH | /api/client-resources/:resource_id | Admin | 修改或停用客户端资源 |
| DELETE | /api/client-resources/:resource_id | Admin | 级联删除客户端资源、全部版本和对象文件 |
| GET | /api/client-resources/:resource_id/releases | Admin | 资源版本列表 |
| POST | /api/client-resources/:resource_id/releases | Admin | 创建资源版本草稿 |
| GET | /api/client-resources/:resource_id/releases/:release_id | Admin | 资源版本详情 |
| POST | /api/client-resources/:resource_id/releases/:release_id/artifacts/complete | Admin | 完成资源文件直传或追加到已发布版本 |
| POST | /api/client-resources/:resource_id/releases/:release_id/publish | Admin | 发布资源版本 |
| DELETE | /api/client-resources/:resource_id/releases/:release_id | Admin | 删除资源版本及关联对象 |
| GET | /api/client-resources/staging | Admin | 当前管理员待完成资源上传 |
| POST | /api/client-resources/staging/retry | Admin | 为待完成上传重新签发完成凭证 |
| GET | /api/storage/audit | Admin | 只读对象引用审计 |
| GET | /api/admin/devices/:id/config | Admin | 任意设备配置读取 |
| PUT | /api/admin/devices/:id/config | Admin | 任意设备配置更新 |
| POST | /api/admin/devices/:id/config/sync | Admin | 任意设备配置下发 |
| GET | /api/operatorlog/list | Admin | 操作日志列表 |
| GET | /api/operatorlog/stats | Admin | 操作日志统计 |
| GET | /api/config/comm-settings | Admin | 通信设置读取 |
| PUT | /api/config/comm-settings | Admin | 通信设置更新 |
| GET | /api/cache/metrics | Admin | 缓存指标 |
| POST | /api/cache/metrics/reset | Admin | 重置缓存指标 |
| GET | /api/udp/metrics | Admin | UDP 转发性能指标 |
| GET | /api/broadcast/metrics | Admin | 自动播报持久化、调度器和媒体指标 |
| GET | /api/broadcast/health | Admin | 自动播报调度器与媒体健康状态 |
| PUT | /api/broadcast/runtime | Admin | 开关站点自动播报运行态 |
| POST | /api/broadcast/emergency-stop | Admin | 紧急停止当前全部自动播报 |
| POST | /api/cache/clear | Admin | 清空缓存 |
| GET | /api/config/category/:category | JWT | 分类配置读取 |
| GET | /api/config/access-discovery | Admin | 接入点发现配置读取 |
| PUT | /api/config/access-discovery | Admin | 更新接入点发现配置 |
| GET | /api/config/registration | Admin | 注册配置读取 |
| PUT | /api/config/registration | Admin | 更新注册配置 |
| PUT | /api/config | Admin | 通用配置更新 |
| PUT | /api/config/icp | Admin | ICP 配置更新 |
| PUT | /api/config/system | Admin | 系统配置更新 |
| PUT | /api/config/aprs | Admin | APRS 配置更新 |
| GET | /api/config/all | Admin | 全部配置 |
| GET | /api/config/system | Admin | 系统配置读取 |
| GET | /api/config/aprs | Admin | APRS 配置读取 |
| GET | /api/config/aprs/logs | Admin | APRS 最近日志 |
| GET | /api/config/smtp | Admin | SMTP 配置读取 |
| PUT | /api/config/smtp | Admin | SMTP 配置更新 |
13. 资源中心¶
| Method | Path | Auth | 说明 |
|---|---|---|---|
| GET | /api/assets | Admin | 资源列表（parent_id） |
| POST | /api/assets/folder | Admin | 创建文件夹 |
| POST | /api/assets/upload | Admin | 上传文件（multipart） |
| POST | /api/assets/complete | Admin | 资源直传落库 |
| PUT | /api/assets/:id | Admin | 更新资源 |
| PUT | /api/assets/:id/move | Admin | 移动资源 |
| POST | /api/assets/:id/replace | Admin | 覆盖文件 |
| DELETE | /api/assets/:id | Admin | 删除资源 |
| GET | /api/assets/tree | Public | 目录树 |
| GET | /api/assets/folder/:id | Public | 文件夹内容 |
| GET | /api/assets/:id/download | Public | 下载链接 |
| GET | /api/storage/get | Token | local 驱动受控下载；只接受短期签名参数 |
14. WebSocket¶
| Method | Path | Auth | 说明 |
|---|---|---|---|
| GET | /ws | Cookie(ws_token) | WebSocket 实时通联 |