# 新增需求 03：站内通知详细方案

> 状态：已合并至标准评审稿，本文保留为实施明细。  
> 评审主文档：`../7月迭代技术方案-标准评审稿.md`  
> 范围：后台账号、代理账号、企业账号和个人客户的站内通知。

## 一、定位

站内通知只负责“用户登录本系统后可以看到的消息”，不承担企业微信审批流程，也不直接发送企业微信消息。

第一版消息来源：

| 来源 | 接收人 | 示例 |
|---|---|---|
| 企微审批结果 | 业务申请人、相关平台角色 | 退款审批通过、线下充值审批驳回 |
| 套餐临期 | 代理账号、企业业务员、个人客户 | 套餐剩余 15/7/3 天 |
| 数据同步异常 | 平台运维角色 | 模板失效、回调找不到资产、连续同步失败 |
| 系统配置异常 | 平台超管 | 企微配置不可用、支付配置失效 |

企微审批中的“待我审批”由企业微信自身提醒，不在本系统重复创建审批待办。

## 二、设计原则

1. 业务事务不直接写 `tb_notification`，关键事件通过 Outbox 可靠投递。
2. 一条事件向多个接收人发送时，每个接收人保存一条独立通知。
3. 使用 `event_id + recipient_kind + recipient_id` 保证重复消费不生成重复消息。
4. 通知正文是发送时快照，使用受控纯文本模板，不保存任意 HTML。
5. 通知只能跳转到受控业务类型，前端不接受后端返回任意 URL。
6. 通知已读状态只属于当前接收人，任何查询和更新都必须带接收人条件。
7. 过期通知不进入列表和未读数，但历史数据按保留策略清理，不由用户删除。
8. 站内通知是简单写模型，使用 Application + Query + Infrastructure，不为形式强行创建领域聚合。
9. 后续新增短信、企微消息等外部渠道时使用独立 Delivery，不在站内通知 Handler 中追加外部调用。

## 三、流程

```mermaid
sequenceDiagram
    participant Biz as 业务 Application
    participant DB as 业务数据库
    participant Outbox as Outbox
    participant Relay as Outbox Relay
    participant Worker as Notification Worker
    participant Notice as tb_notification
    participant Web as 前端

    Biz->>DB: 提交业务状态
    Biz->>Outbox: 同事务写通知事件
    Relay->>Worker: 至少一次投递
    Worker->>Worker: 解析接收人和受控模板
    Worker->>Notice: 幂等批量插入
    Web->>Notice: 查询未读数/列表
    Web->>Notice: 当前接收人标记已读
```

非关键系统告警允许直接入 Asynq，但必须携带稳定 `event_id`；不能在重试时重新生成。

## 四、数据模型

```sql
CREATE TABLE tb_notification (
    id               BIGSERIAL PRIMARY KEY,
    event_id         VARCHAR(64) NOT NULL,
    recipient_kind   VARCHAR(32) NOT NULL,
    recipient_id     BIGINT NOT NULL,
    category         VARCHAR(32) NOT NULL,
    type             VARCHAR(64) NOT NULL,
    severity         VARCHAR(16) NOT NULL DEFAULT 'info',
    title            VARCHAR(200) NOT NULL,
    body             TEXT NOT NULL DEFAULT '',
    ref_type         VARCHAR(64),
    ref_id           BIGINT,
    ref_key          VARCHAR(128),
    is_read          BOOLEAN NOT NULL DEFAULT FALSE,
    read_at          TIMESTAMPTZ,
    expires_at       TIMESTAMPTZ,
    created_at       TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    UNIQUE (event_id, recipient_kind, recipient_id)
);

CREATE INDEX idx_notification_recipient_unread
    ON tb_notification (recipient_kind, recipient_id, is_read, created_at DESC);

CREATE INDEX idx_notification_recipient_category
    ON tb_notification (recipient_kind, recipient_id, category, created_at DESC);

CREATE INDEX idx_notification_expired
    ON tb_notification (expires_at)
    WHERE expires_at IS NOT NULL;
```

字段说明：

| 字段 | 说明 |
|---|---|
| `recipient_kind` | `account` 或 `personal_customer` |
| `category` | `approval / expiry / sync / system` |
| `type` | 具体通知类型常量 |
| `severity` | `info / warning / error / critical` |
| `ref_type` | 受控业务引用类型 |
| `ref_id` | 业务主键，可为空 |
| `ref_key` | 业务编号或资产标识快照，用于列表展示和资源删除后的追溯 |

不在通知表保存接收人名称、店铺名称等实时关联字段；正文已经是发送时快照，查询时也不需要联表才能展示。

## 五、通知类型

```go
const (
    NotifyTypeWeComApprovalApproved       = "wecom.approval.approved"
    NotifyTypeWeComApprovalRejected       = "wecom.approval.rejected"
    NotifyTypeWeComApprovalCancelled      = "wecom.approval.cancelled"
    NotifyTypeWeComApprovalRevoked        = "wecom.approval.revoked_after_approved"
    NotifyTypeWeComTemplateInvalid        = "wecom.template.invalid"
    NotifyTypePackageExpiring             = "package.expiring"
    NotifyTypeCardSyncFailed              = "card_sync.failed"
    NotifyTypeCarrierCallbackCardNotFound = "carrier_callback.card_not_found"
    NotifyTypeSystemAlert                 = "system.alert"
)
```

