huang
80f560df33
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 6m17s
- 合并 customer_account 和 shop_account 路由到统一的 account 接口 - 新增统一认证接口 (auth handler) - 实现越权防护中间件和权限检查工具函数 - 新增操作审计日志模型和服务 - 更新数据库迁移 (版本 39: account_operation_log 表) - 补充集成测试覆盖权限检查和审计日志场景
94 lines
3.1 KiB
Markdown
94 lines
3.1 KiB
Markdown
# 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 依赖 |
|
||
|
||
## 开放问题
|
||
|
||
无
|