98 lines
7.5 KiB
Markdown
98 lines
7.5 KiB
Markdown
# asset-device 当前行为
|
||
|
||
## Purpose
|
||
|
||
描述卡、设备、资产状态与绑定关系的当前可观察行为。
|
||
|
||
## Requirements
|
||
|
||
### Requirement: 资产业务状态
|
||
|
||
系统 SHALL 将资产状态按 1=在库、2=已销售、3=已换货、4=已停用返回，并与运营商网络状态分离。
|
||
|
||
#### Scenario: 资产业务状态
|
||
|
||
- **GIVEN** 资产存在且具有业务与网络状态
|
||
- **WHEN** 查询资产详情
|
||
- **THEN** 响应分别返回业务状态与网络状态
|
||
|
||
### Requirement: 设备多卡关系
|
||
|
||
系统 SHALL 允许设备显式绑定和解绑卡，并在设备资产查询中展示当前卡关系。
|
||
|
||
#### Scenario: 设备多卡关系
|
||
|
||
- **GIVEN** 设备与卡均存在且操作人有权管理
|
||
- **WHEN** 执行绑定或解绑
|
||
- **THEN** 后续设备卡列表反映该关系变化
|
||
|
||
### Requirement: ICCID 按原始长度精确唯一
|
||
|
||
系统 SHALL 将未删除卡的 ICCID 唯一性按原始 ICCID 长度分别约束：原始长度为 19 的卡以 `iccid_19` 唯一；原始长度为 20 的卡以 `iccid_20` 唯一。20 位 ICCID 卡共享相同的前 19 位 SHALL 被视为有效数据。
|
||
|
||
#### Scenario: 20 位 ICCID 共享前缀
|
||
|
||
- **WHEN** 两张未删除卡具有不同的 20 位完整 ICCID，但其前 19 位相同
|
||
- **THEN** 数据库接受两张卡，并通过各自的 `iccid_20` 保证完整 ICCID 唯一
|
||
|
||
#### Scenario: 19 位 ICCID 重复
|
||
|
||
- **WHEN** 两张未删除卡具有相同的 19 位完整 ICCID
|
||
- **THEN** 数据库拒绝第二张卡的重复值
|
||
|
||
|
||
### Requirement: 临期颜色等级仅用于展示
|
||
系统 SHALL 对剩余 8 至 15 个上海自然日的临期资产返回粉色等级、对剩余 4 至 7 天返回紫色等级、对剩余 0 至 3 天返回红色等级。颜色等级 MUST 不改变资产是否进入每日临期提醒扫描的条件。
|
||
|
||
#### Scenario: 红色资产仍每日提醒
|
||
- **GIVEN** 一项资产剩余 2 个上海自然日且存在有效通知接收人
|
||
- **WHEN** 查询临期资产列表并执行每日临期扫描
|
||
- **THEN** 列表返回红色等级，且扫描创建当天的套餐临期通知
|
||
|
||
### Requirement: 卡业务观测可靠事件标识
|
||
|
||
系统 SHALL 为卡与设备控制及其后续网络、流量观测生成不超过公共可靠事件存储上限的稳定事件标识，相同业务事实重试时 SHALL 保持同一标识。
|
||
|
||
#### Scenario: 停复机成功写入观测事件
|
||
|
||
- **WHEN** 卡或设备停复机的上游调用成功且本地事务记录业务结果
|
||
- **THEN** 系统在同一事务写入合法长度的业务观测可靠事件，不因事件标识超长回滚本地结果
|
||
|
||
#### Scenario: 网络或流量变化写入可靠事件
|
||
|
||
- **WHEN** 一次具有长观测标识的观测产生网络状态变化或流量正增量
|
||
- **THEN** 系统写入合法长度且可重复计算的可靠事件标识
|
||
|
||
#### Scenario: 非法可靠事件标识被边界拒绝
|
||
|
||
- **WHEN** 生产者向公共可靠事件存储提交超过字段上限的事件标识或父事件标识
|
||
- **THEN** 系统在持久化边界返回明确的参数错误而不是数据库字段错误
|
||
|
||
## 可达操作索引
|
||
|
||
本节只用于入口导航，不是行为 Requirement；业务义务以上述 Requirements 为准。
|
||
|
||
### IoT卡管理
|
||
|
||
`GET /api/admin/iot-cards/{iccid}/realname-link`（获取实名认证链接）；`PUT /api/admin/iot-cards/{iccid}/speed-tier`（设置卡固定限速档位）；`POST /api/admin/iot-cards/batch-update-realname-policy`（批量更新卡实名认证策略）；`POST /api/admin/iot-cards/import`（批量导入IoT卡（ICCID+MSISDN））；`GET /api/admin/iot-cards/import-tasks`（导入任务列表）；`GET /api/admin/iot-cards/import-tasks/{id}`（导入任务详情）；`PATCH /api/admin/iot-cards/series-binding`（批量设置卡的套餐系列绑定）；`GET /api/admin/iot-cards/standalone`（单卡列表（未绑定设备））；`POST /api/admin/iot-cards/standalone/allocate`（批量分配单卡）；`POST /api/admin/iot-cards/standalone/recall`（批量回收单卡）。
|
||
|
||
### 设备管理
|
||
|
||
`GET /api/admin/devices`（设备列表）；`DELETE /api/admin/devices/{virtual_no}`（删除设备）；`GET /api/admin/devices/{virtual_no}/cards`（获取设备绑定的卡列表）；`POST /api/admin/devices/{virtual_no}/cards`（绑定卡到设备）；`DELETE /api/admin/devices/{virtual_no}/cards/{iccid}`（解绑设备上的卡）；`POST /api/admin/devices/allocate`（批量分配设备）；`POST /api/admin/devices/batch-update-realname-policy`（批量更新设备实名认证策略）；`GET /api/admin/devices/by-identifier/{identifier}/gateway-slots`（查询卡槽信息）；`POST /api/admin/devices/by-identifier/{identifier}/reboot`（重启设备）；`POST /api/admin/devices/by-identifier/{identifier}/reset`（恢复出厂）；`POST /api/admin/devices/by-identifier/{identifier}/switch-card`（切卡）；`POST /api/admin/devices/by-identifier/{identifier}/switch-mode`（设置切卡模式）；`PUT /api/admin/devices/by-identifier/{identifier}/wifi`（设置 WiFi）；`POST /api/admin/devices/import`（批量导入设备）；`POST /api/admin/devices/import/allocations`（创建CSV设备批量分配或回收任务）；`GET /api/admin/devices/import/tasks`（导入任务列表）；`GET /api/admin/devices/import/tasks/{id}`（导入任务详情）；`POST /api/admin/devices/recall`（批量回收设备）；`PATCH /api/admin/devices/series-binding`（批量设置设备的套餐系列绑定）。
|
||
|
||
### 资产管理
|
||
|
||
`GET /api/admin/assets/{identifier}/current-package`（当前生效套餐）；`PATCH /api/admin/assets/{identifier}/deactivate`（停用资产）；`GET /api/admin/assets/{identifier}/operation-logs`（查询平台旧资产操作日志）；`GET /api/admin/assets/{identifier}/orders`（资产历史订单）；`GET /api/admin/assets/{identifier}/packages`（资产套餐列表）；`PATCH /api/admin/assets/{identifier}/packages/{package_usage_id}/expires-at`（修改资产套餐过期时间）；`PATCH /api/admin/assets/{identifier}/packages/{package_usage_id}/used-data`（修改资产套餐已用量）；`PATCH /api/admin/assets/{identifier}/polling-status`（更新资产轮询状态）；`PATCH /api/admin/assets/{identifier}/realname-mode`（更新资产实名认证策略）；`PATCH /api/admin/assets/{identifier}/realname-status`（手动更新卡实名状态）；`GET /api/admin/assets/{identifier}/realtime-status`（资产实时状态）；`POST /api/admin/assets/{identifier}/refresh`（刷新资产状态）；`POST /api/admin/assets/{identifier}/start`（复机）；`POST /api/admin/assets/{identifier}/stop`（停机）；`GET /api/admin/assets/{identifier}/wallet`（资产钱包概况）；`GET /api/admin/assets/{identifier}/wallet/transactions`（资产钱包流水列表）；`GET /api/admin/assets/resolve/{identifier}`（解析资产）；`GET /api/admin/expiring-assets`（查询临期资产列表）；`POST /api/admin/expiring-assets/reminder-scan`（手动触发套餐临期提醒扫描）。
|
||
|
||
### 资产分配记录
|
||
|
||
`GET /api/admin/asset-allocation-records`（分配记录列表）；`GET /api/admin/asset-allocation-records/{id}`（分配记录详情）。
|
||
|
||
### 企业卡授权
|
||
|
||
`POST /api/admin/enterprises/{id}/allocate-cards`（授权卡给企业）；`GET /api/admin/enterprises/{id}/cards`（企业卡列表）；`POST /api/admin/enterprises/{id}/recall-cards`（回收卡授权）。
|
||
|
||
### 企业设备授权
|
||
|
||
`POST /api/admin/enterprises/{id}/allocate-devices`（授权设备给企业）；`GET /api/admin/enterprises/{id}/devices`（企业设备列表）；`POST /api/admin/enterprises/{id}/recall-devices`（撤销设备授权）。
|