七月迭代短暂完结,还有很多后端的关键东西没有弄,这是一版赶时间做的东西

docs/iot-card-speed-tier/功能总结.md

@@ -0,0 +1,55 @@
+# IoT 卡固定档位限速功能总结
+
+## 功能边界
+
+本功能只允许后台账号为有权限的 IoT 卡设置 Gateway 固定限速档位。限速对象始终是请求路径中的卡 ICCID：设备没有限速接口，系统也不会查询设备当前绑定卡后间接限速。
+
+接口：
+
+```text
+PUT /api/admin/iot-cards/:iccid/speed-tier
+```
+
+请求体：
+
+```json
+{
+  "code": 3
+}
+```
+
+## 固定档位
+
+| code | 含义 |
+| ---: | --- |
+| -1 | 恢复不限速 |
+| 0 | 0kbps |
+| 1 | 128Kbps |
+| 2 | 512Kbps |
+| 3 | 1Mbps |
+| 4 | 2Mbps |
+| 5 | 10Mbps |
+| 6 | 20Mbps |
+| 7 | 50Mbps |
+| 8 | 100Mbps |
+
+前端只能提交上述固定档位，不允许输入任意速率。`-1` 与 `0` 是不同操作，不能混用。
+
+## 权限与调用链
+
+- 仅超级管理员、平台账号和代理后台账号可调用。
+- 通过现有 `IotCardStore.GetByICCID` 查询卡并应用当前数据权限；不存在和无权限统一返回“无权限操作该资源或资源不存在”。
+- 外呼 Gateway 使用 `/flow-card/speedLimit`，请求业务参数只有 `cardNo` 和 `code`，其中 `cardNo` 必须是已校验的卡 ICCID。
+- 不根据套餐流量、运营商或设备绑定关系自动计算或转换档位。
+
+## 审计与结果未知
+
+每次实际外呼前先创建 `pending` Integration Log，记录卡、档位、操作者和请求关联标识；外呼完成后终结为 `success`、`failed` 或 `unknown`。资产操作审计使用 `card_speed_tier` 动作编码记录操作者、卡、档位及结果。
+
+Gateway 请求超时时，外部是否已生效无法确定。接口返回可识别的结果未知错误，Integration Log 保存人工恢复策略：通过 Gateway 运维侧按 ICCID 核对当前档位后，再决定是否重试。系统不会盲目声称成功，也不会自动重复提交。
+
+## 联调与回滚
+
+联调需覆盖全部固定档位、越权卡、Gateway 明确失败和请求超时，并确认设备详情和设备 API 中不存在限速入口。
+
+回滚时可隐藏前端入口并回退应用版本；已经产生的资产操作审计和 Integration Log 不得删除或清空。由于本功能不保存本地“当前限速档位”，不涉及数据库状态回滚。