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/handler/admin/h5_popup_configuration.go
+++ b/internal/handler/admin/h5_popup_configuration.go
@@ -0,0 +1,178 @@
+package admin
+
+import (
+	"strconv"
+
+	"github.com/go-playground/validator/v10"
+	"github.com/gofiber/fiber/v2"
+
+	h5popupapp "github.com/break/junhong_cmp_fiber/internal/application/h5popup"
+	"github.com/break/junhong_cmp_fiber/internal/handler/validation"
+	"github.com/break/junhong_cmp_fiber/internal/model/dto"
+	h5popupquery "github.com/break/junhong_cmp_fiber/internal/query/h5popup"
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+	"github.com/break/junhong_cmp_fiber/pkg/response"
+)
+
+// H5PopupConfigurationHandler H5 运营弹窗配置后台 Handler。
+// 全部接口仅超级管理员与平台账号可用，代理与企业统一返回 403。
+type H5PopupConfigurationHandler struct {
+	service   *h5popupapp.ConfigurationService
+	query     *h5popupquery.Query
+	validator *validator.Validate
+}
+
+// NewH5PopupConfigurationHandler 创建 H5 运营弹窗配置后台 Handler。
+func NewH5PopupConfigurationHandler(service *h5popupapp.ConfigurationService, query *h5popupquery.Query, validate *validator.Validate) *H5PopupConfigurationHandler {
+	return &H5PopupConfigurationHandler{service: service, query: query, validator: validate}
+}
+
+// ListH5PopupConfigurations 查询运营弹窗配置列表。
+// GET /api/admin/h5-popup-configurations
+func (h *H5PopupConfigurationHandler) ListH5PopupConfigurations(c *fiber.Ctx) error {
+	if err := requirePlatformManagement(c); err != nil {
+		return err
+	}
+	var request dto.H5PopupConfigurationListRequest
+	if err := c.QueryParser(&request); err != nil {
+		return errors.New(errors.CodeInvalidParam)
+	}
+	if h.validator != nil {
+		if err := h.validator.Struct(&request); err != nil {
+			return errors.New(errors.CodeInvalidParam, validation.Message("运营弹窗配置列表参数不合法", &request, err))
+		}
+	}
+	if h.query == nil {
+		return errors.New(errors.CodeServiceUnavailable, "运营弹窗配置维护能力尚未配置")
+	}
+	result, err := h.query.List(c.UserContext(), request)
+	if err != nil {
+		return err
+	}
+	return response.SuccessWithPagination(c, result.Items, result.Total, result.Page, result.Size)
+}
+
+// GetH5PopupConfiguration 查询运营弹窗配置详情。
+// GET /api/admin/h5-popup-configurations/:id
+func (h *H5PopupConfigurationHandler) GetH5PopupConfiguration(c *fiber.Ctx) error {
+	if err := requirePlatformManagement(c); err != nil {
+		return err
+	}
+	id, err := h.parseID(c)
+	if err != nil {
+		return err
+	}
+	if h.query == nil {
+		return errors.New(errors.CodeServiceUnavailable, "运营弹窗配置维护能力尚未配置")
+	}
+	result, err := h.query.Get(c.UserContext(), id)
+	if err != nil {
+		return err
+	}
+	return response.Success(c, result)
+}
+
+// CreateH5PopupConfiguration 创建运营弹窗配置，初始版本为 1。
+// POST /api/admin/h5-popup-configurations
+func (h *H5PopupConfigurationHandler) CreateH5PopupConfiguration(c *fiber.Ctx) error {
+	if err := requirePlatformManagement(c); err != nil {
+		return err
+	}
+	var request dto.CreateH5PopupConfigurationRequest
+	if err := c.BodyParser(&request); err != nil {
+		return errors.New(errors.CodeInvalidParam)
+	}
+	if h.validator != nil {
+		if err := h.validator.Struct(&request); err != nil {
+			return errors.New(errors.CodeInvalidParam, validation.Message("创建运营弹窗配置参数不合法", &request, err))
+		}
+	}
+	if h.service == nil || h.query == nil {
+		return errors.New(errors.CodeServiceUnavailable, "运营弹窗配置维护能力尚未配置")
+	}
+	id, err := h.service.Create(c.UserContext(), request)
+	if err != nil {
+		return err
+	}
+	result, err := h.query.Get(c.UserContext(), id)
+	if err != nil {
+		return err
+	}
+	return response.Success(c, result)
+}
+
+// UpdateH5PopupConfiguration 更新运营弹窗配置并递增版本。
+// PUT /api/admin/h5-popup-configurations/:id
+func (h *H5PopupConfigurationHandler) UpdateH5PopupConfiguration(c *fiber.Ctx) error {
+	if err := requirePlatformManagement(c); err != nil {
+		return err
+	}
+	id, err := h.parseID(c)
+	if err != nil {
+		return err
+	}
+	var request dto.UpdateH5PopupConfigurationParams
+	if err := c.BodyParser(&request); err != nil {
+		return errors.New(errors.CodeInvalidParam)
+	}
+	// 路径来源字段必须由 Handler 回填后再校验，避免被请求体覆盖，也避免 required 恒失败。
+	request.ID = id
+	if h.validator != nil {
+		if err := h.validator.Struct(&request); err != nil {
+			return errors.New(errors.CodeInvalidParam, validation.Message("更新运营弹窗配置参数不合法", &request, err))
+		}
+	}
+	if h.service == nil || h.query == nil {
+		return errors.New(errors.CodeServiceUnavailable, "运营弹窗配置维护能力尚未配置")
+	}
+	if err := h.service.Update(c.UserContext(), id, request.UpdateH5PopupConfigurationRequest); err != nil {
+		return err
+	}
+	result, err := h.query.Get(c.UserContext(), id)
+	if err != nil {
+		return err
+	}
+	return response.Success(c, result)
+}
+
+// EnableH5PopupConfiguration 启用运营弹窗配置，仅影响后续候选并刷新最近更新时间。
+// POST /api/admin/h5-popup-configurations/:id/enable
+func (h *H5PopupConfigurationHandler) EnableH5PopupConfiguration(c *fiber.Ctx) error {
+	return h.setEnabled(c, true)
+}
+
+// DisableH5PopupConfiguration 停用运营弹窗配置，仅影响后续候选并刷新最近更新时间。
+// POST /api/admin/h5-popup-configurations/:id/disable
+func (h *H5PopupConfigurationHandler) DisableH5PopupConfiguration(c *fiber.Ctx) error {
+	return h.setEnabled(c, false)
+}
+
+func (h *H5PopupConfigurationHandler) setEnabled(c *fiber.Ctx, enabled bool) error {
+	if err := requirePlatformManagement(c); err != nil {
+		return err
+	}
+	id, err := h.parseID(c)
+	if err != nil {
+		return err
+	}
+	if h.service == nil || h.query == nil {
+		return errors.New(errors.CodeServiceUnavailable, "运营弹窗配置维护能力尚未配置")
+	}
+	if err := h.service.SetEnabled(c.UserContext(), id, enabled); err != nil {
+		return err
+	}
+	result, err := h.query.Get(c.UserContext(), id)
+	if err != nil {
+		return err
+	}
+	return response.Success(c, result)
+}
+
+// parseID 从路径解析运营弹窗配置 ID。
+func (h *H5PopupConfigurationHandler) parseID(c *fiber.Ctx) (uint, error) {
+	id, err := strconv.ParseUint(c.Params("id"), 10, 64)
+	if err != nil || id == 0 {
+		return 0, errors.New(errors.CodeInvalidParam, "运营弹窗配置ID不合法")
+	}
+	return uint(id), nil
+}
--- a/internal/handler/admin/withdrawal_qualification.go
+++ b/internal/handler/admin/withdrawal_qualification.go
@@ -1,15 +1,14 @@
 package admin

 import (
-	"reflect"
 	"strconv"
-	"strings"

 	"github.com/go-playground/validator/v10"
 	"github.com/gofiber/fiber/v2"

 	distributionapp "github.com/break/junhong_cmp_fiber/internal/application/distributionwithdrawal"
 	distributiondomain "github.com/break/junhong_cmp_fiber/internal/domain/distribution"
+	"github.com/break/junhong_cmp_fiber/internal/handler/validation"
 	"github.com/break/junhong_cmp_fiber/internal/model/dto"
 	distributionquery "github.com/break/junhong_cmp_fiber/internal/query/distributionwithdrawal"
 	"github.com/break/junhong_cmp_fiber/pkg/constants"
@@ -107,91 +106,9 @@ func (h *WithdrawalQualificationHandler) VoidWithdrawalQualification(c *fiber.Ct
 }

 // validationMessage 把请求校验失败转换为可定位字段的中文提示。
-// 只使用字段的 description 与校验规则，不拼接底层错误文本，也不回显字段值。
+// 规则实现收口在 internal/handler/validation，管理端与 C 端共用同一套提示口径。
 func validationMessage(prefix string, req any, err error) string {
-	fieldErrs, ok := err.(validator.ValidationErrors)
-	if !ok || len(fieldErrs) == 0 {
-		return prefix
-	}
-	return prefix + "：" + describeFieldError(req, fieldErrs[0])
-}
-
-// describeFieldError 用字段中文名与失败规则描述单个字段错误。
-func describeFieldError(req any, fieldErr validator.FieldError) string {
-	label := fieldDescription(req, fieldErr.StructField())
-	switch fieldErr.Tag() {
-	case "required":
-		// 数字字段的 required 只在零值失败；说“不能为空”会误导为缺字段。
-		if isNumericField(req, fieldErr.StructField()) {
-			return label + "必须大于 0"
-		}
-		return label + "不能为空"
-	case "min":
-		if isNumericField(req, fieldErr.StructField()) {
-			return label + "不能小于 " + fieldErr.Param()
-		}
-		return label + "长度不能小于 " + fieldErr.Param()
-	case "max":
-		if isNumericField(req, fieldErr.StructField()) {
-			return label + "不能超过 " + fieldErr.Param()
-		}
-		return label + "长度不能超过 " + fieldErr.Param()
-	case "oneof":
-		return label + "必须为 " + strings.ReplaceAll(fieldErr.Param(), " ", "/") + " 之一"
-	default:
-		return label + "不合法（" + fieldErr.Tag() + "）"
-	}
-}
-
-// isNumericField 判断字段是否为整数或浮点类型。
-func isNumericField(req any, fieldName string) bool {
-	field, ok := lookupField(req, fieldName)
-	if !ok {
-		return false
-	}
-	switch field.Type.Kind() {
-	case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64,
-		reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64,
-		reflect.Float32, reflect.Float64:
-		return true
-	default:
-		return false
-	}
-}
-
-// lookupField 在去指针的结构体类型上按名取字段。
-func lookupField(req any, fieldName string) (reflect.StructField, bool) {
-	typ := reflect.TypeOf(req)
-	for typ != nil && typ.Kind() == reflect.Ptr {
-		typ = typ.Elem()
-	}
-	if typ == nil || typ.Kind() != reflect.Struct {
-		return reflect.StructField{}, false
-	}
-	return typ.FieldByName(fieldName)
-}
-
-// fieldDescription 取字段 description 的首个中文短语作为提示名，缺失时退回字段名。
-func fieldDescription(req any, fieldName string) string {
-	field, ok := lookupField(req, fieldName)
-	if !ok {
-		return fieldName
-	}
-	description := strings.TrimSpace(field.Tag.Get("description"))
-	if description == "" {
-		return fieldName
-	}
-	if cut := strings.IndexAny(description, "（(：:，,；;"); cut > 0 {
-		description = strings.TrimSpace(description[:cut])
-	}
-	if description == "" {
-		return fieldName
-	}
-	// 提示名以拉丁字母/数字结尾时补一个空格，避免与后续中文粘连。
-	if last := description[len(description)-1]; last < 0x80 {
-		description += " "
-	}
-	return description
+	return validation.Message(prefix, req, err)
 }

 // ListWithdrawalQualifications 查询提现资料资格版本