junhong_cmp_fiber/.sisyphus/notepads/add-gateway-admin-api/context.md

Context & Architecture Understanding

Key Findings

Gateway Client Already Initialized

• ✅ internal/gateway/client.go - Complete Gateway client implementation
• ✅ internal/bootstrap/dependencies.go - GatewayClient is a field in Dependencies struct
• ✅ internal/gateway/flow_card.go - 6+ card-related Gateway methods
• ✅ internal/gateway/device.go - 7+ device-related Gateway methods

Current Handler Structure

• internal/handler/admin/iot_card.go - Has 4 existing methods (ListStandalone, GetByICCID, AllocateCards, RecallCards)
• internal/handler/admin/device.go - Has 5 existing methods (List, GetByID, GetByIMEI, Delete, ListCards)
• Both handlers receive only service, not Gateway client yet

Service Layer Already Uses Gateway

• internal/service/iot_card/service.go - Already has gateway.Client dependency
• internal/service/device/service.go - Needs to be checked if it has gateway.Client

Handler Constructor Pattern

// Current pattern
func NewIotCardHandler(service *iotCardService.Service) *IotCardHandler
func NewDeviceHandler(service *deviceService.Service) *DeviceHandler

// New pattern (needed)
func NewIotCardHandler(service *iotCardService.Service, gatewayClient *gateway.Client) *IotCardHandler
func NewDeviceHandler(service *deviceService.Service, gatewayClient *gateway.Client) *DeviceHandler

Bootstrap Injection Pattern

// In initHandlers() function at internal/bootstrap/handlers.go
IotCard: admin.NewIotCardHandler(svc.IotCard),
Device:  admin.NewDeviceHandler(svc.Device),

// Needs to be changed to:
IotCard: admin.NewIotCardHandler(svc.IotCard, deps.GatewayClient),
Device:  admin.NewDeviceHandler(svc.Device, deps.GatewayClient),

Route Registration Pattern

// From internal/routes/iot_card.go
Register(iotCards, doc, groupPath, "GET", "/standalone", handler.ListStandalone, RouteSpec{
    Summary: "单卡列表（未绑定设备）",
    Tags:    []string{"IoT卡管理"},
    Input:   new(dto.ListStandaloneIotCardRequest),
    Output:  new(dto.ListStandaloneIotCardResponse),
    Auth:    true,
})

Gateway Method Mappings

Card Methods (flow_card.go)

• QueryCardStatus(ctx, req) → CardStatusResp
• QueryFlow(ctx, req) → FlowUsageResp
• QueryRealnameStatus(ctx, req) → RealnameStatusResp
• GetRealnameLink(ctx, req) → string (link)
• StopCard(ctx, req) → error
• StartCard(ctx, req) → error

Device Methods (device.go)

• GetDeviceInfo(ctx, req) → DeviceInfoResp
• GetSlotInfo(ctx, req) → SlotInfoResp
• SetSpeedLimit(ctx, req) → error
• SetWiFi(ctx, req) → error
• SwitchCard(ctx, req) → error
• RebootDevice(ctx, req) → error
• ResetDevice(ctx, req) → error

Store Methods for Permission Validation

• IotCardStore.GetByICCID(ctx, iccid) - Validate card ownership
• DeviceStore.GetByDeviceNo(ctx, imei) - Validate device ownership

Important Conventions

1. Permission errors return: errors.New(errors.CodeNotFound, "卡不存在或无权限访问")
2. All card params: ICCID from path param, CardNo = ICCID
3. All device params: IMEI from path param, DeviceID = IMEI
4. Handler methods follow: Get params → Validate permissions → Call Gateway → Format response