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/application/notification/delivery.go

@@ -51,6 +51,7 @@ type deliveryRequest struct {
 	refID            string
 	refKey           string
 	expiresAt        *time.Time
+	popupSnapshot    *model.NotificationPopupSnapshot
 }
 
 // DeliveryService 校验接收人并幂等生成站内通知。
@@ -123,6 +124,7 @@ func (s *DeliveryService) consumeDynamic(ctx context.Context, envelope outbox.De
 		notificationType: payload.NotificationType, templateData: payload.TemplateData,
 		refType: payload.RefType, refID: payload.RefID, refKey: payload.RefKey, expiresAt: payload.ExpiresAt,
 	}
+	// 载荷校验必须先于接收人解析：无效事件不应触发接收人查询。
 	if err := validateDeliveryRequest(request); err != nil {
 		return err
 	}
@@ -153,19 +155,45 @@ func validateDeliveryRequest(request deliveryRequest) error {
 	if request.refType != "" && request.refID == "" && request.refKey == "" {
 		return errors.New(errors.CodeInvalidParam, "通知资源引用缺少定位值")
 	}
+	// 投放快照与弹窗类型必须成对出现：非弹窗类型不得写快照，弹窗类型不得缺少快照。
+	isPopup := constants.IsH5PopupNotificationType(request.notificationType)
+	if request.popupSnapshot != nil && !isPopup {
+		return errors.New(errors.CodeInvalidParam, "投放快照只允许用于弹窗通知类型")
+	}
+	if isPopup && request.popupSnapshot == nil {
+		return errors.New(errors.CodeInvalidParam, "弹窗通知缺少投放快照")
+	}
 	return nil
 }
 