类别映射由后端常量维护，前端只按返回值展示，不自行猜测：

```go
func NotificationCategory(notifyType string) string
```

## 六、发布命令

```go
type Recipient struct {
    Kind string
    ID   uint
}

type PublishNotificationCommand struct {
    EventID    string
    Recipients []Recipient
    Type       string
    Severity   string
    TemplateData map[string]any
    RefType    string
    RefID      uint
    RefKey     string
    ExpiresAt  *time.Time
}
```

Application 只提交通知类型和受控模板数据，不直接提交最终 HTML。Notification Worker 通过代码内模板注册表渲染：

```go
type TemplateRenderer func(data map[string]any) (title string, body string, err error)

var notificationTemplates = map[string]TemplateRenderer{
    constants.NotifyTypeWeComApprovalApproved: renderWeComApprovalApproved,
    constants.NotifyTypePackageExpiring:       renderPackageExpiring,
}
```

模板字段不足时任务失败并重试，禁止生成标题为空或只有业务编号的残缺通知。

## 七、接收人解析

业务 Application 在发布事件前确定稳定业务接收人：

| 场景 | 接收人来源 |
|---|---|
| 退款/充值审批结果 | 申请人账号 ID |
| 通过后撤销 | 申请人 + 财务角色当前启用账号 |
| 企微模板失效 | 平台超管角色账号 |
| 数据同步连续失败 | 平台运维角色账号 |
| 代理套餐临期 | 资产所属代理及配置的业务员账号 |
| 企业套餐临期 | 企业关联业务员账号 |
| 个人客户套餐临期 | 资产当前绑定的个人客户 ID |

角色接收人应在事件消费时批量解析当前启用账号，具体用户接收人直接使用事件快照中的 ID。

不存在接收人时记录消费结果 `no_recipient`，不能无限重试。

## 八、API

后台账号、代理账号和企业账号统一使用 `/api/admin`，后端从登录上下文取得当前账号 ID。

### 8.1 未读总数

```http
GET /api/admin/notifications/unread-count
GET /api/c/v1/notifications/unread-count
```

响应：

```json
{
  "code": 0,
  "data": {
    "count": 12,
    "display_count": "12"
  }
}
```

超过 99 时 `display_count` 返回 `99+`，前端也必须兼容直接按 count 计算。

查询条件：

```sql
recipient_kind = ?
AND recipient_id = ?
AND is_read = FALSE
AND (expires_at IS NULL OR expires_at > NOW())
```

第一版直接查询 PostgreSQL，不额外维护 Redis 未读计数，避免数据库与缓存双写不一致。

### 8.2 分类未读数

```http
GET /api/admin/notifications/unread-summary
```

```json
{
  "code": 0,
  "data": {
    "total": 12,
    "categories": {
      "approval": 3,
      "expiry": 5,
      "sync": 2,
      "system": 2
    }
  }
}
```

个人客户第一版只返回总数，不开放运维类分类。

### 8.3 通知列表

```http
GET /api/admin/notifications
    ?category=approval
    &type=
    &severity=
    &is_read=false
    &page=1&page_size=20

GET /api/c/v1/notifications?page=1&page_size=20
```

响应项：

```json
{
  "id": 1001,
  "category": "approval",
  "type": "wecom.approval.approved",
  "severity": "info",
  "title": "退款审批已通过",
  "body": "退款单 RF202607150001 已通过企业微信审批。",
  "ref_type": "refund",
  "ref_id": 42,
  "ref_key": "RF202607150001",
  "is_read": false,
  "read_at": null,
  "created_at": "2026-07-15T10:00:00+08:00"
}
```

列表固定按 `created_at DESC, id DESC` 排序并服务端分页，最大 `page_size=50`。

### 8.4 单条标记已读

```http
PUT /api/admin/notifications/{id}/read
PUT /api/c/v1/notifications/{id}/read
```

条件更新：

```sql
UPDATE tb_notification
SET is_read = TRUE, read_at = NOW()
WHERE id = ?
  AND recipient_kind = ?
  AND recipient_id = ?
  AND is_read = FALSE;
```

记录不存在、无权访问或已经已读时统一返回成功，保持幂等且不泄露其他用户通知是否存在。

### 8.5 批量标记已读

```http
PUT /api/admin/notifications/read-all
PUT /api/c/v1/notifications/read-all
```

```json
{
  "category": "approval"
}
```

`category` 为空表示当前接收人的全部未过期通知。接口返回本次实际更新数量。

### 8.6 点击并读取跳转信息

前端通常可直接使用列表中的 `ref_type/ref_id`。为了处理业务被删除、权限变化等情况，允许：

```http
GET /api/admin/notifications/{id}/target
```

后端先校验通知属于当前用户，再返回受控目标：

