diff --git a/docs/7月迭代/七月迭代人工验收清单.md b/docs/7月迭代/七月迭代人工验收清单.md index 65ab57a..61cd1cd 100644 --- a/docs/7月迭代/七月迭代人工验收清单.md +++ b/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 企业微信审核流转**：核对企微应用、模板、成员绑定、代理固定代提交人、回调、主动同步和异常恢复；系统内不得提供本地同意或拒绝入口。 diff --git a/docs/admin-openapi.yaml b/docs/admin-openapi.yaml index 78181f3..8d7fbfd 100644 --- a/docs/admin-openapi.yaml +++ b/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 diff --git a/docs/tech-inapp-notifications/前端联调与验收契约.md b/docs/tech-inapp-notifications/前端联调与验收契约.md index c6b870f..75757ca 100644 --- a/docs/tech-inapp-notifications/前端联调与验收契约.md +++ b/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 diff --git a/docs/tech-inapp-notifications/功能总结.md b/docs/tech-inapp-notifications/功能总结.md index ac1488c..57e14e6 100644 --- a/docs/tech-inapp-notifications/功能总结.md +++ b/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 错误。已经生成的通知保持原接收人事实，关系后续变化不会转移历史通知。 diff --git a/internal/infrastructure/notification/registry.go b/internal/infrastructure/notification/registry.go index e5c64b2..9a760ed 100644 --- a/internal/infrastructure/notification/registry.go +++ b/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: {}, diff --git a/internal/infrastructure/packageexpiry/reminder_publisher.go b/internal/infrastructure/packageexpiry/reminder_publisher.go index 128b5c0..ce09cdb 100644 --- a/internal/infrastructure/packageexpiry/reminder_publisher.go +++ b/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) } diff --git a/internal/infrastructure/wallet/credit_event.go b/internal/infrastructure/wallet/credit_event.go index b7b1d09..f0847cd 100644 --- a/internal/infrastructure/wallet/credit_event.go +++ b/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, }, }) diff --git a/internal/model/dto/notification_dto.go b/internal/model/dto/notification_dto.go index 4c9052e..c099a38 100644 --- a/internal/model/dto/notification_dto.go +++ b/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:卡同步记录。后台点击通知应调用目标解析接口，不得直接拼接路由"`