设备的部分改造

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** 不进行任何重试