feat(H5弹窗): AUG26-007 风险换卡与运营弹窗投放通知

新增 000225 迁移：运营弹窗配置表 tb_h5_popup_configuration（页面/范围/优先级/频率/受控动作/启停/有效期/版本）
与 tb_notification 可空 JSONB 列 popup_snapshot。

新增通知直建窄接口 DirectWriter.CreateOrGetPersonal：与 Outbox 消费共用 prepareDelivery 的渲染、
展示期与 CreateIdempotent 规则，冲突时回查返回既有行；同步扩展个人通知查询与已读两处类型白名单，
并按个人客户入口补齐投递审计来源。

新增 H5 候选与风险换卡：GET /api/c/v1/popup-candidates 先判风险资格（广电卡 + 风险停机 +
无活动物流换货单），命中只返回风险候选；未命中再按时间/启停/页面/店铺/设备类型/卡类型范围/频率
匹配运营配置。POST /api/c/v1/risk-exchanges/:asset_id/address 锁资产行后幂等创建待发货物流换货单，
首次地址锁定，不沿用资产级群发通知。

新增后台运营弹窗配置 CRUD 与启停（仅超级管理员与平台账号），更新递增版本并刷新最近更新时间，
标题与正文统一拒绝 URL 与前端路由，全部写操作记录操作者、前后值、版本与时间。

同步 OpenAPI（cmd/gendocs、cmd/api/docs.go、pkg/openapi/handlers.go）与参数校验中文提示共用实现。

internal/routes/admin.go

@@ -76,6 +76,9 @@ func RegisterAdminRoutes(router fiber.Router, handlers *bootstrap.Handlers, midd
 	if handlers.Notification != nil {
 		registerNotificationRoutes(authGroup, handlers.Notification, doc, basePath)
 	}
+	if handlers.H5PopupConfiguration != nil {
+		registerH5PopupConfigurationRoutes(authGroup, handlers.H5PopupConfiguration, doc, basePath)
+	}
 	if handlers.Device != nil {
 		registerDeviceRoutes(authGroup, handlers.Device, handlers.DeviceImport, doc, basePath)
 	}

internal/routes/h5_popup_configuration.go

@@ -0,0 +1,72 @@
+package routes
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"github.com/break/junhong_cmp_fiber/internal/handler/admin"
+	"github.com/break/junhong_cmp_fiber/internal/model/dto"
+	"github.com/break/junhong_cmp_fiber/pkg/openapi"
+)
+
+// registerH5PopupConfigurationRoutes 注册 H5 运营弹窗配置的维护路由。
+// 全部接口仅超级管理员与平台账号可用，代理与企业统一返回 403。
+func registerH5PopupConfigurationRoutes(router fiber.Router, handler *admin.H5PopupConfigurationHandler, doc *openapi.Generator, basePath string) {
+	configurations := router.Group("/h5-popup-configurations")
+	groupPath := basePath + "/h5-popup-configurations"
+
+	Register(configurations, doc, groupPath, "GET", "", handler.ListH5PopupConfigurations, RouteSpec{
+		Summary:     "查询运营弹窗配置列表",
+		Description: "按最近更新时间倒序分页返回运营弹窗配置，可按启停筛选。",
+		Tags:        []string{"H5 运营弹窗配置"},
+		Auth:        true,
+		Input:       new(dto.H5PopupConfigurationListRequest),
+		Output:      new(dto.H5PopupConfigurationListResponse),
+	})
+
+	Register(configurations, doc, groupPath, "POST", "", handler.CreateH5PopupConfiguration, RouteSpec{
+		Summary: "创建运营弹窗配置",
+		Description: "创建全局运营弹窗配置，初始版本为 1。范围同一维度多选取任一命中，未配置范围即全量；" +
+			"页面必选；受控动作只允许套餐购买或资产钱包充值，不接受 URL、前端路由或任意动作；结束时间不得早于开始时间。",
+		Tags:   []string{"H5 运营弹窗配置"},
+		Auth:   true,
+		Input:  new(dto.CreateH5PopupConfigurationRequest),
+		Output: new(dto.H5PopupConfigurationResponse),
+	})
+
+	Register(configurations, doc, groupPath, "GET", "/:id", handler.GetH5PopupConfiguration, RouteSpec{
+		Summary: "查询运营弹窗配置详情",
+		Tags:    []string{"H5 运营弹窗配置"},
+		Auth:    true,
+		Input:   new(dto.H5PopupConfigurationIDParams),
+		Output:  new(dto.H5PopupConfigurationResponse),
+	})
+
+	Register(configurations, doc, groupPath, "PUT", "/:id", handler.UpdateH5PopupConfiguration, RouteSpec{
+		Summary: "更新运营弹窗配置",
+		Description: "更新运营弹窗配置并递增版本；旧版本已投放通知的内容与快照不被改写，" +
+			"新版本可向原命中客户按频率重新投放一次。",
+		Tags:   []string{"H5 运营弹窗配置"},
+		Auth:   true,
+		Input:  new(dto.UpdateH5PopupConfigurationParams),
+		Output: new(dto.H5PopupConfigurationResponse),
+	})
+
+	// 静态后缀必须先于 /:id 动态路径注册，避免被动态参数吞掉。
+	Register(configurations, doc, groupPath, "POST", "/:id/enable", handler.EnableH5PopupConfiguration, RouteSpec{
+		Summary:     "启用运营弹窗配置",
+		Description: "启用后参与候选匹配，并刷新最近更新时间，影响同优先级排序。",
+		Tags:        []string{"H5 运营弹窗配置"},
+		Auth:        true,
+		Input:       new(dto.H5PopupConfigurationIDParams),
+		Output:      new(dto.H5PopupConfigurationResponse),
+	})
+
+	Register(configurations, doc, groupPath, "POST", "/:id/disable", handler.DisableH5PopupConfiguration, RouteSpec{
+		Summary:     "停用运营弹窗配置",
+		Description: "停用后停止新投放，并刷新最近更新时间；历史通知在展示期内仍可见。",
+		Tags:        []string{"H5 运营弹窗配置"},
+		Auth:        true,
+		Input:       new(dto.H5PopupConfigurationIDParams),
+		Output:      new(dto.H5PopupConfigurationResponse),
+	})
+}

