refactor(account): 统一账号管理API、完善权限检查和操作审计
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 6m17s

- 合并 customer_account 和 shop_account 路由到统一的 account 接口
- 新增统一认证接口 (auth handler)
- 实现越权防护中间件和权限检查工具函数
- 新增操作审计日志模型和服务
- 更新数据库迁移 (版本 39: account_operation_log 表)
- 补充集成测试覆盖权限检查和审计日志场景
This commit is contained in:
2026-02-02 17:23:20 +08:00
parent 5851cc6403
commit 80f560df33
58 changed files with 10743 additions and 4915 deletions

View File

@@ -0,0 +1,93 @@
# 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. 调用 GatewayICCID/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 依赖 |
## 开放问题