break
b09275a0d0
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 9m53s
140 lines
8.1 KiB
Markdown
140 lines
8.1 KiB
Markdown
# personal-customer 当前行为
|
||
|
||
## Purpose
|
||
|
||
描述个人客户身份与资产归属隔离的当前行为。
|
||
## Requirements
|
||
### Requirement: 个人客户身份
|
||
|
||
系统 SHALL 支持个人客户通过既有认证入口登录、退出并查询当前资料。有效登录材料对应的客户创建、资料同步或资产绑定 SHALL 不因审计事件构造、校验或持久化失败而失败；审计失败 SHALL 按运营审计要求记录。
|
||
|
||
#### Scenario: 个人客户身份
|
||
|
||
- **GIVEN** 个人客户提供有效登录材料
|
||
- **WHEN** 请求认证
|
||
- **THEN** 系统返回个人客户身份和访问凭证
|
||
|
||
#### Scenario: 登录审计失败
|
||
|
||
- **GIVEN** 个人客户提供有效登录材料且登录需要创建或绑定资产
|
||
- **WHEN** 对应审计事件写入失败
|
||
- **THEN** 系统仍完成客户和资产绑定并返回访问凭证
|
||
|
||
### Requirement: 资产归属查询
|
||
|
||
系统 SHALL 只向个人客户返回当前有效绑定的卡与设备资产。所有以资产标识读取个人客户换货信息的入口 SHALL 依据资产类型采用与个人客户绑定一致的归属判定：有虚拟号的物联网卡和设备按当前有效设备号绑定确定归属；无虚拟号的物联网卡按当前有效 ICCID 绑定确定归属。空虚拟号不得作为任何资产的归属键。
|
||
|
||
#### Scenario: 资产归属查询
|
||
|
||
- **GIVEN** 客户已认证
|
||
- **WHEN** 查询资产列表或详情
|
||
- **THEN** 返回该客户可见的资产而不包含其他客户资产
|
||
|
||
#### Scenario: 无虚拟号卡查询待处理物流换货单
|
||
|
||
- **GIVEN** 当前个人客户存在一张无虚拟号物联网卡的有效 ICCID 绑定，且该卡存在状态为待填写收货信息、待发货或已发货的物流换货单
|
||
- **WHEN** 客户以该卡任一已登记标识请求 `GET /api/c/v1/exchange/pending`
|
||
- **THEN** 响应返回该物流换货单的既有待处理投影
|
||
|
||
#### Scenario: 无虚拟号卡无待处理物流换货单
|
||
|
||
- **GIVEN** 当前个人客户存在一张无虚拟号物联网卡的有效 ICCID 绑定，且该卡不存在状态为待填写收货信息、待发货或已发货的物流换货单
|
||
- **WHEN** 客户以该卡任一已登记标识请求 `GET /api/c/v1/exchange/pending`
|
||
- **THEN** 请求成功且数据为空
|
||
|
||
#### Scenario: 空虚拟号历史绑定不授予换货可见性
|
||
|
||
- **GIVEN** 当前个人客户仅存在空虚拟号的历史设备号绑定，且未拥有目标无虚拟号物联网卡的有效 ICCID 绑定
|
||
- **WHEN** 客户以该卡标识请求 `GET /api/c/v1/exchange/pending`
|
||
- **THEN** 系统返回既有“资产不存在”错误，且不得返回该卡的换货信息
|
||
|
||
#### Scenario: 有虚拟号资产保持既有换货可见性
|
||
|
||
- **GIVEN** 当前个人客户拥有一项有虚拟号的物联网卡或设备资产，且该资产存在待处理物流换货单
|
||
- **WHEN** 客户以该资产标识请求 `GET /api/c/v1/exchange/pending`
|
||
- **THEN** 响应保持返回该换货单的既有待处理投影
|
||
|
||
### Requirement: 资产信息展示当前可用或已用完主套餐
|
||
|
||
系统 SHALL 在个人客户查询其已绑定资产的 `GET /api/c/v1/asset/info` 时，将当前世代中状态为生效中（`status=1`）或已用完（`status=2`）的主套餐作为当前套餐摘要返回。返回的套餐摘要 SHALL 包含套餐名称、套餐使用记录 ID、开始时间、到期时间、真流量与虚流量指标。待生效、已过期和已失效的主套餐不得作为当前套餐摘要返回。
|
||
|
||
#### Scenario: 已用完主套餐仍展示使用情况
|
||
|
||
- **GIVEN** 已认证个人客户拥有当前世代唯一的已用完主套餐，且该主套餐状态为 `status=2`
|
||
- **WHEN** 客户请求 `GET /api/c/v1/asset/info`
|
||
- **THEN** 响应返回该主套餐的名称、使用记录 ID、开始时间、到期时间及流量指标
|
||
- **AND** 响应不得将该套餐摘要字段返回为无套餐零值
|
||
|
||
#### Scenario: 生效中主套餐保持既有展示
|
||
|
||
- **GIVEN** 已认证个人客户拥有当前世代唯一的生效中主套餐，且该主套餐状态为 `status=1`
|
||
- **WHEN** 客户请求 `GET /api/c/v1/asset/info`
|
||
- **THEN** 响应返回该主套餐的既有套餐摘要和流量指标
|
||
|
||
#### Scenario: 不可展示状态不作为当前套餐
|
||
|
||
- **GIVEN** 已认证个人客户没有状态为 `status=1` 或 `status=2` 的主套餐
|
||
- **WHEN** 客户请求 `GET /api/c/v1/asset/info`
|
||
- **THEN** 响应的当前套餐摘要保持无套餐零值
|
||
|
||
### Requirement: 缺少当前使用卡时的设备实名判定
|
||
|
||
系统 SHALL 在个人客户查询设备资产 `GET /api/c/v1/asset/info` 时按下述规则返回外层 `real_name_status`：存在有效绑定卡的当前使用标识时，返回该卡的实名状态；不存在任何当前使用卡时，只要该设备存在任一已实名（`real_name_status=1`）的有效绑定卡，SHALL 返回已实名，否则返回未实名。返回的 `real_name_status_name` SHALL 与 `real_name_status` 保持一致。卡列表中的逐卡实名状态 MUST 保持按卡返回，不受本判定影响。该判定 MUST NOT 因运营商实时接口调用失败或超时而改变。
|
||
|
||
#### Scenario: 无当前使用卡但绑定卡已实名
|
||
|
||
- **GIVEN** 设备存在有效绑定卡且其中至少一张已实名，且该设备没有任何 `is_current=true` 的有效绑定卡
|
||
- **WHEN** 已认证个人客户请求该设备的 `GET /api/c/v1/asset/info`
|
||
- **THEN** 响应外层 `real_name_status` 返回 `1` 且 `real_name_status_name` 为已实名
|
||
- **AND** 卡列表中该已实名卡仍按其自身实名状态返回
|
||
|
||
#### Scenario: 无当前使用卡且绑定卡均未实名
|
||
|
||
- **GIVEN** 设备存在有效绑定卡且全部未实名，且该设备没有任何 `is_current=true` 的有效绑定卡
|
||
- **WHEN** 已认证个人客户请求该设备的 `GET /api/c/v1/asset/info`
|
||
- **THEN** 响应外层 `real_name_status` 返回 `0` 且 `real_name_status_name` 为未实名
|
||
|
||
#### Scenario: 有当前使用卡时沿用该卡状态
|
||
|
||
- **GIVEN** 设备存在一张 `is_current=true` 的未实名绑定卡，同时存在另一张已实名绑定卡
|
||
- **WHEN** 已认证个人客户请求该设备的 `GET /api/c/v1/asset/info`
|
||
- **THEN** 响应外层 `real_name_status` 返回该当前使用卡的未实名状态
|
||
|
||
#### Scenario: 运营商实时查询失败不改变实名判定
|
||
|
||
- **GIVEN** 设备的运营商实时状态查询失败或超时
|
||
- **WHEN** 已认证个人客户请求该设备的 `GET /api/c/v1/asset/info`
|
||
- **THEN** 响应仍按绑定卡事实返回外层实名状态，不因实时查询失败而返回未实名
|
||
|
||
## 可达操作索引
|
||
|
||
本节只用于入口导航，不是行为 Requirement；业务义务以上述 Requirements 为准。
|
||
|
||
### 个人客户 - 认证
|
||
|
||
`POST /api/c/v1/auth/bind-phone`（绑定手机号）；`POST /api/c/v1/auth/change-phone`（更换手机号）；`POST /api/c/v1/auth/logout`（退出登录）；`POST /api/c/v1/auth/miniapp-login`（小程序登录）；`POST /api/c/v1/auth/send-code`（发送验证码）；`POST /api/c/v1/auth/verify-asset`（资产验证）；`POST /api/c/v1/auth/wechat-login`（公众号登录）。仅在开发模式开启时，系统 SHALL 额外提供 `POST /api/c/v1/auth/dev-login`。
|
||
|
||
### 个人客户 - 账户
|
||
|
||
`GET /api/c/v1/profile`（获取个人资料）；`PUT /api/c/v1/profile`（更新个人资料）。
|
||
|
||
### 个人客户 - 微信
|
||
|
||
`GET /api/c/v1/wechat/appid`（获取当前生效的公众号 AppID）；`GET /api/c/v1/wechat/jssdk-config`（获取微信 JSSDK 签名配置）。
|
||
|
||
### 个人客户 - 资产
|
||
|
||
`GET /api/c/v1/asset/info`（资产信息）；`GET /api/c/v1/asset/package-history`（资产套餐历史）；`GET /api/c/v1/asset/packages`（资产可购套餐列表）；`POST /api/c/v1/asset/refresh`（资产刷新）。
|
||
|
||
### 个人客户 - 设备
|
||
|
||
`GET /api/c/v1/device/cards`（获取设备卡列表）；`POST /api/c/v1/device/factory-reset`（恢复出厂设置）；`POST /api/c/v1/device/reboot`（设备重启）；`POST /api/c/v1/device/switch-card`（设备切卡）；`POST /api/c/v1/device/wifi`（设备WiFi配置）。
|
||
|
||
### 个人客户 - 实名
|
||
|
||
`GET /api/c/v1/realname/link`（获取实名认证链接）。
|
||
|
||
### 个人客户 - 换货
|
||
|
||
`POST /api/c/v1/exchange/{id}/shipping-info`（提交收货信息）；`GET /api/c/v1/exchange/pending`（查询待处理换货单）。
|