one-pipe-system/openspec/changes/add-h5-popup-configuration-management/proposal.md

Change: 新增 H5 运营弹窗配置管理（管理后台）

Why

H5 端（个人客户）需要在首页、资产详情、套餐购买、资产钱包充值等页面投放运营/风险弹窗，弹窗文案、命中页面、投放范围与生效规则需要后台配置。当前后台没有任何弹窗配置入口，运营只能走数据库操作。

本 Change 为管理后台新增「H5 运营弹窗配置」管理能力：配置标题与正文、命中页面、投放范围（店铺/设备类型/卡类型）、优先级、投放频率、生效时间与启停。

H5 端契约（GET /api/c/v1/popup-candidates、POST /api/c/v1/risk-exchanges/{asset_id}/address、通知列表/未读/已读接口）不在本 Change 范围，需求方已明确不处理 C 端。

What Changes

• 新增 6 个后台接口（仅超管/平台，代理/企业/个人 403）：
  • GET /api/admin/h5-popup-configurations：配置列表，page（1–10000）/ page_size（1–100）/ enabled 筛选，按最近更新时间倒序分页返回 items/page/size/total。
  • POST /api/admin/h5-popup-configurations：创建；title/content/pages/frequency/starts_at/ends_at 必填；priority/enabled/action_type/shop_ids/device_types/card_types 可选（范围集合空数组 = 全量）。
  • GET /api/admin/h5-popup-configurations/{id}：详情（含 version、frequency_text、enabled_text、creator/updater）。
  • PUT /api/admin/h5-popup-configurations/{id}：更新；成功即版本 +1，新版本可向原命中客户按频率重新投放一次，旧版本已投放通知的内容与快照不被改写；除 id 外全部字段可选，不传保持原值；action_type 传空字符串 = 清除受控动作；shop_ids/device_types/card_types 传空数组 = 改为全量；pages 传空数组非法（页面必选）；enabled 不传保持原值（启停刷新最近更新时间）；ends_at 不得早于 starts_at；content 1–2000 字符、title 1–100 字符、priority 0–1000000。
  • POST /api/admin/h5-popup-configurations/{id}/enable：启用，参与候选匹配，刷新 updated_at（影响同优先级排序），返回更新后的配置。
  • POST /api/admin/h5-popup-configurations/{id}/disable：停用，停止新投放，历史通知在展示期内仍可见；刷新 updated_at，返回更新后的配置。
• 新增「H5 运营弹窗配置」管理页（设置管理下，仅超管/平台可见）：分页列表 + 创建/编辑表单 + 详情 + 行操作启用/停用。
• 前端契约约定：
  • 范围集合 shop_ids / device_types / card_types 空数组 = 全量，列表与编辑回显「全部」。
  • 枚举：pages = home / asset_detail / package_purchase / asset_wallet_recharge；frequency = once / daily；action_type = package_purchase / asset_wallet_recharge（空字符串 = 无受控动作）；card_types = CMCC / CUCC / CTCC / CBN。
  • 无「删除」接口，页面不提供删除入口；停用不清数据，列表保留历史配置。
  • 编辑表单整表提交（所有字段都传，未传语义仅在部分更新时生效）；范围清空传空数组、动作清除传空字符串、页面集合不可为空。
  • 权限编码由前端确定：h5_popup_configuration:list / :create / :update / :enable / :disable。

Impact

• Affected specs:
  • h5-popup-configuration-management
• Affected code:
  • src/api/modules/h5PopupConfiguration.ts（新增）
  • src/types/api/h5PopupConfiguration.ts（新增）
  • src/api/modules/index.ts、src/types/api/index.ts
  • src/config/constants/（权限码常量）
  • src/router/routesAlias.ts、src/router/routes/asyncRoutes.ts（设置管理下新增菜单与路由）
  • src/locales/langs/zh.json、src/locales/langs/en.json
  • src/views/settings/h5-popup-configuration/（列表、表单弹窗、详情）
• Dependencies:
  • 后端按 docs/产品迭代8月份/通知.md 提供上述 6 接口，Bearer JWT 鉴权，代理/企业/个人 403。
• Breaking changes:
  • 无；全部为新增页面、接口模块与类型。
• 待确认：
  • 权限编码（前端默认 h5_popup_configuration:list/create/update/enable/disable）以后端菜单配置为准。
  • 列表分页上限与「按最近更新时间倒序」以文档为准，联调核对后端行为。