MiFaZhan
5.1 KiB
5.1 KiB
v1.0.4 权限修复上线说明
受保护的 V3 接口仅在资源已启用、API 账号已启用、账号已分配权限组且权限组绑定该资源时放行。未登记资源、资源停用、账号不可用、未绑定权限组一律拒绝，不降级放行。
错误码
| 码 | 含义 | 触发条件 | 排查方向 |
|---|---|---|---|
10014 |
没有权限 | 资源未登记、资源停用、账号停用/不存在、账号无权限组、权限组未绑定该资源 | 业务与授权配置问题：查 t_api_resource、t_api、t_api_group_resource |
10016 |
权限校验失败 | 权限数据查询本身出错（如 t_api_resource 查询失败） |
系统侧故障：查数据库连通性与表结构，不要按授权问题处理 |
两个码必须区分：数据库抖动时若复用 10014，运维会把系统故障误判成客户未授权。
上线前
- 执行资源登记脚本
iotlcm-database/SQL/20261016_openapi_resource_register.sql。共 24 条 V3 路由，扣除 2 条取 token 入口后为 22 条受保护路由：登记 15 条，另 7 条已决定下线（/common/*6 条 +/change/traffic-cutoff-config1 条）。脚本幂等可重复执行，且不改动既有status、api_code、method、path。 执行顺序：只读核对 → 登记（第 1 段）→ 计数校验应为 15 → 按实际授权范围绑定（第 3 段）。 - 检查正在使用接口的账号对应
t_api.group_id，以及t_api_group_resource绑定。按已确认的授权范围补齐，不能将所有资源自动赋给所有权限组——那是扩大授权，属于安全倒退。 - 资源登记使用完整请求路径与正确方法（
method=1即 POST）。查询与变更的traffic-cutoff-config路径前缀不同，分别登记。 - 在验证环境检查：已授权接口正常；未登记/未授权/停用资源拒绝返回
10014；账号停用或无权限组拒绝；权限数据查询失败返回10016。确认全部在用账号与接口后再部署生产。
免登录路径
/openapi/v3/query/token 与 /openapi/v3/query/operator-token 由配置 router.exceptLogin 控制，中间件内已无硬编码白名单。部署配置必须保留这两条，否则取 token 接口自身会被鉴权拦截而无法调用。
已确认 dev / preview / preview2 / prod 四套配置均含这两条。
重复路由的处置决定
代码中存在 12 条功能重叠的路由（/common 与 /change 各 6 条为同义路径）。判定分两层：先看对外文档是否发布过（发布过的必须保住），再看业务是否确认在用（业务确认不用的才硬删除）。
| 路径 | 决定 | 依据 |
|---|---|---|
/change/traffic-cutoff-config |
下线（不登记） | 从未写入对外文档（原始 common.md 只发布 4 个接口）；与 /change/batch-sim-traffic-cutoff 参数类型、实现完全相同，控制器代码逐行重复，客户迁移无需改报文体；尾路径与只读的 /query/traffic-cutoff-config 同名，最易误调 |
/common/*（6 条） |
已删除（代码级，返回 404） | 业务确认真实客户只走 /change/，从不使用 /common/；该前缀是新增 /change 分组时未删旧分组的遗留，从未作为对外接口发布（原始 common.md 只发布 4 个 /change 接口） |
/change/renew |
保留，登记授权，待观察 | 08-21 建立、09-10 才新增标准入口，存在早期接入客户；且入参只收 cards[]，与 batch-sim-subscribe（兼容平铺 iccid[]）不等价，不能直接判定为重复 |
/change/sim-subscribe、/change/sim-traffic-cutoff（单卡）与对应批量接口 |
保留 | 已对外文档化，且同步单卡与异步批次是两套实现，粒度不同，非重复 |
两种下线方式的差别：
/common/* |
/change/traffic-cutoff-config |
|
|---|---|---|
| 手段 | 删除 internal/router/common.go，router.go 不再调用 Common() |
不登记资源、不授权 |
| 客户端表现 | 404（路由不存在） |
10014（没有权限） |
| 恢复成本 | 需重新发版恢复路由，并补登记 6 条资源与授权 | 执行 SQL 文末的恢复语句即可，无需发版 |
| 选择理由 | 业务已确认无客户，该前缀无文档包袱，继续保留只会放大接口表面积与登记/授权工作量 | 参数与标准入口完全一致，但缺少「无人在用」的确认，需保住可逆性 |
/change/renew 上线后查调用日志，确认无调用再走「不登记」方式下线。
注意：g.Meta 的 deprecated 标签在 GoFrame v2.9.6 中不被解析，没有运行时或文档生成效果，不能作为废弃告知手段。对外废弃说明由 openapi-docs 承担。
回归验证
go test ./internal/logic/middleware -count=1
测试使用内存 SQLite，覆盖：数字/文本方法登记、路径规范化与末尾斜杠、未登记资源、方法不匹配、资源停用、缺失权限绑定、兼容入口独立授权（登记但未授权仍拒绝）、账号停用/无权限组/不存在、token 路径不在中间件白名单内，以及权限数据查询失败必须返回错误而非静默放行。