6.5 KiB
6.5 KiB
Change: 对接十月份第 1 批 H5 接口变更
本提案仅覆盖 /api/c/v1 的现有 H5 功能。用户于 2026-10-13 批准执行；实现和验证结果见 IMPLEMENTATION.md。
Why
第 1 批前端对接说明中的 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调用返回的一次性提醒，防止首页子组件或其他调用方先获得字段后将其丢弃；不为提醒新增轮询或额外请求。 - 首页旧未读通知弹窗不再以临期通知作为弹窗依据；临期通知仍保留在通知中心，其他通知和既有运营/风险换货弹窗不变。
- 临期弹窗与风险换货/运营、普通通知弹窗依次展示，不叠加；通知卡片去掉左侧未读边框，标题右侧使用“未读/已读”小按钮，点击卡片或按钮后按单条已读响应更新。
- 全部已读保持
PUT /api/c/v1/notifications/read-all，以用户 2026-10-14 最新确认覆盖此前 POST 约定；通知列表和未读数沿用现有入参，由后端过滤当前资产的临期通知。
Scope and confirmed decisions
用户确认：不处理代理注册；手机号行为以当前对接说明为准。全部已读以 2026-10-14 最新确认的 PUT 为准，不采用此前文档中的 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 |
使用后端当前上下文计数 | 原请求参数、未读入口 |
PUT /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：其“不同于客户主号则拒绝”“换号迁移全部资产关联”“用 bound_phone 判断资产关联”的旧约定，被本提案的 F1 约定替代；不覆盖其历史文件及完成标记。
- update-post-bind-wechat-login-recheck：根据用户最新确认，替代其“强制绑定后清除 token 并要求手动重登”的约定；改为保留登录态直接进入首页，不改写历史提案。
- update-july-h5-c-iteration：仅替代临期通知作为首页弹窗来源的约定，保留通知中心、其他通知和套餐到期信息展示。
- add-personal-notifications：保持单条/全部已读的 PUT，遵循当前资产临期通知范围及最新卡片样式。
- add-h5-popup-candidate-flow：保留候选弹窗与单条已读链路；候选结束后再显示临期弹窗，不调用全部已读来关闭任何弹窗。