设备的部分改造

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** 错误信息为 "卡不存在或无权限访问"