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）与参数校验中文提示共用实现。

pkg/constants/audit.go

@@ -446,6 +446,16 @@ const (
 	AuditActionCarrierDeleted = "carrier.delete"
 	// AuditActionCarrierStatusUpdated 表示更新运营商配置状态。
 	AuditActionCarrierStatusUpdated = "carrier.update_status"
+	// AuditActionH5PopupConfigurationCreated 表示创建 H5 运营弹窗配置。
+	AuditActionH5PopupConfigurationCreated = "h5_popup_configuration.create"
+	// AuditActionH5PopupConfigurationUpdated 表示更新 H5 运营弹窗配置并递增版本。
+	AuditActionH5PopupConfigurationUpdated = "h5_popup_configuration.update"
+	// AuditActionH5PopupConfigurationEnabled 表示启用 H5 运营弹窗配置。
+	AuditActionH5PopupConfigurationEnabled = "h5_popup_configuration.enable"
+	// AuditActionH5PopupConfigurationDisabled 表示停用 H5 运营弹窗配置。
+	AuditActionH5PopupConfigurationDisabled = "h5_popup_configuration.disable"
+	// AuditActionCardRiskExchangeRequested 表示个人客户自助发起风险换卡。
+	AuditActionCardRiskExchangeRequested = "exchange.card.request_risk_exchange"
 	// AuditActionWeComApplicationSaved 表示保存企业微信应用配置。
 	AuditActionWeComApplicationSaved = "wecom.application.save"
 	// AuditActionWeComDefaultCreatorSaved 表示保存企业微信默认审批发起人。
@@ -618,6 +628,14 @@ const (
 	AuditOperationCarrierDelete = "carrier_delete"
 	// AuditOperationCarrierStatusUpdate 表示更新运营商配置状态。
 	AuditOperationCarrierStatusUpdate = "carrier_status_update"
+	// AuditOperationH5PopupConfigurationCreate 表示创建 H5 运营弹窗配置。
+	AuditOperationH5PopupConfigurationCreate = "h5_popup_configuration_create"
+	// AuditOperationH5PopupConfigurationUpdate 表示更新 H5 运营弹窗配置。
+	AuditOperationH5PopupConfigurationUpdate = "h5_popup_configuration_update"
+	// AuditOperationH5PopupConfigurationEnable 表示启用 H5 运营弹窗配置。
+	AuditOperationH5PopupConfigurationEnable = "h5_popup_configuration_enable"
+	// AuditOperationH5PopupConfigurationDisable 表示停用 H5 运营弹窗配置。
+	AuditOperationH5PopupConfigurationDisable = "h5_popup_configuration_disable"
 	// AuditOperationWeComApplicationSave 表示保存企业微信应用配置。
 	AuditOperationWeComApplicationSave = "wecom_application_save"
 	// AuditOperationWeComDefaultCreatorSave 表示保存企业微信默认审批发起人。
@@ -645,6 +663,8 @@ const (
 	AuditResourcePaymentConfig = "payment_config"
 	// AuditResourceCarrier 表示运营商配置资源。
 	AuditResourceCarrier = "carrier"
+	// AuditResourceH5PopupConfiguration 表示 H5 运营弹窗配置资源。
+	AuditResourceH5PopupConfiguration = "h5_popup_configuration"
 	// AuditResourceEmployeeCollectionPaymentMethod 表示线下收款方式字典资源。
 	AuditResourceEmployeeCollectionPaymentMethod = "employee_collection_payment_method"
 	// AuditResourceEmployeeCollectionBill 表示员工代收款账单资源。

pkg/constants/h5_popup.go

@@ -0,0 +1,140 @@
+package constants
+
+const (
+	// H5PopupPageHome 表示 H5 首页。
+	H5PopupPageHome = "home"
+	// H5PopupPageAssetDetail 表示 H5 资产详情页。
+	H5PopupPageAssetDetail = "asset_detail"
+	// H5PopupPagePackagePurchase 表示 H5 套餐购买页。
+	H5PopupPagePackagePurchase = "package_purchase"
+	// H5PopupPageAssetWalletRecharge 表示 H5 资产钱包充值页。
+	H5PopupPageAssetWalletRecharge = "asset_wallet_recharge"
+
+	// H5PopupFrequencyOnce 表示每客户每配置版本仅投放一次。
+	H5PopupFrequencyOnce = "once"
+	// H5PopupFrequencyDaily 表示每客户每配置版本每个上海自然日投放一次。
+	H5PopupFrequencyDaily = "daily"
+
+	// H5PopupActionPackagePurchase 表示受控动作套餐购买。
+	H5PopupActionPackagePurchase = "package_purchase"
+	// H5PopupActionAssetWalletRecharge 表示受控动作资产钱包充值。
+	H5PopupActionAssetWalletRecharge = "asset_wallet_recharge"
+
+	// H5PopupStatusDisabled 表示运营弹窗配置已停用。
+	H5PopupStatusDisabled = 0
+	// H5PopupStatusEnabled 表示运营弹窗配置已启用。
+	H5PopupStatusEnabled = 1
+
+	// H5PopupCandidateTypeRiskExchange 表示候选为风险换卡弹窗。
+	H5PopupCandidateTypeRiskExchange = "risk_exchange"
+	// H5PopupCandidateTypeOperation 表示候选为运营弹窗。
+	H5PopupCandidateTypeOperation = "operation"
+
+	// H5PopupRiskExchangeReason 是客户自助风险换卡单的固定换货原因，保证换货原因非空且可追溯来源。
+	H5PopupRiskExchangeReason = "运营商风险停机，客户自助申请寄送新卡"
+
+	// H5PopupDisplayDays 表示弹窗投放通知的展示保留天数，与投放时间共同决定 expires_at。
+	H5PopupDisplayDays = 90
+
+	// H5PopupRiskEventKeyPrefix 是风险换卡候选通知的事件键前缀，键内包含上海自然日以保证一天一条。
+	H5PopupRiskEventKeyPrefix = "h5popup.risk"
+	// H5PopupOperationOnceEventKeyPrefix 是仅一次运营弹窗通知的事件键前缀。
+	H5PopupOperationOnceEventKeyPrefix = "h5popup.once"
+	// H5PopupOperationDailyEventKeyPrefix 是每天一次运营弹窗通知的事件键前缀，键内包含上海自然日。
+	H5PopupOperationDailyEventKeyPrefix = "h5popup.daily"
+
+	// H5PopupAuditConfigKeyPrefix 表示运营弹窗配置审计配置键前缀。
+	H5PopupAuditConfigKeyPrefix = "h5_popup_configuration"
+	// H5PopupAuditModule 表示 H5 弹窗能力的审计模块标识。
+	H5PopupAuditModule = "h5_popup"
+)
+
+// IsH5PopupPage 判断页面是否为受控的 H5 弹窗页面。
+func IsH5PopupPage(page string) bool {
+	switch page {
+	case H5PopupPageHome, H5PopupPageAssetDetail, H5PopupPagePackagePurchase, H5PopupPageAssetWalletRecharge:
+		return true
+	default:
+		return false
+	}
+}
+
+// IsH5PopupFrequency 判断投放频率是否为受控值。
+func IsH5PopupFrequency(frequency string) bool {
+	switch frequency {
+	case H5PopupFrequencyOnce, H5PopupFrequencyDaily:
+		return true
+	default:
+		return false
+	}
+}
+
+// IsH5PopupActionType 判断受控动作是否合法；空值表示无受控动作。
+func IsH5PopupActionType(actionType string) bool {
+	switch actionType {
+	case "", H5PopupActionPackagePurchase, H5PopupActionAssetWalletRecharge:
+		return true
+	default:
+		return false
+	}
+}
+
+// IsCarrierType 判断卡类型是否为受控运营商类型；用于范围配置的取值校验。
+func IsCarrierType(carrierType string) bool {
+	switch carrierType {
+	case CarrierTypeCMCC, CarrierTypeCUCC, CarrierTypeCTCC, CarrierTypeCBN:
+		return true
+	default:
+		return false
+	}
+}
+
+// IsH5PopupNotificationType 判断通知类型是否为弹窗投放类型；只有弹窗类型才写投放快照。
+func IsH5PopupNotificationType(notificationType string) bool {
+	switch notificationType {
+	case NotificationTypeH5PopupRiskExchange, NotificationTypeH5PopupOperation:
+		return true
+	default:
+		return false
+	}
+}
+
+// GetH5PopupFrequencyName 获取运营弹窗投放频率名称。
+func GetH5PopupFrequencyName(frequency string) string {
+	switch frequency {
+	case H5PopupFrequencyOnce:
+		return "仅一次"
+	case H5PopupFrequencyDaily:
+		return "每天一次"
+	default:
+		return ""
+	}
+}
+
+// GetH5PopupEnabledName 获取运营弹窗启停状态名称。
+func GetH5PopupEnabledName(status int) string {
+	switch status {
+	case H5PopupStatusEnabled:
+		return "启用"
+	case H5PopupStatusDisabled:
+		return "停用"
+	default:
+		return ""
+	}
+}
+
+// GetH5PopupPageName 获取 H5 弹窗页面名称。
+func GetH5PopupPageName(page string) string {
+	switch page {
+	case H5PopupPageHome:
+		return "首页"
+	case H5PopupPageAssetDetail:
+		return "资产详情"
+	case H5PopupPagePackagePurchase:
+		return "套餐购买"
+	case H5PopupPageAssetWalletRecharge:
+		return "资产钱包充值"
+	default:
+		return ""
+	}
+}

pkg/constants/notification.go

@@ -42,6 +42,10 @@ const (
 	NotificationTypeExchangeShippingCreated = "exchange.shipping.created"
 	// NotificationTypeAgentMainWalletLowBalance 表示代理主钱包余额低于固定阈值提醒。
 	NotificationTypeAgentMainWalletLowBalance = "agent.main_wallet.low_balance"
+	// NotificationTypeH5PopupRiskExchange 表示 H5 广电卡风险换卡弹窗投放。
+	NotificationTypeH5PopupRiskExchange = "h5.popup.risk_exchange"
+	// NotificationTypeH5PopupOperation 表示 H5 运营弹窗投放。
+	NotificationTypeH5PopupOperation = "h5.popup.operation"
 
 	// NotificationRefTypeSystemConfig 表示系统配置资源引用。
 	NotificationRefTypeSystemConfig = "system_config"

pkg/errors/codes.go

@@ -192,6 +192,10 @@ const (
 	CodeEmployeeCollectionBillClosed               = 1242 // 账单已关闭
 	CodeEmployeeCollectionVoucherInvalid           = 1243 // 支付凭证数量或内容不符合要求
 
+	// H5 弹窗相关错误 (1250-1259)
+	CodeH5PopupConfigurationNotFound = 1250 // 运营弹窗配置不存在
+	CodeH5PopupRiskNotEligible       = 1251 // 当前资产不满足风险换卡条件
+
 	// 服务端错误 (2000-2999) -> 5xx HTTP 状态码
 	CodeInternalError      = 2001 // 内部服务器错误
 	CodeDatabaseError      = 2002 // 数据库错误
@@ -350,6 +354,8 @@ var allErrorCodes = []int{
 	CodeEmployeeCollectionApplicationPending,
 	CodeEmployeeCollectionBillClosed,
 	CodeEmployeeCollectionVoucherInvalid,
+	CodeH5PopupConfigurationNotFound,
+	CodeH5PopupRiskNotEligible,
 	CodeInternalError,
 	CodeDatabaseError,
 	CodeRedisError,
@@ -502,6 +508,8 @@ var errorMessages = map[int]string{
 	CodeEmployeeCollectionApplicationPending:       "账单存在审批中核销申请，不能关闭",
 	CodeEmployeeCollectionBillClosed:               "账单已关闭",
 	CodeEmployeeCollectionVoucherInvalid:           "支付凭证数量或内容不符合要求",
+	CodeH5PopupConfigurationNotFound:               "运营弹窗配置不存在",
+	CodeH5PopupRiskNotEligible:                     "当前资产不满足风险换卡条件",
 	CodeInvalidCredentials:                         "用户名或密码错误",
 	CodeAccountLocked:                              "账号已锁定",
 	CodePasswordExpired:                            "密码已过期",

pkg/openapi/handlers.go

@@ -26,6 +26,7 @@ func BuildDocHandlers() *bootstrap.Handlers {
 		ClientDevice:                app.NewClientDeviceHandler(nil, nil, nil, nil, nil, nil, nil),
 		ClientRechargeOrder:         app.NewClientRechargeOrderHandler(nil, nil, nil),
 		ClientNotification:          app.NewClientNotificationHandler(nil, nil, nil),
+		ClientPopup:                 app.NewClientPopupHandler(nil, nil, nil),
 		Shop:                        admin.NewShopHandler(nil, nil),
 		ShopRole:                    admin.NewShopRoleHandler(nil),
 		AdminAuth:                   admin.NewAuthHandler(nil, nil),
@@ -42,6 +43,7 @@ func BuildDocHandlers() *bootstrap.Handlers {
 		IotCardImport:               admin.NewIotCardImportHandler(nil),
 		ExportTask:                  admin.NewExportTaskHandler(nil),
 		Notification:                admin.NewNotificationHandler(nil, nil, nil),
+		H5PopupConfiguration:        admin.NewH5PopupConfigurationHandler(nil, nil, nil),
 		Device:                      admin.NewDeviceHandler(nil),
 		DeviceImport:                admin.NewDeviceImportHandler(nil),
 		AssetAllocationRecord:       admin.NewAssetAllocationRecordHandler(nil),