```json
{
  "target_type": "refund_detail",
  "target_id": 42,
  "available": true
}
```

该接口不返回任意 URL。

## 九、受控跳转

| ref_type | target_type | 后台页面 |
|---|---|---|
| `refund` | `refund_detail` | `/refunds/{id}` |
| `agent_recharge` | `agent_recharge_detail` | `/agent-recharges/{id}` |
| `wecom_approval` | `wecom_approval_detail` | `/operations/wecom-approvals/{id}` |
| `iot_card` | `iot_card_detail` | `/iot-cards/{id}` |
| `device` | `device_detail` | `/devices/{id}` |
| `card_sync` | `card_sync_execution` | `/operations/card-sync?execution_id={id}` |
| `system_config` | `system_config` | `/system/config` |

前端维护 `target_type -> route` 映射。未知类型只展示通知，不执行跳转。

跳转目标页面仍按原业务权限重新校验，拥有通知不等于永久拥有业务数据访问权。

## 十、前端方案

### 10.1 顶部铃铛

```text
登录成功/布局挂载
→ 立即请求 unread-count
→ 每 30 秒轮询
→ 页面不可见时暂停
→ 恢复可见时立即刷新
```

- 未读为 0 时不显示数字。
- 1～99 显示实际数字，超过 99 显示 `99+`。
- 请求失败保留上一次数字，不闪回 0。
- 铃铛区域固定宽度，数字变化不得造成导航布局位移。

### 10.2 通知抽屉

点击铃铛打开右侧抽屉：

- 顶部显示“全部、审批、临期、系统”分段控件。
- 默认加载最近 10 条，提供“查看全部消息”。
- 未读消息使用左侧状态点，不用整行高饱和背景。
- 点击消息先本地进入已读视觉状态，再并行调用标记已读和目标解析。
- 标记已读失败时，下次未读轮询恢复服务端真实状态。

### 10.3 通知中心

后台路由：`/notifications`

页面结构：

```text
分类 Tab + 已读状态筛选 + 严重级别筛选
通知时间线列表
全部已读按钮
服务端分页
```

错误和严重通知显示级别图标；普通通知不使用警告色。

个人客户使用简化通知列表，只显示套餐临期、订单和资产相关消息，不显示平台运维消息。

## 十一、权限与数据安全

- Notification Query 从登录 Context 固定注入接收人，不接收前端传入 `recipient_id`。
- 后台账号只能查看自己的消息，平台超管也不能通过通知接口查看其他人的消息。
- 运维需要排查通知投递时，使用全局审计/运维查询接口，不复用用户通知列表接口。
- 正文禁止包含操作密码、支付密钥、身份证完整号码、长期对象存储 URL 和完整企微回调正文。
- 附件只提示“包含附件”，用户进入有权限的业务详情后获取短期下载 URL。
- 所有已读接口不区分“通知不存在”和“通知不属于当前用户”。

## 十二、保留与清理

| 通知类型 | 展示期限 | 数据保留期限 |
|---|---:|---:|
| 套餐临期 | 到期后自动不展示 | 180 天 |
| 审批结果 | 不自动过期 | 365 天 |
| 同步异常 | 30 天 | 180 天 |
| 系统告警 | 由事件指定 | 365 天 |

每日低峰期使用现有数据清理任务按批次删除超过保留期限的数据。清理不修改业务审计和领域流水。

## 十三、外部渠道扩展

未来如果需要企微消息或短信，新增独立投递表：

```text
tb_notification_delivery
notification_event_id
recipient
channel
status
attempts
provider_message_id
last_error
```

站内通知写入和外部渠道发送分别消费同一业务事件，互不影响。不能在 `NotificationHandler` 写入站内消息后直接循环调用企微或短信接口，否则某个外部渠道故障会拖慢所有站内消息。

## 十四、代码结构

```text
internal/
├── application/notification/
│   ├── publish_notification.go
│   ├── mark_read.go
│   └── mark_all_read.go
├── query/notification/
│   ├── list_notifications.go
│   ├── unread_count.go
│   └── resolve_target.go
├── infrastructure/messaging/
│   └── notification_event_handler.go
├── infrastructure/persistence/
│   └── notification_repository.go
├── handler/admin/notification.go
└── handler/app/client_notification.go
```

通知没有复杂状态机，不创建空洞的 `domain/notification` 聚合。Application 负责写操作和幂等，Query 直接使用 GORM 查询读取模型。

## 十五、人工验证

1. 同一事件重复消费不会为同一接收人生成重复通知。
2. 同一事件的两个接收人各自生成一条通知，已读状态互不影响。
3. 用户无法读取或标记其他用户通知。
4. 过期通知不进入未读数和列表。
5. 全部已读只影响当前用户和指定分类。
6. 业务权限变化后，通知仍可展示，但目标接口重新校验权限。
7. 前端隐藏页签时暂停轮询，恢复后立即刷新。
8. 企微审批待办不重复生成站内待办，审批结果可以正常通知申请人。
9. 外部消息渠道失败不影响站内通知生成。
10. 通知正文、日志和 API 不包含密钥、操作密码或长期附件 URL。