break
41722760b1
6.6 KiB
h5-popup-notification 当前行为
Purpose
在客户实际访问 H5 时，按当前资产事实投放风险换卡或运营弹窗，并将投放内容作为个人客户通知留存，避免预生成通知或开放任意跳转链接。
Requirements
Requirement: 风险换卡候选与地址提交
系统 SHALL 仅在当前 H5 客户访问的资产为广电卡、运营商扩展状态为风险停机、且不存在待填写收货信息、待发货、已发货待确认或已完成的物流换货单时返回风险换卡弹窗。物流换货单只统计物流换货流程；直接换货单不参与该判定。同一客户同一资产每天至多展示一次；稍后处理仅抑制当天，次日仍可命中。当天已投放风险换卡候选后，无论客户是否已读，当天不再返回运营弹窗候选；次日风险与运营按各自的频率与优先级规则恢复匹配。风险换卡优先级固定高于运营弹窗仅适用于两者同时命中的场景。
客户提交收货人姓名、收货手机号和完整地址文本后，系统 MUST 幂等创建关联旧资产的物流换货单；首次地址锁定，客户不得修改，重复提交返回首次创建的换货单与首次地址且不覆盖。并发提交同一资产时只创建一张换货单。自动换货单不预设业务数据迁移，发货选择新资产时仍由后台按既有换货流程决定。风险条件不再成立或地址已提交后停止新投放，已投放通知在通知中心展示 90 天。客户请求不属于自己的资产时，系统 MUST 返回与资产不存在相同的不可见结果。
Scenario: 重复提交风险地址
- WHEN 客户对同一风险资产重复提交收货地址
- THEN 系统保留首次地址和唯一物流换货单，不创建第二张换货单，也不覆盖首次地址
Scenario: 并发提交同一资产
- WHEN 同一风险资产同时收到两次地址提交
- THEN 系统只创建一张物流换货单，两次均返回同一张换货单与首次地址
Scenario: 已完成物流换货单
- WHEN 当前资产已存在已完成的物流换货单
- THEN 系统不再返回风险换卡候选
Scenario: 直接换货单不压制风险候选
- WHEN 当前资产只有已完成的直接换货单，且其余风险条件成立
- THEN 系统仍返回风险换卡候选
Scenario: 他人资产
- WHEN 客户请求候选或提交地址的资产不属于自己
- THEN 系统返回与资产不存在相同的不可见结果
Requirement: 运营弹窗实时匹配
系统 SHALL 允许超级管理员和平台用户管理全局运营弹窗的标题、内容、有效期、启停、优先级、店铺/设备类型/卡类型范围、四种页面（首页、资产详情、套餐购买、资产钱包充值）、频率和一个可选受控操作。范围同一维度多选为任一匹配，未配置范围即全量；已配置范围而当前资产在该维度没有可判定值时该配置不命中。H5 请求必须携带当前页面资产标识。操作仅可为套餐购买或资产钱包充值，不得配置任意 URL。
运营弹窗仅在客户请求候选时实时匹配并创建或复用通知；每客户每配置支持仅一次或每天一次。候选只返回优先级最高一条，同优先级取最近更新时间最新，启停操作同样更新最近更新时间。配置修改形成新版本，既有通知保留原快照且不被改写；修改后的仅一次配置可向原命中客户重新投放。配置到期或停用停止新投放，历史通知在通知中心展示 90 天。
Scenario: 风险与运营候选同时命中
- WHEN 当前资产同时满足风险换卡和多个运营弹窗条件
- THEN 系统仅返回风险换卡候选，并保持通知未读
Scenario: 优先级与最近更新排序
- WHEN 多条运营配置同时命中且优先级相同
- THEN 系统只返回最近更新时间最新的一条
Scenario: 独立卡的设备类型维度
- WHEN 命中的运营配置配置了设备类型范围，但当前资产是未绑定设备的独立卡
- THEN 系统不命中该配置
Scenario: 配置修改后重新投放
- WHEN 已按仅一次频率向客户投放过的配置被修改
- THEN 配置版本递增，既有通知的内容与快照保持不变，该客户可再次命中一次
Scenario: 到期或停用
- WHEN 配置已到期或被停用
- THEN 系统停止新投放，既有通知在展示期内仍可见
Requirement: 通知留存与已读
弹窗投放 SHALL 复用个人客户站内通知，保存投放时内容、受控操作与旧资产关联；运营弹窗通知额外保存配置标识与配置版本快照。投放后通知同时出现在通知列表与未读数中，并自投放时间起展示 90 天。
创建或返回候选不得自动已读；客户关闭、点击操作或进入通知详情后通过既有已读接口幂等标记已读。通知读取必须维持个人客户隔离。
Scenario: 关闭弹窗
- WHEN 当前个人客户关闭其未读弹窗
- THEN 系统仅标记该客户该通知已读，不影响其他客户或未来符合条件的投放
Scenario: 同一天重复请求
- WHEN 客户在同一天多次请求同一资产的候选
- THEN 系统复用同一条通知，不重复投放，且当日只返回一次候选
Scenario: 已读后当天不再返回
- WHEN 客户关闭弹窗后当天再次请求候选
- THEN 系统不再返回该候选，次日条件仍成立时创建新通知重新投放
Scenario: 通知列表可见
- WHEN 投放产生了一条弹窗通知
- THEN 该通知出现在当前客户的未读数与通知列表中，并可通过既有已读接口标记已读
可达操作索引
本节只用于入口导航，不是行为 Requirement；业务义务以上述 Requirements 为准。
H5 运营弹窗配置
GET /api/admin/h5-popup-configurations（查询运营弹窗配置列表）；POST /api/admin/h5-popup-configurations（创建运营弹窗配置）；GET /api/admin/h5-popup-configurations/{id}（查询运营弹窗配置详情）；PUT /api/admin/h5-popup-configurations/{id}（更新运营弹窗配置并递增版本）；POST /api/admin/h5-popup-configurations/{id}/enable（启用运营弹窗配置）；POST /api/admin/h5-popup-configurations/{id}/disable（停用运营弹窗配置）。
H5 弹窗候选与风险换卡
GET /api/c/v1/popup-candidates（查询当前页面的弹窗候选，命中时创建或复用未读通知）；POST /api/c/v1/risk-exchanges/{asset_id}/address（提交风险换卡收货地址，幂等创建物流换货单）。