Files
lanhongguangandClaude Opus 4.8 602b355ff1 docs: 更新 README/schema,新增 reference.md,剔除过时内容
- README 精简:移除项目结构/页面说明/API/WebSocket 到专门文档;
  更新功能特性(通讯录/系统日志/稍后发送/飞行模式)、配置(Go 环境变量)、
  技术栈(Go/gin/gorm,非旧 Python/FastAPI)
- 新增 docs/reference.md:最新的项目结构、页面路由、REST(/api/v1)、
  WebSocket(/ws)、权限与通知模型
- schema.sql:补 modems.vowifi_airplane 列 + contacts 表
- database-schema.md:补通讯录与 VoWiFi 列说明

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-12 23:53:51 +08:00

8.9 KiB
Raw Permalink Blame History

SimNexus 参考手册

项目结构、页面路由、REST/WebSocket 接口、权限与通知模型的详细说明。功能介绍与部署见根目录 README.md。

后端为 Go(gin + gorm),所有 REST 接口前缀 /api/v1,WebSocket 前缀 /ws(无 /api/v1)。


项目结构

SimNexus/
├── backend-go/
│   ├── main.go                     # 入口:初始化日志缓冲、DB、后台服务、路由,监听 :8000
│   ├── config/                     # 环境变量配置加载
│   ├── database/                   # gorm 连接 + AutoMigrate + ensureColumns
│   ├── models/                     # 数据模型(user/role/modem/sms/contact/…)
│   ├── middleware/                 # 认证、CORS、HTTP 日志中间件
│   ├── security/                   # JWT、bcrypt、权限解析
│   ├── router/router.go            # 全部路由注册
│   ├── handlers/                   # HTTP 处理器(每个业务域一个文件)
│   ├── services/
│   │   ├── modem_manager.go        # mmcli 封装(标准 AT 命令设备)
│   │   ├── modem_poller.go         # 后台轮询设备状态(mmcli + ZTE),按 ICCID 识别
│   │   ├── sms_scheduler.go        # 定时任务引擎(cron / 单次)
│   │   ├── zte_http_modem.go       # ZTE 随身 WiFi goform HTTP 驱动
│   │   ├── vowifi_manager.go       # VoWiFi 每卡常驻会话 + 看门狗自愈
│   │   ├── vowifi_service.go       # VoWiFi 业务接入(含 ePDG 动态解析)
│   │   ├── logbuffer.go            # 日志环形缓冲 + slog Handler(供日志页)
│   │   └── vowifi/                 # 自建 VoWiFi 协议栈(IKEv2/EAP-AKA/IMS/ESP)
│   ├── cmd/epdgprobe/              # ePDG DNS 解析独立验证探针
│   └── Dockerfile
├── frontend/
│   ├── src/
│   │   ├── api/                    # Axios 客户端 + 各域接口(含 contacts.ts)
│   │   ├── components/Layout.tsx   # 主布局(侧边栏、顶栏、通知铃铛)
│   │   ├── hooks/useModemSocket.ts # 设备状态 WebSocket
│   │   ├── i18n/{zh,en}.ts         # 中英文案
│   │   ├── pages/                  # 页面(见「页面路由」)
│   │   └── store/                  # Zustand:auth / modem / lang / theme
│   ├── Dockerfile
│   └── nginx.conf                  # 静态托管 + /api、/ws 反代到 backend:8000
├── docs/                           # 本手册、数据库 schema、拓扑图
├── scripts/setup-debian.sh         # 本地开发系统依赖(ModemManager/udev/dialout)
├── deploy.sh                       # 一键部署
└── docker-compose.yml

页面路由

路径 页面 访问要求
/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

权限模型

系统角色(admin / user)
    ↓
RBAC 角色列表(可多个,取并集)
  • 管理员(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 仅指定用户