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

191 lines
8.9 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 | 仅指定用户 |