- 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>
12 KiB
数据库表结构与关系文档
总览
SimNexus 使用 SQLite,分为若干功能域:
| 功能域 | 表 |
|---|---|
| 用户与权限 | users、roles、user_roles |
| 设备管理 | modems、sim_access_requests、sim_grants |
| 短信与任务 | sms_messages、sms_scheduled_tasks、sms_templates |
| 通讯录 | contacts |
| 通知与客服 | notifications、support_messages |
| Telegram 集成 | telegram_messages |
建表 SQL 以
schema.sql为准(后端启动时 gorm AutoMigrate + ensureColumns 亦会补齐新表/新列)。modems表含 VoWiFi 相关列:vowifi_mode、vowifi_epdg_ip、vowifi_at_port、vowifi_airplane(飞行模式,与 VoWiFi 解耦)。contacts为每个用户私有通讯录(按owner_id隔离)。
一、用户与权限域
users — 用户
| 字段 | 类型 | 说明 |
|---|---|---|
| id | INTEGER PK | 主键 |
| username | VARCHAR(50) UNIQUE | 登录名 |
| password_hash | VARCHAR(200) | bcrypt 哈希(不使用 passlib) |
| role | ENUM | 系统级角色:admin | user |
| is_active | BOOLEAN | 账号是否启用 |
| created_at / updated_at | DATETIME | 时间戳 |
role=admin的用户拥有全部权限,不受 RBAC 角色限制。
roles — RBAC 角色
| 字段 | 类型 | 说明 |
|---|---|---|
| id | INTEGER PK | 主键 |
| name | VARCHAR(64) UNIQUE | 角色名 |
| description | TEXT | 描述 |
| is_system | BOOLEAN | 系统预置角色,不可删除 |
| can_view_sim | BOOLEAN | 可查看 SIM 卡 |
| can_send_sms | BOOLEAN | 可发送短信 |
| can_manage_tasks | BOOLEAN | 可管理定时任务 |
| can_view_history | BOOLEAN | 可查看短信记录 |
| read_only | BOOLEAN | 只读模式(禁止写操作) |
| can_support | BOOLEAN | 可回复用户咨询 |
| allowed_modem_ids | JSON | 可访问的设备 ID 列表,null 表示不限制 |
| created_at / updated_at | DATETIME | 时间戳 |
系统预置 5 个角色:全功能用户、只读用户、短信操作员、任务管理员、客服。
user_roles — 用户角色关联(多对多)
| 字段 | 类型 | 说明 |
|---|---|---|
| user_id | INTEGER FK → users.id | 联合主键,CASCADE 删除 |
| role_id | INTEGER FK → roles.id | 联合主键,CASCADE 删除 |
一个用户可分配多个角色,权限取所有角色的并集:
- 功能权限:任一角色开启即生效(
any()) - 只读模式:所有角色均为只读才生效(
all()) - 设备范围:任一角色无限制则全部可访问;否则取各角色 ID 的并集
user_permissions — 旧版独立权限(兜底)
| 字段 | 类型 | 说明 |
|---|---|---|
| id | INTEGER PK | 主键 |
| user_id | INTEGER FK → users.id UNIQUE | 一对一 |
| can_view_sim | BOOLEAN | 同 roles 字段含义 |
| can_send_sms | BOOLEAN | |
| can_manage_tasks | BOOLEAN | |
| can_view_history | BOOLEAN | |
| read_only | BOOLEAN | |
| allowed_modem_ids | JSON |
使用时机:仅当用户未分配任何 RBAC 角色时,回落到此表的设置。新用户推荐使用 RBAC 角色管理权限。
二、设备管理域
modems — 调制解调器
| 字段 | 类型 | 说明 |
|---|---|---|
| id | INTEGER PK | 主键 |
| mm_object_path | VARCHAR(200) UNIQUE | ModemManager D-Bus 路径,唯一业务键 |
| device_path | VARCHAR(100) | 如 /dev/ttyUSB0 |
| imei | VARCHAR(20) UNIQUE | 设备 IMEI |
| manufacturer / model | VARCHAR | 厂商/型号 |
| phone_number | VARCHAR(30) | SIM 卡号码 |
| operator | VARCHAR(100) | 运营商 |
| signal_quality | INTEGER | 信号强度 0-100 |
| status | ENUM | connected | disconnected | error | unknown |
| alias | VARCHAR(100) | 用户自定义别名 |
| is_active | BOOLEAN | 是否当前在线 |
| last_seen | DATETIME | 最后一次轮询发现时间 |
| access_technologies | VARCHAR(100) | 网络制式,如 lte、umts |
| registration_state | VARCHAR(50) | 注册状态,如 home、roaming |
| tx_bytes / rx_bytes | INTEGER | 发送/接收流量(字节) |
| connection_duration | INTEGER | 连接时长(秒) |
| created_at | DATETIME | 首次发现时间 |
mm_object_path是唯一业务标识,不要用imei或device_path做唯一键(两者可能缺失或变化)。
三、短信与任务域
sms_messages — 短信记录
| 字段 | 类型 | 说明 |
|---|---|---|
| id | INTEGER PK | 主键 |
| modem_id | INTEGER FK → modems.id | 所属设备 |
| created_by_id | INTEGER FK → users.id | 发送者(可为空,收件无发送者) |
| scheduled_task_id | INTEGER FK → sms_scheduled_tasks.id | 来源定时任务(可为空) |
| direction | ENUM | inbound(收件)| outbound(发件) |
| phone_number | VARCHAR(30) | 对端号码 |
| content | TEXT | 短信内容 |
| status | ENUM | pending | sent | failed | received |
| error_message | TEXT | 失败原因 |
| mm_sms_index | VARCHAR(20) | mmcli SMS 对象索引,收件去重用 |
| sent_at / received_at | DATETIME | 发送/接收时间 |
| created_at | DATETIME | 入库时间 |
收件去重:以 (modem_id, mm_sms_index, direction=inbound) 联合去重,避免轮询重复入库。
sms_scheduled_tasks — 定时任务
| 字段 | 类型 | 说明 |
|---|---|---|
| id | INTEGER PK | 主键 |
| modem_id | INTEGER FK → modems.id | 使用的设备 |
| created_by_id | INTEGER FK → users.id | 创建者 |
| name | VARCHAR(100) | 任务名称 |
| recipients | JSON | 收件号码列表,如 ["+8613800138000"] |
| content | TEXT | 短信内容 |
| cron_expression | VARCHAR(100) | Cron 表达式(循环任务),如 0 9 * * * |
| send_once_at | DATETIME | 单次发送时间(与 cron 二选一) |
| status | ENUM | active | paused | completed | failed |
| run_count | INTEGER | 累计执行次数 |
| last_run_at / next_run_at | DATETIME | 上次/下次执行时间 |
| created_at / updated_at | DATETIME | 时间戳 |
sms_templates — 短信模板(独立)
| 字段 | 类型 | 说明 |
|---|---|---|
| id | INTEGER PK | 主键 |
| name | VARCHAR(100) | 模板名称 |
| content | TEXT | 模板内容 |
| variables | JSON | 变量名列表,如 ["name", "code"] |
| created_at / updated_at | DATETIME | 时间戳 |
此表无外键,独立存在,不与任务或消息关联。
四、通知与客服域
notifications — 系统通知
| 字段 | 类型 | 说明 |
|---|---|---|
| id | INTEGER PK | 主键 |
| type | VARCHAR(32) | 通知类型,如 modem_online、sms_failed |
| title | VARCHAR(128) | 标题 |
| body | TEXT | 正文 |
| is_read | BOOLEAN | 已读状态 |
| audience | VARCHAR(16) | 可见范围(见下表) |
| target_user_id | INTEGER | 软引用 users.id,audience=user 时使用 |
| created_at | DATETIME | 创建时间 |
audience 路由规则:
| audience 值 | 可见用户 |
|---|---|
admin |
仅 role=admin 的管理员 |
support |
管理员 + 拥有 can_support=true 角色的用户 |
all |
所有已登录用户 |
user |
仅 id = target_user_id 的用户 |
target_user_id是软引用,无数据库外键约束,用户被删除后通知仍保留。
support_messages — 用户咨询消息
| 字段 | 类型 | 说明 |
|---|---|---|
| id | INTEGER PK | 主键 |
| user_id | INTEGER FK → users.id | 咨询会话所属用户(永远是普通用户) |
| sender_id | INTEGER FK → users.id | 实际发送者(用户本人或客服/管理员) |
| content | TEXT | 消息内容 |
| is_from_user | BOOLEAN | true = 用户发,false = 客服发 |
| is_read | BOOLEAN | 已读状态 |
| attachment_url | TEXT | 附件路径(UUID 命名文件) |
| attachment_name | TEXT | 原始文件名 |
| attachment_type | TEXT | image | file |
| created_at | DATETIME | 发送时间 |
user_id标识"这条消息属于哪个会话(用户)",sender_id标识"谁发的"。客服回复时user_id是用户 ID,sender_id是客服 ID。
五、Telegram 集成域
telegram_messages — Telegram 消息记录
| 字段 | 类型 | 说明 |
|---|---|---|
| id | INTEGER PK | 主键 |
| chat_id | VARCHAR(64) | Telegram chat/group ID |
| username | VARCHAR(128) | 发送者用户名(收件时填写,发件为 SimNexus) |
| direction | VARCHAR(8) | in = bot 收到 | out = bot 发出 |
| text | TEXT | 消息文本;媒体消息存说明文字或文件名 |
| is_command | BOOLEAN | 是否为 bot 命令(/send、/list、/modems、/help) |
| file_id | VARCHAR(256) | Telegram 文件 ID,通过 /api/telegram/file/<id> 代理 |
| file_type | VARCHAR(32) | photo | document | video | sticker | voice |
| created_at | DATETIME | 入库时间 |
此表无外键,独立存在。文件通过 Telegram Bot API 代理访问,前端携带 JWT token(
?token=)请求/api/telegram/file/<file_id>。
Bot 命令说明:
| 命令 | 功能 |
|---|---|
/modems |
列出所有在线设备 |
/list [#id] |
查看最近 10 条收到的短信,可按设备过滤 |
/send <号码> <内容> |
通过单卡或自动选择设备发送短信 |
/send #<设备ID> <号码> <内容> |
指定设备发送短信 |
/help |
显示帮助信息 |
外键关系汇总
users ──────────────────────────────────────────────┐
│ (M:N via user_roles) │
├──► roles │
│ └──► role_modem_scope (M:N via modems) │
│ │
│ created_by_id (可选) │
├──► sms_messages │
│ │
│ created_by_id (可选) │
├──► sms_scheduled_tasks │
│ │
│ user_id / sender_id │
├──► support_messages │
│ │
│ user_id │
└──► sim_access_requests │
│
modems │
├──► sms_messages (modem_id) │
├──► sms_scheduled_tasks (modem_id) │
├──► sim_access_requests (modem_id) │
└──► role_modem_scope (modem_id) │
│
sms_scheduled_tasks │
└──► sms_messages (scheduled_task_id, 可选) │
│
notifications │
└── target_user_id → users.id (软引用,无 FK) ┘
sms_templates (独立,无外键)
telegram_messages(独立,无外键)
权限解析优先级
1. user.role == admin → 全部权限(跳过后续步骤)
2. user.rbac_roles 不为空 → 合并所有角色权限
正向权限(can_*):any() — 任一角色开启即生效
read_only:all() — 所有角色均只读才生效
设备范围:union(role_modem_scope) — 取并集;任一角色无 scope 则无限制
3. user.rbac_roles 为空 → 无权限
SIM 卡访问控制流程
用户申请 (sim_access_requests, status=pending)
↓ 审批员审批
approved → granted_level: view | use
↓
get_user_modem_grants() 查询有效授权
↑
审批员自动拥有其 role_modem_scope 内所有卡的使用权(无需申请)