## Why 现有代理开放接口仅支持单卡维度的查询和操作,无法满足代理对设备维度的管理需求。代理需要通过开放接口查询设备套餐内流量、对多卡设备执行切网,以及对设备执行重启和恢复出厂操作。 ## What Changes - **新增** `GET /api/open/v1/devices/traffic` — 查询设备套餐内流量,返回结构与 `/cards/traffic` 一致 - **新增** `POST /api/open/v1/devices/switch-card` — 切网(多卡设备切换到指定 ICCID) - **新增** `POST /api/open/v1/devices/reboot` — 重启设备 - **新增** `POST /api/open/v1/devices/reset` — 恢复出厂设置 ## Capabilities ### New Capabilities - `open-api-device-traffic`: 代理开放接口设备套餐内流量查询,按设备标识符(虚拟号/IMEI)查询设备级 PackageUsage,返回生效/待生效套餐流量信息 - `open-api-device-operations`: 代理开放接口设备操作,包括切网(switch-card)、重启(reboot)、恢复出厂(reset),复用 device service 现有 Gateway 调用,增加代理权限校验 ### Modified Capabilities (无现有 spec 级别的需求变更) ## Impact - `internal/handler/openapi/handler.go` — 新增 4 个 Handler 方法 - `internal/routes/open.go` — 注册 4 条新路由 - `internal/service/agent_open_api/service.go` — 新增设备流量查询和设备操作业务逻辑,注入 device service 依赖 - `cmd/api/docs.go` 和 `cmd/gendocs/main.go` — 同步更新文档生成器 - 权限校验:`device.ShopID IN 代理管辖店铺`,与现有卡权限逻辑一致