mirror of
https://github.com/hongguang1994/SimNexus.git
synced 2026-11-22 04:36:58 +08:00
- 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>
191 lines
8.9 KiB
Markdown
191 lines
8.9 KiB
Markdown
# SimNexus 参考手册
|
||
|
||
项目结构、页面路由、REST/WebSocket 接口、权限与通知模型的详细说明。功能介绍与部署见根目录 [README.md](../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 | 仅指定用户 |
|