提案

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

@@ -0,0 +1,31 @@
+## 1. DTO 定义
+
+- [x] 1.1 在 `internal/model/dto/` 新增设备开放接口请求/响应 DTO：`AgentOpenAPIDeviceQueryRequest`（含 `device_no` 字段）、`AgentOpenAPIDeviceSwitchCardRequest`（含 `device_no`、`iccid` 字段）、`AgentOpenAPIDeviceOperationRequest`（含 `device_no` 字段，用于 reboot/reset）、`AgentOpenAPIDeviceTrafficResponse`（结构与 `AgentOpenAPICardTrafficResponse` 一致，`card_no` 换成 `device_no`）
+
+## 2. Service 层
+
+- [x] 2.1 在 `agent_open_api.Service` 结构体中新增 `deviceService *device.Service` 字段，更新 `New()` 构造函数签名，在 `internal/bootstrap/services.go` 的 `agentOpenAPISvc.New(...)` 调用处传入 `s.Device`
+- [x] 2.2 在 `agent_open_api` service 中新增私有方法 `resolveOpenAPIDevice(ctx, deviceNo)`：调用 `deviceService.GetDeviceByIdentifier`，校验 `device.ShopID IN SubordinateShopIDs`，不存在或无权限统一返回 `CodeForbidden`
+- [x] 2.3 实现 `GetDeviceTraffic(ctx, req)`：调用 `resolveOpenAPIDevice` 获取设备，通过 `packageUsageStore.ListByCarrier(ctx, "device", device.ID, &activeStatus)` 和 `ListByCarrier(ctx, "device", device.ID, &pendingStatus)` 查询套餐，复用 `loadUsagePackageContext` 和 `buildTrafficItem`，组装 `AgentOpenAPIDeviceTrafficResponse`
+- [x] 2.4 实现 `SwitchDeviceCard(ctx, req)`：调用 `resolveOpenAPIDevice` 校验权限，再调用 `deviceService.GatewaySwitchCard(ctx, req.DeviceNo, &dto.SwitchCardRequest{ICCID: req.ICCID})`
+- [x] 2.5 实现 `RebootDevice(ctx, req)`：调用 `resolveOpenAPIDevice` 校验权限，再调用 `deviceService.GatewayRebootDevice(ctx, req.DeviceNo)`
+- [x] 2.6 实现 `ResetDevice(ctx, req)`：调用 `resolveOpenAPIDevice` 校验权限，再调用 `deviceService.GatewayResetDevice(ctx, req.DeviceNo)`
+
+## 3. Handler 层
+
+- [x] 3.1 在 `internal/handler/openapi/handler.go` 新增 `GetDeviceTraffic` Handler 方法（GET，QueryParser 解析 `AgentOpenAPIDeviceQueryRequest`）
+- [x] 3.2 新增 `SwitchDeviceCard` Handler 方法（POST，BodyParser 解析 `AgentOpenAPIDeviceSwitchCardRequest`）
+- [x] 3.3 新增 `RebootDevice` Handler 方法（POST，BodyParser 解析 `AgentOpenAPIDeviceOperationRequest`）
+- [x] 3.4 新增 `ResetDevice` Handler 方法（POST，BodyParser 解析 `AgentOpenAPIDeviceOperationRequest`）
+
+## 4. 路由注册
+
+- [x] 4.1 在 `internal/routes/open.go` 的 `RegisterOpenAPIRoutes` 中注册 4 条新路由：`GET /devices/traffic`、`POST /devices/switch-card`、`POST /devices/reboot`、`POST /devices/reset`，补充 Summary、Description（含 authDescription）、Input/Output、Tags、Auth、SecurityScheme
+
+## 5. 文档生成器更新
+
+- [x] 5.1 在 `cmd/api/docs.go` 和 `cmd/gendocs/main.go` 的 `bootstrap.Handlers{}` 初始化中，将 `AgentOpenAPI` 字段更新为 `openapiHandler.NewHandler(nil, nil)`（或对应的空值初始化），确保新增的 4 个 Handler 方法被文档生成器扫描到
+
+## 6. 编译验证
+
+- [x] 6.1 运行 `go build ./...` 确认无编译错误