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

1. DTO 定义

• 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 层

• 2.1 在 agent_open_api.Service 结构体中新增 deviceService *device.Service 字段，更新 New() 构造函数签名，在 internal/bootstrap/services.go 的 agentOpenAPISvc.New(...) 调用处传入 s.Device
• 2.2 在 agent_open_api service 中新增私有方法 resolveOpenAPIDevice(ctx, deviceNo)：调用 deviceService.GetDeviceByIdentifier，校验 device.ShopID IN SubordinateShopIDs，不存在或无权限统一返回 CodeForbidden
• 2.3 实现 GetDeviceTraffic(ctx, req)：调用 resolveOpenAPIDevice 获取设备，通过 packageUsageStore.ListByCarrier(ctx, "device", device.ID, &activeStatus) 和 ListByCarrier(ctx, "device", device.ID, &pendingStatus) 查询套餐，复用 loadUsagePackageContext 和 buildTrafficItem，组装 AgentOpenAPIDeviceTrafficResponse
• 2.4 实现 SwitchDeviceCard(ctx, req)：调用 resolveOpenAPIDevice 校验权限，再调用 deviceService.GatewaySwitchCard(ctx, req.DeviceNo, &dto.SwitchCardRequest{ICCID: req.ICCID})
• 2.5 实现 RebootDevice(ctx, req)：调用 resolveOpenAPIDevice 校验权限，再调用 deviceService.GatewayRebootDevice(ctx, req.DeviceNo)
• 2.6 实现 ResetDevice(ctx, req)：调用 resolveOpenAPIDevice 校验权限，再调用 deviceService.GatewayResetDevice(ctx, req.DeviceNo)

3. Handler 层

• 3.1 在 internal/handler/openapi/handler.go 新增 GetDeviceTraffic Handler 方法（GET，QueryParser 解析 AgentOpenAPIDeviceQueryRequest）
• 3.2 新增 SwitchDeviceCard Handler 方法（POST，BodyParser 解析 AgentOpenAPIDeviceSwitchCardRequest）
• 3.3 新增 RebootDevice Handler 方法（POST，BodyParser 解析 AgentOpenAPIDeviceOperationRequest）
• 3.4 新增 ResetDevice Handler 方法（POST，BodyParser 解析 AgentOpenAPIDeviceOperationRequest）

4. 路由注册

• 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. 文档生成器更新

• 5.1 在 cmd/api/docs.go 和 cmd/gendocs/main.go 的 bootstrap.Handlers{} 初始化中，将 AgentOpenAPI 字段更新为 openapiHandler.NewHandler(nil, nil)（或对应的空值初始化），确保新增的 4 个 Handler 方法被文档生成器扫描到

6. 编译验证

• 6.1 运行 go build ./... 确认无编译错误