# agent-open-api 当前行为

## Purpose

描述代理开放接口认证与店铺数据范围的当前行为。

## Requirements

### Requirement: 开放接口认证

系统 SHALL 在代理开放接口执行业务前校验调用方身份与请求签名。

#### Scenario: 开放接口认证

- **GIVEN** 请求缺少、伪造或过期的认证材料
- **WHEN** 调用任一代理开放接口
- **THEN** 请求被拒绝且不执行资源或资金变化

### Requirement: 开放接口数据范围

系统 SHALL 仅允许代理访问其店铺数据范围内的卡、套餐和钱包。

#### Scenario: 开放接口数据范围

- **GIVEN** 代理请求其他店铺资源
- **WHEN** 查询或写入
- **THEN** 请求被统一拒绝且不泄露资源存在性

### Requirement: 代理开放接口查询不触发可靠卡观测

系统 SHALL 对卡流量、卡状态、实名状态和设备流量查询返回当前本地业务事实，且 MUST NOT 因查询成功而提交卡观测序列、展开设备绑定卡观测或安排 Gateway 后台刷新任务。

#### Scenario: 查询单卡本地事实

- **WHEN** 已通过认证和数据范围校验的代理查询单卡流量、状态或实名状态
- **THEN** 系统返回当前本地业务事实，且不创建卡观测序列或后台观测任务

#### Scenario: 查询设备流量

- **WHEN** 已通过认证和数据范围校验的代理查询设备流量，或以设备标识查询卡流量
- **THEN** 系统返回当前本地业务事实，且不展开该设备的绑定卡来创建后台观测任务

#### Scenario: 查询后本地事实仍可能由既有机制更新

- **WHEN** 代理完成上述查询后发生既有轮询、回调或可靠业务事件驱动的本地事实更新
- **THEN** 系统按对应既有机制更新本地事实，查询请求本身不承担触发该更新的责任

## 可达操作索引

本节只用于入口导航，不是行为 Requirement；业务义务以上述 Requirements 为准。

### 代理开放接口

`GET /api/open/v1/cards/realname-status`（查询单卡实名状态）；`POST /api/open/v1/cards/resume`（机卡分离卡复机）；`GET /api/open/v1/cards/status`（查询单卡状态）；`GET /api/open/v1/cards/traffic`（查询单卡或设备流量）；`POST /api/open/v1/devices/reboot`（重启设备）；`POST /api/open/v1/devices/reset`（恢复出厂设置）；`POST /api/open/v1/devices/switch-card`（切网（多卡设备切换 ICCID））；`GET /api/open/v1/devices/traffic`（查询设备套餐内流量）；`GET /api/open/v1/packages`（查询套餐列表）；`GET /api/open/v1/wallet/balance`（查询预充值钱包余额）；`POST /api/open/v1/wallet/package-orders`（钱包套餐购买）；`GET /api/open/v1/wallet/transactions`（查询预充值钱包流水）。