internal/routes/personal.go

@@ -121,6 +121,9 @@ func RegisterPersonalCustomerRoutes(router fiber.Router, doc *openapi.Generator,
 	if handlers.ClientNotification != nil {
 		registerPersonalNotificationRoutes(authGroup, handlers.ClientNotification, doc, basePath)
 	}
+	if handlers.ClientPopup != nil {
+		registerPersonalPopupRoutes(authGroup, handlers.ClientPopup, doc, basePath)
+	}
 
 	// 获取个人资料
 	Register(authGroup, doc, basePath, "GET", "/profile", handlers.PersonalCustomer.GetProfile, RouteSpec{

internal/routes/personal_popup.go

@@ -0,0 +1,35 @@
+package routes
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	apphandler "github.com/break/junhong_cmp_fiber/internal/handler/app"
+	"github.com/break/junhong_cmp_fiber/internal/model/dto"
+	"github.com/break/junhong_cmp_fiber/pkg/openapi"
+)
+
+// registerPersonalPopupRoutes 注册当前个人客户的 H5 弹窗候选与风险换卡地址路由。
+// 候选查询是产品契约中的带副作用 GET：命中时会创建或复用未读通知，客户端随后走既有已读接口。
+func registerPersonalPopupRoutes(router fiber.Router, handler *apphandler.ClientPopupHandler, doc *openapi.Generator, basePath string) {
+	Register(router, doc, basePath, "GET", "/popup-candidates", handler.GetCandidates, RouteSpec{
+		Summary: "查询当前页面的弹窗候选",
+		Description: "按当前页面与当前资产实时匹配弹窗：先判风险换卡资格，命中只返回风险候选；未命中再按时间、启停、页面、店铺、设备类型、卡类型范围与频率匹配运营配置，只返回优先级最高一条。" +
+			"该查询会创建或复用个人站内通知并保持未读（不预生成通知），关闭或稍后处理请用返回的 notification_id 调用 PUT /api/c/v1/notifications/{id}/read。" +
+			"资产不属于当前客户或资产不存在统一返回资源不可见。响应只返回受控动作，不含任何 URL 或前端路由。",
+		Tags:   []string{"个人客户 - 弹窗"},
+		Auth:   true,
+		Input:  &dto.PopupCandidateRequest{},
+		Output: &dto.PopupCandidateResponse{},
+	})
+
+	Register(router, doc, basePath, "POST", "/risk-exchanges/:asset_id/address", handler.SubmitRiskAddress, RouteSpec{
+		Summary: "提交风险换卡收货地址",
+		Description: "当前个人客户为本人风险停机资产提交收货人姓名、手机号与完整地址，幂等创建关联旧资产的物流换货单。" +
+			"首次地址锁定，重复或并发提交返回首次创建的换货单与首次地址且不覆盖；换货单创建即待发货，不预设业务数据迁移。" +
+			"资产不属于当前客户或资产不存在统一返回资源不可见。",
+		Tags:   []string{"个人客户 - 弹窗"},
+		Auth:   true,
+		Input:  &dto.ClientRiskExchangeAddressParams{},
+		Output: &dto.ClientRiskExchangeResponse{},
+	})
+}