补充通知信息

docs/7月迭代/七月迭代人工验收清单.md

@@ -4,8 +4,8 @@
 
 ## 一、业务需求
 
-- [ ] **UR#33 套餐临期提醒**：核对 0～15 天临期列表、0～3 天置顶、Dashboard 数量、C 端续费入口，以及 15/7/3 天向全部有效店铺账号、有效绑定的平台业务员和资产绑定个人账号发送防重站内通知。
-- [ ] **UR#34 充值审核流程**：核对代理在线扫码充值与平台线下代充值隔离；支付、企微审批、重复回调和入账补偿正确；到账后通知全部有效店铺账号及有效绑定的平台业务员。
+- [ ] **UR#33 套餐临期提醒**：核对 0～15 天临期列表、0～3 天置顶、Dashboard 数量、C 端续费入口，以及 15/7/3 天向全部有效店铺账号、有效绑定的平台业务员和资产绑定个人账号发送防重站内通知；正文明确资产标识、到期状态和到期日期。
+- [ ] **UR#34 充值审核流程**：核对代理在线扫码充值与平台线下代充值隔离；支付、企微审批、重复回调和入账补偿正确；到账后通知全部有效店铺账号及有效绑定的平台业务员，正文明确店铺名称和精确到分的充值金额。
 - [ ] **UR#35 退款审核**：核对企微审批、整单终结、钱包回充、套餐失效和佣金处理；重复终态不重复退款或通知；退款完成后通知全部有效店铺账号及有效绑定的平台业务员。
 - [ ] **UR#36 批量订购套餐**：核对 CSV 上传、跨代理资产、统一支付方式、逐行结果、部分成功、失败原因、任务恢复及重复执行不重复扣款。
 - [ ] **UR#37 企业微信审核流转**：核对企微应用、模板、成员绑定、代理固定代提交人、回调、主动同步和异常恢复；系统内不得提供本地同意或拒绝入口。

docs/admin-openapi.yaml

@@ -7024,6 +7024,11 @@ components:
                     type: string
                 category:
                     description: 通知类别 (approval:审批, expiry:临期, sync:同步, system:系统)
+                    enum:
+                        - approval
+                        - expiry
+                        - sync
+                        - system
                     type: string
                 created_at:
                     description: 创建时间（ISO 8601）
@@ -7052,12 +7057,24 @@ components:
                     type: string
                 severity:
                     description: 通知级别 (info:提示, warning:警告, error:错误, critical:严重)
+                    enum:
+                        - info
+                        - warning
+                        - error
+                        - critical
                     type: string
                 title:
                     description: 纯文本标题
                     type: string
                 type:
-                    description: 稳定通知类型
+                    description: 稳定通知类型 (system.notice:系统通知, package.expiring:套餐临期, agent.recharge.completed:店铺充值入账, refund.completed:店铺退款完成, exchange.shipping.created:换货申请待处理, agent.main_wallet.low_balance:主钱包低余额)
+                    enum:
+                        - system.notice
+                        - package.expiring
+                        - agent.recharge.completed
+                        - refund.completed
+                        - exchange.shipping.created
+                        - agent.main_wallet.low_balance
                     type: string
             type: object
         DtoNotificationListResponse:
@@ -20265,18 +20282,35 @@ paths:
                   name: category
                   schema:
                     description: 通知类别 (approval:审批, expiry:临期, sync:同步, system:系统)
+                    enum:
+                        - approval
+                        - expiry
+                        - sync
+                        - system
                     type: string
-                - description: 稳定通知类型
+                - description: 稳定通知类型 (system.notice:系统通知, package.expiring:套餐临期, agent.recharge.completed:店铺充值入账, refund.completed:店铺退款完成, exchange.shipping.created:换货申请待处理, agent.main_wallet.low_balance:主钱包低余额)
                   in: query
                   name: type
                   schema:
-                    description: 稳定通知类型
+                    description: 稳定通知类型 (system.notice:系统通知, package.expiring:套餐临期, agent.recharge.completed:店铺充值入账, refund.completed:店铺退款完成, exchange.shipping.created:换货申请待处理, agent.main_wallet.low_balance:主钱包低余额)
+                    enum:
+                        - system.notice
+                        - package.expiring
+                        - agent.recharge.completed
+                        - refund.completed
+                        - exchange.shipping.created
+                        - agent.main_wallet.low_balance
                     type: string
                 - description: 通知级别 (info:提示, warning:警告, error:错误, critical:严重)
                   in: query
                   name: severity
                   schema:
                     description: 通知级别 (info:提示, warning:警告, error:错误, critical:严重)
