# Draft: 新增 Gateway 后台管理接口

## 需求背景

Gateway 层已封装了 14 个第三方运营商/设备厂商的 API 能力（流量卡查询、停复机、设备控制等），但这些能力目前仅供内部服务调用，**后台管理员和代理商无法通过管理界面直接使用这些功能**。

## 确认的需求

### 卡 Gateway 接口（6个）

| 接口 | 说明 | Gateway 方法 |
|------|------|-------------|
| `GET /:iccid/gateway-status` | 查询卡实时状态 | `QueryCardStatus` |
| `GET /:iccid/gateway-flow` | 查询流量使用 | `QueryFlow` |
| `GET /:iccid/gateway-realname` | 查询实名状态 | `QueryRealnameStatus` |
| `GET /:iccid/realname-link` | 获取实名链接 | `GetRealnameLink` |
| `POST /:iccid/stop` | 停机 | `StopCard` |
| `POST /:iccid/start` | 复机 | `StartCard` |

### 设备 Gateway 接口（7个）

| 接口 | 说明 | Gateway 方法 |
|------|------|-------------|
| `GET /by-imei/:imei/gateway-info` | 查询设备信息 | `GetDeviceInfo` |
| `GET /by-imei/:imei/gateway-slots` | 查询卡槽信息 | `GetSlotInfo` |
| `PUT /by-imei/:imei/speed-limit` | 设置限速 | `SetSpeedLimit` |
| `PUT /by-imei/:imei/wifi` | 设置WiFi | `SetWiFi` |
| `POST /by-imei/:imei/switch-card` | 切换卡 | `SwitchCard` |
| `POST /by-imei/:imei/reboot` | 重启设备 | `RebootDevice` |
| `POST /by-imei/:imei/reset` | 恢复出厂 | `ResetDevice` |

## 技术决策

| 项目 | 决策 |
|------|------|
| **接口归属** | 集成到现有 iot-cards 和 devices 路径下 |
| **业务逻辑** | 简单透传，仅做权限校验 |
| **权限控制** | 平台 + 代理商（自动数据权限过滤） |
| **ICCID/CardNo** | 相同，直接透传 |
| **IMEI/DeviceID** | 相同，直接透传 |
| **权限验证** | 先查数据库确认归属，再调用 Gateway |

## 实现方案

### Handler 处理流程

```
1. 从 URL 获取 ICCID/IMEI
2. 查数据库验证归属权限（使用 UserContext 自动数据权限过滤）
   - 找不到 → 返回 404/403
3. 调用 Gateway（ICCID/IMEI 直接透传）
4. 返回结果
```

### 代码示例

```go
// 卡接口 - 带权限校验
func (h *IotCardHandler) GetGatewayStatus(c *fiber.Ctx) error {
    iccid := c.Params("iccid")
    ctx := c.UserContext()
    
    // 1. 验证权限
    _, err := h.iotCardStore.GetByICCID(ctx, iccid)
    if err != nil {
        return errors.New(errors.CodeNotFound, "卡不存在或无权限访问")
    }
    
    // 2. 调用 Gateway
    status, err := h.gatewayClient.QueryCardStatus(ctx, &gateway.CardStatusReq{
        CardNo: iccid,
    })
    if err != nil {
        return err
    }
    
    return response.Success(c, status)
}
```

## 代码影响

| 层级 | 文件 | 变更类型 |
|------|------|---------|
| Handler | `internal/handler/admin/iot_card.go` | 扩展：新增 6 个方法 |
| Handler | `internal/handler/admin/device.go` | 扩展：新增 7 个方法 |
| Routes | `internal/routes/iot_card.go` | 扩展：注册 6 个新路由 |
| Routes | `internal/routes/device.go` | 扩展：注册 7 个新路由 |
| Bootstrap | `internal/bootstrap/handlers.go` | 扩展：注入 Gateway Client 依赖 |

## 开放问题

无