feat: 网关只读资产改为数据表,只读资产只允许查询类调用
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 9m36s

- 新增 tb_gateway_readonly_card(卡 ICCID / 设备 IMEI)与开关 JUNHONG_GATEWAY_READONLY_ENABLED,
  替换环境变量名单 JUNHONG_GATEWAY_READONLY_ICCIDS
- 只读资产只放行查卡状态、查实名、查流量、查设备信息、查设备槽位、同步设备状态;
  停机、复机、限速、实名认证链接与设备写操作在网关出口本地拦截;查表失败按拦截;不缓存
- 测试环境部署开启只读模式;新增技术方案与清理顺序文档

Change: add-gateway-readonly-prod-import

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
邹进
2026-10-29 17:55:52 +09:00
parent a7428c7924
commit 5cf67b98de
19 changed files with 536 additions and 41 deletions

View File

@@ -0,0 +1,57 @@
## ADDED Requirements
### Requirement: 网关只读资产表
系统 SHALL 提供网关只读资产表,每行保存一个网关请求卡号(卡为 ICCID,设备为 IMEI,统一大写)及其类型、来源、备注与写入时间,卡号唯一。表中的资产即"只读资产"。系统 MUST NOT 在迁移中写入只读资产数据;数据只由测试环境的导入脚本写入。
#### Scenario: 同一卡号重复写入
- **WHEN** 导入脚本对已存在的卡号再次写入
- **THEN** 只读表中该卡号仍只有一行
#### Scenario: 卡号大小写
- **WHEN** 网关请求卡号为小写,表中保存的是大写
- **THEN** 系统视为同一只读资产
### Requirement: 只读模式开关
系统 SHALL 通过环境变量 `JUNHONG_GATEWAY_READONLY_ENABLED` 控制只读模式:为 `true` 时按只读表限制网关调用;未配置或为 `false` 时 MUST NOT 查询只读表,所有网关调用行为与本变更前一致。系统 MUST NOT 再读取 `JUNHONG_GATEWAY_READONLY_ICCIDS`。API 与全部 Worker 进程 MUST 使用一致的取值。
#### Scenario: 生产未配置
- **WHEN** 环境未配置 `JUNHONG_GATEWAY_READONLY_ENABLED`
- **THEN** 网关调用不查只读表,停机、复机等照常发出
#### Scenario: 旧名单变量不再生效
- **WHEN** 环境只配置了 `JUNHONG_GATEWAY_READONLY_ICCIDS`,未开启只读模式
- **THEN** 系统不按该名单拦截任何调用
### Requirement: 只读资产只允许查询类调用
只读模式开启时,对只读资产系统 SHALL 只允许查询类网关调用:查卡状态(`/flow-card/status`)、查实名(`/flow-card/realName`)、查流量(`/flow-card/flow`)、查设备信息(`/device/info`)、查设备槽位(`/device/slot-info`)、同步设备状态(`/device/sync-info`),这些调用 MUST NOT 查只读表。其余网关调用(包括停机、复机、限速、实名认证链接,以及设备切卡、恢复出厂、重启、WiFi 配置、模式切换)在请求卡号命中只读表时,系统 MUST 在本地拦截、MUST NOT 向网关发送请求,并返回明确失败(不是结果未知),同时记录拦截日志。拦截 MUST 在网关客户端统一出口实现,覆盖自动停复机、人工停复机、套餐激活与到期、订单、退款、通道阈值、限速与设备操作等全部入口;业务流程 MUST NOT 为此改变。被拦截的停复机按现有失败处理记录与重试,本地卡状态不改变。
#### Scenario: 只读卡触发自动停机
- **WHEN** 只读卡在测试环境因无套餐或流量用完触发自动停机
- **THEN** 系统不向网关发送停机请求,记录停机失败与拦截日志,卡的本地网络状态不变
#### Scenario: 只读卡查流量
- **WHEN** 轮询对只读卡查询流量
- **THEN** 请求照常发往网关,不查只读表
#### Scenario: 只读设备重启
- **WHEN** 管理员对只读设备执行重启
- **THEN** 系统不向网关发送请求并返回失败
#### Scenario: 只读设备查实时状态
- **WHEN** 后台查看只读设备详情,读取设备信息与同步状态
- **THEN** 请求照常发往网关,不查只读表
#### Scenario: 非只读卡停机
- **WHEN** 只读模式开启,对不在只读表中的卡发起停机
- **THEN** 请求照常发往网关
### Requirement: 查表失败按拦截处理
只读模式开启时,非查询类网关调用在查询只读表失败(包括超时、连接错误与表不存在)时,系统 MUST 按拦截处理:不发送请求、返回明确失败并记录日志。系统 MUST NOT 缓存只读表;只读表写入后,下一次调用即按新数据判断。
#### Scenario: 只读表查询超时
- **WHEN** 只读模式开启,停机前查询只读表超时
- **THEN** 系统不发送停机请求并返回失败
#### Scenario: 新写入的只读卡立即生效
- **WHEN** 只读表刚写入某卡号,随即对该卡发起复机
- **THEN** 系统拦截该复机请求