设置 LTE Band（即将推出）
在设备、通信模块和固件明确支持的范围内设置首选 LTE Band，用于满足特定运营商网络或现场通信环境的配置需要。
能力预告
该接口尚未开放调用。设置 LTE Band 可能导致设备暂时离线；正式使用前应确认目标设备和所在网络支持所选 Band。
当前 Band 与首选 Band
这两个概念不会使用同一个字段：
| 字段 | 含义 | 获取方式 |
|---|---|---|
currentBand | 设备当前实际驻留的 LTE Band | 通过查询 LTE 网络信息读取 |
preferredBands | 通信模块允许优先选择的 LTE Band 集合 | 由本配置接口设置，并在设备确认成功后返回 |
通信模块使用 Band 集合表达网络偏好，而不是只保存一个固定 Band。因此，本接口计划接受数组，不提供容易产生歧义的单值 band 字段。
计划请求字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
preferredBands | integer[] | 是 | 非空且不重复的 LTE Band 编号列表；每个值都必须在目标设备支持范围内 |
正式发布前会根据设备类型定义确定可选 Band。文档不会提供一个适用于所有 A76XX 型号的固定列表，因为不同地区版本支持的频段并不相同。
计划成功响应
该操作将沿用异步命令模型，HTTP 接受请求后返回 202 Accepted 和 COMMAND_ACCEPTED。以下字段位于 data.command。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | string | 是 | 命令 ID，用于查询最终结果 |
deviceId | string | 是 | 目标设备 ID |
status | string | 是 | SENT、SUCCESS、FAILED 或 TIMEOUT |
params.preferredBands | integer[] | 是 | 本次请求的标准化 Band 集合 |
result.preferredBands | integer[] | 否 | 设备确认成功后返回的实际首选 Band 集合 |
createdAt | string | 是 | 命令创建时间，RFC3339 UTC |
只有设备确认配置成功时才返回 result.preferredBands。TIMEOUT 表示结果未确认，不表示设备一定没有应用配置；调用方应先重新读取网络信息或配置结果，再决定是否使用新的幂等键重试。
安全边界
- 只允许选择设备明确声明支持的 Band，不能使用其他 A76XX 型号的频段表代替目标设备能力。
- 只接受正式文档中列出的 Band 配置值。
- 同一设备同一时间只执行一个网络配置操作。
- 操作将使用幂等机制，避免客户端重复请求造成重复配置。
- 超时后不应盲目重试，应先确认设备当前连接状态和配置结果。
- 返回异步命令结果时，将沿用 OpenAPI 的命令状态模型。
能力判断
正式发布后，调用方应先通过设备能力信息确认目标设备是否支持 Band 配置。不同设备、地区、运营商、通信模块或固件可用的 Band 可能不同。
OpenAPI 不会假设所有 LTE 设备支持相同的 Band，也不会允许调用方绕过设备能力限制。
字段依据
SIMCom A76XX 将 LTE Band 偏好定义为可组合的频段集合，部分高编号频段使用扩展集合表示。OpenAPI 会把该能力转换为 preferredBands 数组，并在服务端完成设备型号校验和模块配置转换；调用方不需要处理厂商位掩码。
限流与重试
Band 切换属于设备配置操作，不使用普通只读查询的频率。正式规则将重点限制：
- 同一设备的并发操作
- 连续配置操作之间的间隔
- 命令执行期间的重复提交
具体限流数值和重试规则将在接口正式开放时公布。