# Gateway 接入契约

## 元数据

- Owner：IoT Gateway 适配维护人
- 实现：`internal/gateway/`
- 核验日期：2026-08-07
- 证据：`internal/gateway/client.go`、`crypto.go`、`card_status.go`、`flow_card.go`、`device.go`

## 当前实际使用范围

Gateway 是运营商流量卡、实名、停复机、限速和设备信息的统一封装入口。具体路径、请求字段和响应字段以同目录详细协议与 `internal/gateway/*.go` 的实际调用交集为准；文档中出现但代码未调用的接口不视为系统能力。

## 配置、认证与报文

配置键为 `gateway.base_url`、`gateway.app_id`、`gateway.app_secret`、`gateway.timeout`。业务参数先包装为 `{"params": ...}`，使用 AppSecret 做 AES-128-ECB 加密；外层请求含 `appId`、`data`、`sign`、`timestamp`，签名使用 MD5。HTTP 方法统一为 POST，内容类型为 `application/json;charset=utf-8`。HTTP 200 且 Gateway `code=200` 才算成功，`data` 再按具体能力解码。

## 超时、重试与幂等

客户端默认超时 60 秒；生效配置可覆盖。默认最多重试 2 次，即最多 3 次尝试，退避为 100ms、200ms，更多重试时封顶 300ms。仅客户端超时、连接和 DNS 等网络级错误重试；用户 Context 取消、HTTP 非 200、响应解析失败和 Gateway 业务码失败不重试。每次尝试重新生成时间戳与签名。

查询天然只读；停复机、限速等写操作的幂等和状态条件由调用它的业务 Service 承担，Gateway 客户端本身不提供幂等键。

## 安全、错误与验证

AppSecret、加密前业务数据、完整身份标识不得写入本文或普通日志；当前客户端存在请求结构日志，运行环境必须依赖日志脱敏策略。Gateway 错误映射为项目 `CodeGatewayError`、`CodeGatewayTimeout` 或 `CodeGatewayInvalidResp`。

可复现静态证据：`internal/gateway/client.go`、`internal/gateway/crypto.go` 及同目录能力文件。真实写操作可能改变卡或设备状态，本次只允许静态核对和隔离账号只读验证，不调用生产写接口。

协议、路径、认证、成功码、超时或重试分类变化时更新本文。