3.8 KiB
open-api-device-operations Specification
ADDED Requirements
Requirement: 设备切网开放接口
系统 SHALL 提供 POST /api/open/v1/devices/switch-card 接口，允许代理对多卡设备执行切网操作（切换到指定 ICCID）。请求 body MUST 包含 device_no（虚拟号或 IMEI）和 iccid（目标卡 ICCID）。
系统 MUST 校验该设备的 shop_id 在当前代理管辖店铺范围内，否则返回 CodeForbidden。权限校验通过后，系统 MUST 复用 device.Service.GatewaySwitchCard 执行切网，底层调用 Gateway 接口。
响应 data MUST 为空对象（操作成功即可）。
Scenario: 切网成功
- WHEN 代理对管辖范围内的多卡设备传入有效目标 ICCID 执行切网
- THEN 系统调用 Gateway 切换设备到目标 ICCID，返回成功
Scenario: 无权限设备切网
- WHEN 代理对不在自己管辖店铺范围内的设备执行切网
- THEN 系统返回
CodeForbidden，不调用 Gateway
Scenario: 设备标识符不存在
- WHEN 代理传入的
device_no无法解析为任何设备 - THEN 系统返回
CodeForbidden，消息为"无权限操作该资源或资源不存在"
Requirement: 设备重启开放接口
系统 SHALL 提供 POST /api/open/v1/devices/reboot 接口，允许代理对设备执行重启操作。请求 body MUST 包含 device_no（虚拟号或 IMEI）。
系统 MUST 校验该设备的 shop_id 在当前代理管辖店铺范围内，否则返回 CodeForbidden。权限校验通过后，系统 MUST 复用 device.Service.GatewayRebootDevice 执行重启。
响应 data MUST 为空对象。
Scenario: 重启成功
- WHEN 代理对管辖范围内的设备执行重启
- THEN 系统调用 Gateway 重启设备，返回成功
Scenario: 无权限设备重启
- WHEN 代理对不在自己管辖店铺范围内的设备执行重启
- THEN 系统返回
CodeForbidden，不调用 Gateway
Requirement: 设备恢复出厂开放接口
系统 SHALL 提供 POST /api/open/v1/devices/reset 接口，允许代理对设备执行恢复出厂设置操作。请求 body MUST 包含 device_no（虚拟号或 IMEI）。
系统 MUST 校验该设备的 shop_id 在当前代理管辖店铺范围内，否则返回 CodeForbidden。权限校验通过后，系统 MUST 复用 device.Service.GatewayResetDevice 执行恢复出厂。
响应 data MUST 为空对象。
Scenario: 恢复出厂成功
- WHEN 代理对管辖范围内的设备执行恢复出厂
- THEN 系统调用 Gateway 恢复设备出厂设置，返回成功
Scenario: 无权限设备恢复出厂
- WHEN 代理对不在自己管辖店铺范围内的设备执行恢复出厂
- THEN 系统返回
CodeForbidden，不调用 Gateway
Requirement: 设备操作开放接口权限校验
系统 SHALL 对所有设备操作开放接口（switch-card、reboot、reset）统一执行权限校验。校验逻辑 MUST 为：通过设备标识符（虚拟号或 IMEI）查询设备，若设备不存在或 device.ShopID 不在当前代理的 SubordinateShopIDs 中，则返回 CodeForbidden，消息为"无权限操作该资源或资源不存在"，不区分"不存在"与"无权限"以防止信息泄露。
Scenario: 设备属于代理管辖店铺
- WHEN 设备的
shop_id在代理的SubordinateShopIDs中 - THEN 系统允许执行操作
Scenario: 设备不属于代理管辖店铺
- WHEN 设备的
shop_id不在代理的SubordinateShopIDs中 - THEN 系统返回
CodeForbidden，消息为"无权限操作该资源或资源不存在"
Scenario: 设备 shop_id 为 NULL（平台库存）
- WHEN 设备的
shop_id为 NULL（平台库存设备） - THEN 系统返回
CodeForbidden，代理无权操作平台库存设备