30 lines
1.6 KiB
Markdown
30 lines
1.6 KiB
Markdown
## 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 代理管辖店铺`，与现有卡权限逻辑一致
|