break
370fd3e67f
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 10m49s
55 lines
2.7 KiB
Markdown
55 lines
2.7 KiB
Markdown
# 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`（查询预充值钱包流水）。
|