309 lines
7.3 KiB
Markdown
309 lines
7.3 KiB
Markdown
# 七月迭代 H5/C 端改动说明
|
||
|
||
本文根据《七月迭代实现与接口对接说明》整理，重点说明本期 H5/C 端需要调整的页面、接口和预期效果。
|
||
|
||
## 一、改动总览
|
||
|
||
本期 H5/C 端主要涉及以下功能：
|
||
|
||
1. 店铺 C 端登录限制。
|
||
2. 实名认证流程和实名状态展示。
|
||
3. 支付方式展示与支付提交。
|
||
4. 下架套餐老客户续费。
|
||
5. 预计套餐最终到期时间展示。
|
||
6. 套餐临期提醒。
|
||
7. 换货通知提醒。
|
||
8. C 端订单字段展示调整。
|
||
|
||
## 二、具体改动说明
|
||
|
||
### 1. 店铺 C 端登录限制（#41）
|
||
|
||
#### 前端改动
|
||
|
||
资产验证后，根据接口返回结果判断是否允许登录。如果接口返回店铺已禁止 C 端登录，应直接展示后端错误提示，不继续获取或保存资产 Token。
|
||
|
||
#### 接口
|
||
|
||
```http
|
||
POST /api/c/v1/auth/verify-asset
|
||
```
|
||
|
||
管理后台相关接口：
|
||
|
||
```http
|
||
PUT /api/admin/shops/:id
|
||
GET /api/admin/shops
|
||
GET /api/admin/shops/:id
|
||
```
|
||
|
||
店铺字段：
|
||
|
||
```json
|
||
{
|
||
"client_login_disabled": true
|
||
}
|
||
```
|
||
|
||
#### 预期效果
|
||
|
||
- 被限制的店铺无法新登录 H5/C 端。
|
||
- 前端展示后端返回的业务错误信息。
|
||
- 已经签发的 Token 不会被强制吊销。
|
||
|
||
### 2. 实名认证流程（#62）
|
||
|
||
#### 前端改动
|
||
|
||
资产初始化时只使用后端返回的实名策略和实名状态，不要根据卡、设备或前端本地规则自行推断。
|
||
|
||
重点使用以下字段：
|
||
|
||
- `effective_realname_policy`
|
||
- `realname_required`
|
||
- `real_name_status`
|
||
|
||
#### 接口
|
||
|
||
```http
|
||
GET /api/c/v1/asset/info?identifier=...
|
||
```
|
||
|
||
#### 预期效果
|
||
|
||
- `none`：不需要实名。
|
||
- `before_order`：下单前要求实名。
|
||
- `after_order`：下单后要求实名。
|
||
- 卡和设备存在策略冲突时，以设备最终生效策略为准。
|
||
- 设备只要有一张有效绑定卡已实名，即视为设备已实名。
|
||
|
||
### 3. 支付方式展示和提交（#48）
|
||
|
||
#### 前端改动
|
||
|
||
支付按钮和支付方式列表必须使用后端返回的 `allowed_payment_methods`，不能在前端写死卡、设备的微信、支付宝或钱包规则。
|
||
|
||
下单或充值时必须将用户选择的 `payment_method` 传给后端；微信支付场景按接口要求传递 `app_type`。
|
||
|
||
#### 接口
|
||
|
||
资产初始化：
|
||
|
||
```http
|
||
GET /api/c/v1/asset/info
|
||
```
|
||
|
||
充值前校验：
|
||
|
||
```http
|
||
GET /api/c/v1/wallet/recharge-check
|
||
```
|
||
|
||
创建订单：
|
||
|
||
```http
|
||
POST /api/c/v1/orders/create
|
||
```
|
||
|
||
钱包充值：
|
||
|
||
```http
|
||
POST /api/c/v1/wallet/recharge
|
||
```
|
||
|
||
#### 预期效果
|
||
|
||
- 不同资产类型显示正确的支付方式。
|
||
- 强充和普通充值遵循后端允许的支付配置。
|
||
- 前端无法绕过后端支付限制。
|
||
- 支付方式变化后，前端无需重新发布即可按接口结果生效。
|
||
|
||
### 4. 下架套餐老客户续费（#40）
|
||
|
||
#### 前端改动
|
||
|
||
普通套餐列表中不展示下架套餐，但当前正在使用下架套餐的老客户仍可通过资产信息或历史订单获取套餐 ID，并继续调用现有创建订单接口。
|
||
|
||
创建订单时传递：
|
||
|
||
- 选中的套餐 ID；
|
||
- 资产 `identifier`；
|
||
- 当前允许的 `payment_method`。
|
||
|
||
#### 接口
|
||
|
||
获取当前资产套餐：
|
||
|
||
```http
|
||
GET /api/c/v1/asset/info
|
||
```
|
||
|
||
获取历史订单：
|
||
|
||
```http
|
||
GET /api/c/v1/orders
|
||
GET /api/c/v1/orders/:id
|
||
```
|
||
|
||
创建续费订单：
|
||
|
||
```http
|
||
POST /api/c/v1/orders/create
|
||
```
|
||
|
||
相关返回字段：
|
||
|
||
- 资产信息中的 `current_package_id`；
|
||
- 历史订单中的 `package_ids`。
|
||
|
||
#### 预期效果
|
||
|
||
- 老客户可以继续续费已下架套餐。
|
||
- 不新增专用续费接口，仍复用普通创建订单接口。
|
||
- 新客户和代理代购仍不能购买下架套餐。
|
||
- 历史订单数据不被修改。
|
||
|
||
### 5. 预计套餐最终到期时间（#46）
|
||
|
||
#### 前端改动
|
||
|
||
资产详情、资产列表等页面展示后端返回的预计最终到期时间，不要只展示当前套餐的到期时间。
|
||
|
||
重点使用：
|
||
|
||
- `estimated_final_expires_at`
|
||
- `is_expiring`
|
||
- 剩余天数及临期等级字段（如接口返回）
|
||
|
||
#### 接口
|
||
|
||
```http
|
||
GET /api/c/v1/asset/info
|
||
```
|
||
|
||
后台资产解析接口也会返回相关字段：
|
||
|
||
```http
|
||
GET /api/admin/assets/resolve/:identifier
|
||
```
|
||
|
||
#### 预期效果
|
||
|
||
- 用户看到资产综合计算后的最终到期时间。
|
||
- 临期资产可以按后端返回的临期字段进行高亮。
|
||
- 避免因只显示当前套餐到期时间导致到期日期不准确。
|
||
|
||
### 6. 套餐临期提醒（#33）
|
||
|
||
#### 前端改动
|
||
|
||
接入 C 端现有站内通知能力，读取未读通知并在合适时机展示弹窗或提醒入口。
|
||
|
||
#### 接口
|
||
|
||
获取未读数量：
|
||
|
||
```http
|
||
GET /api/c/v1/notifications/unread-count
|
||
```
|
||
|
||
获取通知列表：
|
||
|
||
```http
|
||
GET /api/c/v1/notifications
|
||
```
|
||
|
||
标记已读：
|
||
|
||
```http
|
||
PUT /api/c/v1/notifications/:id/read
|
||
```
|
||
|
||
#### 预期效果
|
||
|
||
- 在套餐剩余 15 天、7 天、3 天时触发提醒。
|
||
- 前端可按后端返回的临期等级进行展示。
|
||
- 0～3 天的临期提醒优先级最高。
|
||
- 通知通过 C 端站内消息展示，不新增企微业务员提醒。
|
||
|
||
### 7. 换货通知提醒（#188）
|
||
|
||
#### 前端改动
|
||
|
||
继续使用现有 C 端通知接口，展示换货相关的未读通知，并支持点击后标记已读。
|
||
|
||
#### 接口
|
||
|
||
```http
|
||
GET /api/c/v1/notifications/unread-count
|
||
GET /api/c/v1/notifications
|
||
PUT /api/c/v1/notifications/:id/read
|
||
```
|
||
|
||
#### 预期效果
|
||
|
||
- 换货创建后，用户可以在 H5/C 端收到站内通知。
|
||
- 首页或通知入口能够展示未读数量。
|
||
- 用户查看后可以正常标记已读。
|
||
- 不新增营销投放、ERP 或其他业务单据。
|
||
|
||
### 8. C 端订单字段展示（#181）
|
||
|
||
#### 前端改动
|
||
|
||
订单列表和订单详情使用后端返回的订单角色及资产标识字段。
|
||
|
||
重点字段：
|
||
|
||
- `purchase_role`
|
||
- `asset_identifier`
|
||
|
||
设备资产标识的显示规则：
|
||
|
||
1. 优先显示 `VirtualNo`；
|
||
2. `VirtualNo` 为空时显示 `IMEI`；
|
||
3. 不使用 SN 冒充订单设备标识；
|
||
4. 历史空数据不需要前端伪造。
|
||
|
||
#### 接口
|
||
|
||
```http
|
||
GET /api/c/v1/orders
|
||
GET /api/c/v1/orders/:id
|
||
```
|
||
|
||
#### 预期效果
|
||
|
||
- 订单中的购买角色显示准确。
|
||
- 卡展示正确的 ICCID 或资产标识。
|
||
- 设备展示 VirtualNo，缺失时使用 IMEI。
|
||
- 订单资产标识与退款、换货等业务中的固化快照保持一致。
|
||
|
||
## 三、H5/C 端不需要改动的内容
|
||
|
||
以下事项本期明确不需要 H5/C 端新增功能或接口：
|
||
|
||
- #84 H5 首页隐藏设备下 ICCID：本期确认不做。
|
||
- #73 行业卡未实名复机：保持现有逻辑。
|
||
- #94 状态同步和运营商回调：继续读取现有资产状态字段，无新增前端调用。
|
||
- 企业微信审批回调：由企微服务器调用，前端禁止调用。
|
||
- 原路退款、聚水潭、跨品类换货、分销码/佣金提现：本期不做。
|
||
|
||
## 四、前端联调注意事项
|
||
|
||
- 金额接口字段默认单位为“分”，页面展示时转换为“元”，提交时仍传整数分。
|
||
- `effective_realname_policy` 和 `allowed_payment_methods` 必须以后端返回值为准。
|
||
- 企微审批业务只读展示 `approval_provider`、`approval_status`、`approval_status_name`，不能再显示旧的人工通过、驳回或线下充值确认按钮。
|
||
- 企微回调接口由企微服务器调用，H5/C 端不调用：
|
||
|
||
```http
|
||
GET/POST /api/callback/wecom/approval/:application_id
|
||
```
|
||
|
||
- 前端不要根据接口名称自行假设存在“下架套餐续费接口”，续费仍调用：
|
||
|
||
```http
|
||
POST /api/c/v1/orders/create
|
||
```
|
||
|