61 lines
6.1 KiB
Markdown
61 lines
6.1 KiB
Markdown
# Change: 对接十月份第 1 批 H5 接口变更
|
||
|
||
本提案仅覆盖 `/api/c/v1` 的现有 H5 功能。用户于 2026-10-13 批准执行；实现和验证结果见 [IMPLEMENTATION.md](IMPLEMENTATION.md)。
|
||
|
||
## Why
|
||
|
||
[第 1 批前端对接说明](../../../docs/10月份修改/第1批-8-9月迭代前端对接说明.md)中的 F1、M9 改变了手机号关联和临期提醒的行为。当前代码仍混用客户手机号与资产绑定状态、在客户换号后覆盖资产本地手机号，并从未读通知触发临期弹窗，可能出现错误的绑定提示和重复提醒。
|
||
|
||
## What Changes
|
||
|
||
- 接收并保存公众号登录返回的 `asset_phone_bound`、`asset_phone_is_own`、`need_bind_phone`，区分客户手机号与当前资产手机号关联，不能再用一个“已绑定”缓存表达两者。
|
||
- 按 F1 的四种场景调整绑定页文案、绑定入口及提交后的状态处理；客户已有手机号、资产无号时，允许给资产绑定不同号码。
|
||
- 对 `bind-phone` 的 `1192` 提示“该资产已绑定手机号，如需更换请联系管理员”，不提供重试当前绑定请求的操作；保留 `1184` 的既有错误处理。
|
||
- 绑定成功保留有效 token 和资产标识；登录引导的绑定页直接进入首页，不再清除登录态、提示或要求重新登录。普通绑定成功仍返回上一页。
|
||
- **BREAKING（替代旧前端假设）**：`change-phone` 只修改客户手机号，不更新任何资产手机号关联；停止将新客户手机号写入资产绑定缓存。
|
||
- 接收 `asset/info.expiry_reminder`，在首页资产信息区展示可关闭横幅，展示后端提供的剩余天数、到期时间和等级；无字段时不自行计算或补发提醒。
|
||
- 统一接收各 `asset/info` 调用返回的一次性提醒，防止首页子组件或其他调用方先获得字段后将其丢弃；不为提醒新增轮询或额外请求。
|
||
- 首页旧未读通知弹窗不再以临期通知作为弹窗依据；临期通知仍保留在通知中心，其他通知和既有运营/风险换货弹窗不变。
|
||
- **BREAKING（请求方法切换）**：全部已读改为 `POST /api/c/v1/notifications/read-all`，不再发送旧 `PUT` 或自动回退；通知列表和未读数沿用现有入参，由后端过滤当前资产的临期通知。
|
||
|
||
## Scope and confirmed decisions
|
||
|
||
用户于 2026-10-13 确认：不处理代理注册；手机号行为以当前对接说明为准；全部已读以新文档的 `POST` 为准。
|
||
|
||
后续用户补充确认：绑定手机号不会使 token 失效，绑定成功不得再跳转登录页。本次修订覆盖旧强制绑定后手动重登流程。
|
||
|
||
| 接口 | 本次处理 | 不变部分 |
|
||
|---|---|---|
|
||
| `POST /api/c/v1/auth/wechat-login` | 消费两个资产绑定布尔字段及新的绑定提示语义 | OAuth、令牌、资产校验流程 |
|
||
| `POST /api/c/v1/auth/bind-phone` | 四种绑定场景、1192、成功后的分类状态更新 | `{ phone, code }`、验证码接口与场景 |
|
||
| `POST /api/c/v1/auth/change-phone` | 客户换号，不再假设资产关联迁移 | 原/新手机号及验证码表单、接口入参 |
|
||
| `GET /api/c/v1/asset/info` | 接收一次性 `expiry_reminder`，区分手机号用途 | 原资产、套餐、实名、支付字段 |
|
||
| `GET /api/c/v1/notifications` | 回归当前资产临期通知的可见性 | 分页、排序、通知中心展示 |
|
||
| `GET /api/c/v1/notifications/unread-count` | 使用后端当前上下文计数 | 原请求参数、未读入口 |
|
||
| `POST /api/c/v1/notifications/read-all` | 从旧 PUT 切换为 POST | 用户主动点击“全部已读”的入口 |
|
||
|
||
明确排除：
|
||
|
||
- 代理注册页面、接口封装、密码新规则及注册 `status=3`。
|
||
- 所有 `/api/admin`、`/api/auth` 的变更，以及后台订单、审批、换货、导入、预警、导出功能。
|
||
- 新增小程序登录入口；`miniapp-login` 的同名字段仅作为后端共用契约背景，本 H5 继续使用公众号登录。
|
||
- 修改 C 端订单、退款接口、WiFi 密码规则、支付路由及实名流程。
|
||
- 新增后端接口、手机号关联解除/迁移接口，或从布尔字段推测资产实际号码。
|
||
|
||
## Impact
|
||
|
||
- Affected specs: `index-phone-bind-gate`、`phone-bind-association-prefill`、`phone-change-migration`、`c-notification-reminders`、`personal-notifications`。
|
||
- Affected code: `pages/login/login.vue`、`pages/index/index.vue`、`pages/bind/bind.vue`、`pages/change-phone/change-phone.vue`、`components/FunctionCard.vue`、`components/DeviceStatusCard.vue`、`api/modules/asset.js`、`api/modules/notification.js`、`store/user.js`、`store/asset.js`、`utils/phone-bind.js`。
|
||
- 检查但不预设必须修改：`components/TrafficCard.vue`、`components/RenewalPaymentPopup.vue`、其他 `assetApi.getInfo` 调用方及通知中心的刷新逻辑。
|
||
- 不增加依赖，不执行后端或数据迁移。
|
||
|
||
## Existing change conflicts
|
||
|
||
- [update-phone-bind-association-flow](../update-phone-bind-association-flow/proposal.md)：其“不同于客户主号则拒绝”“换号迁移全部资产关联”“用 bound_phone 判断资产关联”的旧约定，被本提案的 F1 约定替代；不覆盖其历史文件及完成标记。
|
||
- [update-post-bind-wechat-login-recheck](../update-post-bind-wechat-login-recheck/proposal.md)：根据用户最新确认，替代其“强制绑定后清除 token 并要求手动重登”的约定；改为保留登录态直接进入首页，不改写历史提案。
|
||
- [update-july-h5-c-iteration](../update-july-h5-c-iteration/proposal.md)：仅替代临期通知作为首页弹窗来源的约定，保留通知中心、其他通知和套餐到期信息展示。
|
||
- [add-personal-notifications](../add-personal-notifications/proposal.md)：仅切换全部已读方法及遵循当前资产临期通知范围，不把单条已读的 PUT 一并改为 POST。
|
||
- [add-h5-popup-candidate-flow](../add-h5-popup-candidate-flow/proposal.md)：保留候选弹窗与单条已读链路；临期横幅独立展示，不调用全部已读来关闭任何弹窗。
|
||
|
||
技术选择、字段依据及风险见 [design.md](design.md)，执行及验收清单见 [tasks.md](tasks.md)。
|