修改 Bootstrap 注入 Gateway Client 依赖到 IotCardHandler 和 DeviceHandler

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

@@ -0,0 +1,81 @@
+# 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