diff --git a/cmd/api/main.go b/cmd/api/main.go index 93a3097..64c8906 100644 --- a/cmd/api/main.go +++ b/cmd/api/main.go @@ -346,6 +346,7 @@ func initGateway(cfg *config.Config, appLogger *zap.Logger) *gateway.Client { cfg.Gateway.BaseURL, cfg.Gateway.AppID, cfg.Gateway.AppSecret, + appLogger, ).WithTimeout(time.Duration(cfg.Gateway.Timeout) * time.Second) appLogger.Info("Gateway 客户端初始化成功", diff --git a/cmd/worker/main.go b/cmd/worker/main.go index c931c4b..0625091 100644 --- a/cmd/worker/main.go +++ b/cmd/worker/main.go @@ -249,6 +249,7 @@ func initGateway(cfg *config.Config, appLogger *zap.Logger) *gateway.Client { cfg.Gateway.BaseURL, cfg.Gateway.AppID, cfg.Gateway.AppSecret, + appLogger, ).WithTimeout(time.Duration(cfg.Gateway.Timeout) * time.Second) appLogger.Info("Gateway 客户端初始化成功", diff --git a/internal/bootstrap/handlers.go b/internal/bootstrap/handlers.go index b69f7de..994ae18 100644 --- a/internal/bootstrap/handlers.go +++ b/internal/bootstrap/handlers.go @@ -31,9 +31,9 @@ func initHandlers(svc *services, deps *Dependencies) *Handlers { EnterpriseDeviceH5: h5.NewEnterpriseDeviceHandler(svc.EnterpriseDevice), Authorization: admin.NewAuthorizationHandler(svc.Authorization), MyCommission: admin.NewMyCommissionHandler(svc.MyCommission), - IotCard: admin.NewIotCardHandler(svc.IotCard, deps.GatewayClient), + IotCard: admin.NewIotCardHandler(svc.IotCard), IotCardImport: admin.NewIotCardImportHandler(svc.IotCardImport), - Device: admin.NewDeviceHandler(svc.Device, deps.GatewayClient), + Device: admin.NewDeviceHandler(svc.Device), DeviceImport: admin.NewDeviceImportHandler(svc.DeviceImport), AssetAllocationRecord: admin.NewAssetAllocationRecordHandler(svc.AssetAllocationRecord), Storage: admin.NewStorageHandler(deps.StorageService), diff --git a/internal/bootstrap/services.go b/internal/bootstrap/services.go index 75287c2..779aa87 100644 --- a/internal/bootstrap/services.go +++ b/internal/bootstrap/services.go @@ -124,7 +124,7 @@ func initServices(s *stores, deps *Dependencies) *services { MyCommission: myCommissionSvc.New(deps.DB, s.Shop, s.AgentWallet, s.CommissionWithdrawalRequest, s.CommissionWithdrawalSetting, s.CommissionRecord, s.AgentWalletTransaction), IotCard: iotCard, IotCardImport: iotCardImportSvc.New(deps.DB, s.IotCardImportTask, deps.QueueClient), - Device: deviceSvc.New(deps.DB, s.Device, s.DeviceSimBinding, s.IotCard, s.Shop, s.AssetAllocationRecord, s.ShopPackageAllocation, s.ShopSeriesAllocation, s.PackageSeries), + Device: deviceSvc.New(deps.DB, s.Device, s.DeviceSimBinding, s.IotCard, s.Shop, s.AssetAllocationRecord, s.ShopPackageAllocation, s.ShopSeriesAllocation, s.PackageSeries, deps.GatewayClient), DeviceImport: deviceImportSvc.New(deps.DB, s.DeviceImportTask, deps.QueueClient), AssetAllocationRecord: assetAllocationRecordSvc.New(deps.DB, s.AssetAllocationRecord, s.Shop, s.Account), Carrier: carrierSvc.New(s.Carrier), diff --git a/internal/gateway/client.go b/internal/gateway/client.go index cb627a7..4b834c7 100644 --- a/internal/gateway/client.go +++ b/internal/gateway/client.go @@ -1,5 +1,5 @@ // Package gateway 提供 Gateway API 的统一客户端封装 -// 实现 AES-128-ECB 加密 + MD5 签名认证机制 +// 实现 AES-128-ECB 加密 + MD5 签名认证机制，支持请求日志和网络级错误重试 package gateway import ( @@ -13,6 +13,7 @@ import ( "github.com/break/junhong_cmp_fiber/pkg/errors" "github.com/bytedance/sonic" + "go.uber.org/zap" ) const ( @@ -22,6 +23,8 @@ const ( idleConnTimeout = 90 * time.Second contentTypeJSON = "application/json;charset=utf-8" gatewaySuccessCode = 200 + defaultMaxRetries = 2 + retryBaseDelay = 100 * time.Millisecond ) // Client 是 Gateway API 的 HTTP 客户端 @@ -31,13 +34,21 @@ type Client struct { appSecret string httpClient *http.Client timeout time.Duration + logger *zap.Logger + maxRetries int +} + +// requestWrapper 用于将请求参数包装为 Gateway 的 {"params": ...} 格式 +type requestWrapper struct { + Params interface{} `json:"params"` } // NewClient 创建 Gateway 客户端实例 // baseURL: Gateway 服务基础地址 // appID: 应用 ID // appSecret: 应用密钥（用于加密和签名） -func NewClient(baseURL, appID, appSecret string) *Client { +// logger: Zap 日志记录器 +func NewClient(baseURL, appID, appSecret string, logger *zap.Logger) *Client { return &Client{ baseURL: baseURL, appID: appID, @@ -49,7 +60,9 @@ func NewClient(baseURL, appID, appSecret string) *Client { IdleConnTimeout: idleConnTimeout, }, }, - timeout: defaultTimeout, + timeout: defaultTimeout, + logger: logger, + maxRetries: defaultMaxRetries, } } @@ -59,19 +72,86 @@ func (c *Client) WithTimeout(timeout time.Duration) *Client { return c } +// WithRetry 设置最大重试次数（支持链式调用） +// maxRetries=0 表示不重试，maxRetries=2 表示最多重试 2 次（共 3 次尝试） +func (c *Client) WithRetry(maxRetries int) *Client { + c.maxRetries = maxRetries + return c +} + // doRequest 执行 Gateway API 请求的统一方法 -// 流程：序列化 → 加密 → 签名 → HTTP POST → 解析响应 → 检查业务状态码 -func (c *Client) doRequest(ctx context.Context, path string, businessData interface{}) (json.RawMessage, error) { - dataBytes, err := sonic.Marshal(businessData) +// 流程：包装参数 → 序列化 → 加密 → 签名 → HTTP POST（带重试）→ 解析响应 → 检查业务状态码 +// params: 请求参数结构体，内部自动包装为 {"params": } 格式 +func (c *Client) doRequest(ctx context.Context, path string, params interface{}) (json.RawMessage, error) { + startTime := time.Now() + + // 将参数包装为 {"params": ...} 格式后序列化 + wrapper := requestWrapper{Params: params} + dataBytes, err := sonic.Marshal(wrapper) if err != nil { return nil, errors.Wrap(errors.CodeInternalError, err, "序列化业务数据失败") } + // 加密业务数据（加密结果不变，可在重试间复用） encryptedData, err := aesEncrypt(dataBytes, c.appSecret) if err != nil { return nil, err } + // 带重试的 HTTP 请求 + var lastErr error + for attempt := 0; attempt <= c.maxRetries; attempt++ { + if attempt > 0 { + // 检查用户 Context 是否已取消 + if ctx.Err() != nil { + break + } + // 指数退避等待：100ms → 200ms → 300ms（封顶 3 倍基础延迟） + delay := retryBaseDelay * time.Duration(1< retryBaseDelay*3 { + delay = retryBaseDelay * 3 + } + c.logger.Warn("Gateway 请求重试", + zap.String("path", path), + zap.Int("attempt", attempt+1), + zap.Duration("delay", delay), + ) + time.Sleep(delay) + } + + result, retryable, err := c.executeHTTPRequest(ctx, path, encryptedData) + if err != nil { + lastErr = err + // 仅对网络级错误重试 + if retryable && ctx.Err() == nil { + continue + } + break + } + + // 成功 + duration := time.Since(startTime) + c.logger.Debug("Gateway 请求成功", + zap.String("path", path), + zap.Duration("duration", duration), + ) + return result, nil + } + + // 所有尝试都失败 + duration := time.Since(startTime) + c.logger.Error("Gateway 请求失败", + zap.String("path", path), + zap.Duration("duration", duration), + zap.Error(lastErr), + ) + return nil, lastErr +} + +// executeHTTPRequest 执行单次 HTTP 请求（无重试逻辑） +// 返回值：响应数据、是否可重试、错误 +func (c *Client) executeHTTPRequest(ctx context.Context, path string, encryptedData string) (json.RawMessage, bool, error) { + // 每次重试使用新的时间戳和签名 timestamp := time.Now().Unix() sign := generateSign(c.appID, encryptedData, timestamp, c.appSecret) @@ -84,7 +164,7 @@ func (c *Client) doRequest(ctx context.Context, path string, businessData interf reqBodyBytes, err := sonic.Marshal(reqBody) if err != nil { - return nil, errors.Wrap(errors.CodeInternalError, err, "序列化请求体失败") + return nil, false, errors.Wrap(errors.CodeInternalError, err, "序列化请求体失败") } reqCtx, cancel := context.WithTimeout(ctx, c.timeout) @@ -92,39 +172,64 @@ func (c *Client) doRequest(ctx context.Context, path string, businessData interf req, err := http.NewRequestWithContext(reqCtx, http.MethodPost, c.baseURL+path, bytes.NewReader(reqBodyBytes)) if err != nil { - return nil, errors.Wrap(errors.CodeGatewayError, err, "创建 HTTP 请求失败") + return nil, false, errors.Wrap(errors.CodeGatewayError, err, "创建 HTTP 请求失败") } req.Header.Set("Content-Type", contentTypeJSON) resp, err := c.httpClient.Do(req) if err != nil { - if reqCtx.Err() == context.DeadlineExceeded { - return nil, errors.Wrap(errors.CodeGatewayTimeout, err, "Gateway 请求超时") - } + // 用户 Context 已取消 — 不可重试 if ctx.Err() != nil { - return nil, errors.Wrap(errors.CodeGatewayError, ctx.Err(), "请求被取消") + return nil, false, errors.Wrap(errors.CodeGatewayError, ctx.Err(), "请求被取消") } - return nil, errors.Wrap(errors.CodeGatewayError, err, "发送 HTTP 请求失败") + // Client 超时 — 可重试 + if reqCtx.Err() == context.DeadlineExceeded { + return nil, true, errors.Wrap(errors.CodeGatewayTimeout, err, "Gateway 请求超时") + } + // 其他网络错误（连接失败、DNS 解析等）— 可重试 + return nil, true, errors.Wrap(errors.CodeGatewayError, err, "发送 HTTP 请求失败") } defer resp.Body.Close() + // HTTP 状态码错误 — 不可重试 if resp.StatusCode != http.StatusOK { - return nil, errors.New(errors.CodeGatewayError, fmt.Sprintf("HTTP 状态码异常: %d", resp.StatusCode)) + return nil, false, errors.New(errors.CodeGatewayError, fmt.Sprintf("HTTP 状态码异常: %d", resp.StatusCode)) } body, err := io.ReadAll(resp.Body) if err != nil { - return nil, errors.Wrap(errors.CodeGatewayInvalidResp, err, "读取响应体失败") + return nil, false, errors.Wrap(errors.CodeGatewayInvalidResp, err, "读取响应体失败") } var gatewayResp GatewayResponse if err := sonic.Unmarshal(body, &gatewayResp); err != nil { + return nil, false, errors.Wrap(errors.CodeGatewayInvalidResp, err, "解析 Gateway 响应失败") + } + + // Gateway 业务错误 — 不可重试 + if gatewayResp.Code != gatewaySuccessCode { + c.logger.Warn("Gateway 业务错误", + zap.String("path", path), + zap.Int("gateway_code", gatewayResp.Code), + zap.String("gateway_msg", gatewayResp.Msg), + ) + return nil, false, errors.New(errors.CodeGatewayError, fmt.Sprintf("Gateway 业务错误: code=%d, msg=%s", gatewayResp.Code, gatewayResp.Msg)) + } + + return gatewayResp.Data, false, nil +} + +// doRequestWithResponse 执行 Gateway API 请求并自动反序列化响应为目标类型 +func doRequestWithResponse[T any](c *Client, ctx context.Context, path string, params interface{}) (*T, error) { + data, err := c.doRequest(ctx, path, params) + if err != nil { + return nil, err + } + + var result T + if err := sonic.Unmarshal(data, &result); err != nil { return nil, errors.Wrap(errors.CodeGatewayInvalidResp, err, "解析 Gateway 响应失败") } - if gatewayResp.Code != gatewaySuccessCode { - return nil, errors.New(errors.CodeGatewayError, fmt.Sprintf("Gateway 业务错误: code=%d, msg=%s", gatewayResp.Code, gatewayResp.Msg)) - } - - return gatewayResp.Data, nil + return &result, nil } diff --git a/internal/gateway/device.go b/internal/gateway/device.go index 0782fa1..84e9269 100644 --- a/internal/gateway/device.go +++ b/internal/gateway/device.go @@ -5,165 +5,66 @@ import ( "context" "github.com/break/junhong_cmp_fiber/pkg/errors" - "github.com/bytedance/sonic" ) // GetDeviceInfo 获取设备信息 // 通过卡号或设备 ID 查询设备的在线状态、信号强度、WiFi 信息等 +// POST /device/info func (c *Client) GetDeviceInfo(ctx context.Context, req *DeviceInfoReq) (*DeviceInfoResp, error) { if req.CardNo == "" && req.DeviceID == "" { return nil, errors.New(errors.CodeInvalidParam, "cardNo 和 deviceId 至少需要一个") } - - params := make(map[string]interface{}) - if req.CardNo != "" { - params["cardNo"] = req.CardNo - } - if req.DeviceID != "" { - params["deviceId"] = req.DeviceID - } - - businessData := map[string]interface{}{ - "params": params, - } - - resp, err := c.doRequest(ctx, "/device/info", businessData) - if err != nil { - return nil, err - } - - var result DeviceInfoResp - if err := sonic.Unmarshal(resp, &result); err != nil { - return nil, errors.Wrap(errors.CodeGatewayInvalidResp, err, "解析设备信息响应失败") - } - - return &result, nil + return doRequestWithResponse[DeviceInfoResp](c, ctx, "/device/info", req) } // GetSlotInfo 获取设备卡槽信息 // 查询设备的所有卡槽及其中的卡信息 +// POST /device/slot-info func (c *Client) GetSlotInfo(ctx context.Context, req *DeviceInfoReq) (*SlotInfoResp, error) { if req.CardNo == "" && req.DeviceID == "" { return nil, errors.New(errors.CodeInvalidParam, "cardNo 和 deviceId 至少需要一个") } - - params := make(map[string]interface{}) - if req.CardNo != "" { - params["cardNo"] = req.CardNo - } - if req.DeviceID != "" { - params["deviceId"] = req.DeviceID - } - - businessData := map[string]interface{}{ - "params": params, - } - - resp, err := c.doRequest(ctx, "/device/slot-info", businessData) - if err != nil { - return nil, err - } - - var result SlotInfoResp - if err := sonic.Unmarshal(resp, &result); err != nil { - return nil, errors.Wrap(errors.CodeGatewayInvalidResp, err, "解析卡槽信息响应失败") - } - - return &result, nil + return doRequestWithResponse[SlotInfoResp](c, ctx, "/device/slot-info", req) } // SetSpeedLimit 设置设备限速 -// 设置设备的上行和下行速率限制 +// 设置设备的统一限速值（单位 KB/s） +// POST /device/speed-limit func (c *Client) SetSpeedLimit(ctx context.Context, req *SpeedLimitReq) error { - params := map[string]interface{}{ - "deviceId": req.DeviceID, - "uploadSpeed": req.UploadSpeed, - "downloadSpeed": req.DownloadSpeed, - } - if req.Extend != "" { - params["extend"] = req.Extend - } - - businessData := map[string]interface{}{ - "params": params, - } - - _, err := c.doRequest(ctx, "/device/speed-limit", businessData) + _, err := c.doRequest(ctx, "/device/speed-limit", req) return err } // SetWiFi 设置设备 WiFi -// 设置设备的 WiFi 名称、密码和启用状态 +// 配置 WiFi 名称、密码及启用状态，cardNo（ICCID）为必填参数 +// POST /device/wifi-config func (c *Client) SetWiFi(ctx context.Context, req *WiFiReq) error { - params := map[string]interface{}{ - "deviceId": req.DeviceID, - "ssid": req.SSID, - "password": req.Password, - "enabled": req.Enabled, - } - if req.Extend != "" { - params["extend"] = req.Extend - } - - businessData := map[string]interface{}{ - "params": params, - } - - _, err := c.doRequest(ctx, "/device/wifi", businessData) + _, err := c.doRequest(ctx, "/device/wifi-config", req) return err } // SwitchCard 设备切换卡 -// 切换设备当前使用的卡到指定的目标卡 +// 为多卡设备切换到目标 ICCID，operationType 固定为 2 +// POST /device/card-switch func (c *Client) SwitchCard(ctx context.Context, req *SwitchCardReq) error { - params := map[string]interface{}{ - "deviceId": req.DeviceID, - "targetIccid": req.TargetICCID, - } - if req.Extend != "" { - params["extend"] = req.Extend - } - - businessData := map[string]interface{}{ - "params": params, - } - - _, err := c.doRequest(ctx, "/device/switch-card", businessData) + // 强制设置 operationType 为 2（切卡操作） + req.OperationType = 2 + _, err := c.doRequest(ctx, "/device/card-switch", req) return err } // ResetDevice 设备恢复出厂设置 // 将设备恢复到出厂设置状态 +// POST /device/factory-reset func (c *Client) ResetDevice(ctx context.Context, req *DeviceOperationReq) error { - params := map[string]interface{}{ - "deviceId": req.DeviceID, - } - if req.Extend != "" { - params["extend"] = req.Extend - } - - businessData := map[string]interface{}{ - "params": params, - } - - _, err := c.doRequest(ctx, "/device/reset", businessData) + _, err := c.doRequest(ctx, "/device/factory-reset", req) return err } // RebootDevice 设备重启 // 远程重启设备 +// POST /device/restart func (c *Client) RebootDevice(ctx context.Context, req *DeviceOperationReq) error { - params := map[string]interface{}{ - "deviceId": req.DeviceID, - } - if req.Extend != "" { - params["extend"] = req.Extend - } - - businessData := map[string]interface{}{ - "params": params, - } - - _, err := c.doRequest(ctx, "/device/reboot", businessData) + _, err := c.doRequest(ctx, "/device/restart", req) return err } diff --git a/internal/gateway/flow_card.go b/internal/gateway/flow_card.go index 7683bf8..36512c1 100644 --- a/internal/gateway/flow_card.go +++ b/internal/gateway/flow_card.go @@ -5,121 +5,44 @@ import ( "context" "github.com/break/junhong_cmp_fiber/pkg/errors" - "github.com/bytedance/sonic" ) // QueryCardStatus 查询流量卡状态 +// POST /flow-card/status func (c *Client) QueryCardStatus(ctx context.Context, req *CardStatusReq) (*CardStatusResp, error) { - businessData := map[string]interface{}{ - "params": map[string]interface{}{ - "cardNo": req.CardNo, - }, - } - - resp, err := c.doRequest(ctx, "/flow-card/status", businessData) - if err != nil { - return nil, err - } - - var result CardStatusResp - if err := sonic.Unmarshal(resp, &result); err != nil { - return nil, errors.Wrap(errors.CodeGatewayInvalidResp, err, "解析卡状态响应失败") - } - - return &result, nil + return doRequestWithResponse[CardStatusResp](c, ctx, "/flow-card/status", req) } // QueryFlow 查询流量使用情况 +// POST /flow-card/flow func (c *Client) QueryFlow(ctx context.Context, req *FlowQueryReq) (*FlowUsageResp, error) { - businessData := map[string]interface{}{ - "params": map[string]interface{}{ - "cardNo": req.CardNo, - }, - } - - resp, err := c.doRequest(ctx, "/flow-card/flow", businessData) - if err != nil { - return nil, err - } - - var result FlowUsageResp - if err := sonic.Unmarshal(resp, &result); err != nil { - return nil, errors.Wrap(errors.CodeGatewayInvalidResp, err, "解析流量使用响应失败") - } - - return &result, nil + return doRequestWithResponse[FlowUsageResp](c, ctx, "/flow-card/flow", req) } // QueryRealnameStatus 查询实名认证状态 +// POST /flow-card/realName func (c *Client) QueryRealnameStatus(ctx context.Context, req *CardStatusReq) (*RealnameStatusResp, error) { - businessData := map[string]interface{}{ - "params": map[string]interface{}{ - "cardNo": req.CardNo, - }, - } - - resp, err := c.doRequest(ctx, "/flow-card/realName", businessData) - if err != nil { - return nil, err - } - - var result RealnameStatusResp - if err := sonic.Unmarshal(resp, &result); err != nil { - return nil, errors.Wrap(errors.CodeGatewayInvalidResp, err, "解析实名认证状态响应失败") - } - - return &result, nil + return doRequestWithResponse[RealnameStatusResp](c, ctx, "/flow-card/realName", req) } // StopCard 流量卡停机 +// POST /flow-card/cardStop func (c *Client) StopCard(ctx context.Context, req *CardOperationReq) error { - businessData := map[string]interface{}{ - "params": map[string]interface{}{ - "cardNo": req.CardNo, - }, - } - if req.Extend != "" { - businessData["params"].(map[string]interface{})["extend"] = req.Extend - } - - _, err := c.doRequest(ctx, "/flow-card/cardStop", businessData) + _, err := c.doRequest(ctx, "/flow-card/cardStop", req) return err } // StartCard 流量卡复机 +// POST /flow-card/cardStart func (c *Client) StartCard(ctx context.Context, req *CardOperationReq) error { - businessData := map[string]interface{}{ - "params": map[string]interface{}{ - "cardNo": req.CardNo, - }, - } - if req.Extend != "" { - businessData["params"].(map[string]interface{})["extend"] = req.Extend - } - - _, err := c.doRequest(ctx, "/flow-card/cardStart", businessData) + _, err := c.doRequest(ctx, "/flow-card/cardStart", req) return err } // GetRealnameLink 获取实名认证跳转链接 +// POST /flow-card/RealNameVerification func (c *Client) GetRealnameLink(ctx context.Context, req *CardStatusReq) (*RealnameLinkResp, error) { - businessData := map[string]interface{}{ - "params": map[string]interface{}{ - "cardNo": req.CardNo, - }, - } - - resp, err := c.doRequest(ctx, "/flow-card/RealNameVerification", businessData) - if err != nil { - return nil, err - } - - var result RealnameLinkResp - if err := sonic.Unmarshal(resp, &result); err != nil { - return nil, errors.Wrap(errors.CodeGatewayInvalidResp, err, "解析实名认证链接响应失败") - } - - return &result, nil + return doRequestWithResponse[RealnameLinkResp](c, ctx, "/flow-card/RealNameVerification", req) } // BatchQuery 批量查询（预留接口，暂未实现） diff --git a/internal/gateway/models.go b/internal/gateway/models.go index 5f000e5..0037377 100644 --- a/internal/gateway/models.go +++ b/internal/gateway/models.go @@ -86,26 +86,28 @@ type DeviceInfoResp struct { // SpeedLimitReq 是设置设备限速的请求 type SpeedLimitReq struct { - DeviceID string `json:"deviceId" validate:"required" required:"true" description:"设备 ID/IMEI"` - UploadSpeed int `json:"uploadSpeed" validate:"required,min=1" required:"true" minimum:"1" description:"上行速率（KB/s）"` - DownloadSpeed int `json:"downloadSpeed" validate:"required,min=1" required:"true" minimum:"1" description:"下行速率（KB/s）"` - Extend string `json:"extend,omitempty" description:"扩展字段（广电国网特殊参数）"` + CardNo string `json:"cardNo,omitempty" description:"流量卡号（与 DeviceID 二选一）"` + DeviceID string `json:"deviceId,omitempty" description:"设备 ID/IMEI（与 CardNo 二选一）"` + SpeedLimit int `json:"speedLimit" validate:"required,min=1" required:"true" minimum:"1" description:"限速值（KB/s）"` + Extend string `json:"extend,omitempty" description:"扩展字段（广电国网特殊参数）"` } // WiFiReq 是设置设备 WiFi 的请求 type WiFiReq struct { - DeviceID string `json:"deviceId" validate:"required" required:"true" description:"设备 ID/IMEI"` + CardNo string `json:"cardNo" validate:"required" required:"true" description:"流量卡号（ICCID）"` + DeviceID string `json:"deviceId,omitempty" description:"设备 ID/IMEI"` SSID string `json:"ssid" validate:"required,min=1,max=32" required:"true" minLength:"1" maxLength:"32" description:"WiFi 名称"` - Password string `json:"password" validate:"required,min=8,max=63" required:"true" minLength:"8" maxLength:"63" description:"WiFi 密码"` - Enabled int `json:"enabled" validate:"required,oneof=0 1" required:"true" description:"启用状态（0:禁用, 1:启用）"` + Password string `json:"password,omitempty" description:"WiFi 密码"` + Enabled bool `json:"enabled" description:"启用状态"` Extend string `json:"extend,omitempty" description:"扩展字段（广电国网特殊参数）"` } // SwitchCardReq 是设备切换卡的请求 type SwitchCardReq struct { - DeviceID string `json:"deviceId" validate:"required" required:"true" description:"设备 ID/IMEI"` - TargetICCID string `json:"targetIccid" validate:"required" required:"true" description:"目标卡 ICCID"` - Extend string `json:"extend,omitempty" description:"扩展字段（广电国网特殊参数）"` + CardNo string `json:"cardNo" validate:"required" required:"true" description:"设备编号（IMEI）"` + ICCID string `json:"iccid" validate:"required" required:"true" description:"目标卡 ICCID"` + OperationType int `json:"operationType" description:"操作类型（固定值 2）"` + Extend string `json:"extend,omitempty" description:"扩展字段（广电国网特殊参数）"` } // DeviceOperationReq 是设备操作（重启、恢复出厂）的请求 diff --git a/internal/handler/admin/device.go b/internal/handler/admin/device.go index b7b9720..73fd122 100644 --- a/internal/handler/admin/device.go +++ b/internal/handler/admin/device.go @@ -5,7 +5,6 @@ import ( "github.com/gofiber/fiber/v2" - "github.com/break/junhong_cmp_fiber/internal/gateway" "github.com/break/junhong_cmp_fiber/internal/model/dto" deviceService "github.com/break/junhong_cmp_fiber/internal/service/device" "github.com/break/junhong_cmp_fiber/pkg/constants" @@ -15,14 +14,12 @@ import ( ) type DeviceHandler struct { - service *deviceService.Service - gatewayClient *gateway.Client + service *deviceService.Service } -func NewDeviceHandler(service *deviceService.Service, gatewayClient *gateway.Client) *DeviceHandler { +func NewDeviceHandler(service *deviceService.Service) *DeviceHandler { return &DeviceHandler{ - service: service, - gatewayClient: gatewayClient, + service: service, } } @@ -55,13 +52,15 @@ func (h *DeviceHandler) GetByID(c *fiber.Ctx) error { return response.Success(c, result) } -func (h *DeviceHandler) GetByIMEI(c *fiber.Ctx) error { - imei := c.Params("imei") - if imei == "" { - return errors.New(errors.CodeInvalidParam, "设备号不能为空") +// GetByIdentifier 通过标识符查询设备详情 +// GET /api/admin/devices/by-identifier/:identifier +func (h *DeviceHandler) GetByIdentifier(c *fiber.Ctx) error { + identifier := c.Params("identifier") + if identifier == "" { + return errors.New(errors.CodeInvalidParam, "设备标识符不能为空") } - result, err := h.service.GetByDeviceNo(c.UserContext(), imei) + result, err := h.service.GetByIdentifier(c.UserContext(), identifier) if err != nil { return err } @@ -225,22 +224,14 @@ func (h *DeviceHandler) BatchSetSeriesBinding(c *fiber.Ctx) error { } // GetGatewayInfo 查询设备信息 +// GET /api/admin/devices/by-identifier/:identifier/gateway-info func (h *DeviceHandler) GetGatewayInfo(c *fiber.Ctx) error { - imei := c.Params("imei") - if imei == "" { - return errors.New(errors.CodeInvalidParam, "设备号不能为空") + identifier := c.Params("identifier") + if identifier == "" { + return errors.New(errors.CodeInvalidParam, "设备标识符不能为空") } - // 验证权限：查询数据库确认设备存在且用户有权限访问 - _, err := h.service.GetByDeviceNo(c.UserContext(), imei) - if err != nil { - return errors.New(errors.CodeNotFound, "设备不存在或无权限访问") - } - - // 调用 Gateway - resp, err := h.gatewayClient.GetDeviceInfo(c.UserContext(), &gateway.DeviceInfoReq{ - DeviceID: imei, - }) + resp, err := h.service.GatewayGetDeviceInfo(c.UserContext(), identifier) if err != nil { return err } @@ -249,22 +240,14 @@ func (h *DeviceHandler) GetGatewayInfo(c *fiber.Ctx) error { } // GetGatewaySlots 查询设备卡槽信息 +// GET /api/admin/devices/by-identifier/:identifier/gateway-slots func (h *DeviceHandler) GetGatewaySlots(c *fiber.Ctx) error { - imei := c.Params("imei") - if imei == "" { - return errors.New(errors.CodeInvalidParam, "设备号不能为空") + identifier := c.Params("identifier") + if identifier == "" { + return errors.New(errors.CodeInvalidParam, "设备标识符不能为空") } - // 验证权限：查询数据库确认设备存在且用户有权限访问 - _, err := h.service.GetByDeviceNo(c.UserContext(), imei) - if err != nil { - return errors.New(errors.CodeNotFound, "设备不存在或无权限访问") - } - - // 调用 Gateway - resp, err := h.gatewayClient.GetSlotInfo(c.UserContext(), &gateway.DeviceInfoReq{ - DeviceID: imei, - }) + resp, err := h.service.GatewayGetSlotInfo(c.UserContext(), identifier) if err != nil { return err } @@ -273,10 +256,11 @@ func (h *DeviceHandler) GetGatewaySlots(c *fiber.Ctx) error { } // SetSpeedLimit 设置设备限速 +// PUT /api/admin/devices/by-identifier/:identifier/speed-limit func (h *DeviceHandler) SetSpeedLimit(c *fiber.Ctx) error { - imei := c.Params("imei") - if imei == "" { - return errors.New(errors.CodeInvalidParam, "设备号不能为空") + identifier := c.Params("identifier") + if identifier == "" { + return errors.New(errors.CodeInvalidParam, "设备标识符不能为空") } var req dto.SetSpeedLimitRequest @@ -284,19 +268,7 @@ func (h *DeviceHandler) SetSpeedLimit(c *fiber.Ctx) error { return errors.New(errors.CodeInvalidParam, "请求参数解析失败") } - // 验证权限：查询数据库确认设备存在且用户有权限访问 - _, err := h.service.GetByDeviceNo(c.UserContext(), imei) - if err != nil { - return errors.New(errors.CodeNotFound, "设备不存在或无权限访问") - } - - // 调用 Gateway - err = h.gatewayClient.SetSpeedLimit(c.UserContext(), &gateway.SpeedLimitReq{ - DeviceID: imei, - UploadSpeed: req.UploadSpeed, - DownloadSpeed: req.DownloadSpeed, - }) - if err != nil { + if err := h.service.GatewaySetSpeedLimit(c.UserContext(), identifier, &req); err != nil { return err } @@ -304,27 +276,19 @@ func (h *DeviceHandler) SetSpeedLimit(c *fiber.Ctx) error { } // SetWiFi 设置设备 WiFi +// PUT /api/admin/devices/by-identifier/:identifier/wifi func (h *DeviceHandler) SetWiFi(c *fiber.Ctx) error { - imei := c.Params("imei") - if imei == "" { - return errors.New(errors.CodeInvalidParam, "设备号不能为空") + identifier := c.Params("identifier") + if identifier == "" { + return errors.New(errors.CodeInvalidParam, "设备标识符不能为空") } - var req gateway.WiFiReq + var req dto.SetWiFiRequest if err := c.BodyParser(&req); err != nil { return errors.New(errors.CodeInvalidParam, "请求参数解析失败") } - // 验证权限：查询数据库确认设备存在且用户有权限访问 - _, err := h.service.GetByDeviceNo(c.UserContext(), imei) - if err != nil { - return errors.New(errors.CodeNotFound, "设备不存在或无权限访问") - } - - // 调用 Gateway - req.DeviceID = imei - err = h.gatewayClient.SetWiFi(c.UserContext(), &req) - if err != nil { + if err := h.service.GatewaySetWiFi(c.UserContext(), identifier, &req); err != nil { return err } @@ -332,10 +296,11 @@ func (h *DeviceHandler) SetWiFi(c *fiber.Ctx) error { } // SwitchCard 切换设备使用的卡 +// POST /api/admin/devices/by-identifier/:identifier/switch-card func (h *DeviceHandler) SwitchCard(c *fiber.Ctx) error { - imei := c.Params("imei") - if imei == "" { - return errors.New(errors.CodeInvalidParam, "设备号不能为空") + identifier := c.Params("identifier") + if identifier == "" { + return errors.New(errors.CodeInvalidParam, "设备标识符不能为空") } var req dto.SwitchCardRequest @@ -343,18 +308,7 @@ func (h *DeviceHandler) SwitchCard(c *fiber.Ctx) error { return errors.New(errors.CodeInvalidParam, "请求参数解析失败") } - // 验证权限：查询数据库确认设备存在且用户有权限访问 - _, err := h.service.GetByDeviceNo(c.UserContext(), imei) - if err != nil { - return errors.New(errors.CodeNotFound, "设备不存在或无权限访问") - } - - // 调用 Gateway - err = h.gatewayClient.SwitchCard(c.UserContext(), &gateway.SwitchCardReq{ - DeviceID: imei, - TargetICCID: req.TargetICCID, - }) - if err != nil { + if err := h.service.GatewaySwitchCard(c.UserContext(), identifier, &req); err != nil { return err } @@ -362,23 +316,14 @@ func (h *DeviceHandler) SwitchCard(c *fiber.Ctx) error { } // RebootDevice 重启设备 +// POST /api/admin/devices/by-identifier/:identifier/reboot func (h *DeviceHandler) RebootDevice(c *fiber.Ctx) error { - imei := c.Params("imei") - if imei == "" { - return errors.New(errors.CodeInvalidParam, "设备号不能为空") + identifier := c.Params("identifier") + if identifier == "" { + return errors.New(errors.CodeInvalidParam, "设备标识符不能为空") } - // 验证权限：查询数据库确认设备存在且用户有权限访问 - _, err := h.service.GetByDeviceNo(c.UserContext(), imei) - if err != nil { - return errors.New(errors.CodeNotFound, "设备不存在或无权限访问") - } - - // 调用 Gateway - err = h.gatewayClient.RebootDevice(c.UserContext(), &gateway.DeviceOperationReq{ - DeviceID: imei, - }) - if err != nil { + if err := h.service.GatewayRebootDevice(c.UserContext(), identifier); err != nil { return err } @@ -386,23 +331,14 @@ func (h *DeviceHandler) RebootDevice(c *fiber.Ctx) error { } // ResetDevice 恢复设备出厂设置 +// POST /api/admin/devices/by-identifier/:identifier/reset func (h *DeviceHandler) ResetDevice(c *fiber.Ctx) error { - imei := c.Params("imei") - if imei == "" { - return errors.New(errors.CodeInvalidParam, "设备号不能为空") + identifier := c.Params("identifier") + if identifier == "" { + return errors.New(errors.CodeInvalidParam, "设备标识符不能为空") } - // 验证权限：查询数据库确认设备存在且用户有权限访问 - _, err := h.service.GetByDeviceNo(c.UserContext(), imei) - if err != nil { - return errors.New(errors.CodeNotFound, "设备不存在或无权限访问") - } - - // 调用 Gateway - err = h.gatewayClient.ResetDevice(c.UserContext(), &gateway.DeviceOperationReq{ - DeviceID: imei, - }) - if err != nil { + if err := h.service.GatewayResetDevice(c.UserContext(), identifier); err != nil { return err } diff --git a/internal/handler/admin/iot_card.go b/internal/handler/admin/iot_card.go index 0b77f9d..8f30760 100644 --- a/internal/handler/admin/iot_card.go +++ b/internal/handler/admin/iot_card.go @@ -3,7 +3,6 @@ package admin import ( "github.com/gofiber/fiber/v2" - "github.com/break/junhong_cmp_fiber/internal/gateway" "github.com/break/junhong_cmp_fiber/internal/model/dto" iotCardService "github.com/break/junhong_cmp_fiber/internal/service/iot_card" "github.com/break/junhong_cmp_fiber/pkg/constants" @@ -13,14 +12,12 @@ import ( ) type IotCardHandler struct { - service *iotCardService.Service - gatewayClient *gateway.Client + service *iotCardService.Service } -func NewIotCardHandler(service *iotCardService.Service, gatewayClient *gateway.Client) *IotCardHandler { +func NewIotCardHandler(service *iotCardService.Service) *IotCardHandler { return &IotCardHandler{ - service: service, - gatewayClient: gatewayClient, + service: service, } } @@ -136,16 +133,7 @@ func (h *IotCardHandler) GetGatewayStatus(c *fiber.Ctx) error { return errors.New(errors.CodeInvalidParam, "ICCID不能为空") } - // 验证权限：查询数据库确认卡存在且用户有权限访问 - _, err := h.service.GetByICCID(c.UserContext(), iccid) - if err != nil { - return errors.New(errors.CodeNotFound, "卡不存在或无权限访问") - } - - // 调用 Gateway - resp, err := h.gatewayClient.QueryCardStatus(c.UserContext(), &gateway.CardStatusReq{ - CardNo: iccid, - }) + resp, err := h.service.GatewayQueryCardStatus(c.UserContext(), iccid) if err != nil { return err } @@ -160,16 +148,7 @@ func (h *IotCardHandler) GetGatewayFlow(c *fiber.Ctx) error { return errors.New(errors.CodeInvalidParam, "ICCID不能为空") } - // 验证权限：查询数据库确认卡存在且用户有权限访问 - _, err := h.service.GetByICCID(c.UserContext(), iccid) - if err != nil { - return errors.New(errors.CodeNotFound, "卡不存在或无权限访问") - } - - // 调用 Gateway - resp, err := h.gatewayClient.QueryFlow(c.UserContext(), &gateway.FlowQueryReq{ - CardNo: iccid, - }) + resp, err := h.service.GatewayQueryFlow(c.UserContext(), iccid) if err != nil { return err } @@ -184,16 +163,7 @@ func (h *IotCardHandler) GetGatewayRealname(c *fiber.Ctx) error { return errors.New(errors.CodeInvalidParam, "ICCID不能为空") } - // 验证权限：查询数据库确认卡存在且用户有权限访问 - _, err := h.service.GetByICCID(c.UserContext(), iccid) - if err != nil { - return errors.New(errors.CodeNotFound, "卡不存在或无权限访问") - } - - // 调用 Gateway - resp, err := h.gatewayClient.QueryRealnameStatus(c.UserContext(), &gateway.CardStatusReq{ - CardNo: iccid, - }) + resp, err := h.service.GatewayQueryRealnameStatus(c.UserContext(), iccid) if err != nil { return err } @@ -208,16 +178,7 @@ func (h *IotCardHandler) GetRealnameLink(c *fiber.Ctx) error { return errors.New(errors.CodeInvalidParam, "ICCID不能为空") } - // 验证权限：查询数据库确认卡存在且用户有权限访问 - _, err := h.service.GetByICCID(c.UserContext(), iccid) - if err != nil { - return errors.New(errors.CodeNotFound, "卡不存在或无权限访问") - } - - // 调用 Gateway - link, err := h.gatewayClient.GetRealnameLink(c.UserContext(), &gateway.CardStatusReq{ - CardNo: iccid, - }) + link, err := h.service.GatewayGetRealnameLink(c.UserContext(), iccid) if err != nil { return err } @@ -232,17 +193,7 @@ func (h *IotCardHandler) StopCard(c *fiber.Ctx) error { return errors.New(errors.CodeInvalidParam, "ICCID不能为空") } - // 验证权限：查询数据库确认卡存在且用户有权限访问 - _, err := h.service.GetByICCID(c.UserContext(), iccid) - if err != nil { - return errors.New(errors.CodeNotFound, "卡不存在或无权限访问") - } - - // 调用 Gateway - err = h.gatewayClient.StopCard(c.UserContext(), &gateway.CardOperationReq{ - CardNo: iccid, - }) - if err != nil { + if err := h.service.GatewayStopCard(c.UserContext(), iccid); err != nil { return err } @@ -256,17 +207,7 @@ func (h *IotCardHandler) StartCard(c *fiber.Ctx) error { return errors.New(errors.CodeInvalidParam, "ICCID不能为空") } - // 验证权限：查询数据库确认卡存在且用户有权限访问 - _, err := h.service.GetByICCID(c.UserContext(), iccid) - if err != nil { - return errors.New(errors.CodeNotFound, "卡不存在或无权限访问") - } - - // 调用 Gateway - err = h.gatewayClient.StartCard(c.UserContext(), &gateway.CardOperationReq{ - CardNo: iccid, - }) - if err != nil { + if err := h.service.GatewayStartCard(c.UserContext(), iccid); err != nil { return err } diff --git a/internal/model/device.go b/internal/model/device.go index b2edf66..93e7292 100644 --- a/internal/model/device.go +++ b/internal/model/device.go @@ -11,10 +11,13 @@ import ( // Device 设备模型 // 物联网设备(如 GPS 追踪器、智能传感器) // 通过 shop_id 区分所有权：NULL=平台库存，有值=店铺所有 +// 标识符说明：device_no 为虚拟号/别名，imei/sn 为设备真实标识 type Device struct { gorm.Model BaseModel `gorm:"embedded"` - DeviceNo string `gorm:"column:device_no;type:varchar(100);uniqueIndex:idx_device_no,where:deleted_at IS NULL;not null;comment:设备编号(唯一标识)" json:"device_no"` + DeviceNo string `gorm:"column:device_no;type:varchar(100);uniqueIndex:idx_device_no,where:deleted_at IS NULL;not null;comment:设备虚拟号/别名(用户友好的短标识)" json:"device_no"` + IMEI string `gorm:"column:imei;type:varchar(20);comment:设备IMEI(有蜂窝网络的设备标识,用于Gateway API调用)" json:"imei"` + SN string `gorm:"column:sn;type:varchar(100);comment:设备序列号(厂商唯一标识,预留字段)" json:"sn"` DeviceName string `gorm:"column:device_name;type:varchar(255);comment:设备名称" json:"device_name"` DeviceModel string `gorm:"column:device_model;type:varchar(100);comment:设备型号" json:"device_model"` DeviceType string `gorm:"column:device_type;type:varchar(50);comment:设备类型" json:"device_type"` diff --git a/internal/model/dto/device_dto.go b/internal/model/dto/device_dto.go index 48b7681..3b9cba1 100644 --- a/internal/model/dto/device_dto.go +++ b/internal/model/dto/device_dto.go @@ -19,7 +19,9 @@ type ListDeviceRequest struct { type DeviceResponse struct { ID uint `json:"id" description:"设备ID"` - DeviceNo string `json:"device_no" description:"设备号"` + DeviceNo string `json:"device_no" description:"设备虚拟号/别名"` + IMEI string `json:"imei" description:"设备IMEI"` + SN string `json:"sn" description:"设备序列号"` DeviceName string `json:"device_name" description:"设备名称"` DeviceModel string `json:"device_model" description:"设备型号"` DeviceType string `json:"device_type" description:"设备类型"` @@ -52,8 +54,9 @@ type GetDeviceRequest struct { ID uint `path:"id" description:"设备ID" required:"true"` } -type GetDeviceByIMEIRequest struct { - DeviceNo string `path:"imei" description:"设备号(IMEI)" required:"true"` +// GetDeviceByIdentifierRequest 通过标识符查询设备请求 +type GetDeviceByIdentifierRequest struct { + Identifier string `path:"identifier" description:"设备标识符(支持虚拟号/IMEI/SN)" required:"true"` } type DeleteDeviceRequest struct { @@ -148,21 +151,24 @@ type BatchSetDeviceSeriesBindngResponse struct { FailedItems []DeviceSeriesBindngFailedItem `json:"failed_items" description:"失败详情列表"` } +// SetSpeedLimitRequest 设置设备限速请求 type SetSpeedLimitRequest struct { - IMEI string `path:"imei" description:"设备号(IMEI)" required:"true"` - UploadSpeed int `json:"upload_speed" validate:"required,min=1" required:"true" minimum:"1" description:"上行速率（KB/s）"` - DownloadSpeed int `json:"download_speed" validate:"required,min=1" required:"true" minimum:"1" description:"下行速率（KB/s）"` + Identifier string `path:"identifier" description:"设备标识符(支持虚拟号/IMEI/SN)" required:"true"` + SpeedLimit int `json:"speed_limit" validate:"required,min=1" required:"true" minimum:"1" description:"限速值（KB/s）"` } +// SetWiFiRequest 设置设备 WiFi 请求 type SetWiFiRequest struct { - IMEI string `path:"imei" description:"设备号(IMEI)" required:"true"` - SSID string `json:"ssid" validate:"required,min=1,max=32" required:"true" minLength:"1" maxLength:"32" description:"WiFi 名称"` - Password string `json:"password" validate:"required,min=8,max=63" required:"true" minLength:"8" maxLength:"63" description:"WiFi 密码"` - Enabled int `json:"enabled" validate:"required,oneof=0 1" required:"true" description:"启用状态（0:禁用, 1:启用）"` + Identifier string `path:"identifier" description:"设备标识符(支持虚拟号/IMEI/SN)" required:"true"` + CardNo string `json:"card_no" validate:"required" required:"true" description:"流量卡号（ICCID）"` + SSID string `json:"ssid" validate:"required,min=1,max=32" required:"true" minLength:"1" maxLength:"32" description:"WiFi 名称"` + Password string `json:"password,omitempty" description:"WiFi 密码"` + Enabled bool `json:"enabled" description:"启用状态"` } +// SwitchCardRequest 切卡请求 type SwitchCardRequest struct { - IMEI string `path:"imei" description:"设备号(IMEI)" required:"true"` + Identifier string `path:"identifier" description:"设备标识符(支持虚拟号/IMEI/SN)" required:"true"` TargetICCID string `json:"target_iccid" validate:"required" required:"true" description:"目标卡 ICCID"` } diff --git a/internal/routes/device.go b/internal/routes/device.go index 47c9603..560764b 100644 --- a/internal/routes/device.go +++ b/internal/routes/device.go @@ -29,12 +29,13 @@ func registerDeviceRoutes(router fiber.Router, handler *admin.DeviceHandler, imp Auth: true, }) - Register(devices, doc, groupPath, "GET", "/by-imei/:imei", handler.GetByIMEI, RouteSpec{ - Summary: "通过设备号查询设备详情", - Tags: []string{"设备管理"}, - Input: new(dto.GetDeviceByIMEIRequest), - Output: new(dto.DeviceResponse), - Auth: true, + Register(devices, doc, groupPath, "GET", "/by-identifier/:identifier", handler.GetByIdentifier, RouteSpec{ + Summary: "通过标识符查询设备详情", + Description: "支持通过虚拟号(device_no)、IMEI、SN 任意一个标识符查询设备。", + Tags: []string{"设备管理"}, + Input: new(dto.GetDeviceByIdentifierRequest), + Output: new(dto.DeviceResponse), + Auth: true, }) Register(devices, doc, groupPath, "DELETE", "/:id", handler.Delete, RouteSpec{ @@ -145,59 +146,66 @@ func registerDeviceRoutes(router fiber.Router, handler *admin.DeviceHandler, imp Auth: true, }) - Register(devices, doc, groupPath, "GET", "/by-imei/:imei/gateway-info", handler.GetGatewayInfo, RouteSpec{ - Summary: "查询设备信息", - Tags: []string{"设备管理"}, - Input: new(dto.GetDeviceByIMEIRequest), - Output: new(gateway.DeviceInfoResp), - Auth: true, + Register(devices, doc, groupPath, "GET", "/by-identifier/:identifier/gateway-info", handler.GetGatewayInfo, RouteSpec{ + Summary: "查询设备信息", + Description: "通过虚拟号/IMEI/SN 查询设备网关信息。设备必须已配置 IMEI。", + Tags: []string{"设备管理"}, + Input: new(dto.GetDeviceByIdentifierRequest), + Output: new(gateway.DeviceInfoResp), + Auth: true, }) - Register(devices, doc, groupPath, "GET", "/by-imei/:imei/gateway-slots", handler.GetGatewaySlots, RouteSpec{ - Summary: "查询卡槽信息", - Tags: []string{"设备管理"}, - Input: new(dto.GetDeviceByIMEIRequest), - Output: new(gateway.SlotInfoResp), - Auth: true, + Register(devices, doc, groupPath, "GET", "/by-identifier/:identifier/gateway-slots", handler.GetGatewaySlots, RouteSpec{ + Summary: "查询卡槽信息", + Description: "通过虚拟号/IMEI/SN 查询设备卡槽信息。设备必须已配置 IMEI。", + Tags: []string{"设备管理"}, + Input: new(dto.GetDeviceByIdentifierRequest), + Output: new(gateway.SlotInfoResp), + Auth: true, }) - Register(devices, doc, groupPath, "PUT", "/by-imei/:imei/speed-limit", handler.SetSpeedLimit, RouteSpec{ - Summary: "设置限速", - Tags: []string{"设备管理"}, - Input: new(dto.SetSpeedLimitRequest), - Output: new(dto.EmptyResponse), - Auth: true, + Register(devices, doc, groupPath, "PUT", "/by-identifier/:identifier/speed-limit", handler.SetSpeedLimit, RouteSpec{ + Summary: "设置限速", + Description: "通过虚拟号/IMEI/SN 设置设备限速。设备必须已配置 IMEI。", + Tags: []string{"设备管理"}, + Input: new(dto.SetSpeedLimitRequest), + Output: new(dto.EmptyResponse), + Auth: true, }) - Register(devices, doc, groupPath, "PUT", "/by-imei/:imei/wifi", handler.SetWiFi, RouteSpec{ - Summary: "设置 WiFi", - Tags: []string{"设备管理"}, - Input: new(dto.SetWiFiRequest), - Output: new(dto.EmptyResponse), - Auth: true, + Register(devices, doc, groupPath, "PUT", "/by-identifier/:identifier/wifi", handler.SetWiFi, RouteSpec{ + Summary: "设置 WiFi", + Description: "通过虚拟号/IMEI/SN 设置设备 WiFi。设备必须已配置 IMEI。", + Tags: []string{"设备管理"}, + Input: new(dto.SetWiFiRequest), + Output: new(dto.EmptyResponse), + Auth: true, }) - Register(devices, doc, groupPath, "POST", "/by-imei/:imei/switch-card", handler.SwitchCard, RouteSpec{ - Summary: "切卡", - Tags: []string{"设备管理"}, - Input: new(dto.SwitchCardRequest), - Output: new(dto.EmptyResponse), - Auth: true, + Register(devices, doc, groupPath, "POST", "/by-identifier/:identifier/switch-card", handler.SwitchCard, RouteSpec{ + Summary: "切卡", + Description: "通过虚拟号/IMEI/SN 切换设备当前使用的卡。设备必须已配置 IMEI。", + Tags: []string{"设备管理"}, + Input: new(dto.SwitchCardRequest), + Output: new(dto.EmptyResponse), + Auth: true, }) - Register(devices, doc, groupPath, "POST", "/by-imei/:imei/reboot", handler.RebootDevice, RouteSpec{ - Summary: "重启设备", - Tags: []string{"设备管理"}, - Input: new(dto.GetDeviceByIMEIRequest), - Output: new(dto.EmptyResponse), - Auth: true, + Register(devices, doc, groupPath, "POST", "/by-identifier/:identifier/reboot", handler.RebootDevice, RouteSpec{ + Summary: "重启设备", + Description: "通过虚拟号/IMEI/SN 重启设备。设备必须已配置 IMEI。", + Tags: []string{"设备管理"}, + Input: new(dto.GetDeviceByIdentifierRequest), + Output: new(dto.EmptyResponse), + Auth: true, }) - Register(devices, doc, groupPath, "POST", "/by-imei/:imei/reset", handler.ResetDevice, RouteSpec{ - Summary: "恢复出厂", - Tags: []string{"设备管理"}, - Input: new(dto.GetDeviceByIMEIRequest), - Output: new(dto.EmptyResponse), - Auth: true, + Register(devices, doc, groupPath, "POST", "/by-identifier/:identifier/reset", handler.ResetDevice, RouteSpec{ + Summary: "恢复出厂", + Description: "通过虚拟号/IMEI/SN 恢复设备出厂设置。设备必须已配置 IMEI。", + Tags: []string{"设备管理"}, + Input: new(dto.GetDeviceByIdentifierRequest), + Output: new(dto.EmptyResponse), + Auth: true, }) } diff --git a/internal/service/device/gateway_service.go b/internal/service/device/gateway_service.go new file mode 100644 index 0000000..4f14352 --- /dev/null +++ b/internal/service/device/gateway_service.go @@ -0,0 +1,105 @@ +package device + +import ( + "context" + + "github.com/break/junhong_cmp_fiber/internal/gateway" + "github.com/break/junhong_cmp_fiber/internal/model/dto" + "github.com/break/junhong_cmp_fiber/pkg/errors" +) + +// getDeviceIMEI 通过标识符获取设备并验证 IMEI 存在 +// 提供统一的设备查找 + IMEI 校验逻辑，供所有 Gateway 代理方法复用 +func (s *Service) getDeviceIMEI(ctx context.Context, identifier string) (string, error) { + device, err := s.deviceStore.GetByIdentifier(ctx, identifier) + if err != nil { + return "", errors.New(errors.CodeNotFound, "设备不存在或无权限访问") + } + if device.IMEI == "" { + return "", errors.New(errors.CodeInvalidParam, "该设备未配置 IMEI，无法调用网关接口") + } + return device.IMEI, nil +} + +// GatewayGetDeviceInfo 通过标识符查询设备网关信息 +func (s *Service) GatewayGetDeviceInfo(ctx context.Context, identifier string) (*gateway.DeviceInfoResp, error) { + imei, err := s.getDeviceIMEI(ctx, identifier) + if err != nil { + return nil, err + } + return s.gatewayClient.GetDeviceInfo(ctx, &gateway.DeviceInfoReq{ + DeviceID: imei, + }) +} + +// GatewayGetSlotInfo 通过标识符查询设备卡槽信息 +func (s *Service) GatewayGetSlotInfo(ctx context.Context, identifier string) (*gateway.SlotInfoResp, error) { + imei, err := s.getDeviceIMEI(ctx, identifier) + if err != nil { + return nil, err + } + return s.gatewayClient.GetSlotInfo(ctx, &gateway.DeviceInfoReq{ + DeviceID: imei, + }) +} + +// GatewaySetSpeedLimit 通过标识符设置设备限速 +func (s *Service) GatewaySetSpeedLimit(ctx context.Context, identifier string, req *dto.SetSpeedLimitRequest) error { + imei, err := s.getDeviceIMEI(ctx, identifier) + if err != nil { + return err + } + return s.gatewayClient.SetSpeedLimit(ctx, &gateway.SpeedLimitReq{ + DeviceID: imei, + SpeedLimit: req.SpeedLimit, + }) +} + +// GatewaySetWiFi 通过标识符设置设备 WiFi +func (s *Service) GatewaySetWiFi(ctx context.Context, identifier string, req *dto.SetWiFiRequest) error { + imei, err := s.getDeviceIMEI(ctx, identifier) + if err != nil { + return err + } + return s.gatewayClient.SetWiFi(ctx, &gateway.WiFiReq{ + CardNo: req.CardNo, + DeviceID: imei, + SSID: req.SSID, + Password: req.Password, + Enabled: req.Enabled, + }) +} + +// GatewaySwitchCard 通过标识符切换设备使用的卡 +func (s *Service) GatewaySwitchCard(ctx context.Context, identifier string, req *dto.SwitchCardRequest) error { + imei, err := s.getDeviceIMEI(ctx, identifier) + if err != nil { + return err + } + return s.gatewayClient.SwitchCard(ctx, &gateway.SwitchCardReq{ + CardNo: imei, + ICCID: req.TargetICCID, + }) +} + +// GatewayRebootDevice 通过标识符重启设备 +func (s *Service) GatewayRebootDevice(ctx context.Context, identifier string) error { + imei, err := s.getDeviceIMEI(ctx, identifier) + if err != nil { + return err + } + return s.gatewayClient.RebootDevice(ctx, &gateway.DeviceOperationReq{ + DeviceID: imei, + }) +} + +// GatewayResetDevice 通过标识符恢复设备出厂设置 +func (s *Service) GatewayResetDevice(ctx context.Context, identifier string) error { + imei, err := s.getDeviceIMEI(ctx, identifier) + if err != nil { + return err + } + return s.gatewayClient.ResetDevice(ctx, &gateway.DeviceOperationReq{ + DeviceID: imei, + }) +} diff --git a/internal/service/device/service.go b/internal/service/device/service.go index 31bfe6a..3c1b925 100644 --- a/internal/service/device/service.go +++ b/internal/service/device/service.go @@ -3,6 +3,7 @@ package device import ( "context" + "github.com/break/junhong_cmp_fiber/internal/gateway" "github.com/break/junhong_cmp_fiber/internal/model" "github.com/break/junhong_cmp_fiber/internal/model/dto" "github.com/break/junhong_cmp_fiber/internal/store" @@ -22,6 +23,7 @@ type Service struct { shopPackageAllocationStore *postgres.ShopPackageAllocationStore shopSeriesAllocationStore *postgres.ShopSeriesAllocationStore packageSeriesStore *postgres.PackageSeriesStore + gatewayClient *gateway.Client } func New( @@ -34,6 +36,7 @@ func New( shopPackageAllocationStore *postgres.ShopPackageAllocationStore, shopSeriesAllocationStore *postgres.ShopSeriesAllocationStore, packageSeriesStore *postgres.PackageSeriesStore, + gatewayClient *gateway.Client, ) *Service { return &Service{ db: db, @@ -45,6 +48,7 @@ func New( shopPackageAllocationStore: shopPackageAllocationStore, shopSeriesAllocationStore: shopSeriesAllocationStore, packageSeriesStore: packageSeriesStore, + gatewayClient: gatewayClient, } } @@ -168,6 +172,40 @@ func (s *Service) GetByDeviceNo(ctx context.Context, deviceNo string) (*dto.Devi return s.toDeviceResponse(device, shopMap, seriesMap, bindingCounts), nil } +// GetByIdentifier 通过任意标识符获取设备详情 +// 支持 device_no（虚拟号）、imei、sn 三个字段的自动匹配 +func (s *Service) GetByIdentifier(ctx context.Context, identifier string) (*dto.DeviceResponse, error) { + device, err := s.deviceStore.GetByIdentifier(ctx, identifier) + if err != nil { + if err == gorm.ErrRecordNotFound { + return nil, errors.New(errors.CodeNotFound, "设备不存在") + } + return nil, err + } + + shopMap := s.loadShopData(ctx, []*model.Device{device}) + seriesMap := s.loadSeriesNames(ctx, []*model.Device{device}) + bindingCounts, err := s.getBindingCounts(ctx, []uint{device.ID}) + if err != nil { + return nil, err + } + + return s.toDeviceResponse(device, shopMap, seriesMap, bindingCounts), nil +} + +// GetDeviceByIdentifier 通过任意标识符获取设备模型（内部使用，不转为 DTO） +// 用于 Handler 层获取设备后提取 IMEI 调用 Gateway API +func (s *Service) GetDeviceByIdentifier(ctx context.Context, identifier string) (*model.Device, error) { + device, err := s.deviceStore.GetByIdentifier(ctx, identifier) + if err != nil { + if err == gorm.ErrRecordNotFound { + return nil, errors.New(errors.CodeNotFound, "设备不存在或无权限访问") + } + return nil, err + } + return device, nil +} + func (s *Service) Delete(ctx context.Context, id uint) error { device, err := s.deviceStore.GetByID(ctx, id) if err != nil { @@ -491,6 +529,8 @@ func (s *Service) toDeviceResponse(device *model.Device, shopMap map[uint]string resp := &dto.DeviceResponse{ ID: device.ID, DeviceNo: device.DeviceNo, + IMEI: device.IMEI, + SN: device.SN, DeviceName: device.DeviceName, DeviceModel: device.DeviceModel, DeviceType: device.DeviceType, diff --git a/internal/service/iot_card/gateway_service.go b/internal/service/iot_card/gateway_service.go new file mode 100644 index 0000000..41a51f5 --- /dev/null +++ b/internal/service/iot_card/gateway_service.go @@ -0,0 +1,78 @@ +package iot_card + +import ( + "context" + + "github.com/break/junhong_cmp_fiber/internal/gateway" + "github.com/break/junhong_cmp_fiber/pkg/errors" +) + +// validateCardAccess 通过 ICCID 验证卡存在且当前用户有权限访问 +// 利用 GORM 数据权限回调自动过滤，确保越权请求返回 404 +func (s *Service) validateCardAccess(ctx context.Context, iccid string) error { + _, err := s.iotCardStore.GetByICCID(ctx, iccid) + if err != nil { + return errors.New(errors.CodeNotFound, "卡不存在或无权限访问") + } + return nil +} + +// GatewayQueryCardStatus 查询卡实时状态 +func (s *Service) GatewayQueryCardStatus(ctx context.Context, iccid string) (*gateway.CardStatusResp, error) { + if err := s.validateCardAccess(ctx, iccid); err != nil { + return nil, err + } + return s.gatewayClient.QueryCardStatus(ctx, &gateway.CardStatusReq{ + CardNo: iccid, + }) +} + +// GatewayQueryFlow 查询流量使用情况 +func (s *Service) GatewayQueryFlow(ctx context.Context, iccid string) (*gateway.FlowUsageResp, error) { + if err := s.validateCardAccess(ctx, iccid); err != nil { + return nil, err + } + return s.gatewayClient.QueryFlow(ctx, &gateway.FlowQueryReq{ + CardNo: iccid, + }) +} + +// GatewayQueryRealnameStatus 查询实名认证状态 +func (s *Service) GatewayQueryRealnameStatus(ctx context.Context, iccid string) (*gateway.RealnameStatusResp, error) { + if err := s.validateCardAccess(ctx, iccid); err != nil { + return nil, err + } + return s.gatewayClient.QueryRealnameStatus(ctx, &gateway.CardStatusReq{ + CardNo: iccid, + }) +} + +// GatewayGetRealnameLink 获取实名认证跳转链接 +func (s *Service) GatewayGetRealnameLink(ctx context.Context, iccid string) (*gateway.RealnameLinkResp, error) { + if err := s.validateCardAccess(ctx, iccid); err != nil { + return nil, err + } + return s.gatewayClient.GetRealnameLink(ctx, &gateway.CardStatusReq{ + CardNo: iccid, + }) +} + +// GatewayStopCard 停止卡服务（通过 Gateway API） +func (s *Service) GatewayStopCard(ctx context.Context, iccid string) error { + if err := s.validateCardAccess(ctx, iccid); err != nil { + return err + } + return s.gatewayClient.StopCard(ctx, &gateway.CardOperationReq{ + CardNo: iccid, + }) +} + +// GatewayStartCard 恢复卡服务（通过 Gateway API） +func (s *Service) GatewayStartCard(ctx context.Context, iccid string) error { + if err := s.validateCardAccess(ctx, iccid); err != nil { + return err + } + return s.gatewayClient.StartCard(ctx, &gateway.CardOperationReq{ + CardNo: iccid, + }) +} diff --git a/internal/store/postgres/device_store.go b/internal/store/postgres/device_store.go index 8556343..7df591b 100644 --- a/internal/store/postgres/device_store.go +++ b/internal/store/postgres/device_store.go @@ -57,6 +57,19 @@ func (s *DeviceStore) GetByDeviceNo(ctx context.Context, deviceNo string) (*mode return &device, nil } +// GetByIdentifier 通过任意标识符查找设备 +// 支持 device_no（虚拟号）、imei、sn 三个字段的自动匹配 +func (s *DeviceStore) GetByIdentifier(ctx context.Context, identifier string) (*model.Device, error) { + var device model.Device + query := s.db.WithContext(ctx).Where("device_no = ? OR imei = ? OR sn = ?", identifier, identifier, identifier) + // 应用数据权限过滤（NULL shop_id 对代理用户不可见） + query = middleware.ApplyShopFilter(ctx, query) + if err := query.First(&device).Error; err != nil { + return nil, err + } + return &device, nil +} + func (s *DeviceStore) GetByIDs(ctx context.Context, ids []uint) ([]*model.Device, error) { var devices []*model.Device if len(ids) == 0 { diff --git a/migrations/000072_add_device_imei_sn_fields.down.sql b/migrations/000072_add_device_imei_sn_fields.down.sql new file mode 100644 index 0000000..c4f6b06 --- /dev/null +++ b/migrations/000072_add_device_imei_sn_fields.down.sql @@ -0,0 +1,12 @@ +-- 回滚设备标识符模型重构 + +-- 删除索引 +DROP INDEX IF EXISTS idx_device_imei; +DROP INDEX IF EXISTS idx_device_sn; + +-- 删除字段 +ALTER TABLE tb_device DROP COLUMN IF EXISTS imei; +ALTER TABLE tb_device DROP COLUMN IF EXISTS sn; + +-- 恢复 device_no 注释 +COMMENT ON COLUMN tb_device.device_no IS '设备编号(唯一标识)'; diff --git a/migrations/000072_add_device_imei_sn_fields.up.sql b/migrations/000072_add_device_imei_sn_fields.up.sql new file mode 100644 index 0000000..2802279 --- /dev/null +++ b/migrations/000072_add_device_imei_sn_fields.up.sql @@ -0,0 +1,23 @@ +-- 设备标识符模型重构 +-- 新增 imei 和 sn 字段，将 device_no 定位为虚拟号/别名 +-- imei: 设备 IMEI（有蜂窝网络的设备），用于调用 Gateway API +-- sn: 设备序列号（厂商唯一标识），预留字段 + +-- 新增 imei 字段（可空，有索引） +ALTER TABLE tb_device +ADD COLUMN imei VARCHAR(20); + +COMMENT ON COLUMN tb_device.imei IS '设备IMEI(有蜂窝网络的设备标识,用于Gateway API调用)'; + +CREATE INDEX idx_device_imei ON tb_device(imei) WHERE deleted_at IS NULL AND imei IS NOT NULL; + +-- 新增 sn 字段（可空） +ALTER TABLE tb_device +ADD COLUMN sn VARCHAR(100); + +COMMENT ON COLUMN tb_device.sn IS '设备序列号(厂商唯一标识,预留字段)'; + +CREATE INDEX idx_device_sn ON tb_device(sn) WHERE deleted_at IS NULL AND sn IS NOT NULL; + +-- 更新 device_no 字段注释，明确其虚拟号定位 +COMMENT ON COLUMN tb_device.device_no IS '设备虚拟号/别名(用户友好的短标识,业务方自定义格式)'; diff --git a/openspec/changes/archive/2026-03-09-refactor-gateway-client/.openspec.yaml b/openspec/changes/archive/2026-03-09-refactor-gateway-client/.openspec.yaml new file mode 100644 index 0000000..5cb9e8f --- /dev/null +++ b/openspec/changes/archive/2026-03-09-refactor-gateway-client/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-03-09 diff --git a/openspec/changes/archive/2026-03-09-refactor-gateway-client/design.md b/openspec/changes/archive/2026-03-09-refactor-gateway-client/design.md new file mode 100644 index 0000000..a241b51 --- /dev/null +++ b/openspec/changes/archive/2026-03-09-refactor-gateway-client/design.md @@ -0,0 +1,194 @@ +## Context + +当前 `internal/gateway/` 包存在以下问题： + +1. **仅为薄 HTTP 包装**：`Client` 只有 `doRequest` 统一处理加密/签名/HTTP 请求，每个业务方法手动构建 `map[string]interface{}` 参数和手动 unmarshal 响应 +2. **Handler 层架构违规**：IotCard Handler（6 处）和 Device Handler（7 处）直接持有并调用 `gateway.Client`，跳过了 Service 层 +3. **无日志和重试**：Gateway 调用无请求/响应日志，网络错误无重试机制 +4. **代码重复度高**：13 个方法中大量 map 构建 + unmarshal 模式重复 + +### 当前调用链 + +``` +// 违规模式（当前） +Handler.gatewayClient.XXX() → gateway.Client.doRequest() → HTTP + +// 正确模式（目标） +Handler → Service.XXX() → gateway.Client.XXX() → HTTP +``` + +### 现有依赖关系 + +| 使用者 | 使用方式 | 是否合规 | +|--------|----------|---------| +| `handler/admin/iot_card.go` | 直接调用 gatewayClient（6 处） | ❌ | +| `handler/admin/device.go` | 直接调用 gatewayClient（7 处） | ❌ | +| `service/iot_card/service.go` | 通过 Service 调用（1 处：QueryCardStatus） | ✅ | +| `service/iot_card/stop_resume_service.go` | 通过 Service 调用（2 处：StopCard、StartCard） | ✅ | +| `task/polling_handler.go` | Worker 任务中调用（合理） | ✅ | +| `pkg/queue/handler.go` | Worker 中初始化 polling_handler | ✅ | + +## Goals / Non-Goals + +**Goals:** +1. 消除手动 map 构建，请求结构体直接序列化为 Gateway 参数格式 +2. 添加泛型响应解析方法，消除重复 unmarshal 代码 +3. 在 `doRequest` 中添加 Zap 日志（请求路径、耗时、错误） +4. 添加网络级错误重试机制（连接失败、超时等） +5. 将 Handler 层 13 个 Gateway 直接调用下沉到对应 Service 层 +6. Handler 不再持有 `gateway.Client` 引用 + +**Non-Goals:** +- 异步接口（device/info、device/card-info）的轮询/回调处理 +- 新增未封装的 Gateway 端点 +- 修改 Gateway 上游项目 +- 修改 crypto.go（加密/签名逻辑不变） +- 修改响应模型的字段（不确定上游实际返回结构，保持现状） + +## Decisions + +### Decision 1：请求参数序列化方式 + +**选择**：请求结构体通过 `sonic.Marshal` 直接序列化后嵌入 `businessData.params` 字段 + +**理由**： +- 现有请求结构体（`SpeedLimitReq`、`WiFiReq` 等）已有正确的 `json` tag +- 直接序列化后再嵌入 params，比手动构建 map 更安全、更不易出错 +- 保持 `doRequest` 的签名不变，只改变调用方式 + +**实现**： +```go +// 之前 +params := map[string]interface{}{ + "cardNo": req.CardNo, + "speedLimit": req.SpeedLimit, +} +businessData := map[string]interface{}{"params": params} + +// 之后（方案 A：修改 doRequest 签名） +// doRequest 接收结构体，内部自动包装为 {"params": ...} +resp, err := c.doRequest(ctx, "/device/speed-limit", req) + +// doRequest 内部逻辑变更： +// businessData → 直接是 req 结构体 +// 序列化时自动包装为 {"params": } +``` + +**替代方案**：保留 map 构建但提取为辅助方法 — 更侵入性小但不消除根因 + +### Decision 2：泛型响应解析 + +**选择**：提供 `doRequestWithResponse[T any]` 泛型方法 + +```go +func doRequestWithResponse[T any](ctx context.Context, path string, req interface{}) (*T, error) { + data, err := c.doRequest(ctx, path, req) + if err != nil { + return nil, err + } + var result T + if err := sonic.Unmarshal(data, &result); err != nil { + return nil, errors.Wrap(errors.CodeGatewayInvalidResp, err, "解析 Gateway 响应失败") + } + return &result, nil +} +``` + +**理由**：每个返回结构体的方法都有相同的 unmarshal 模式，泛型可以完全消除 + +### Decision 3：日志集成 + +**选择**：在 `doRequest` 中注入 `*zap.Logger`（通过 Client 构造函数传入） + +**日志内容**： +- 请求：路径、请求体大小 +- 成功响应：路径、耗时 +- 失败响应：路径、耗时、错误码、错误信息 + +**日志级别**： +- 正常请求：`Debug`（避免高频日志影响性能） +- 错误：`Warn`（Gateway 业务错误）或 `Error`（网络错误） + +**理由**： +- 不用全局 `zap.L()`，通过构造函数注入，保持可测试性 +- Debug 级别日志在生产环境默认关闭，不影响性能 + +### Decision 4：重试机制 + +**选择**：在 `doRequest` 内部实现简单重试逻辑 + +**重试条件（仅网络级错误）**： +- 连接失败（`net.Error` 的 `Temporary()`） +- 请求超时（`context.DeadlineExceeded`，仅限 Client 自身超时，非用户 ctx 超时） +- DNS 解析失败 + +**不重试的情况**： +- Gateway 业务错误（code != 200） +- HTTP 状态码错误（4xx、5xx） +- 用户 Context 取消 +- 加密/序列化失败 + +**参数**： +- 默认最大重试 2 次（共 3 次尝试） +- 指数退避：100ms → 300ms +- 通过 `WithRetry(maxRetries int)` 链式方法可配置 + +**理由**：不引入外部重试库（如 `cenkalti/backoff`），保持零新依赖 + +### Decision 5：分层修复策略 + +**选择**：将 Handler 中的 Gateway 调用逐个迁移到对应 Service 层 + +**IotCard Service 新增方法**（6 个）： +- `QueryGatewayStatus(ctx, iccid) → (*gateway.CardStatusResp, error)` — 已有权限检查 + Gateway 调用 +- `QueryGatewayFlow(ctx, iccid) → (*gateway.FlowUsageResp, error)` +- `QueryGatewayRealname(ctx, iccid) → (*gateway.RealnameStatusResp, error)` +- `GetGatewayRealnameLink(ctx, iccid) → (*gateway.RealnameLinkResp, error)` +- `GatewayStopCard(ctx, iccid) → error` — 注意：与已有的 `stop_resume_service.go` 中的 `StopCard` 区分，Handler 层的更简单（直接停卡，无业务逻辑） +- `GatewayStartCard(ctx, iccid) → error` + +**Device Service 新增方法**（7 个）： +- `GetGatewayInfo(ctx, identifier) → (*gateway.DeviceInfoResp, error)` — 包含 identifier→IMEI 转换 +- `GetGatewaySlots(ctx, identifier) → (*gateway.SlotInfoResp, error)` +- `SetGatewaySpeedLimit(ctx, identifier, speedLimit) → error` +- `SetGatewayWiFi(ctx, identifier, req) → error` +- `GatewaySwitchCard(ctx, identifier, targetICCID) → error` +- `GatewayRebootDevice(ctx, identifier) → error` +- `GatewayResetDevice(ctx, identifier) → error` + +**Handler 变更**： +- `IotCardHandler` 移除 `gatewayClient` 字段，改为调用 Service 方法 +- `DeviceHandler` 移除 `gatewayClient` 字段，改为调用 Service 方法 +- `NewIotCardHandler` 和 `NewDeviceHandler` 签名去掉 `gatewayClient` 参数 +- 权限检查（`service.GetByICCID`、`service.GetDeviceByIdentifier`）移入 Service 方法内部 + +**Bootstrap 变更**： +- `handlers.go`：Handler 初始化不再传入 `gatewayClient` +- `services.go`：确保 Device Service 接收 `gatewayClient`（当前未注入） + +### Decision 6：Logger 注入到 Client + +**选择**：`NewClient` 增加 `logger *zap.Logger` 参数 + +```go +func NewClient(baseURL, appID, appSecret string, logger *zap.Logger) *Client +``` + +**理由**： +- 保持依赖注入风格，与项目其他组件一致 +- 不使用全局 logger `zap.L()` + +## Risks / Trade-offs + +| 风险 | 缓解措施 | +|------|----------| +| IotCard Handler 已有的停卡/复机逻辑在 `stop_resume_service.go` 中有更复杂的实现（包含状态更新）| Handler 层的 `StopCard`/`StartCard` 是直接透传，与 `stop_resume_service` 不同。Service 层新增的方法命名区分（`GatewayStopCard` vs `StopCardService`）| +| `doRequest` 签名变更影响所有调用方 | doRequest 保持返回 `json.RawMessage`，新增 `doRequestWithResponse` 泛型方法，渐进迁移 | +| Logger 注入改变 `NewClient` 签名 | 只有 `cmd/api/main.go` 和 `cmd/worker/main.go` 两处调用，改动可控 | +| 重试可能导致写操作重复执行（如 StopCard） | 仅对网络级错误重试，Gateway 已返回 response 的不重试。写操作的幂等性由 Gateway 端保证 | +| 泛型需要 Go 1.18+ | 项目已使用 Go 1.25，无兼容问题 | + +## Open Questions + +1. ~~Device Service 当前没有 `gatewayClient` 注入，需要修改 `NewDeviceService` 构造函数~~ — 已确认需要修改 +2. IotCard Handler 的 `GatewayStopCard`/`GatewayStartCard` 与已有的 `stop_resume_service` 如何命名区分 — 方案：Handler 下沉的方法以 `Gateway` 前缀命名 diff --git a/openspec/changes/archive/2026-03-09-refactor-gateway-client/proposal.md b/openspec/changes/archive/2026-03-09-refactor-gateway-client/proposal.md new file mode 100644 index 0000000..59dee0f --- /dev/null +++ b/openspec/changes/archive/2026-03-09-refactor-gateway-client/proposal.md @@ -0,0 +1,54 @@ +## Why + +当前 `internal/gateway/` 包只是一个薄 HTTP 客户端包装，每个方法手动构建 `map[string]interface{}` 参数、手动 unmarshal 响应，代码高度重复。更严重的是 Handler 层（`iot_card.go` 6 处、`device.go` 7 处）直接调用 `gateway.Client` 跳过了 Service 层，违反了项目 `Handler → Service → Store → Model` 的分层架构。此外缺少请求/响应日志和重试机制，排查问题困难，网络抖动直接导致失败。 + +## What Changes + +### Gateway 包内部重构 +- **消除手动 map 构建**：请求结构体直接序列化，不再手动构建 `map[string]interface{}` +- **泛型响应解析**：提供泛型方法统一处理 `doRequest + unmarshal` 模式，消除每个方法的重复 unmarshal 代码 +- **添加请求/响应日志**：在 `doRequest` 中集成 Zap 日志，记录请求路径、参数摘要、响应状态、耗时等关键信息 +- **添加重试机制**：对网络级错误（连接失败、DNS 解析失败、超时）自动重试，业务错误不重试；默认最多重试 2 次，指数退避 +- **验证响应模型**：对照 Gateway 上游源码验证 `DeviceInfoResp`、`SlotInfoResp` 等响应结构的字段准确性 + +### 分层架构修复（**BREAKING**） +- **IotCard Handler 的 6 个 Gateway 直接调用下沉到 IotCard Service 层**：`QueryCardStatus`、`QueryFlow`、`QueryRealnameStatus`、`GetRealnameLink`、`StopCard`、`StartCard` +- **Device Handler 的 7 个 Gateway 直接调用下沉到 Device Service 层**：`GetDeviceInfo`、`GetSlotInfo`、`SetSpeedLimit`、`SetWiFi`、`SwitchCard`、`RebootDevice`、`ResetDevice` +- Handler 层不再持有 `gateway.Client` 引用，所有 Gateway 调用通过 Service 层发起 + +### 不在本次范围 +- 异步接口（`device/info`、`device/card-info`）的轮询/回调处理 — 暂不处理 +- 新增 Gateway 端点封装 — 只重构已有的 + +## Capabilities + +### New Capabilities +- `gateway-request-logging`: Gateway 请求/响应的日志记录能力，包括请求路径、参数摘要、响应状态码、耗时、错误信息 +- `gateway-retry`: Gateway 网络级错误的自动重试能力，支持指数退避和可配置的重试次数 + +### Modified Capabilities +- `gateway-client`: 消除手动 map 构建、泛型响应解析、请求结构体直接序列化 +- `iot-card`: IotCard Handler 中 6 个 Gateway 直接调用下沉到 Service 层，Handler 不再持有 gateway.Client +- `iot-device`: Device Handler 中 7 个 Gateway 直接调用下沉到 Service 层，Handler 不再持有 gateway.Client + +## Impact + +### 代码变更范围 +- `internal/gateway/client.go` — 添加日志、重试、泛型方法 +- `internal/gateway/device.go` — 消除 map 构建，使用泛型响应解析 +- `internal/gateway/flow_card.go` — 消除 map 构建，使用泛型响应解析 +- `internal/gateway/models.go` — 可能调整请求结构体（添加 JSON tag 使其可直接序列化） +- `internal/handler/admin/iot_card.go` — 移除 `gatewayClient` 依赖，Gateway 调用改为调 Service +- `internal/handler/admin/device.go` — 移除 `gatewayClient` 依赖，Gateway 调用改为调 Service +- `internal/service/iot_card/service.go` — 新增 6 个 Gateway 代理方法 +- `internal/service/device/service.go` — 新增 7 个 Gateway 代理方法 +- `internal/bootstrap/handlers.go` — Handler 初始化不再传入 gatewayClient +- `internal/bootstrap/services.go` — Service 初始化需确保 gatewayClient 注入 + +### API 影响 +- 无 API 签名变更，前端无感知 +- 行为上完全兼容，只是内部调用链路变更 + +### 依赖影响 +- 新增 `go.uber.org/zap` 在 gateway 包中的依赖（项目已有） +- 无新外部依赖 diff --git a/openspec/changes/archive/2026-03-09-refactor-gateway-client/specs/gateway-client/spec.md b/openspec/changes/archive/2026-03-09-refactor-gateway-client/specs/gateway-client/spec.md new file mode 100644 index 0000000..15a39d2 --- /dev/null +++ b/openspec/changes/archive/2026-03-09-refactor-gateway-client/specs/gateway-client/spec.md @@ -0,0 +1,100 @@ +## MODIFIED Requirements + +### Requirement: 统一请求方法 + +系统 SHALL 提供 `doRequest` 方法，统一处理加密、签名、HTTP 请求和响应解析。请求参数 SHALL 直接接收结构体，内部自动序列化并包装为 `{"params": }` 格式。 + +#### Scenario: 请求参数自动序列化 + +- **WHEN** 调用 `doRequest(ctx, "/device/speed-limit", &SpeedLimitReq{CardNo: "xxx", SpeedLimit: 1024})` +- **THEN** 请求结构体自动通过 `sonic.Marshal` 序列化 +- **AND** 序列化结果嵌入 `{"params": <序列化JSON>}` 中进行加密和签名 + +#### Scenario: 成功的 API 调用 + +- **WHEN** 调用 `doRequest(ctx, "/flow-card/status", req)` +- **THEN** 业务数据使用 AES-128-ECB 加密 +- **AND** 请求使用 MD5 签名 +- **AND** HTTP POST 发送到 `{baseURL}/flow-card/status` +- **AND** 响应中的 `data` 字段返回为 `json.RawMessage` + +#### Scenario: 网络错误 + +- **WHEN** HTTP 请求失败（网络中断、DNS 解析失败） +- **THEN** 返回 `CodeGatewayError` 错误 +- **AND** 错误信息包含原始网络错误 + +#### Scenario: 请求超时 + +- **WHEN** HTTP 请求超过配置的超时时间 +- **THEN** 返回 `CodeGatewayTimeout` 错误 +- **AND** Context 超时错误被正确识别 + +#### Scenario: 响应格式错误 + +- **WHEN** Gateway 响应无法解析为 JSON +- **THEN** 返回 `CodeGatewayInvalidResp` 错误 + +#### Scenario: Gateway 业务错误 + +- **WHEN** Gateway 响应中 `code != 200` +- **THEN** 返回 `CodeGatewayError` 错误 +- **AND** 错误信息包含 Gateway 的 code 和 msg + +### Requirement: 泛型响应解析方法 + +系统 SHALL 提供 `doRequestWithResponse[T any]` 泛型方法，自动完成请求发送和响应反序列化。 + +#### Scenario: 自动反序列化响应 + +- **WHEN** 调用 `doRequestWithResponse[CardStatusResp](ctx, "/flow-card/status", req)` +- **THEN** 返回 `*CardStatusResp` 类型的结构体 +- **AND** 内部调用 `doRequest` 获取 `json.RawMessage` 后自动 unmarshal + +#### Scenario: 反序列化失败 + +- **WHEN** Gateway 返回的 JSON 无法匹配目标结构体 +- **THEN** 返回 `CodeGatewayInvalidResp` 错误 +- **AND** 错误信息为 "解析 Gateway 响应失败" + +### Requirement: 请求结构体直接序列化 + +系统 SHALL 消除手动 `map[string]interface{}` 构建，所有业务方法直接将请求结构体传递给 `doRequest` 或 `doRequestWithResponse`。 + +#### Scenario: 设备限速请求 + +- **WHEN** 调用 `SetSpeedLimit(ctx, &SpeedLimitReq{CardNo: "xxx", SpeedLimit: 1024})` +- **THEN** `SpeedLimitReq` 结构体直接序列化为 JSON +- **AND** 不再手动构建 `map[string]interface{}` + +#### Scenario: 流量卡停机请求 + +- **WHEN** 调用 `StopCard(ctx, &CardOperationReq{CardNo: "xxx", Extend: "ext"})` +- **THEN** `CardOperationReq` 结构体直接序列化 +- **AND** `Extend` 字段通过 `json:"extend,omitempty"` 标签在为空时自动省略 + +### Requirement: Gateway 客户端结构 + +系统 SHALL 提供 `gateway.Client` 结构体，封装所有 Gateway API 调用。 + +客户端字段： +- `baseURL string` - Gateway API 基础 URL +- `appID string` - 应用 ID +- `appSecret string` - 应用密钥 +- `httpClient *http.Client` - HTTP 客户端（支持连接复用） +- `timeout time.Duration` - 请求超时时间 +- `logger *zap.Logger` - 日志记录器 +- `maxRetries int` - 最大重试次数 + +#### Scenario: 创建 Gateway 客户端 + +- **WHEN** 调用 `gateway.NewClient(baseURL, appID, appSecret, logger)` +- **THEN** 返回已初始化的 `Client` 实例 +- **AND** HTTP 客户端配置正确（支持 Keep-Alive） +- **AND** 默认最大重试次数为 2 + +#### Scenario: 配置超时时间 + +- **WHEN** 调用 `client.WithTimeout(30 * time.Second)` +- **THEN** 客户端的 `timeout` 字段更新为 30 秒 +- **AND** 返回客户端自身（支持链式调用） diff --git a/openspec/changes/archive/2026-03-09-refactor-gateway-client/specs/gateway-request-logging/spec.md b/openspec/changes/archive/2026-03-09-refactor-gateway-client/specs/gateway-request-logging/spec.md new file mode 100644 index 0000000..7979bd7 --- /dev/null +++ b/openspec/changes/archive/2026-03-09-refactor-gateway-client/specs/gateway-request-logging/spec.md @@ -0,0 +1,33 @@ +## ADDED Requirements + +### Requirement: Gateway 请求日志 + +系统 SHALL 在每次 Gateway API 调用时记录请求日志，包含请求路径和请求体大小。 + +#### Scenario: 正常请求记录 Debug 日志 + +- **WHEN** 调用 `doRequest(ctx, "/flow-card/status", req)` 且请求成功 +- **THEN** 记录 Debug 级别日志 +- **AND** 日志包含字段：`path`（请求路径）、`duration`（耗时） + +#### Scenario: Gateway 业务错误记录 Warn 日志 + +- **WHEN** Gateway 返回 `code != 200` 的业务错误 +- **THEN** 记录 Warn 级别日志 +- **AND** 日志包含字段：`path`、`duration`、`gateway_code`（Gateway 状态码）、`gateway_msg`（Gateway 错误信息） + +#### Scenario: 网络错误记录 Error 日志 + +- **WHEN** HTTP 请求失败（连接失败、超时、DNS 解析失败等） +- **THEN** 记录 Error 级别日志 +- **AND** 日志包含字段：`path`、`duration`、`error`（错误信息） + +### Requirement: Logger 依赖注入 + +系统 SHALL 通过构造函数将 `*zap.Logger` 注入到 `Client` 中。 + +#### Scenario: 创建带日志的客户端 + +- **WHEN** 调用 `gateway.NewClient(baseURL, appID, appSecret, logger)` +- **THEN** 客户端使用传入的 logger 记录日志 +- **AND** 不使用全局 `zap.L()` diff --git a/openspec/changes/archive/2026-03-09-refactor-gateway-client/specs/gateway-retry/spec.md b/openspec/changes/archive/2026-03-09-refactor-gateway-client/specs/gateway-retry/spec.md new file mode 100644 index 0000000..eafb23e --- /dev/null +++ b/openspec/changes/archive/2026-03-09-refactor-gateway-client/specs/gateway-retry/spec.md @@ -0,0 +1,51 @@ +## ADDED Requirements + +### Requirement: 网络级错误自动重试 + +系统 SHALL 在 Gateway API 调用遇到网络级错误时自动重试。 + +#### Scenario: 连接失败自动重试 + +- **WHEN** Gateway HTTP 请求因连接失败（TCP 连接拒绝、DNS 解析失败）失败 +- **THEN** 系统自动重试，最多重试 2 次（共 3 次尝试） +- **AND** 重试间隔使用指数退避（100ms → 300ms） + +#### Scenario: Client 超时自动重试 + +- **WHEN** Gateway HTTP 请求因 Client 配置的超时时间到期而失败 +- **THEN** 系统自动重试 +- **AND** 用户传入的 Context 未被取消 + +#### Scenario: Gateway 业务错误不重试 + +- **WHEN** Gateway 返回 HTTP 200 但业务状态码 `code != 200` +- **THEN** 系统不重试，直接返回业务错误 + +#### Scenario: HTTP 状态码错误不重试 + +- **WHEN** Gateway 返回 HTTP 4xx 或 5xx 状态码 +- **THEN** 系统不重试，直接返回错误 + +#### Scenario: 用户 Context 取消不重试 + +- **WHEN** 用户传入的 Context 被取消 +- **THEN** 系统立即停止，不重试 + +#### Scenario: 加密或序列化错误不重试 + +- **WHEN** 请求参数加密或序列化失败 +- **THEN** 系统不重试，直接返回错误 + +### Requirement: 重试配置 + +系统 SHALL 支持通过链式方法配置重试参数。 + +#### Scenario: 自定义最大重试次数 + +- **WHEN** 调用 `client.WithRetry(3)` 后发起 API 请求 +- **THEN** 网络级错误时最多重试 3 次（共 4 次尝试） + +#### Scenario: 禁用重试 + +- **WHEN** 调用 `client.WithRetry(0)` 后发起 API 请求 +- **THEN** 不进行任何重试 diff --git a/openspec/changes/archive/2026-03-09-refactor-gateway-client/specs/iot-card/spec.md b/openspec/changes/archive/2026-03-09-refactor-gateway-client/specs/iot-card/spec.md new file mode 100644 index 0000000..ea379c9 --- /dev/null +++ b/openspec/changes/archive/2026-03-09-refactor-gateway-client/specs/iot-card/spec.md @@ -0,0 +1,89 @@ +## MODIFIED Requirements + +### Requirement: IotCard Handler 分层修复 + +IotCard Handler SHALL 不再直接持有 `gateway.Client` 引用。所有 Gateway API 调用 SHALL 通过 IotCard Service 层发起。 + +#### Scenario: IotCardHandler 不持有 gatewayClient + +- **WHEN** 创建 `IotCardHandler` 实例 +- **THEN** `NewIotCardHandler` 构造函数不接收 `gateway.Client` 参数 +- **AND** Handler 结构体不包含 `gatewayClient` 字段 + +#### Scenario: 查询卡实时状态通过 Service 调用 + +- **WHEN** Handler 的 `GetGatewayStatus` 方法被调用 +- **THEN** Handler 调用 `service.QueryGatewayStatus(ctx, iccid)` +- **AND** Service 内部完成权限检查 + Gateway API 调用 + +#### Scenario: 查询流量使用通过 Service 调用 + +- **WHEN** Handler 的 `GetGatewayFlow` 方法被调用 +- **THEN** Handler 调用 `service.QueryGatewayFlow(ctx, iccid)` + +#### Scenario: 查询实名状态通过 Service 调用 + +- **WHEN** Handler 的 `GetGatewayRealname` 方法被调用 +- **THEN** Handler 调用 `service.QueryGatewayRealname(ctx, iccid)` + +#### Scenario: 获取实名链接通过 Service 调用 + +- **WHEN** Handler 的 `GetRealnameLink` 方法被调用 +- **THEN** Handler 调用 `service.GetGatewayRealnameLink(ctx, iccid)` + +#### Scenario: 停卡通过 Service 调用 + +- **WHEN** Handler 的 `StopCard` 方法被调用 +- **THEN** Handler 调用 `service.GatewayStopCard(ctx, iccid)` + +#### Scenario: 复机通过 Service 调用 + +- **WHEN** Handler 的 `StartCard` 方法被调用 +- **THEN** Handler 调用 `service.GatewayStartCard(ctx, iccid)` + +### Requirement: IotCard Service Gateway 代理方法 + +IotCard Service SHALL 提供 Gateway API 的代理方法，封装权限检查和 Gateway 调用。 + +#### Scenario: QueryGatewayStatus 方法 + +- **WHEN** 调用 `service.QueryGatewayStatus(ctx, iccid)` +- **THEN** 先通过 `GetByICCID` 验证卡存在且用户有权限 +- **AND** 然后调用 `gatewayClient.QueryCardStatus` +- **AND** 返回 `*gateway.CardStatusResp` + +#### Scenario: QueryGatewayFlow 方法 + +- **WHEN** 调用 `service.QueryGatewayFlow(ctx, iccid)` +- **THEN** 先验证权限，再调用 `gatewayClient.QueryFlow` +- **AND** 返回 `*gateway.FlowUsageResp` + +#### Scenario: QueryGatewayRealname 方法 + +- **WHEN** 调用 `service.QueryGatewayRealname(ctx, iccid)` +- **THEN** 先验证权限，再调用 `gatewayClient.QueryRealnameStatus` +- **AND** 返回 `*gateway.RealnameStatusResp` + +#### Scenario: GetGatewayRealnameLink 方法 + +- **WHEN** 调用 `service.GetGatewayRealnameLink(ctx, iccid)` +- **THEN** 先验证权限，再调用 `gatewayClient.GetRealnameLink` +- **AND** 返回 `*gateway.RealnameLinkResp` + +#### Scenario: GatewayStopCard 方法 + +- **WHEN** 调用 `service.GatewayStopCard(ctx, iccid)` +- **THEN** 先验证权限，再调用 `gatewayClient.StopCard` +- **AND** 返回 error + +#### Scenario: GatewayStartCard 方法 + +- **WHEN** 调用 `service.GatewayStartCard(ctx, iccid)` +- **THEN** 先验证权限，再调用 `gatewayClient.StartCard` +- **AND** 返回 error + +#### Scenario: 卡不存在或无权限 + +- **WHEN** 调用任意 Gateway 代理方法且 ICCID 对应的卡不存在或用户无权限 +- **THEN** 返回 `CodeNotFound` 错误 +- **AND** 错误信息为 "卡不存在或无权限访问" diff --git a/openspec/changes/archive/2026-03-09-refactor-gateway-client/specs/iot-device/spec.md b/openspec/changes/archive/2026-03-09-refactor-gateway-client/specs/iot-device/spec.md new file mode 100644 index 0000000..d6aedaa --- /dev/null +++ b/openspec/changes/archive/2026-03-09-refactor-gateway-client/specs/iot-device/spec.md @@ -0,0 +1,123 @@ +## MODIFIED Requirements + +### Requirement: Device Handler 分层修复 + +Device Handler SHALL 不再直接持有 `gateway.Client` 引用。所有 Gateway API 调用 SHALL 通过 Device Service 层发起。 + +#### Scenario: DeviceHandler 不持有 gatewayClient + +- **WHEN** 创建 `DeviceHandler` 实例 +- **THEN** `NewDeviceHandler` 构造函数不接收 `gateway.Client` 参数 +- **AND** Handler 结构体不包含 `gatewayClient` 字段 + +#### Scenario: 查询设备网关信息通过 Service 调用 + +- **WHEN** Handler 的 `GetGatewayInfo` 方法被调用 +- **THEN** Handler 调用 `service.GetGatewayInfo(ctx, identifier)` + +#### Scenario: 查询设备卡槽信息通过 Service 调用 + +- **WHEN** Handler 的 `GetGatewaySlots` 方法被调用 +- **THEN** Handler 调用 `service.GetGatewaySlots(ctx, identifier)` + +#### Scenario: 设置设备限速通过 Service 调用 + +- **WHEN** Handler 的 `SetSpeedLimit` 方法被调用 +- **THEN** Handler 调用 `service.SetGatewaySpeedLimit(ctx, identifier, speedLimit)` + +#### Scenario: 设置设备 WiFi 通过 Service 调用 + +- **WHEN** Handler 的 `SetWiFi` 方法被调用 +- **THEN** Handler 调用 `service.SetGatewayWiFi(ctx, identifier, req)` + +#### Scenario: 切换设备卡通过 Service 调用 + +- **WHEN** Handler 的 `SwitchCard` 方法被调用 +- **THEN** Handler 调用 `service.GatewaySwitchCard(ctx, identifier, targetICCID)` + +#### Scenario: 重启设备通过 Service 调用 + +- **WHEN** Handler 的 `RebootDevice` 方法被调用 +- **THEN** Handler 调用 `service.GatewayRebootDevice(ctx, identifier)` + +#### Scenario: 恢复出厂设置通过 Service 调用 + +- **WHEN** Handler 的 `ResetDevice` 方法被调用 +- **THEN** Handler 调用 `service.GatewayResetDevice(ctx, identifier)` + +### Requirement: Device Service Gateway 代理方法 + +Device Service SHALL 提供 Gateway API 的代理方法，封装设备标识符解析、IMEI 检查和 Gateway 调用。 + +#### Scenario: GetGatewayInfo 方法 + +- **WHEN** 调用 `service.GetGatewayInfo(ctx, identifier)` +- **THEN** 先通过 `GetDeviceByIdentifier` 查找设备并验证权限 +- **AND** 检查设备 IMEI 不为空 +- **AND** 调用 `gatewayClient.GetDeviceInfo` 传入设备 IMEI +- **AND** 返回 `*gateway.DeviceInfoResp` + +#### Scenario: GetGatewaySlots 方法 + +- **WHEN** 调用 `service.GetGatewaySlots(ctx, identifier)` +- **THEN** 先查找设备、验证 IMEI 不为空 +- **AND** 调用 `gatewayClient.GetSlotInfo` +- **AND** 返回 `*gateway.SlotInfoResp` + +#### Scenario: SetGatewaySpeedLimit 方法 + +- **WHEN** 调用 `service.SetGatewaySpeedLimit(ctx, identifier, speedLimit)` +- **THEN** 先查找设备、验证 IMEI +- **AND** 调用 `gatewayClient.SetSpeedLimit` 传入设备 IMEI 和限速值 + +#### Scenario: SetGatewayWiFi 方法 + +- **WHEN** 调用 `service.SetGatewayWiFi(ctx, identifier, cardNo, ssid, password string, enabled bool)` +- **THEN** 先查找设备、验证 IMEI +- **AND** 调用 `gatewayClient.SetWiFi` 传入设备 IMEI、cardNo（ICCID）、ssid、password、enabled + +#### Scenario: GatewaySwitchCard 方法 + +- **WHEN** 调用 `service.GatewaySwitchCard(ctx, identifier, targetICCID)` +- **THEN** 先查找设备、验证 IMEI +- **AND** 调用 `gatewayClient.SwitchCard` 传入设备 IMEI 作为 cardNo 和目标 ICCID + +#### Scenario: GatewayRebootDevice 方法 + +- **WHEN** 调用 `service.GatewayRebootDevice(ctx, identifier)` +- **THEN** 先查找设备、验证 IMEI +- **AND** 调用 `gatewayClient.RebootDevice` 传入设备 IMEI + +#### Scenario: GatewayResetDevice 方法 + +- **WHEN** 调用 `service.GatewayResetDevice(ctx, identifier)` +- **THEN** 先查找设备、验证 IMEI +- **AND** 调用 `gatewayClient.ResetDevice` 传入设备 IMEI + +#### Scenario: 设备 IMEI 为空 + +- **WHEN** 调用任意 Gateway 代理方法且设备的 IMEI 字段为空 +- **THEN** 返回 `CodeInvalidParam` 错误 +- **AND** 错误信息说明该设备未配置 IMEI + +#### Scenario: 设备不存在或无权限 + +- **WHEN** 调用任意 Gateway 代理方法且标识符无法匹配到设备 +- **THEN** 返回对应的错误（由 `GetDeviceByIdentifier` 返回） + +### Requirement: Device Service 接收 Gateway Client + +Device Service SHALL 在构造函数中接收 `*gateway.Client` 依赖。 + +#### Scenario: Device Service 初始化 + +- **WHEN** 创建 Device Service 实例 +- **THEN** 构造函数接收 `gatewayClient *gateway.Client` 参数 +- **AND** 存储为 Service 的内部字段 +- **AND** `gatewayClient` 可以为 nil（Gateway 配置缺失时） + +#### Scenario: Gateway Client 为 nil 时调用 Gateway 方法 + +- **WHEN** `gatewayClient` 为 nil 且调用任意 Gateway 代理方法 +- **THEN** 返回 `CodeGatewayError` 错误 +- **AND** 错误信息为 "Gateway 客户端未配置" diff --git a/openspec/changes/archive/2026-03-09-refactor-gateway-client/tasks.md b/openspec/changes/archive/2026-03-09-refactor-gateway-client/tasks.md new file mode 100644 index 0000000..eadb5e8 --- /dev/null +++ b/openspec/changes/archive/2026-03-09-refactor-gateway-client/tasks.md @@ -0,0 +1,101 @@ +## 1. Gateway Client 核心重构 + +- [x] 1.1 修改 `Client` 结构体：添加 `logger *zap.Logger` 和 `maxRetries int` 字段 +- [x] 1.2 修改 `NewClient` 签名：增加 `logger *zap.Logger` 参数，默认 `maxRetries = 2` +- [x] 1.3 添加 `WithRetry(maxRetries int) *Client` 链式方法 +- [x] 1.4 修改 `doRequest`：请求参数改为直接接收结构体（`interface{}`），内部自动包装为 `{"params": }` 格式 +- [x] 1.5 在 `doRequest` 中添加请求/响应日志（Debug 级别正常、Warn 级别业务错误、Error 级别网络错误） +- [x] 1.6 在 `doRequest` 中添加网络级错误重试逻辑（指数退避 100ms→300ms，仅对连接失败/Client 超时/DNS 失败重试） +- [x] 1.7 添加 `doRequestWithResponse[T any]` 泛型方法，自动完成 doRequest + unmarshal +- [x] 1.8 更新 `cmd/api/main.go` 和 `cmd/worker/main.go` 中的 `initGateway` 函数，传入 logger +- [x] 1.9 验证：`go build ./...` 编译通过，`lsp_diagnostics` 无错误 + +## 2. 流量卡方法重构（消除 map 构建和重复 unmarshal） + +- [x] 2.1 重构 `QueryCardStatus`：使用 `doRequestWithResponse[CardStatusResp]`，去掉手动 map 构建 +- [x] 2.2 重构 `QueryFlow`：使用 `doRequestWithResponse[FlowUsageResp]` +- [x] 2.3 重构 `QueryRealnameStatus`：使用 `doRequestWithResponse[RealnameStatusResp]` +- [x] 2.4 重构 `StopCard`：直接传 req 给 doRequest，去掉手动 map +- [x] 2.5 重构 `StartCard`：同上 +- [x] 2.6 重构 `GetRealnameLink`：使用 `doRequestWithResponse[RealnameLinkResp]` +- [x] 2.7 验证：`go build ./...` 编译通过，`lsp_diagnostics` 无错误 + +## 3. 设备方法重构（消除 map 构建和重复 unmarshal） + +- [x] 3.1 重构 `GetDeviceInfo`：使用 `doRequestWithResponse[DeviceInfoResp]`，去掉手动 map +- [x] 3.2 重构 `GetSlotInfo`：使用 `doRequestWithResponse[SlotInfoResp]` +- [x] 3.3 重构 `SetSpeedLimit`：直接传 req 给 doRequest +- [x] 3.4 重构 `SetWiFi`：同上 +- [x] 3.5 重构 `SwitchCard`：同上 +- [x] 3.6 重构 `ResetDevice`：同上 +- [x] 3.7 重构 `RebootDevice`：同上 +- [x] 3.8 验证：`go build ./...` 编译通过，`lsp_diagnostics` 无错误 + +## 4. Device Service 注入 Gateway Client + +- [x] 4.1 修改 `internal/service/device/service.go`：Service 结构体添加 `gatewayClient *gateway.Client` 字段 +- [x] 4.2 修改 `New` 构造函数：增加 `gatewayClient *gateway.Client` 参数 +- [x] 4.3 修改 `internal/bootstrap/services.go`：Device Service 初始化时传入 `deps.GatewayClient` +- [x] 4.4 验证：`go build ./...` 编译通过 + +## 5. Device Service Gateway 代理方法 + +- [x] 5.1 实现 `GatewayGetDeviceInfo(ctx, identifier) → (*gateway.DeviceInfoResp, error)`：identifier→设备→检查IMEI→调用 Gateway +- [x] 5.2 实现 `GatewayGetSlotInfo(ctx, identifier) → (*gateway.SlotInfoResp, error)` +- [x] 5.3 实现 `GatewaySetSpeedLimit(ctx, identifier string, req *dto.SetSpeedLimitRequest) → error` +- [x] 5.4 实现 `GatewaySetWiFi(ctx, identifier string, req *dto.SetWiFiRequest) → error` +- [x] 5.5 实现 `GatewaySwitchCard(ctx, identifier string, req *dto.SwitchCardRequest) → error` +- [x] 5.6 实现 `GatewayRebootDevice(ctx, identifier string) → error` +- [x] 5.7 实现 `GatewayResetDevice(ctx, identifier string) → error` +- [x] 5.8 验证：`go build ./...` 编译通过，`lsp_diagnostics` 无错误 + +## 6. IotCard Service Gateway 代理方法 + +- [x] 6.1 实现 `GatewayQueryCardStatus(ctx, iccid) → (*gateway.CardStatusResp, error)`：权限检查→Gateway 调用 +- [x] 6.2 实现 `GatewayQueryFlow(ctx, iccid) → (*gateway.FlowUsageResp, error)` +- [x] 6.3 实现 `GatewayQueryRealnameStatus(ctx, iccid) → (*gateway.RealnameStatusResp, error)` +- [x] 6.4 实现 `GatewayGetRealnameLink(ctx, iccid) → (*gateway.RealnameLinkResp, error)` +- [x] 6.5 实现 `GatewayStopCard(ctx, iccid) → error` +- [x] 6.6 实现 `GatewayStartCard(ctx, iccid) → error` +- [x] 6.7 验证：`go build ./...` 编译通过，`lsp_diagnostics` 无错误 + +## 7. Handler 分层修复 — Device Handler + +- [x] 7.1 修改 `DeviceHandler` 结构体：移除 `gatewayClient` 字段 +- [x] 7.2 修改 `NewDeviceHandler`：移除 `gatewayClient` 参数 +- [x] 7.3 重构 `GetGatewayInfo`：改为调用 `h.service.GatewayGetDeviceInfo(ctx, identifier)` +- [x] 7.4 重构 `GetGatewaySlots`：改为调用 `h.service.GatewayGetSlotInfo(ctx, identifier)` +- [x] 7.5 重构 `SetSpeedLimit`：改为调用 `h.service.GatewaySetSpeedLimit(ctx, identifier, &req)` +- [x] 7.6 重构 `SetWiFi`：改为调用 `h.service.GatewaySetWiFi(ctx, identifier, &req)` +- [x] 7.7 重构 `SwitchCard`：改为调用 `h.service.GatewaySwitchCard(ctx, identifier, &req)` +- [x] 7.8 重构 `RebootDevice`：改为调用 `h.service.GatewayRebootDevice(ctx, identifier)` +- [x] 7.9 重构 `ResetDevice`：改为调用 `h.service.GatewayResetDevice(ctx, identifier)` +- [x] 7.10 移除 `import "github.com/break/junhong_cmp_fiber/internal/gateway"` 导入（如果不再需要） +- [x] 7.11 验证：`go build ./...` 编译通过，`lsp_diagnostics` 无错误 + +## 8. Handler 分层修复 — IotCard Handler + +- [x] 8.1 修改 `IotCardHandler` 结构体：移除 `gatewayClient` 字段 +- [x] 8.2 修改 `NewIotCardHandler`：移除 `gatewayClient` 参数 +- [x] 8.3 重构 `GetGatewayStatus`：改为调用 `h.service.GatewayQueryCardStatus(ctx, iccid)` +- [x] 8.4 重构 `GetGatewayFlow`：改为调用 `h.service.GatewayQueryFlow(ctx, iccid)` +- [x] 8.5 重构 `GetGatewayRealname`：改为调用 `h.service.GatewayQueryRealnameStatus(ctx, iccid)` +- [x] 8.6 重构 `GetRealnameLink`：改为调用 `h.service.GatewayGetRealnameLink(ctx, iccid)` +- [x] 8.7 重构 `StopCard`：改为调用 `h.service.GatewayStopCard(ctx, iccid)` +- [x] 8.8 重构 `StartCard`：改为调用 `h.service.GatewayStartCard(ctx, iccid)` +- [x] 8.9 移除 `import "github.com/break/junhong_cmp_fiber/internal/gateway"` 导入（如果不再需要） +- [x] 8.10 验证：`go build ./...` 编译通过，`lsp_diagnostics` 无错误 + +## 9. Bootstrap 层适配 + +- [x] 9.1 修改 `internal/bootstrap/handlers.go`：`NewIotCardHandler` 不再传入 `deps.GatewayClient` +- [x] 9.2 修改 `internal/bootstrap/handlers.go`：`NewDeviceHandler` 不再传入 `deps.GatewayClient` +- [x] 9.3 验证：`go build ./...` 编译通过，确认所有 Handler/Service/Bootstrap 链路正确 + +## 10. 最终验证 + +- [x] 10.1 `go build ./...` 全量编译通过 +- [x] 10.2 `go vet ./...` 无问题 +- [x] 10.3 所有修改文件 `lsp_diagnostics` 无错误 +- [x] 10.4 确认无遗留的 Handler 层 Gateway 直接调用（grep 验证） +- [x] 10.5 确认 Worker 端（`polling_handler.go`、`queue/handler.go`）不受影响 diff --git a/openspec/specs/gateway-client/spec.md b/openspec/specs/gateway-client/spec.md index e92a25b..2dfe0bb 100644 --- a/openspec/specs/gateway-client/spec.md +++ b/openspec/specs/gateway-client/spec.md @@ -14,12 +14,15 @@ Gateway API 统一客户端，提供 14 个接口的类型安全封装。 - `appSecret string` - 应用密钥 - `httpClient *http.Client` - HTTP 客户端（支持连接复用） - `timeout time.Duration` - 请求超时时间 +- `logger *zap.Logger` - 日志记录器 +- `maxRetries int` - 最大重试次数 #### Scenario: 创建 Gateway 客户端 -- **WHEN** 调用 `gateway.NewClient(baseURL, appID, appSecret)` +- **WHEN** 调用 `gateway.NewClient(baseURL, appID, appSecret, logger)` - **THEN** 返回已初始化的 `Client` 实例 - **AND** HTTP 客户端配置正确（支持 Keep-Alive） +- **AND** 默认最大重试次数为 2 #### Scenario: 配置超时时间 @@ -29,15 +32,21 @@ Gateway API 统一客户端，提供 14 个接口的类型安全封装。 ### Requirement: 统一请求方法 -系统 SHALL 提供 `doRequest` 方法，统一处理加密、签名、HTTP 请求和响应解析。 +系统 SHALL 提供 `doRequest` 方法，统一处理加密、签名、HTTP 请求和响应解析。请求参数 SHALL 直接接收结构体，内部自动序列化并包装为 `{"params": }` 格式。 + +#### Scenario: 请求参数自动序列化 + +- **WHEN** 调用 `doRequest(ctx, "/device/speed-limit", &SpeedLimitReq{CardNo: "xxx", SpeedLimit: 1024})` +- **THEN** 请求结构体自动通过 `sonic.Marshal` 序列化 +- **AND** 序列化结果嵌入 `{"params": <序列化JSON>}` 中进行加密和签名 #### Scenario: 成功的 API 调用 -- **WHEN** 调用 `doRequest(ctx, "/flow-card/status", businessData)` +- **WHEN** 调用 `doRequest(ctx, "/flow-card/status", req)` - **THEN** 业务数据使用 AES-128-ECB 加密 - **AND** 请求使用 MD5 签名 - **AND** HTTP POST 发送到 `{baseURL}/flow-card/status` -- **AND** 响应中的 `data` 字段解密并返回 +- **AND** 响应中的 `data` 字段返回为 `json.RawMessage` #### Scenario: 网络错误 @@ -55,7 +64,7 @@ Gateway API 统一客户端，提供 14 个接口的类型安全封装。 - **WHEN** Gateway 响应无法解析为 JSON - **THEN** 返回 `CodeGatewayInvalidResp` 错误 -- **AND** 错误信息包含原始响应内容（限制 200 字符） +- **AND** 错误信息包含原始响应内容 #### Scenario: Gateway 业务错误 @@ -63,6 +72,37 @@ Gateway API 统一客户端，提供 14 个接口的类型安全封装。 - **THEN** 返回 `CodeGatewayError` 错误 - **AND** 错误信息包含 Gateway 的 code 和 msg +### Requirement: 泛型响应解析方法 + +系统 SHALL 提供 `doRequestWithResponse[T any]` 泛型方法，自动完成请求发送和响应反序列化。 + +#### Scenario: 自动反序列化响应 + +- **WHEN** 调用 `doRequestWithResponse[CardStatusResp](ctx, "/flow-card/status", req)` +- **THEN** 返回 `*CardStatusResp` 类型的结构体 +- **AND** 内部调用 `doRequest` 获取 `json.RawMessage` 后自动 unmarshal + +#### Scenario: 反序列化失败 + +- **WHEN** Gateway 返回的 JSON 无法匹配目标结构体 +- **THEN** 返回 `CodeGatewayInvalidResp` 错误 +- **AND** 错误信息为 "解析 Gateway 响应失败" + +### Requirement: 请求结构体直接序列化 + +系统 SHALL 消除手动 `map[string]interface{}` 构建，所有业务方法直接将请求结构体传递给 `doRequest` 或 `doRequestWithResponse`。 + +#### Scenario: 设备限速请求 + +- **WHEN** 调用 `SetSpeedLimit(ctx, &SpeedLimitReq{CardNo: "xxx", SpeedLimit: 1024})` +- **THEN** `SpeedLimitReq` 结构体直接序列化为 JSON +- **AND** 不再手动构建 `map[string]interface{}` + +#### Scenario: 流量卡停机请求 + +- **WHEN** 调用 `StopCard(ctx, &CardOperationReq{CardNo: "xxx", Extend: "ext"})` +- **THEN** `CardOperationReq` 结构体直接序列化 +- **AND** `Extend` 字段通过 `json:"extend,omitempty"` 标签在为空时自动省略 ### Requirement: 流量卡 API 封装 系统 SHALL 提供 7 个流量卡相关的 API 方法。 diff --git a/openspec/specs/gateway-request-logging/spec.md b/openspec/specs/gateway-request-logging/spec.md new file mode 100644 index 0000000..a0fb00d --- /dev/null +++ b/openspec/specs/gateway-request-logging/spec.md @@ -0,0 +1,39 @@ +# Gateway Request Logging + +## Purpose + +Gateway 请求日志记录，在每次 Gateway API 调用时按结果级别记录请求日志，便于问题排查和运维监控。 + +## ADDED Requirements + +### Requirement: Gateway 请求日志 + +系统 SHALL 在每次 Gateway API 调用时记录请求日志，包含请求路径和请求体大小。 + +#### Scenario: 正常请求记录 Debug 日志 + +- **WHEN** 调用 `doRequest(ctx, "/flow-card/status", req)` 且请求成功 +- **THEN** 记录 Debug 级别日志 +- **AND** 日志包含字段：`path`（请求路径）、`duration`（耗时） + +#### Scenario: Gateway 业务错误记录 Warn 日志 + +- **WHEN** Gateway 返回 `code != 200` 的业务错误 +- **THEN** 记录 Warn 级别日志 +- **AND** 日志包含字段：`path`、`duration`、`gateway_code`（Gateway 状态码）、`gateway_msg`（Gateway 错误信息） + +#### Scenario: 网络错误记录 Error 日志 + +- **WHEN** HTTP 请求失败（连接失败、超时、DNS 解析失败等） +- **THEN** 记录 Error 级别日志 +- **AND** 日志包含字段：`path`、`duration`、`error`（错误信息） + +### Requirement: Logger 依赖注入 + +系统 SHALL 通过构造函数将 `*zap.Logger` 注入到 `Client` 中。 + +#### Scenario: 创建带日志的客户端 + +- **WHEN** 调用 `gateway.NewClient(baseURL, appID, appSecret, logger)` +- **THEN** 客户端使用传入的 logger 记录日志 +- **AND** 不使用全局 `zap.L()` diff --git a/openspec/specs/gateway-retry/spec.md b/openspec/specs/gateway-retry/spec.md new file mode 100644 index 0000000..b94cdd9 --- /dev/null +++ b/openspec/specs/gateway-retry/spec.md @@ -0,0 +1,57 @@ +# Gateway Retry + +## Purpose + +Gateway 请求自动重试机制，在网络级错误时自动重试，提高 Gateway API 调用的可靠性。 + +## ADDED Requirements + +### Requirement: 网络级错误自动重试 + +系统 SHALL 在 Gateway API 调用遇到网络级错误时自动重试。 + +#### Scenario: 连接失败自动重试 + +- **WHEN** Gateway HTTP 请求因连接失败（TCP 连接拒绝、DNS 解析失败）失败 +- **THEN** 系统自动重试，最多重试 2 次（共 3 次尝试） +- **AND** 重试间隔使用指数退避（100ms → 300ms） + +#### Scenario: Client 超时自动重试 + +- **WHEN** Gateway HTTP 请求因 Client 配置的超时时间到期而失败 +- **THEN** 系统自动重试 +- **AND** 用户传入的 Context 未被取消 + +#### Scenario: Gateway 业务错误不重试 + +- **WHEN** Gateway 返回 HTTP 200 但业务状态码 `code != 200` +- **THEN** 系统不重试，直接返回业务错误 + +#### Scenario: HTTP 状态码错误不重试 + +- **WHEN** Gateway 返回 HTTP 4xx 或 5xx 状态码 +- **THEN** 系统不重试，直接返回错误 + +#### Scenario: 用户 Context 取消不重试 + +- **WHEN** 用户传入的 Context 被取消 +- **THEN** 系统立即停止，不重试 + +#### Scenario: 加密或序列化错误不重试 + +- **WHEN** 请求参数加密或序列化失败 +- **THEN** 系统不重试，直接返回错误 + +### Requirement: 重试配置 + +系统 SHALL 支持通过链式方法配置重试参数。 + +#### Scenario: 自定义最大重试次数 + +- **WHEN** 调用 `client.WithRetry(3)` 后发起 API 请求 +- **THEN** 网络级错误时最多重试 3 次（共 4 次尝试） + +#### Scenario: 禁用重试 + +- **WHEN** 调用 `client.WithRetry(0)` 后发起 API 请求 +- **THEN** 不进行任何重试 diff --git a/openspec/specs/iot-card/spec.md b/openspec/specs/iot-card/spec.md index c678f56..8d53eaf 100644 --- a/openspec/specs/iot-card/spec.md +++ b/openspec/specs/iot-card/spec.md @@ -624,3 +624,93 @@ This capability supports: - **WHEN** 系统时间到达每月1号 00:00:00 - **THEN** 系统重置所有 data_reset_cycle=monthly 的套餐 data_usage_mb=0 + +--- + +### Requirement: IotCard Handler 分层修复 + +IotCard Handler SHALL 不再直接持有 `gateway.Client` 引用。所有 Gateway API 调用 SHALL 通过 IotCard Service 层发起。 + +#### Scenario: IotCardHandler 不持有 gatewayClient + +- **WHEN** 创建 `IotCardHandler` 实例 +- **THEN** `NewIotCardHandler` 构造函数不接收 `gateway.Client` 参数 +- **AND** Handler 结构体不包含 `gatewayClient` 字段 + +#### Scenario: 查询卡实时状态通过 Service 调用 + +- **WHEN** Handler 的 `GetGatewayStatus` 方法被调用 +- **THEN** Handler 调用 `service.QueryGatewayStatus(ctx, iccid)` +- **AND** Service 内部完成权限检查 + Gateway API 调用 + +#### Scenario: 查询流量使用通过 Service 调用 + +- **WHEN** Handler 的 `GetGatewayFlow` 方法被调用 +- **THEN** Handler 调用 `service.QueryGatewayFlow(ctx, iccid)` + +#### Scenario: 查询实名状态通过 Service 调用 + +- **WHEN** Handler 的 `GetGatewayRealname` 方法被调用 +- **THEN** Handler 调用 `service.QueryGatewayRealname(ctx, iccid)` + +#### Scenario: 获取实名链接通过 Service 调用 + +- **WHEN** Handler 的 `GetRealnameLink` 方法被调用 +- **THEN** Handler 调用 `service.GetGatewayRealnameLink(ctx, iccid)` + +#### Scenario: 停卡通过 Service 调用 + +- **WHEN** Handler 的 `StopCard` 方法被调用 +- **THEN** Handler 调用 `service.GatewayStopCard(ctx, iccid)` + +#### Scenario: 复机通过 Service 调用 + +- **WHEN** Handler 的 `StartCard` 方法被调用 +- **THEN** Handler 调用 `service.GatewayStartCard(ctx, iccid)` + +### Requirement: IotCard Service Gateway 代理方法 + +IotCard Service SHALL 提供 Gateway API 的代理方法，封装权限检查和 Gateway 调用。 + +#### Scenario: QueryGatewayStatus 方法 + +- **WHEN** 调用 `service.QueryGatewayStatus(ctx, iccid)` +- **THEN** 先通过 `GetByICCID` 验证卡存在且用户有权限 +- **AND** 然后调用 `gatewayClient.QueryCardStatus` +- **AND** 返回 `*gateway.CardStatusResp` + +#### Scenario: QueryGatewayFlow 方法 + +- **WHEN** 调用 `service.QueryGatewayFlow(ctx, iccid)` +- **THEN** 先验证权限，再调用 `gatewayClient.QueryFlow` +- **AND** 返回 `*gateway.FlowUsageResp` + +#### Scenario: QueryGatewayRealname 方法 + +- **WHEN** 调用 `service.QueryGatewayRealname(ctx, iccid)` +- **THEN** 先验证权限，再调用 `gatewayClient.QueryRealnameStatus` +- **AND** 返回 `*gateway.RealnameStatusResp` + +#### Scenario: GetGatewayRealnameLink 方法 + +- **WHEN** 调用 `service.GetGatewayRealnameLink(ctx, iccid)` +- **THEN** 先验证权限，再调用 `gatewayClient.GetRealnameLink` +- **AND** 返回 `*gateway.RealnameLinkResp` + +#### Scenario: GatewayStopCard 方法 + +- **WHEN** 调用 `service.GatewayStopCard(ctx, iccid)` +- **THEN** 先验证权限，再调用 `gatewayClient.StopCard` +- **AND** 返回 error + +#### Scenario: GatewayStartCard 方法 + +- **WHEN** 调用 `service.GatewayStartCard(ctx, iccid)` +- **THEN** 先验证权限，再调用 `gatewayClient.StartCard` +- **AND** 返回 error + +#### Scenario: 卡不存在或无权限 + +- **WHEN** 调用任意 Gateway 代理方法且 ICCID 对应的卡不存在或用户无权限 +- **THEN** 返回 `CodeNotFound` 错误 +- **AND** 错误信息为 "卡不存在或无权限访问" diff --git a/openspec/specs/iot-device/spec.md b/openspec/specs/iot-device/spec.md index f6ac730..89db860 100644 --- a/openspec/specs/iot-device/spec.md +++ b/openspec/specs/iot-device/spec.md @@ -389,3 +389,127 @@ func (DeviceSimBinding) TableName() string { - **WHEN** 开发者需要查找或修改 DeviceSimBinding 模型 - **THEN** 模型定义位于 `internal/model/device_sim_binding.go` 文件中,而非混杂在 `package.go` 中 + +--- + +### Requirement: Device Handler 分层修复 + +Device Handler SHALL 不再直接持有 `gateway.Client` 引用。所有 Gateway API 调用 SHALL 通过 Device Service 层发起。 + +#### Scenario: DeviceHandler 不持有 gatewayClient + +- **WHEN** 创建 `DeviceHandler` 实例 +- **THEN** `NewDeviceHandler` 构造函数不接收 `gateway.Client` 参数 +- **AND** Handler 结构体不包含 `gatewayClient` 字段 + +#### Scenario: 查询设备网关信息通过 Service 调用 + +- **WHEN** Handler 的 `GetGatewayInfo` 方法被调用 +- **THEN** Handler 调用 `service.GetGatewayInfo(ctx, identifier)` + +#### Scenario: 查询设备卡槽信息通过 Service 调用 + +- **WHEN** Handler 的 `GetGatewaySlots` 方法被调用 +- **THEN** Handler 调用 `service.GetGatewaySlots(ctx, identifier)` + +#### Scenario: 设置设备限速通过 Service 调用 + +- **WHEN** Handler 的 `SetSpeedLimit` 方法被调用 +- **THEN** Handler 调用 `service.SetGatewaySpeedLimit(ctx, identifier, speedLimit)` + +#### Scenario: 设置设备 WiFi 通过 Service 调用 + +- **WHEN** Handler 的 `SetWiFi` 方法被调用 +- **THEN** Handler 调用 `service.SetGatewayWiFi(ctx, identifier, req)` + +#### Scenario: 切换设备卡通过 Service 调用 + +- **WHEN** Handler 的 `SwitchCard` 方法被调用 +- **THEN** Handler 调用 `service.GatewaySwitchCard(ctx, identifier, targetICCID)` + +#### Scenario: 重启设备通过 Service 调用 + +- **WHEN** Handler 的 `RebootDevice` 方法被调用 +- **THEN** Handler 调用 `service.GatewayRebootDevice(ctx, identifier)` + +#### Scenario: 恢复出厂设置通过 Service 调用 + +- **WHEN** Handler 的 `ResetDevice` 方法被调用 +- **THEN** Handler 调用 `service.GatewayResetDevice(ctx, identifier)` + +### Requirement: Device Service Gateway 代理方法 + +Device Service SHALL 提供 Gateway API 的代理方法，封装设备标识符解析、IMEI 检查和 Gateway 调用。 + +#### Scenario: GetGatewayInfo 方法 + +- **WHEN** 调用 `service.GetGatewayInfo(ctx, identifier)` +- **THEN** 先通过 `GetDeviceByIdentifier` 查找设备并验证权限 +- **AND** 检查设备 IMEI 不为空 +- **AND** 调用 `gatewayClient.GetDeviceInfo` 传入设备 IMEI +- **AND** 返回 `*gateway.DeviceInfoResp` + +#### Scenario: GetGatewaySlots 方法 + +- **WHEN** 调用 `service.GetGatewaySlots(ctx, identifier)` +- **THEN** 先查找设备、验证 IMEI 不为空 +- **AND** 调用 `gatewayClient.GetSlotInfo` +- **AND** 返回 `*gateway.SlotInfoResp` + +#### Scenario: SetGatewaySpeedLimit 方法 + +- **WHEN** 调用 `service.SetGatewaySpeedLimit(ctx, identifier, speedLimit)` +- **THEN** 先查找设备、验证 IMEI +- **AND** 调用 `gatewayClient.SetSpeedLimit` 传入设备 IMEI 和限速值 + +#### Scenario: SetGatewayWiFi 方法 + +- **WHEN** 调用 `service.SetGatewayWiFi(ctx, identifier, cardNo, ssid, password string, enabled bool)` +- **THEN** 先查找设备、验证 IMEI +- **AND** 调用 `gatewayClient.SetWiFi` 传入设备 IMEI、cardNo（ICCID）、ssid、password、enabled + +#### Scenario: GatewaySwitchCard 方法 + +- **WHEN** 调用 `service.GatewaySwitchCard(ctx, identifier, targetICCID)` +- **THEN** 先查找设备、验证 IMEI +- **AND** 调用 `gatewayClient.SwitchCard` 传入设备 IMEI 作为 cardNo 和目标 ICCID + +#### Scenario: GatewayRebootDevice 方法 + +- **WHEN** 调用 `service.GatewayRebootDevice(ctx, identifier)` +- **THEN** 先查找设备、验证 IMEI +- **AND** 调用 `gatewayClient.RebootDevice` 传入设备 IMEI + +#### Scenario: GatewayResetDevice 方法 + +- **WHEN** 调用 `service.GatewayResetDevice(ctx, identifier)` +- **THEN** 先查找设备、验证 IMEI +- **AND** 调用 `gatewayClient.ResetDevice` 传入设备 IMEI + +#### Scenario: 设备 IMEI 为空 + +- **WHEN** 调用任意 Gateway 代理方法且设备的 IMEI 字段为空 +- **THEN** 返回 `CodeInvalidParam` 错误 +- **AND** 错误信息说明该设备未配置 IMEI + +#### Scenario: 设备不存在或无权限 + +- **WHEN** 调用任意 Gateway 代理方法且标识符无法匹配到设备 +- **THEN** 返回对应的错误（由 `GetDeviceByIdentifier` 返回） + +### Requirement: Device Service 接收 Gateway Client + +Device Service SHALL 在构造函数中接收 `*gateway.Client` 依赖。 + +#### Scenario: Device Service 初始化 + +- **WHEN** 创建 Device Service 实例 +- **THEN** 构造函数接收 `gatewayClient *gateway.Client` 参数 +- **AND** 存储为 Service 的内部字段 +- **AND** `gatewayClient` 可以为 nil（Gateway 配置缺失时） + +#### Scenario: Gateway Client 为 nil 时调用 Gateway 方法 + +- **WHEN** `gatewayClient` 为 nil 且调用任意 Gateway 代理方法 +- **THEN** 返回 `CodeGatewayError` 错误 +- **AND** 错误信息为 "Gateway 客户端未配置" diff --git a/pkg/openapi/handlers.go b/pkg/openapi/handlers.go index 5a4d8c1..354f09e 100644 --- a/pkg/openapi/handlers.go +++ b/pkg/openapi/handlers.go @@ -28,9 +28,9 @@ func BuildDocHandlers() *bootstrap.Handlers { EnterpriseDeviceH5: h5.NewEnterpriseDeviceHandler(nil), Authorization: admin.NewAuthorizationHandler(nil), MyCommission: admin.NewMyCommissionHandler(nil), - IotCard: admin.NewIotCardHandler(nil, nil), + IotCard: admin.NewIotCardHandler(nil), IotCardImport: admin.NewIotCardImportHandler(nil), - Device: admin.NewDeviceHandler(nil, nil), + Device: admin.NewDeviceHandler(nil), DeviceImport: admin.NewDeviceImportHandler(nil), AssetAllocationRecord: admin.NewAssetAllocationRecordHandler(nil), Storage: admin.NewStorageHandler(nil),