# 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 不得删除或清空。由于本功能不保存本地“当前限速档位”，不涉及数据库状态回滚。