提案

2026-06-02 16:56:18 +08:00
parent a6cd550b94
commit 36e68e6672
6 changed files with 269 additions and 0 deletions
--- a/openspec/changes/add-open-api-device-endpoints/specs/open-api-device-operations/spec.md
+++ b/openspec/changes/add-open-api-device-endpoints/specs/open-api-device-operations/spec.md
@@ -0,0 +1,87 @@
+# open-api-device-operations Specification
+
+## ADDED Requirements
+
+### Requirement: 设备切网开放接口
+
+系统 SHALL 提供 `POST /api/open/v1/devices/switch-card` 接口，允许代理对多卡设备执行切网操作（切换到指定 ICCID）。请求 body MUST 包含 `device_no`（虚拟号或 IMEI）和 `iccid`（目标卡 ICCID）。
+
+系统 MUST 校验该设备的 `shop_id` 在当前代理管辖店铺范围内，否则返回 `CodeForbidden`。权限校验通过后，系统 MUST 复用 `device.Service.GatewaySwitchCard` 执行切网，底层调用 Gateway 接口。
+
+响应 data MUST 为空对象（操作成功即可）。
+
+#### Scenario: 切网成功
+
+- **WHEN** 代理对管辖范围内的多卡设备传入有效目标 ICCID 执行切网
+- **THEN** 系统调用 Gateway 切换设备到目标 ICCID，返回成功
+
+#### Scenario: 无权限设备切网
+
+- **WHEN** 代理对不在自己管辖店铺范围内的设备执行切网
+- **THEN** 系统返回 `CodeForbidden`，不调用 Gateway
+
+#### Scenario: 设备标识符不存在
+
+- **WHEN** 代理传入的 `device_no` 无法解析为任何设备
+- **THEN** 系统返回 `CodeForbidden`，消息为"无权限操作该资源或资源不存在"
+
+---
+
+### Requirement: 设备重启开放接口
+
+系统 SHALL 提供 `POST /api/open/v1/devices/reboot` 接口，允许代理对设备执行重启操作。请求 body MUST 包含 `device_no`（虚拟号或 IMEI）。
+
+系统 MUST 校验该设备的 `shop_id` 在当前代理管辖店铺范围内，否则返回 `CodeForbidden`。权限校验通过后，系统 MUST 复用 `device.Service.GatewayRebootDevice` 执行重启。
+
+响应 data MUST 为空对象。
+
+#### Scenario: 重启成功
+
+- **WHEN** 代理对管辖范围内的设备执行重启
+- **THEN** 系统调用 Gateway 重启设备，返回成功
+
+#### Scenario: 无权限设备重启
+
+- **WHEN** 代理对不在自己管辖店铺范围内的设备执行重启
+- **THEN** 系统返回 `CodeForbidden`，不调用 Gateway
+
+---
+
+### Requirement: 设备恢复出厂开放接口
+
+系统 SHALL 提供 `POST /api/open/v1/devices/reset` 接口，允许代理对设备执行恢复出厂设置操作。请求 body MUST 包含 `device_no`（虚拟号或 IMEI）。
+
+系统 MUST 校验该设备的 `shop_id` 在当前代理管辖店铺范围内，否则返回 `CodeForbidden`。权限校验通过后，系统 MUST 复用 `device.Service.GatewayResetDevice` 执行恢复出厂。
+
+响应 data MUST 为空对象。
+
+#### Scenario: 恢复出厂成功
+
+- **WHEN** 代理对管辖范围内的设备执行恢复出厂
+- **THEN** 系统调用 Gateway 恢复设备出厂设置，返回成功
+
+#### Scenario: 无权限设备恢复出厂
+
+- **WHEN** 代理对不在自己管辖店铺范围内的设备执行恢复出厂
+- **THEN** 系统返回 `CodeForbidden`，不调用 Gateway
+
+---
+
+### Requirement: 设备操作开放接口权限校验
+
+系统 SHALL 对所有设备操作开放接口（switch-card、reboot、reset）统一执行权限校验。校验逻辑 MUST 为：通过设备标识符（虚拟号或 IMEI）查询设备，若设备不存在或 `device.ShopID` 不在当前代理的 `SubordinateShopIDs` 中，则返回 `CodeForbidden`，消息为"无权限操作该资源或资源不存在"，不区分"不存在"与"无权限"以防止信息泄露。
+
+#### Scenario: 设备属于代理管辖店铺
+
+- **WHEN** 设备的 `shop_id` 在代理的 `SubordinateShopIDs` 中
+- **THEN** 系统允许执行操作
+
+#### Scenario: 设备不属于代理管辖店铺
+
+- **WHEN** 设备的 `shop_id` 不在代理的 `SubordinateShopIDs` 中
+- **THEN** 系统返回 `CodeForbidden`，消息为"无权限操作该资源或资源不存在"
+
+#### Scenario: 设备 shop_id 为 NULL（平台库存）
+
+- **WHEN** 设备的 `shop_id` 为 NULL（平台库存设备）
+- **THEN** 系统返回 `CodeForbidden`，代理无权操作平台库存设备
--- a/openspec/changes/add-open-api-device-endpoints/specs/open-api-device-traffic/spec.md
+++ b/openspec/changes/add-open-api-device-endpoints/specs/open-api-device-traffic/spec.md
@@ -0,0 +1,53 @@
+# open-api-device-traffic Specification
+
+## ADDED Requirements
+
+### Requirement: 设备套餐内流量查询开放接口
+
+系统 SHALL 提供 `GET /api/open/v1/devices/traffic` 接口，按设备标识符查询设备级套餐内流量。请求参数 `device_no` MUST 支持虚拟号或 IMEI 中任一种可解析为设备的标识。系统 MUST 校验该设备的 `shop_id` 在当前代理管辖店铺范围内（`device.ShopID IN SubordinateShopIDs`），否则返回 `CodeForbidden`。
+
+接口 MUST 只返回 `usage_type='device'` 的套餐使用记录，不返回单卡套餐信息。
+
+响应 data MUST 包含：
+- `device_no`：请求传入的设备标识符
+- `active_total_flow_mb`：当前生效套餐总流量汇总
+- `active_used_flow_mb`：当前生效套餐已用流量汇总
+- `active_remaining_flow_mb`：当前生效套餐剩余流量汇总
+- `active_expires_at`：当前生效套餐中最晚过期时间
+- `active_packages`：当前生效套餐列表
+- `pending_packages`：待生效套餐列表
+
+流量口径 MUST 与 `/cards/traffic` 保持一致：
+- 总流量使用 `data_limit_mb`
+- 已用流量使用 `min(data_usage_mb * display_gain_ratio_snapshot, data_limit_mb)`
+- 剩余流量使用 `max(data_limit_mb - used_flow_mb, 0)`
+- 响应 MUST NOT 包含虚流量、停机阈值等内部字段
+
+`active_packages` 每项 MUST 包含：`package_code`、`total_flow_mb`、`used_flow_mb`、`remaining_flow_mb`、`expires_at`、`start_at`、`package_name`、`series_name`、`package_type`、`package_type_name`。
+
+`pending_packages` 每项 MUST 包含：`package_code`、`total_flow_mb`、`package_name`、`series_name`、`package_type`、`package_type_name`、`valid_days`、`priority`。
+
+#### Scenario: 查询有生效套餐的设备流量
+
+- **WHEN** 代理查询自己管辖范围内的设备，且该设备存在生效中的设备级套餐
+- **THEN** 系统返回生效套餐列表、总流量、已用流量、剩余流量和最晚过期时间
+
+#### Scenario: 查询待生效套餐
+
+- **WHEN** 代理查询设备流量，且该设备存在待生效的设备级套餐
+- **THEN** 系统在 `pending_packages` 中返回套餐编码、真总流量、套餐名称、系列名称、套餐类型、有效天数和生效优先级
+
+#### Scenario: 查询无套餐的设备
+
+- **WHEN** 代理查询有权限但当前无生效或待生效设备级套餐的设备
+- **THEN** 系统返回空套餐列表，流量数值为 0
+
+#### Scenario: 无权限设备
+
+- **WHEN** 代理查询不在自己管辖店铺范围内的设备
+- **THEN** 系统返回 `CodeForbidden`，消息为"无权限操作该资源或资源不存在"
+
+#### Scenario: 设备标识符不存在
+
+- **WHEN** 代理传入的 `device_no` 无法解析为任何设备
+- **THEN** 系统返回 `CodeForbidden`，消息为"无权限操作该资源或资源不存在"