+                    enum:
+                        - info
+                        - warning
+                        - error
+                        - critical
                     type: string
                 - description: 已读状态；不传时查询全部
                   in: query

docs/tech-inapp-notifications/前端联调与验收契约.md

@@ -33,7 +33,7 @@
 完整通知中心使用服务端参数：
 
 - `category`：`approval/expiry/sync/system`
-- `type`：稳定通知类型
+- `type`：稳定通知类型，可选 `system.notice`、`package.expiring`、`agent.recharge.completed`、`refund.completed`、`exchange.shipping.created`、`agent.main_wallet.low_balance`
 - `severity`：`info/warning/error/critical`
 - `is_read`：已读状态
 - `page/page_size`：服务端分页，默认 20、最大 50

docs/tech-inapp-notifications/功能总结.md

@@ -15,8 +15,8 @@
 - 后台动态接收人事件类型：`notification.admin.dynamic.requested`。
 - 载荷版本：`1`。
 - 结构化载荷包含后台接收账号 ID、注册通知类型、模板数据、可选受控资源引用和过期时间；调用公共队列时保持 struct/map 载荷，不传预序列化 `[]byte`。
-- 当前内置通知类型为 `system.notice`，标题和正文均由代码内固定模板生成，不接受业务载荷传入任意正文；未知字段、HTML、任意 HTTP URL、超长文本和明显敏感内容会被拒绝。
-- 个人客户首个受控类型为 `package.expiring`，使用固定纯文本模板，只允许 `package` 或 `asset` 资源引用；`system.notice` 只向后台账号开放。
+- 当前内置通知类型为 `system.notice`、`package.expiring`、`agent.recharge.completed`、`refund.completed`、`exchange.shipping.created` 和 `agent.main_wallet.low_balance`；标题和正文均由代码内受控模板生成，不接受业务载荷传入任意正文；未知字段、HTML、任意 HTTP URL、超长文本和明显敏感内容会被拒绝。
+- `package.expiring` 同时向后台账号和个人客户开放，正文包含资产标识、到期状态和到期日期；`agent.recharge.completed` 正文包含店铺名称和精确到分的充值金额。
 - 接收账号必须启用且未软删除；不可用账号记录安全日志并跳过，不把通知写入失败反向传播到原业务事务。
 - `event_id + recipient_kind + recipient_id` 唯一约束与 `ON CONFLICT DO NOTHING` 共同保证重复或并发消费最多生成一条通知。
 
@@ -24,7 +24,7 @@
 
 - `account`：业务事件携带的稳定真实申请人账号 ID，消费时复核账号仍启用且未删除。
 - `platform_role`：批量解析当前启用的平台角色、有效账号角色关系，以及仍启用未删除的超管/平台账号。
-- `shop`：复用 UR#96 接缝，只解析目标店铺当前启用主账号和当前仍可用业务员，不读取父级、祖先、创建人或代理数据权限。
+- `shop`：复用 UR#96 接缝，解析目标店铺全部启用店铺账号和当前仍可用业务员，不读取父级、祖先或创建人。
 
 解析结果按稳定账号 ID 去重和排序。同一事件对每个接收人独立幂等写入；暂无可用接收人记录 `resolution=no_recipient` 并正常结束，数据库故障继续返回 Worker 错误。已经生成的通知保持原接收人事实，关系后续变化不会转移历史通知。
 

internal/infrastructure/notification/registry.go

