临时备份一次

2026-07-13 12:01:18 +09:00
parent 5cdcdad534
commit 2e130b98f5
17 changed files with 3938 additions and 0 deletions
--- a/docs/7月迭代/基础设施/站内消息.md
+++ b/docs/7月迭代/基础设施/站内消息.md
@@ -0,0 +1,340 @@
+# 基础设施：站内消息（Notification）
+
+> 被依赖：需求 18/20/21（审批流通知）、需求 22（临期提醒）  
+> Phase 2 扩展：企业微信推送、短信通知（预留插拔接口）
+
+---
+
+## 一、设计原则
+
+- **业务代码不直接写通知**：只发 Asynq 任务，异步处理
+- **不过度抽象**：不用 interface，用具体的 `NotificationPublisher`（后续加渠道 = 在 handler 里加代码）
+- **前端轮询**：30秒一次 `/admin/notifications/unread-count`，不用 WebSocket
+
+---
+
+## 二、数据库
+
+```sql
+-- 迁移文件：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 '站内消息通知表';
+```
+
+---
+
+## 三、常量定义
+
+```go
+// 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
+
+```go
+// 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
+
+业务代码调这个发布通知，内部异步入队：
+
+```go
+// 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))
+    }
+}
+```
+
+业务代码调用示例（审批推进后通知下一审批人）：
+
+```go
+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
+
+```go
+// 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
+```
+
+响应：
+```json
+{ "code": 0, "data": { "count": 5 } }
+```
+
+### 7.2 通知列表
+
+```
+GET /admin/notifications?is_read=false&type=approval.pending&page=1&page_size=20
+```
+
+请求参数：
+```go
+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）"`
+}
+```
+
+响应：
+```json
+{
+  "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` 过滤（只把某类型全部已读）：
+```json
+{ "type": "approval.pending" }
+```
+
+### DTO
+
+```go
+// 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` 里追加：
+
+```go
+// 企微通知（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 里加一段即可。