定位：未读数是承诺，不是装饰

用户看到「3 条未读」，就会期待正好是 3 条新内容。 数不准比不显示更伤信任。

一、入口与未读数

1.1 三种入口

1.2 未读数的显示规则

<Badge count={unread} overflowCount={99} showZero={false} />

showZero={false} 是关键：显示「0」会让用户以为有新消息但内容是空的。

1.3 红点 vs 数字

• 红点：只表示"有新的"，不承诺数量（适合高频、低价值消息）
• 数字：明确承诺条数（适合低频、高价值消息，如审批、订单）

不要在同一个入口混用——要么都红点，要么都数字。

二、未读数的定义（最容易出错的地方）

2.1 「未读」到底指什么

必须明确三件事：

建议定义：未读数 = 该用户所有 status=unread 且未过期的消息条数

2.2 清零时机（三种模式，选一个）

不要混用。最常见的问题是：进入页面标了已读，但列表项还显示未读小圆点——用户困惑。

2.3 未读数的三个必做

1. 乐观更新：点击后立即把角标清零，不等接口返回（失败再回滚）
2. 服务端权威：每次进入页面以服务端返回的为准重新同步，不信本地缓存的数
3. 跨端同步：A 端读了，B 端的角标要变（见第六节）

三、消息分类与 Tab

3.1 分类原则

分类 ≤ 4 个。超过就说明分类维度混乱（见 3.2）。

3.2 什么时候不该分类

消息总量 < 50 条/天时，不要分 Tab——直接一个列表，加了 Tab 反而增加点击成本。

判断标准：每个分类下的消息量是否都 > 5 条/天？不是就不分。

3.3 Tab 上的未读数

<Tabs items={[
  { key: 'all',      label: '全部',   children: <List /> },
  { key: 'business', label: <span>业务 <Badge count={3} /></span> },
]}/>

只有分类未读数 > 0 时显示角标，为 0 时不显示。

四、列表项设计

4.1 结构

┌─────────────────────────────────────────┐
│ ● [图标] 标题                    3 分钟前 │
│         摘要文本，最多两行，超出省略…      │
│         [操作按钮]（可选）                │
└─────────────────────────────────────────┘

4.2 已读与未读的视觉差异

不要只靠一个小圆点——要让用户扫一眼就能区分：

• 未读：圆点 + 标题加粗 + 背景 #f0f7ff（浅主色）
• 已读：无圆点 + 标题常规 + 背景白

颜色对比要够，浅色背景在深色模式下要换。

4.3 时间格式

function relativeTime(date: Date): string {
  const diff = Date.now() - date.getTime()
  const min = 60_000, hour = 60 * min, day = 24 * hour
  if (diff < min) return '刚刚'
  if (diff < hour) return `${Math.floor(diff / min)} 分钟前`
  if (diff < day) return `${Math.floor(diff / hour)} 小时前`
  if (diff < 2 * day) return `昨天 ${format(date, 'HH:mm')}`
  if (diff < 7 * day) return `${Math.floor(diff / day)} 天前`
  if (date.getFullYear() === new Date().getFullYear()) return format(date, 'MM-DD')
  return format(date, 'YYYY-MM-DD')
}

不要显示「2026-10-28 21:05:33」这种精确时间——消息列表里没人关心秒。

五、标记已读

5.1 三种粒度

「全部标为已读」必须二次确认——这是不可逆操作。

5.2 批量接口

// ✅ 一个接口
POST /api/notifications/read  { ids: [1,2,3] }     // 指定
POST /api/notifications/read  { all: true }         // 全部
POST /api/notifications/read  { category: 'business' }  // 按分类

// ❌ 不要循环调单条接口
for (const id of ids) await api.readOne(id)

5.3 乐观更新 + 回滚

const markRead = useMutation({
  mutationFn: api.markRead,
  onMutate: async (ids) => {
    const prev = queryClient.getQueryData(['notifications'])
    queryClient.setQueryData(['notifications'], patchRead(prev, ids))
    queryClient.setQueryData(['unreadCount'], (n: number) => Math.max(0, n - ids.length))
    return { prev }
  },
  onError: (_e, _v, ctx) => {
    queryClient.setQueryData(['notifications'], ctx.prev)
    queryClient.invalidateQueries(['unreadCount'])
  },
})

未读数必须跟着一起乐观更新，否则点了"全部已读"角标还在。

六、实时推送

6.1 三种方案

后台系统默认用轮询（60 秒一次，只在页面可见时轮询）。要做实时再上 SSE。

6.2 轮询的正确实现

useQuery({
  queryKey: ['unreadCount'],
  queryFn: api.getUnreadCount,
  refetchInterval: 60_000,
  refetchIntervalInBackground: false,   // ★ 页面不可见时不轮询
  refetchOnWindowFocus: true,           // ★ 切回来立即查一次
})

refetchIntervalInBackground: false 必加——否则后台标签页一直在请求。

6.3 WebSocket 的必备处理

「多标签页只建一个连接」经常被忽略：5 个标签页 = 5 个连接，服务端压力翻倍。用 BroadcastChannel 或 localStorage 选主。

七、免打扰

• 夜间免打扰：22:00–08:00 不弹桌面通知（站内消息照常收）
• 分类免打扰：某类消息不推送，但仍在列表里
• 勿扰模式下角标仍然累加，只是不弹提醒

免打扰不等于不接收——消息要存，只是不打扰。

八、验收清单

• 未读 0 时不显示角标（不是显示 0）
• ≥ 100 显示 99+
• 「未读」的定义明确（未查看/未点击），且全站一致
• 进入消息中心后角标清零，列表项也同步变已读态
• 未读数乐观更新，失败回滚
• 每次进入页面从服务端重新同步未读数
• 分类 ≤ 4，且每个分类都有量（否则不分 Tab）
• 已读/未读的视觉差异不只靠小圆点
• 时间是相对格式，超过一年才显示完整日期
• 批量标记用单接口，不是循环
• 「全部标为已读」有二次确认
• 轮询 60s 且 refetchIntervalInBackground: false
• 切回标签页立即刷新一次
• WebSocket 有重连、心跳、去重、补漏
• 多标签页只建一个连接

九、反面清单

1. ❌ 未读数为 0 时显示「0」
2. ❌ 未读数显示 1000+
3. ❌ 进入页面标了已读，但列表项还是未读态
4. ❌ 未读数只在登录时拿一次，之后不更新
5. ❌ 后台标签页还在轮询
6. ❌ 「全部已读」没有二次确认
7. ❌ 批量已读循环调单条接口
8. ❌ 消息列表显示精确到秒的时间
9. ❌ 5 个标签页建 5 个 WebSocket
10. ❌ 免打扰就真的不存消息了
11. ❌ 点击消息后角标不立即变（等接口返回）