@@ -61,9 +61,9 @@ func NewRegistry() *Registry {
 		constants.NotificationTypePackageExpiring: {
 			Type: constants.NotificationTypePackageExpiring, Category: constants.NotificationCategoryExpiry,
 			Severity:       constants.NotificationSeverityWarning,
-			TitleTemplate:  "套餐即将到期",
-			BodyTemplate:   "您的套餐即将到期，请及时查看并处理。",
-			TemplateFields: map[string]struct{}{},
+			TitleTemplate:  "套餐{{.expiry_status}}",
+			BodyTemplate:   "资产 {{.asset_identifier}} 的套餐{{.expiry_status}}，到期日期：{{.expiry_date}}。",
+			TemplateFields: map[string]struct{}{"asset_identifier": {}, "expiry_status": {}, "expiry_date": {}},
 			RecipientKinds: map[string]struct{}{
 				constants.NotificationRecipientKindAccount:          {},
 				constants.NotificationRecipientKindPersonalCustomer: {},
@@ -78,8 +78,8 @@ func NewRegistry() *Registry {
 			Type: constants.NotificationTypeAgentRechargeCompleted, Category: constants.NotificationCategorySystem,
 			Severity:       constants.NotificationSeverityInfo,
 			TitleTemplate:  "店铺充值已入账",
-			BodyTemplate:   "店铺充值已成功入账，请进入充值详情查看。",
-			TemplateFields: map[string]struct{}{},
+			BodyTemplate:   "店铺「{{.shop_name}}」充值 {{.amount}} 已成功入账。",
+			TemplateFields: map[string]struct{}{"shop_name": {}, "amount": {}},
 			RecipientKinds: map[string]struct{}{constants.NotificationRecipientKindAccount: {}},
 			AllowedRefTypes: map[string]struct{}{
 				constants.NotificationRefTypeAgentRecharge: {},

internal/infrastructure/packageexpiry/reminder_publisher.go

@@ -82,7 +82,7 @@ func (p *ReminderPublisher) appendShopNotification(ctx context.Context, tx *gorm
 		ResourceType: candidate.AssetType, ResourceID: assetID, BusinessKey: eventID,
 		Payload: notificationapp.AdminDynamicPayload{
 			TargetKind: constants.NotificationTargetKindShop, TargetID: shopID,
-			NotificationType: constants.NotificationTypePackageExpiring, TemplateData: map[string]string{},
+			NotificationType: constants.NotificationTypePackageExpiring, TemplateData: expiryTemplateData(candidate),
 			RefType: constants.NotificationRefTypeExpiringAsset, RefID: shopIDText,
 			ExpiresAt: candidate.EstimatedFinalExpiresAt,
 		},
@@ -160,7 +160,7 @@ func (p *ReminderPublisher) appendNotification(ctx context.Context, tx *gorm.DB,
 		ResourceType: candidate.AssetType, ResourceID: assetID, BusinessKey: eventID,
 		Payload: notificationapp.PersonalCustomerDirectPayload{
 			RecipientID: customerID, NotificationType: constants.NotificationTypePackageExpiring,
-			TemplateData: map[string]string{}, RefType: constants.NotificationRefTypeAsset,
+			TemplateData: expiryTemplateData(candidate), RefType: constants.NotificationRefTypeAsset,
 			RefID: assetID, RefKey: candidate.Identifier, ExpiresAt: candidate.EstimatedFinalExpiresAt,
 		},
 	})
@@ -170,6 +170,28 @@ func (p *ReminderPublisher) appendNotification(ctx context.Context, tx *gorm.DB,
 	return nil
 }
 
+// expiryTemplateData 为后台和个人客户生成同口径的资产到期文案数据。
+func expiryTemplateData(candidate dto.ExpiringAssetItem) map[string]string {
+	status := "即将到期"
+	if candidate.DaysUntilFinalExpiry != nil {
+		switch {
+		case *candidate.DaysUntilFinalExpiry < 0:
+			status = "已到期"
+		case *candidate.DaysUntilFinalExpiry == 0:
+			status = "今天到期"
+		}
+	}
+	expiryDate := ""
+	if candidate.EstimatedFinalExpiresAt != nil {
+		expiryDate = candidate.EstimatedFinalExpiresAt.In(shanghaiLocation).Format("2006-01-02")
+	}
+	return map[string]string{
+		"asset_identifier": candidate.Identifier,
+		"expiry_status":    status,
+		"expiry_date":      expiryDate,
+	}
+}
+
 func recipientKey(assetType string, assetID uint) string {
 	return fmt.Sprintf("%s:%d", assetType, assetID)
 }

internal/infrastructure/wallet/credit_event.go

@@ -2,11 +2,13 @@ package wallet
 
 import (
 	"context"
+	"fmt"
 	"strconv"
 
 	notificationapp "github.com/break/junhong_cmp_fiber/internal/application/notification"
 	walletapp "github.com/break/junhong_cmp_fiber/internal/application/wallet"
 	"github.com/break/junhong_cmp_fiber/internal/infrastructure/messaging/outbox"
+	"github.com/break/junhong_cmp_fiber/internal/model"
 	"github.com/break/junhong_cmp_fiber/pkg/constants"
 	"github.com/break/junhong_cmp_fiber/pkg/errors"
 	"gorm.io/gorm"
@@ -38,6 +40,10 @@ func (w *CreditEventWriter) Append(ctx context.Context, tx *gorm.DB, event walle
 		return err
 	}
 	rechargeID := strconv.FormatUint(uint64(event.ReferenceID), 10)
+	var shop model.Shop
+	if err := tx.WithContext(ctx).Select("shop_name").Where("id = ?", event.ShopID).Take(&shop).Error; err != nil {
+		return errors.Wrap(errors.CodeDatabaseError, err, "查询充值通知店铺失败")
+	}
 	notificationEventID := "agent-recharge:" + rechargeID + ":completed"
 	_, err = w.outbox.AppendIdempotent(ctx, tx, outbox.Envelope{
 		EventID: notificationEventID, EventType: constants.OutboxEventTypeAdminDynamicNotification,
@@ -47,7 +53,11 @@ func (w *CreditEventWriter) Append(ctx context.Context, tx *gorm.DB, event walle
 		BusinessKey: notificationEventID, RequestID: event.RequestID, CorrelationID: event.CorrelationID,
 		Payload: notificationapp.AdminDynamicPayload{
 			TargetKind: constants.NotificationTargetKindShop, TargetID: event.ShopID,
-			NotificationType: constants.NotificationTypeAgentRechargeCompleted, TemplateData: map[string]string{},
+			NotificationType: constants.NotificationTypeAgentRechargeCompleted,
+			TemplateData: map[string]string{
+				"shop_name": shop.ShopName,
+				"amount":    fmt.Sprintf("%d.%02d 元", event.Amount/100, event.Amount%100),
+			},
 			RefType: constants.NotificationRefTypeAgentRecharge, RefID: rechargeID,
 		},
 	})

internal/model/dto/notification_dto.go

@@ -11,7 +11,7 @@ type NotificationUnreadCountResponse struct {
 // NotificationListRequest 是后台通知基础分页参数。
 type NotificationListRequest struct {
 	Category string `json:"category" query:"category" validate:"omitempty,oneof=approval expiry sync system" enums:"approval,expiry,sync,system" description:"通知类别 (approval:审批, expiry:临期, sync:同步, system:系统)"`
-	Type     string `json:"type" query:"type" validate:"omitempty,max=100" maxlength:"100" description:"稳定通知类型"`
+	Type     string `json:"type" query:"type" validate:"omitempty,oneof=system.notice package.expiring agent.recharge.completed refund.completed exchange.shipping.created agent.main_wallet.low_balance" enums:"system.notice,package.expiring,agent.recharge.completed,refund.completed,exchange.shipping.created,agent.main_wallet.low_balance" description:"稳定通知类型 (system.notice:系统通知, package.expiring:套餐临期, agent.recharge.completed:店铺充值入账, refund.completed:店铺退款完成, exchange.shipping.created:换货申请待处理, agent.main_wallet.low_balance:主钱包低余额)"`
 	Severity string `json:"severity" query:"severity" validate:"omitempty,oneof=info warning error critical" enums:"info,warning,error,critical" description:"通知级别 (info:提示, warning:警告, error:错误, critical:严重)"`
 	IsRead   *bool  `json:"is_read" query:"is_read" description:"已读状态；不传时查询全部"`
 	Page     int    `json:"page" query:"page" validate:"omitempty,min=1,max=10000" minimum:"1" maximum:"10000" description:"页码，默认 1，最大 10000"`
@@ -21,9 +21,9 @@ type NotificationListRequest struct {
 // NotificationItem 是后台账号可见的站内通知投影。
 type NotificationItem struct {
 	ID        uint       `json:"id" description:"通知ID"`
-	Category  string     `json:"category" description:"通知类别 (approval:审批, expiry:临期, sync:同步, system:系统)"`
-	Type      string     `json:"type" description:"稳定通知类型"`
-	Severity  string     `json:"severity" description:"通知级别 (info:提示, warning:警告, error:错误, critical:严重)"`
+	Category  string     `json:"category" enums:"approval,expiry,sync,system" description:"通知类别 (approval:审批, expiry:临期, sync:同步, system:系统)"`
+	Type      string     `json:"type" enums:"system.notice,package.expiring,agent.recharge.completed,refund.completed,exchange.shipping.created,agent.main_wallet.low_balance" description:"稳定通知类型 (system.notice:系统通知, package.expiring:套餐临期, agent.recharge.completed:店铺充值入账, refund.completed:店铺退款完成, exchange.shipping.created:换货申请待处理, agent.main_wallet.low_balance:主钱包低余额)"`
+	Severity  string     `json:"severity" enums:"info,warning,error,critical" description:"通知级别 (info:提示, warning:警告, error:错误, critical:严重)"`
 	Title     string     `json:"title" description:"纯文本标题"`
 	Body      string     `json:"body" description:"纯文本正文"`
 	RefType   string     `json:"ref_type" description:"受控资源类型；可能为空。可选值及含义：system_config:系统配置, integration_log:外部集成日志, package:套餐, asset:C端资产, refund:退款, agent_recharge:代理充值, wecom_approval:企微审批, iot_card:物联网卡, device:设备, expiring_asset:临期资产列表, shop_fund:店铺资金概况, card_sync:卡同步记录。后台点击通知应调用目标解析接口，不得直接拼接路由"`