# 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`）以后端菜单配置为准。
  - 列表分页上限与「按最近更新时间倒序」以文档为准，联调核对后端行为。