# 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
```go
// 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
```go
// 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
```go
// 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