-func (s *DeliveryService) deliver(ctx context.Context, eventID, recipientKind string, recipientIDs []uint, request deliveryRequest) error {
+// preparedDelivery 是一次事件共享的渲染结果、展示期与审计来源，与接收人数量无关。
+type preparedDelivery struct {
+	rendered  notificationinfra.Rendered
+	now       time.Time
+	expiresAt *time.Time
+	origin    deliveryOrigin
+}
+
+// deliveryOrigin 是投递审计的操作者与入口。
+// Outbox 消费路径留空，由统一审计从任务上下文补齐（与既有 worker 入口一致）；
+// API 直投路径必须显式提供，因为个人客户请求上下文不携带审计上下文。
+type deliveryOrigin struct {
+	actor  audit.ActorInput
+	source string
+}
+
+// prepareDelivery 渲染模板并计算展示期；同一事件只计算一次，不随接收人重复计算。
+// 审计接缝缺失在此一次性判空：与既有行为一致，渲染之前就失败，而不是按接收人重复判断。
+func (s *DeliveryService) prepareDelivery(eventID, recipientKind string, request deliveryRequest, origin deliveryOrigin) (*preparedDelivery, error) {
 	if s.auditWriter == nil {
-		return errors.New(errors.CodeInvalidStatus, "通知统一审计接缝未配置")
+		return nil, errors.New(errors.CodeInvalidStatus, "通知统一审计接缝未配置")
 	}
 	rendered, err := s.registry.Render(request.notificationType, request.templateData, request.refType, recipientKind)
 	if err != nil {
 		s.logger.Error("站内通知模板校验失败",
 			zap.String("event_id", eventID), zap.String("notification_type", request.notificationType),
 			zap.String("failure_category", "template"))
-		return errors.Wrap(errors.CodeInvalidParam, err, "站内通知模板校验失败")
+		return nil, errors.Wrap(errors.CodeInvalidParam, err, "站内通知模板校验失败")
 	}
 	now := s.now().UTC()
 	expiresAt, err := notificationDisplayExpiry(rendered.Category, request.expiresAt, now)
@@ -173,46 +201,23 @@ func (s *DeliveryService) deliver(ctx context.Context, eventID, recipientKind st
 		s.logger.Error("站内通知展示期限校验失败",
 			zap.String("event_id", eventID), zap.String("notification_type", request.notificationType),
 			zap.String("failure_category", "display_policy"))
+		return nil, err
+	}
+	return &preparedDelivery{rendered: rendered, now: now, expiresAt: expiresAt, origin: origin}, nil
+}
+
+// deliver 对每个接收人执行同一套单接收人投放规则；接收人不可用时跳过，不影响其他接收人。
+func (s *DeliveryService) deliver(ctx context.Context, eventID, recipientKind string, recipientIDs []uint, request deliveryRequest) error {
+	prepared, err := s.prepareDelivery(eventID, recipientKind, request, deliveryOrigin{})
+	if err != nil {
 		return err
 	}
 	for _, recipientID := range recipientIDs {
-		active, err := s.isActiveRecipient(ctx, recipientKind, recipientID)
+		notification, created, err := s.deliverOne(ctx, eventID, recipientKind, recipientID, request, prepared)
 		if err != nil {
-			return errors.Wrap(errors.CodeDatabaseError, err, "校验通知接收人失败")
+			return err
 		}
-		if !active {
-			s.logger.Info("站内通知接收人不可用，已跳过",
-				zap.String("event_id", eventID), zap.String("recipient_kind", recipientKind), zap.Uint("recipient_id", recipientID))
-			continue
-		}
-		notification := &model.Notification{
-			EventID: eventID, RecipientKind: recipientKind,
-			RecipientID: recipientID, Category: rendered.Category, Type: rendered.Type,
-			Severity: rendered.Severity, Title: rendered.Title, Body: rendered.Body,
-			RefType: request.refType, RefID: request.refID, RefKey: request.refKey,
-			ExpiresAt: expiresAt, CreatedAt: now,
-		}
-		created := false
-		err = s.repository.DB().WithContext(ctx).Transaction(func(tx *gorm.DB) error {
-			var createErr error
-			created, createErr = s.repository.WithTx(tx).CreateIdempotent(ctx, notification)
-			if createErr != nil || !created {
-				return createErr
-			}
-			return s.auditWriter.Append(ctx, tx, audit.AppendInput{
-				EventID:    audit.TaskEventID(constants.AuditResourceNotification, notification.ID, "delivered"),
-				ActionCode: constants.AuditActionNotificationDelivered, Summary: "生成站内通知",
-				ScopeType: constants.AuditScopePlatform, Result: constants.AuditResultSuccess,
-				Metadata: map[string]any{"outbox_event_id": eventID},
-				Resources: []audit.ResourceInput{audit.NotificationResource(notification,
-					constants.AuditResourceRelationPrimary, constants.AuditResourceRoleNotificationTarget,
-					nil, map[string]any{"created": true, "is_read": false})},
-			})
-		})
-		if err != nil {
-			return errors.Wrap(errors.CodeDatabaseError, err, "写入站内通知失败")
-		}
-		if !created {
+		if notification != nil && !created {
 			s.logger.Info("站内通知重复事件已幂等忽略",
 				zap.String("event_id", eventID), zap.String("recipient_kind", recipientKind), zap.Uint("recipient_id", recipientID))
 		}
@@ -220,6 +225,60 @@ func (s *DeliveryService) deliver(ctx context.Context, eventID, recipientKind st
 	return nil
 }
 
+// deliverOne 校验接收人并在单事务内幂等写入一条通知。
+// 事件键与接收人已存在时不重复投放，回查并返回既有行（created=false）；接收人不可用时返回 (nil, false, nil)。
+// Outbox 消费与候选查询直投共用本方法，落库规则只有一处。
+func (s *DeliveryService) deliverOne(ctx context.Context, eventID, recipientKind string, recipientID uint, request deliveryRequest, prepared *preparedDelivery) (*model.Notification, bool, error) {
+	if eventID == "" || recipientID == 0 || prepared == nil {
+		return nil, false, errors.New(errors.CodeInvalidParam, "通知事件或接收人不完整")
+	}
+	active, err := s.isActiveRecipient(ctx, recipientKind, recipientID)
+	if err != nil {
+		return nil, false, errors.Wrap(errors.CodeDatabaseError, err, "校验通知接收人失败")
+	}
+	if !active {
+		s.logger.Info("站内通知接收人不可用，已跳过",
+			zap.String("event_id", eventID), zap.String("recipient_kind", recipientKind), zap.Uint("recipient_id", recipientID))
+		return nil, false, nil
+	}
+	notification := &model.Notification{
+		EventID: eventID, RecipientKind: recipientKind,
+		RecipientID: recipientID, Category: prepared.rendered.Category, Type: prepared.rendered.Type,
+		Severity: prepared.rendered.Severity, Title: prepared.rendered.Title, Body: prepared.rendered.Body,
+		RefType: request.refType, RefID: request.refID, RefKey: request.refKey,
+		ExpiresAt: prepared.expiresAt, CreatedAt: prepared.now, PopupSnapshot: request.popupSnapshot,
+	}
+	created := false
+	err = s.repository.DB().WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		var createErr error
+		created, createErr = s.repository.WithTx(tx).CreateIdempotent(ctx, notification)
+		if createErr != nil || !created {
+			return createErr
+		}
+		return s.auditWriter.Append(ctx, tx, audit.AppendInput{
+			EventID:    audit.TaskEventID(constants.AuditResourceNotification, notification.ID, "delivered"),
+			ActionCode: constants.AuditActionNotificationDelivered, Summary: "生成站内通知",
+			Actor: prepared.origin.actor, Source: prepared.origin.source,
+			ScopeType: constants.AuditScopePlatform, Result: constants.AuditResultSuccess,
+			Metadata: map[string]any{"outbox_event_id": eventID},
+			Resources: []audit.ResourceInput{audit.NotificationResource(notification,
+				constants.AuditResourceRelationPrimary, constants.AuditResourceRoleNotificationTarget,
+				nil, map[string]any{"created": true, "is_read": false})},
+		})
+	})
+	if err != nil {
+		return nil, false, errors.Wrap(errors.CodeDatabaseError, err, "写入站内通知失败")
+	}
+	if created {
+		return notification, true, nil
+	}
+	existing, err := s.repository.FindByEventRecipient(ctx, eventID, recipientKind, recipientID)
+	if err != nil {
+		return nil, false, errors.Wrap(errors.CodeDatabaseError, err, "回查既有站内通知失败")
+	}
+	return existing, false, nil
+}
+
 func notificationDisplayExpiry(category string, requested *time.Time, now time.Time) (*time.Time, error) {
 	switch category {
 	case constants.NotificationCategoryApproval:

internal/application/notification/direct.go

@@ -0,0 +1,63 @@
+package notification
+
+import (
+	"context"
+	"strconv"
+	"time"
+
+	"github.com/break/junhong_cmp_fiber/internal/infrastructure/audit"
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+)
+
+// PersonalDirectRequest 是当次直投或复用个人客户通知的请求参数。
+// PopupSnapshot 只允许弹窗投放类型携带，其余类型必须为空。
+type PersonalDirectRequest struct {
+	NotificationType string
+	TemplateData     map[string]string
+	RefType          string
+	RefID            string
+	RefKey           string
+	ExpiresAt        *time.Time
+	PopupSnapshot    *model.NotificationPopupSnapshot
+}
+
+// DirectWriter 是「当次创建或复用个人客户通知」的窄接口。
+// 候选查询必须当次拿到可用通知标识，不能依赖 Outbox 消费延迟，因此需要这条同步入口。
+type DirectWriter interface {
+	CreateOrGetPersonal(ctx context.Context, eventID string, customerID uint, request PersonalDirectRequest) (*model.Notification, error)
+}
+
+// CreateOrGetPersonal 当次渲染并幂等写入个人客户通知；事件键已存在时不重复投放，回查并返回既有行。
+// 与 Outbox 消费共用同一渲染、展示期与幂等写入规则，避免两条链路规则漂移。
+func (s *DeliveryService) CreateOrGetPersonal(ctx context.Context, eventID string, customerID uint, request PersonalDirectRequest) (*model.Notification, error) {
+	if customerID == 0 || eventID == "" {
+		return nil, errors.New(errors.CodeInvalidParam, "个人客户通知参数不完整")
+	}
+	delivery := deliveryRequest{
+		notificationType: request.NotificationType, templateData: request.TemplateData,
+		refType: request.RefType, refID: request.RefID, refKey: request.RefKey,
+		expiresAt: request.ExpiresAt, popupSnapshot: request.PopupSnapshot,
+	}
+	if err := validateDeliveryRequest(delivery); err != nil {
+		return nil, err
+	}
+	// API 直投不经过 Outbox 消费，自行提供渲染结果与展示期，但仍复用同一落库规则。
+	// 个人客户请求上下文不携带审计上下文，直投必须显式声明操作者与入口，否则投递审计会被入口规则拒绝并静默降级。
+	prepared, err := s.prepareDelivery(eventID, constants.NotificationRecipientKindPersonalCustomer, delivery, deliveryOrigin{
+		actor:  audit.ActorInput{Kind: constants.AuditActorPersonalCustomer, ID: strconv.FormatUint(uint64(customerID), 10)},
+		source: constants.AuditSourcePersonalAPI,
+	})
+	if err != nil {
+		return nil, err
+	}
+	notification, _, err := s.deliverOne(ctx, eventID, constants.NotificationRecipientKindPersonalCustomer, customerID, delivery, prepared)
+	if err != nil {
+		return nil, err
+	}
+	if notification == nil {
+		return nil, errors.New(errors.CodeInvalidStatus, "个人客户通知接收人不可用")
+	}
+	return notification, nil
+}

internal/application/notification/read.go

@@ -214,7 +214,12 @@ func personalReadScope(db *gorm.DB, customerID uint, now time.Time) *gorm.DB {
 		constants.NotificationRecipientKindPersonalCustomer,
 		customerID,
 		[]string{constants.NotificationCategoryApproval, constants.NotificationCategoryExpiry, constants.NotificationCategorySystem},
-		[]string{constants.NotificationTypePackageExpiring, constants.NotificationTypeExchangeShippingCreated},
+		[]string{
+			constants.NotificationTypePackageExpiring,
+			constants.NotificationTypeExchangeShippingCreated,
+			constants.NotificationTypeH5PopupRiskExchange,
+			constants.NotificationTypeH5PopupOperation,
+		},
 		now,
 	)
 }