10 KiB
10 KiB
基础设施：站内消息（Notification）
被依赖：需求 18/20/21（审批流通知）、需求 22（临期提醒）
Phase 2 扩展：企业微信推送、短信通知（预留插拔接口）
一、设计原则
- 业务代码不直接写通知：只发 Asynq 任务，异步处理
- 不过度抽象：不用 interface，用具体的
NotificationPublisher（后续加渠道 = 在 handler 里加代码） - 前端轮询：30秒一次
/admin/notifications/unread-count，不用 WebSocket
二、数据库
-- 迁移文件：YYYYMMDD_create_tb_notification.sql
CREATE TABLE tb_notification (
id BIGSERIAL PRIMARY KEY,
recipient_id BIGINT NOT NULL, -- 用户ID（admin user 或 agent user）
recipient_type VARCHAR(20) NOT NULL DEFAULT 'admin', -- admin | agent
type VARCHAR(50) NOT NULL, -- 通知类型（见常量定义）
title VARCHAR(200) NOT NULL, -- 标题
body TEXT NOT NULL DEFAULT '', -- 正文（支持简单 HTML）
ref_type VARCHAR(50), -- 关联业务类型 approval | recharge | refund | package
ref_id BIGINT, -- 关联业务ID
is_read BOOLEAN NOT NULL DEFAULT FALSE,
read_at TIMESTAMPTZ,
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
expires_at TIMESTAMPTZ -- 过期自动不展示（可选，临期提醒用）
);
CREATE INDEX idx_notification_recipient ON tb_notification (recipient_id, recipient_type, is_read);
CREATE INDEX idx_notification_created ON tb_notification (created_at DESC);
COMMENT ON TABLE tb_notification IS '站内消息通知表';
三、常量定义
// pkg/constants/notification.go
// 通知类型
const (
NotifyTypeApprovalPending = "approval.pending" // 待我审批
NotifyTypeApprovalDone = "approval.done" // 审批完成（申请人收）
NotifyTypeApprovalRejected = "approval.rejected" // 审批驳回（申请人收，流程终止）
NotifyTypeApprovalReturned = "approval.returned" // 审批退回（申请人收，可修改后重新提交）
NotifyTypePackageExpiring = "package.expiring" // 套餐临期
NotifyTypeSystemAlert = "system.alert" // 系统通知
)
// 通知接收者类型
const (
NotifyRecipientAdmin = "admin" // 平台用户
NotifyRecipientAgent = "agent" // 代理用户（预留）
)
四、Model
// internal/model/notification.go
// Notification 站内消息模型
type Notification struct {
ID uint `gorm:"column:id;primaryKey" json:"id"`
RecipientID uint `gorm:"column:recipient_id;not null;index" json:"recipient_id"`
RecipientType string `gorm:"column:recipient_type;type:varchar(20);not null;default:'admin'" json:"recipient_type"`
Type string `gorm:"column:type;type:varchar(50);not null" json:"type"`
Title string `gorm:"column:title;type:varchar(200);not null" json:"title"`
Body string `gorm:"column:body;type:text;not null;default:''" json:"body"`
RefType *string `gorm:"column:ref_type;type:varchar(50)" json:"ref_type,omitempty"`
RefID *uint `gorm:"column:ref_id" json:"ref_id,omitempty"`
IsRead bool `gorm:"column:is_read;not null;default:false" json:"is_read"`
ReadAt *time.Time `gorm:"column:read_at" json:"read_at,omitempty"`
CreatedAt time.Time `gorm:"column:created_at;not null" json:"created_at"`
ExpiresAt *time.Time `gorm:"column:expires_at" json:"expires_at,omitempty"`
}
func (Notification) TableName() string { return "tb_notification" }
五、发布侧：NotificationPublisher
业务代码调这个发布通知，内部异步入队：
// internal/service/notification/publisher.go
// SendPayload 发送通知的参数
type SendPayload struct {
RecipientIDs []uint // 接收人ID列表
RecipientType string // admin | agent
Type string // 通知类型常量
Title string // 标题
Body string // 正文
RefType string // 关联业务类型（可选）
RefID uint // 关联业务ID（可选）
ExpiresAt *time.Time // 过期时间（可选）
}
// NotificationPublisher 通知发布器（非接口，简单具体实现）
type NotificationPublisher struct {
queueClient *queue.Client
logger *zap.Logger
}
// Publish 发布通知（异步，不阻塞业务）
// 失败只记录日志，不影响业务事务
func (p *NotificationPublisher) Publish(ctx context.Context, payload SendPayload) {
if err := p.queueClient.EnqueueTask(ctx, constants.TaskTypeNotification, payload); err != nil {
p.logger.Error("通知入队失败", zap.Error(err), zap.String("type", payload.Type))
}
}
业务代码调用示例（审批推进后通知下一审批人）：
p.notifyPublisher.Publish(ctx, notification.SendPayload{
RecipientIDs: []uint{nextApproverID},
RecipientType: constants.NotifyRecipientAdmin,
Type: constants.NotifyTypeApprovalPending,
Title: "您有一条待审批记录",
Body: fmt.Sprintf("代理「%s」提交了充值申请，请及时审批。", shopName),
RefType: "approval",
RefID: approvalFlowID,
})
六、消费侧：Asynq Task Handler
// internal/task/notification_handler.go
// HandleNotification 处理通知发送任务
func (h *NotificationHandler) HandleNotification(ctx context.Context, t *asynq.Task) error {
var payload notification.SendPayload
if err := sonic.Unmarshal(t.Payload(), &payload); err != nil {
return fmt.Errorf("反序列化通知载荷失败: %w", err)
}
// 批量写入 tb_notification
records := make([]model.Notification, 0, len(payload.RecipientIDs))
for _, uid := range payload.RecipientIDs {
ref_type := (*string)(nil)
ref_id := (*uint)(nil)
if payload.RefType != "" {
ref_type = &payload.RefType
}
if payload.RefID != 0 {
ref_id = &payload.RefID
}
records = append(records, model.Notification{
RecipientID: uid,
RecipientType: payload.RecipientType,
Type: payload.Type,
Title: payload.Title,
Body: payload.Body,
RefType: ref_type,
RefID: ref_id,
ExpiresAt: payload.ExpiresAt,
})
}
if err := h.db.WithContext(ctx).CreateInBatches(records, 100).Error; err != nil {
return fmt.Errorf("批量写入通知失败: %w", err)
}
// Phase 2：在此处加企微/短信调用
// for _, sender := range h.extraSenders { sender.Send(ctx, payload) }
return nil
}
七、API 设计
7.1 未读数量（前端轮询用，30秒一次）
GET /admin/notifications/unread-count
响应：
{ "code": 0, "data": { "count": 5 } }
7.2 通知列表
GET /admin/notifications?is_read=false&type=approval.pending&page=1&page_size=20
请求参数：
type NotificationListRequest struct {
IsRead *bool `query:"is_read" description:"是否已读（不传=全部）"`
Type string `query:"type" description:"通知类型过滤（可选）"`
Page int `query:"page" description:"页码"`
PageSize int `query:"page_size" description:"每页数量（最大50）"`
}
响应：
{
"code": 0,
"data": {
"list": [
{
"id": 1,
"type": "approval.pending",
"title": "您有一条待审批记录",
"body": "代理「XX店」提交了充值申请，请及时审批。",
"ref_type": "approval",
"ref_id": 42,
"is_read": false,
"created_at": "2026-07-11T10:00:00Z"
}
],
"total": 3,
"page": 1,
"page_size": 20
}
}
7.3 标记已读
PUT /admin/notifications/{id}/read
7.4 全部标记已读
PUT /admin/notifications/read-all
可传 type 过滤（只把某类型全部已读）：
{ "type": "approval.pending" }
DTO
// internal/model/dto/notification_dto.go
type NotificationListRequest struct {
IsRead *bool `query:"is_read"`
Type string `query:"type"`
Page int `query:"page" default:"1"`
PageSize int `query:"page_size" default:"20"`
}
type NotificationItem struct {
ID uint `json:"id"`
Type string `json:"type" description:"通知类型"`
Title string `json:"title"`
Body string `json:"body"`
RefType *string `json:"ref_type,omitempty"`
RefID *uint `json:"ref_id,omitempty"`
IsRead bool `json:"is_read"`
ReadAt *time.Time `json:"read_at,omitempty"`
CreatedAt time.Time `json:"created_at"`
}
type UnreadCountResponse struct {
Count int64 `json:"count"`
}
type ReadAllRequest struct {
Type string `json:"type" description:"通知类型（为空则全部已读）"`
}
八、前端对接
顶部导航栏铃铛
组件挂载 → 轮询 GET /admin/notifications/unread-count（30秒一次）
→ count > 0 时铃铛显示红点 + 数字
→ 点击铃铛 → 弹出通知抽屉 or 跳转 /notifications 页面
→ 打开时调 GET /admin/notifications?is_read=false
→ 点击某条通知 → PUT /admin/notifications/{id}/read → 根据 ref_type+ref_id 跳转对应业务页
跳转逻辑（ref_type）
| ref_type | 跳转页面 |
|---|---|
approval |
/approval/{ref_id} 审批详情 |
recharge |
/recharge/{ref_id} 充值单详情 |
refund |
/refund/{ref_id} 退款单详情 |
package |
/assets/{ref_id} 资产详情（临期提醒） |
通知列表页（/notifications）
筛选：通知类型（下拉）、已读状态
操作：全部已读按钮
列表字段：类型、标题、时间、已读状态
点击行：跳转关联业务详情
九、Phase 2 扩展预留
当需要接入企微通知时，只需在 HandleNotification 里追加：
// 企微通知（Phase 2）
if h.wecomClient != nil {
for _, uid := range payload.RecipientIDs {
wecomOpenID := h.userStore.GetWecomOpenID(ctx, uid)
h.wecomClient.SendMessage(wecomOpenID, payload.Title, payload.Body)
}
}
业务代码零修改，Handler 里加一段即可。