提案

openspec/changes/add-open-api-device-endpoints/proposal.md

@@ -0,0 +1,29 @@
+## 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 代理管辖店铺`，与现有卡权限逻辑一致