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）与参数校验中文提示共用实现。
2026-09-15 15:23:52 +08:00
parent 70e680eb0a
commit 333ba4b647
39 changed files with 2861 additions and 166 deletions
--- a/internal/infrastructure/audit/registry.go
+++ b/internal/infrastructure/audit/registry.go
@@ -175,6 +175,13 @@ func NewRegistry() *Registry {
 	carrierUpdated := connectionConfigAction(constants.AuditActionCarrierUpdated, "更新运营商配置", constants.AuditResourceCarrier, constants.AuditRiskNormal)
 	carrierDeleted := connectionConfigAction(constants.AuditActionCarrierDeleted, "删除运营商配置", constants.AuditResourceCarrier, constants.AuditRiskHigh)
 	carrierStatusUpdated := connectionConfigAction(constants.AuditActionCarrierStatusUpdated, "更新运营商配置状态", constants.AuditResourceCarrier, constants.AuditRiskHigh)
+	// H5 运营弹窗配置：启停只影响后续投放，但会改变客户端可见内容与频率口径，统一按关键配置记录前后值。
+	h5PopupConfigCreated := connectionConfigAction(constants.AuditActionH5PopupConfigurationCreated, "创建 H5 运营弹窗配置", constants.AuditResourceH5PopupConfiguration, constants.AuditRiskHigh)
+	h5PopupConfigUpdated := connectionConfigAction(constants.AuditActionH5PopupConfigurationUpdated, "更新 H5 运营弹窗配置", constants.AuditResourceH5PopupConfiguration, constants.AuditRiskHigh)
+	h5PopupConfigEnabled := connectionConfigAction(constants.AuditActionH5PopupConfigurationEnabled, "启用 H5 运营弹窗配置", constants.AuditResourceH5PopupConfiguration, constants.AuditRiskHigh)
+	h5PopupConfigDisabled := connectionConfigAction(constants.AuditActionH5PopupConfigurationDisabled, "停用 H5 运营弹窗配置", constants.AuditResourceH5PopupConfiguration, constants.AuditRiskHigh)
+	// 客户自助风险换卡由个人客户入口发起，创建的是共用换货表事实，因此允许个人客户来源并复用换货单主资源。
+	cardRiskExchangeRequested := cardExchangeAction(constants.AuditActionCardRiskExchangeRequested, "客户自助发起风险换卡", constants.AuditRiskHigh, true)
 	wecomApplicationSaved := connectionConfigAction(constants.AuditActionWeComApplicationSaved, "保存企业微信应用配置", constants.AuditResourceWeComApplication, constants.AuditRiskHigh)
 	wecomDefaultCreatorSaved := connectionConfigAction(constants.AuditActionWeComDefaultCreatorSaved, "保存企业微信默认审批发起人", constants.AuditResourceWeComApplication, constants.AuditRiskHigh)
 	wecomMembersSynced := connectionConfigAction(constants.AuditActionWeComMembersSynced, "同步企业微信应用可见成员", constants.AuditResourceWeComApplication, constants.AuditRiskNormal)
@@ -227,6 +234,8 @@ func NewRegistry() *Registry {
 	phoneAssetUnbindImportTaskCreated := taskAction(constants.AuditActionPhoneAssetUnbindImportTaskCreated, "创建手机号资产解绑导入任务", constants.AuditResourcePhoneAssetUnbindImportTask, constants.AuditActorAccount, constants.AuditSourceAdminAPI)
 	phoneAssetUnbindImportTaskCompleted := taskAction(constants.AuditActionPhoneAssetUnbindImportTaskCompleted, "完成手机号资产解绑导入任务", constants.AuditResourcePhoneAssetUnbindImportTask, constants.AuditActorSystemTask, constants.AuditSourceWorker)
 	notificationDelivered := notificationAction(constants.AuditActionNotificationDelivered, "生成站内通知", constants.AuditResourceNotification, constants.AuditActorSystemTask, constants.AuditSourceWorker)
+	// H5 候选查询会当次直投个人客户通知（不依赖 Outbox 消费），因此同一动作必须同时允许个人客户入口。
+	notificationDelivered.AllowedOrigins = []ActionOrigin{{Actor: constants.AuditActorPersonalCustomer, Source: constants.AuditSourcePersonalAPI}}
 	notificationRead := notificationAction(constants.AuditActionNotificationRead, "标记通知已读", constants.AuditResourceNotification, constants.AuditActorAccount, constants.AuditSourceAdminAPI)
 	notificationRead.AllowedOrigins = []ActionOrigin{{Actor: constants.AuditActorPersonalCustomer, Source: constants.AuditSourcePersonalAPI}}
 	notificationReadAll := notificationAction(constants.AuditActionNotificationReadAll, "批量标记通知已读", constants.AuditResourceNotificationReadBatch, constants.AuditActorAccount, constants.AuditSourceAdminAPI)
@@ -426,6 +435,10 @@ func NewRegistry() *Registry {
 			constants.AuditOperationCarrierUpdate:                         carrierUpdated,
 			constants.AuditOperationCarrierDelete:                         carrierDeleted,
 			constants.AuditOperationCarrierStatusUpdate:                   carrierStatusUpdated,
+			constants.AuditOperationH5PopupConfigurationCreate:            h5PopupConfigCreated,
+			constants.AuditOperationH5PopupConfigurationUpdate:            h5PopupConfigUpdated,
+			constants.AuditOperationH5PopupConfigurationEnable:            h5PopupConfigEnabled,
+			constants.AuditOperationH5PopupConfigurationDisable:           h5PopupConfigDisabled,
 			constants.AuditOperationWeComApplicationSave:                  wecomApplicationSaved,
 			constants.AuditOperationWeComDefaultCreatorSave:               wecomDefaultCreatorSaved,
 			constants.AuditOperationWeComMembersSync:                      wecomMembersSynced,
@@ -545,6 +558,11 @@ func NewRegistry() *Registry {
 			constants.AuditActionCarrierUpdated:                         carrierUpdated,
 			constants.AuditActionCarrierDeleted:                         carrierDeleted,
 			constants.AuditActionCarrierStatusUpdated:                   carrierStatusUpdated,
+			constants.AuditActionH5PopupConfigurationCreated:            h5PopupConfigCreated,
+			constants.AuditActionH5PopupConfigurationUpdated:            h5PopupConfigUpdated,
+			constants.AuditActionH5PopupConfigurationEnabled:            h5PopupConfigEnabled,
+			constants.AuditActionH5PopupConfigurationDisabled:           h5PopupConfigDisabled,
+			constants.AuditActionCardRiskExchangeRequested:              cardRiskExchangeRequested,
 			constants.AuditActionEmployeeCollectionPaymentMethodCreated: employeeCollectionPaymentMethodCreated,
 			constants.AuditActionEmployeeCollectionPaymentMethodUpdated: employeeCollectionPaymentMethodUpdated,
 			constants.AuditActionEmployeeCollectionPaymentMethodDeleted: employeeCollectionPaymentMethodDeleted,
@@ -731,6 +749,13 @@ func NewRegistry() *Registry {
 				Type: constants.AuditResourceCarrier, Name: "运营商配置",
 				IdentityFields: []string{"id", "carrier_code", "carrier_name", "carrier_type", "status"},
 			},
+			constants.AuditResourceH5PopupConfiguration: {
+				Type: constants.AuditResourceH5PopupConfiguration, Name: "H5 运营弹窗配置",
+				IdentityFields: []string{
+					"id", "title", "pages", "shop_ids", "device_types", "card_types",
+					"priority", "frequency", "action_type", "enabled", "starts_at", "ends_at", "version",
+				},
+			},
 			constants.AuditResourceEmployeeCollectionPaymentMethod: {
 				Type: constants.AuditResourceEmployeeCollectionPaymentMethod, Name: "线下收款方式",
 				IdentityFields: []string{"id", "code", "name", "status", "sort"},
--- a/internal/infrastructure/notification/registry.go
+++ b/internal/infrastructure/notification/registry.go
@@ -118,6 +118,30 @@ func NewRegistry() *Registry {
 				constants.NotificationRefTypeShopFund: {},
 			},
 		},
+		// 风险换卡弹窗：内容固定，不含任何配置信息；资源引用只指向旧资产。
+		constants.NotificationTypeH5PopupRiskExchange: {
+			Type: constants.NotificationTypeH5PopupRiskExchange, Category: constants.NotificationCategorySystem,
+			Severity:       constants.NotificationSeverityWarning,
+			TitleTemplate:  "换卡地址待填写",
+			BodyTemplate:   "您的广电卡已被运营商风险停机，请填写收货地址以便寄送新卡。",
+			TemplateFields: map[string]struct{}{},
+			RecipientKinds: map[string]struct{}{constants.NotificationRecipientKindPersonalCustomer: {}},
+			AllowedRefTypes: map[string]struct{}{
+				constants.NotificationRefTypeAsset: {},
+			},
+		},
+		// 运营弹窗：标题与正文由运营配置在投放时冻结，禁止 HTML 与 URL；资源引用只指向当前资产。
+		constants.NotificationTypeH5PopupOperation: {
+			Type: constants.NotificationTypeH5PopupOperation, Category: constants.NotificationCategorySystem,
+			Severity:       constants.NotificationSeverityInfo,
+			TitleTemplate:  "{{.title}}",
+			BodyTemplate:   "{{.content}}",
+			TemplateFields: map[string]struct{}{"title": {}, "content": {}},
+			RecipientKinds: map[string]struct{}{constants.NotificationRecipientKindPersonalCustomer: {}},
+			AllowedRefTypes: map[string]struct{}{
+				constants.NotificationRefTypeAsset: {},
+			},
+		},
 	}}
 }

--- a/internal/infrastructure/notification/repository.go
+++ b/internal/infrastructure/notification/repository.go
@@ -35,6 +35,17 @@ func (r *Repository) CreateIdempotent(ctx context.Context, notification *model.N
 	return result.RowsAffected == 1, result.Error
 }

+// FindByEventRecipient 按事件键与接收人回查既有通知，用于幂等冲突时返回既有行而不是重复投放。
+func (r *Repository) FindByEventRecipient(ctx context.Context, eventID, recipientKind string, recipientID uint) (*model.Notification, error) {
+	var notification model.Notification
+	if err := r.db.WithContext(ctx).
+		Where("event_id = ? AND recipient_kind = ? AND recipient_id = ?", eventID, recipientKind, recipientID).
+		Take(&notification).Error; err != nil {
+		return nil, err
+	}
+	return &notification, nil
+}
+
 // IsActiveAccount 判断明确后台账号是否仍启用且未软删除。
 func (r *Repository) IsActiveAccount(ctx context.Context, accountID uint) (bool, error) {
 	var count int64