SimNexus 参考手册
项目结构、页面路由、REST/WebSocket 接口、权限与通知模型的详细说明。功能介绍与部署见根目录 README.md。
后端为 Go(gin + gorm),所有 REST 接口前缀 /api/v1,WebSocket 前缀 /ws(无 /api/v1)。
项目结构
页面路由
| 路径 |
页面 |
访问要求 |
/login |
登录(含图形验证码) |
公开 |
/ |
设备总览 Dashboard |
登录 |
/sim-cards |
SIM 卡管理 |
can_view_sim |
/resources |
资源库(所有卡 + 访问状态) |
can_view_sim |
/modems/:id |
单卡详情(含 VoWiFi / 飞行模式) |
can_view_sim |
/history |
消息中心(iMessage 风格收发 + 稍后发送) |
登录 |
/contacts |
通讯录(每用户私有) |
登录 |
/admin/tasks |
任务监控 / 我的任务记录 |
非只读(管理员看全部) |
/admin/sim-requests |
SIM 申请审批 |
can_approve_requests |
/support |
用户咨询管理 |
管理员 / can_support |
/users |
用户管理 |
管理员 |
/roles |
角色管理 |
管理员 |
/admin/telegram |
Telegram 管理 |
管理员 |
/admin/logs |
系统日志(分类标签页 + WebSocket) |
管理员 |
已下线页面:独立「定时任务」页(定时改由消息中心「稍后发送」创建)、「短信模板」页。
REST 接口(前缀 /api/v1)
认证
| 方法 |
路径 |
说明 |
| GET |
/auth/captcha |
获取 SVG 验证码(token + svg) |
| POST |
/auth/login |
登录(传 captcha_token + captcha_code) |
| GET |
/auth/me |
当前用户信息(含 RBAC 角色) |
用户 / 角色(管理员)
| 方法 |
路径 |
说明 |
| GET/POST |
/users/ |
列表 / 创建 |
| PATCH/DELETE |
/users/:id |
修改 / 删除 |
| POST |
/users/:id/reset-password |
重置密码 |
| POST |
/users/me/change-password |
修改自己的密码 |
| GET/POST |
/roles/ |
列表 / 创建 |
| PATCH/DELETE |
/roles/:id |
修改 / 删除(系统角色不可删) |
| PUT |
/roles/users/:id/roles |
设置用户的角色列表 |
设备
| 方法 |
路径 |
说明 |
| GET |
/modems/available |
资源库:所有设备 + 访问状态 |
| GET |
/modems/ |
当前用户有权限的设备 |
| GET |
/modems/:id /modems/:id/detail |
基本信息 / 详情(信号、流量、VoWiFi 运行态) |
| PATCH |
/modems/:id |
修改别名 |
| PATCH |
/modems/:id/vowifi |
切换 VoWiFi 模式(管理员) |
| PATCH |
/modems/:id/airplane |
切换飞行模式(管理员) |
| POST |
/modems/:id/refresh |
立即刷新 |
短信与定时任务
| 方法 |
路径 |
说明 |
| POST |
/sms/send |
立即发送 |
| GET |
/sms/messages |
收发记录(需查看历史权限) |
| DELETE |
/sms/messages/:id · POST /sms/messages/batch-delete |
删除 / 批量删除 |
| GET/POST |
/sms/tasks |
定时任务列表 / 创建(消息中心「稍后发送」即调此) |
| PATCH/DELETE |
/sms/tasks/:id |
修改 / 删除 |
| POST |
/sms/tasks/:id/run-now |
立即执行一次 |
| GET |
/sms/admin/tasks · /sms/admin/tasks/stats · /sms/admin/tasks/:id/history |
管理员:全部任务 / 统计 / 历史 |
| GET/POST/DELETE |
/sms/templates /sms/templates/:id |
模板接口(保留,前端页已下线) |
通讯录(每用户私有)
| 方法 |
路径 |
说明 |
| GET/POST |
/contacts/ |
列表 / 新建 |
| PATCH/DELETE |
/contacts/:id |
修改 / 删除 |
SIM 申请审批
| 方法 |
路径 |
说明 |
| POST |
/sim-requests/ |
申请访问某卡 |
| GET |
/sim-requests/my · /sim-requests/my-grants |
我的申请 / 我的授权 |
| GET |
/sim-requests/ |
审批员:待审列表 |
| PUT |
/sim-requests/:id/approve · /:id/reject |
通过 / 拒绝 |
| POST |
/sim-requests/batch-approve · /grant |
批量通过 / 直接授权 |
| DELETE |
/sim-requests/grants/:id |
撤销授权 |
通知 / 用户咨询 / Telegram
| 方法 |
路径 |
说明 |
| GET |
/notifications · /notifications/unread-count |
列表 / 未读数 |
| POST |
/notifications/read-all · /notifications/:id/read |
全部已读 / 单条已读 |
| POST/GET |
/support/messages |
发送 / 拉取咨询消息 |
| POST |
/support/upload · /support/messages/read |
上传附件 / 标记已读 |
| GET |
/support/unread · /support/conversations |
未读数 / 会话列表(客服) |
| GET |
/support/files/:filename |
附件下载(公开,UUID 名) |
| GET/POST |
/telegram/messages · /telegram/send · /telegram/send-file |
消息列表 / 发文字 / 发文件(管理员) |
| DELETE/GET |
/telegram/messages · /telegram/config |
清空 / Bot 状态(管理员) |
| GET |
/telegram/file/*file_id |
代理下载(JWT 经 ?token=) |
其它
| 方法 |
路径 |
说明 |
| GET |
/dashboard/stats |
仪表盘统计 |
| GET |
/admin/logs/stream |
日志 SSE 流(管理员,WebSocket 见下) |
WebSocket(前缀 /ws,JWT 经 ?token= 传入)
| 端点 |
用途 |
/ws/modems |
每 5 秒推送所有设备状态 |
/ws/messages |
短信收发(MT/MO)实时推送给消息中心 |
/ws/support |
客服会话消息实时推送 |
/ws/telegram |
Telegram 消息实时推送给管理端 |
/ws/logs |
后端各类日志实时推送给日志页(管理员);分类:http/vowifi/poller/scheduler/telegram/system |
权限模型
- 管理员(
role=admin)始终拥有全部权限。
- 普通用户的有效权限由其所有 RBAC 角色合并:
- 功能权限(
can_view_sim / can_approve_requests / can_manage_tasks / can_view_history / can_support):任一角色开启即生效
- 只读(
read_only):所有角色均只读才生效
- 设备范围(
allowed_modem_ids):任一角色无限制则无限制,否则取受限角色的设备 ID 并集
- 审批员对其管理范围内的卡自动拥有 use 级访问,无需申请。
通知受众
| audience |
可见对象 |
admin |
仅系统管理员 |
support |
管理员 + 拥有 can_support 的角色 |
all |
所有已登录用户 |
user + target_user_id |
仅指定用户 |