# 站内"邮箱"聚合收件箱 — 设计方案

> 文档版本: v1.2.10 · 拟稿日期: 2026-07-14 · 作者: Claude
> 实施阶段: MVP · Status: 待用户审阅

---

## 方案概述（必读）

### 要解决的问题
**业务侧**: 用户提交举报 / 反馈、参与活动后，目前没有"集中看到所有回执"的入口 —— 处理结果散落在 `myReports / myFeedbacks / activity-center` 三处独立页面，用户很容易漏看。

**技术侧**:
1. 项目已有 `notifications` 主表 + `notification_stats` 未读聚合 + uniPush 推送通道；`allowedTypes` 白名单允许 `like/system/activity`，但**生产代码里只有 `socialService` 在调用 `CreateNotification(type="like")`**（`asset_like_service.go:185`），`system` / `activity` 是白名单预留位、零业务调用；举报与反馈的处理回执**也没有**接进通知流。
2. `utils/api.js` 只暴露了推送设备注册 API，`GET /api/v1/notifications` 等查询类接口在**前端没有客户端封装**。
3. 广场（之前错的）`pages/profile/profile.vue`（你确认改到这）`<!-- 服务与工具 -->` section（profile.vue:162）没有"📬 收件箱"入口位，新功能要在该 section 加一个 `service-button` 类型的入口（参考同 section 的"新手指引/反馈/修改昵称" 等按钮的视觉规范）。

### 整体实现路径
| Stage | 工作 | 估算 |
|------|------|------|
| 后端 type 白名单扩展 + stats migration | map 加 3 key + ALTER TABLE + proto 字段 | 0.5d |
| `moderationService` 3 处 emitter 新增 | 复用现有审核流，补 3 个回调写通知 | 0.5d |
| **`activityService` 1-2 处 emitter 新增**（v1.2.2 自审：原本以为活动是复用，实际是新建）| 留言下发 + 活动开始/结束 | 0.3d |
| 新加清空接口 `DELETE /api/v1/notifications/clear` | proto + repository + service + router | 0.3d |
| 前端 `utils/api.js` 补 5 个查询/动作函数 | notifications 列表/未读/标已读/标全部/删除单条 | 0.2d |
| Vuex `modules/mailbox.js` 全局未读数 | refresh + reset action | 0.2d |
| `pages/mailbox/index.vue` 列表页 + `pages/mailbox/detail.vue` 明信片页 | 4 分组列表 + 单条详情（两页路由） | 1.0d |
| **`profile.vue` `<!-- 服务与工具 -->` section 加 `📬 收件箱` 入口**（v1.2.9 新增/原计划在 `Header.vue` + `square.vue`） | service-button 视觉 + 红点 badge + navigateTo | 0.3d |
| 推送节流三道防线（v1.2.6 新增,参数 60s/10s 见 v1.2.7）| 后端 RateLimiter 60s + App 10s 去抖 + Vuex 幂等 | 0.3d |
| 推送聚合 +N（v1.2.8 新增）| RateLimiter 加 pending[s]count,summary title 拼 "N 条新<type>" | 0.1d |
| 手验 + 单测（moderation 单元测试补 3 用例） | | 0.5d |
| **合计** | | **3.5d ≈ 5-6 个工作日** |

### 关键决策
1. **复用 `notifications` 表**，扩 `type` 白名单 3 个 key（`feedback_replied / report_resolved / target_reported` 三个真的新增），`activity` 复用白名单但**实际是新增 emitter**（无现有业务流调用）。理由: MVP 阶段 1 套表足够；项目已有未读聚合 + 推送链路；零迁移成本。
2. **前端聚合 4 个 type**，不建后端聚合接口。理由: 4 个 Tab（同 1 个 endpoint，按 type 过滤）= 1 个 HTTP 调用 × 4 次（并发），零新接口干净。
3. **两页路由（手机竖屏优先）**: 列表页 `pages/mailbox/index.vue` 装 4 分组可折叠列表 + 顶部 [全部已读 / 全部删除] + 列表项长按 ActionSheet；明信片页 `pages/mailbox/detail.vue?nid=<id>` 装单条明信片全宽 + 顶部 [返回] + 单条 [标已读 / 删除]。点列表项 `navigateTo` 到详情页。所有详情在邮件页面内完成，不跳详情子页。
5. **点赞不进邮箱**（v1.2.10 经你确认）:后端 `socialService/asset_like_service.go:185` 的 `like` emitter 保留不动（用户已习惯手机通知栏+红点旧体验）；前端 inbox 4 GROUPS（§5.7）本来就不含 `like`（已合规）；**profile.vue 📬 badge 显示值改为 Vuex getter `inboxUnreadOnly` = `sum(unreadByType[activity, feedback_replied, report_resolved, target_reported])`**,**不**包括 `like` / `system` 红点。详细见 §3.1 备注、§7.2 badge 计算。
4. **新页 `pages/mailbox/index.vue` 列表页 + `pages/mailbox/detail.vue` 明信片页（两页路由）**，绕过 `myReports / myFeedbacks / 任何详情子页` —— 仓库文件**不删除**（避免无关改动），但下游入口不再引用。
5. **推送节流 + 聚合**（v1.2.6 初版,v1.2.8 加 count 聚合）:① 后端 `RateLimiter` (user, type) **60s** 滑窗 → 首次 concrete,后续 summary `title="您有 N 条新<type中文名>"` 聚合递增（仍 Send 让 App receive 同步红点）；② App `plus.push.addEventListener` 内 **10s** 同 type 去抖；③ Vuex `PREPEND_ITEM` 按 id 去重 + `REPLACE_UNREAD_BY_TYPE` 是 idempotent。详细见 §12.7。

### 核心架构图（TL;DR）
```
┌──────────────────────────────────────────────┐
│            现有业务流(变化点)                   │
│  moderationService(管理员操作)                │
│    └─ (新)CreateNotification 3 处 emitter     │
│         ├─ type=report_resolved  → 我的举报结果│
│         ├─ type=feedback_replied → 我的反馈回复│
│         └─ type=target_reported  → 被举报通知  │
│         └─ (已有) type=activity  → 活动通知    │
│                                              │
│  activityService(留言下发)                    │
│    └─ (新)CreateNotification type=activity    │
│                                              │
├──────────────────────────────────────────────┤
│            通知主表(变化点)                    │
│  public.notifications                        │
│    + type 白名单扩展 4 类                    │
│  public.notification_stats                   │
│    + 列扩展: feedback_replied_unread_count   │
│              report_resolved_unread_count    │
│              target_reported_unread_count    │
│                                              │
├──────────────────────────────────────────────┤
│            API(变化点)                       │
│  POST   /internal/v1/notifications (已)      │
│  GET    /api/v1/notifications   (已有,扩类型)│
│  GET    /api/v1/notifications/unread-count(已)│
│  POST   /api/v1/notifications/{id}/read (已) │
│  POST   /api/v1/notifications/read-all   (已)│
│  DELETE /api/v1/notifications/{id}       (已) │
│  DELETE /api/v1/notifications/clear      (新)│
│    ?type=activity|feedback_replied|report_   │
│     resolved|target_reported|all             │
│                                              │
├──────────────────────────────────────────────┤
│            前端(变化点)                       │
│  utils/api.js                                │
│    + getNotificationsApi                     │
│    + getUnreadCountApi (兜底对齐用,主路径无 HTTP) │
│    + markAsReadApi / markAllAsReadApi       │
│    + deleteNotificationApi                  │
│    + clearNotificationsApi (新)              │
│                                              │
│  store/modules/mailbox.js (新)               │
│    state.unreadCount / unreadByType          │
│    actions.applyPushPayload (uniPush receive 触发,详见 §12) │
│                                              │
│  components/composables/useMailboxCenter.js (新)│
│    封装 4 type 并发拉取 + 上拉加载更多        │
│                                              │
│  pages/profile/profile.vue (v1.2.9 入口位)     │
│    <!-- 服务与工具 --> section               │
│    + 📬 收件箱 service-button + 红点 badge   │
│    + onShow 时 dispatch refreshUnread        │
│                                              │
│  pages/mailbox/index.vue (新,列表页)         │
│  pages/mailbox/detail.vue (新,明信片页)       │
└──────────────────────────────────────────────┘
```

### 文档说明
- **适用范围**: TopFans 站内 App（uni-app + Vue 3 组合式 API，主要面向 app-plus 端，兼容 H5 / 微信小程序）。
- **工作量估算**: ~3.5 工作日（含单测与手验）。
- **前置版本**: 无（绿地新增）。
- **目标读者**: 后端 moderator / 通知 / statistic 三服务模块负责人；前端 Vuex / Vue3 composable 接入方；测试同学。
- **关联文档**:
  - `CLAUDE.md` —— 接口开发规范、数据库操作规范、前端开发规范、Git 提交规范
  - `proto/notification.proto` —— 通知服务协议（本次扩展）
  - `pkg/models/moderation.go` —— 举报 / 反馈数据模型
  - `pkg/models/activity_message.go` —— 活动留言数据模型
  - `services/notificationService/` —— 现有通知服务实现

---

## 目录

1. [现状盘点](#1-现状盘点)
2. [设计目标与验收标准](#2-设计目标与验收标准)
3. [数据契约](#3-数据契约)
4. [后端设计](#4-后端设计)
5. [前端设计](#5-前端设计)
6. [响应式与可达性](#6-响应式与可达性)
7. [错误处理与边界](#7-错误处理与边界)
8. [测试计划](#8-测试计划)
9. [文档 / 运维](#9-文档--运维)
10. [目录变更](#10-目录变更)
11. [部署与回滚](#11-部署与回滚)
12. [不在本期范围](#12-不在本期范围)
13. [关键决策表](#13-关键决策表)
14. [附:与旧 myReports/myFeedbacks 的关系](#14-附与旧-myreportsmyfeedbacks-的关系)
15. [变更日志](#15-变更日志)

---

## 1. 现状盘点

### 1.1 数据表（已有）
| 表 | 关键字段 | 用途 | 复用方式 |
|----|---------|------|---------|
| `public.notifications` | `id/user_id/star_id/type/title/content/data(jsonb)/is_read/is_deleted/created_at/read_at` | 通知主表 | 扩 `type` 白名单 |
| `public.notification_stats` | `user_id/star_id/like_unread/system_unread/activity_unread/total_unread/updated_at` | 未读聚合 | 加 3 列 |
| `reports` | `reporter_id/star_id?/target_type/target_id/target_snapshot/category_code/description/status/resolved_action/resolved_by/resolved_at/resolution_note/...` | 用户提的举报 | 只用 `id` + `reporter_id` + `resolved_*` 当 data 字段塞进通知 |
| `feedbacks` | `user_id/star_id?/category_code/title/content/contact?/status/reply_content/replied_by/replied_at/...` | 用户提的反馈 | 只用 `id` + `reply_content` + `replied_at` 当 data 字段塞进通知 |
| `activity_messages` | `activity_id/user_id/star_id/nickname/avatar_url/content/status/...` | 活动留言 | `activityService` 留言回调写 `type=activity` 通知 |
| `report_evidence` / `feedback_evidence` | 截图证据 | 显示在信片 data 中（缩略图 OSS url） | 可选填 |

> **`target_reported` 的"被处置说明"字段**: `moderation_target_status.reason` 字段已存在（`pkg/models/moderation.go:228`），管理员处理时填入，写入通知 `content` 即可。

### 1.2 后端服务（已有）
| 服务 | 关键功能 | 与本设计的关系 |
|------|---------|--------------|
| `notificationService` | `CreateNotification / GetNotifications / GetUnreadCount / MarkAsRead / MarkAllAsRead / DeleteNotification / DeleteByTarget / RegisterDevice / UnregisterDevice`；支持 `uniPush` 异步推送 | **核心**：扩 `allowedTypes` + 加 `ClearByType` |
| `moderationService` | 举报 / 反馈工单的增删查改；管理员审核动作 | **新增 3 处 emitter 接入点** |
| `activityService` | 活动 / 留言 | **新增 1 处 emitter 接入点**（活动开始 / 结束 / 新留言） |

### 1.3 后端 API（已存在；前端部分缺封装）
| 路径 | 用途 | 前端封装 |
|------|------|---------|
| `POST /internal/v1/notifications` | 内部创建通知 | （后端调用） |
| `GET /api/v1/notifications?type=...&tab=...&page=...&page_size=...` | 用户拉一页通知 | **缺** |
| `GET /api/v1/notifications/unread-count` | 拉全局未读（兜底对齐用，主路径不走 HTTP —— 见 §12） | **缺** |
| `POST /api/v1/notifications/{id}/read` | 单条已读 | **缺** |
| `POST /api/v1/notifications/targets/{target_id}/read` | 按 target 全标已读（现有 `like` 专用） | 暂不用 |
| `POST /api/v1/notifications/read-all?type=...` | 按 type 全标已读 | **缺** |
| `DELETE /api/v1/notifications/{id}` | 单条软删 | **缺** |
| `DELETE /api/v1/notifications/targets/{target_id}` | 按 target 全软删 | 暂不用 |
| `DELETE /api/v1/notifications/clear?type=...` | 按 user + type 软删 | **新加** |
| `POST /api/v1/notifications/devices` | 注册推送 cid | 已有 `registerDeviceApi` |
| `POST /api/v1/notifications/devices/unregister` | 注销推送 cid | 已有 `unregisterDeviceApi` |

### 1.4 前端页面 / 组件（已有）
| 路径 | 用途 | 与本设计的关系 |
|------|------|--------------|
| `pages/profile/profile.vue` | 我的页（含 `<!-- 服务与工具 -->` section） | **新增** 📬 收件箱 `service-button` 在该 section 内,onShow 时刷新 unread badge |
| `pages/components/Header.vue` | 通用顶部条，广场 `square.vue` 在用 | **不动**（v1.2.9 取消 Header.vue 上加 icon 的方案） |
| `pages/square/square.vue` | 广场首页 | **不动** |
| `pages/profile/myReports.vue` | 我的举报列表（旧） | **保留**，但下游入口不再引用 |
| `pages/profile/myFeedbacks.vue` | 我的反馈列表（旧） | **保留**，但下游入口不再引用 |
| `pages/support-activity/center.vue` | 活动中心 | 不动 |

### 1.5 前端 store / composables（已有）
- `store/index.js` + `modules/user.js / guide.js` —— **新增** `modules/mailbox.js`
- `composables/useHolographicPreview / useDashboardData / useLenticularStudioTilt` —— 范例模式
- **新增** `composables/useMailboxCenter.js`

---

## 2. 设计目标与验收标准

### 2.1 目标
1. 用户在 `pages/profile/profile.vue` 的 `<!-- 服务与工具 -->` section 看到一个 📬 收件箱 service-button + 红点 badge
2. 点击进入"邮箱"页面，左侧 4 分组列表（活动通知 / 反馈回复 / 举报结果 / 被举报），右侧明信片详情
3. 所有详情（举报处理备注、反馈回复全文、举报处置说明、活动摘要）**全部在邮件页面内展示，不跳转**
4. 4 个操作按钮：单条标已读 / 全部已读 / 单条删除 / 全部删除

### 2.2 验收标准
- [ ] `Acceptance 1`: 用户在 `pages/profile/profile.vue` 的 `<!-- 服务与工具 -->` section 看到 📬 收件箱 按钮 + 红点 badge，点击进入邮箱
- [ ] `Acceptance 1.1`: profile.vue 进入 onShow 时拉一次 unread,刷新 badge（不订阅 store 变化以避免重复监听）
- [ ] `Acceptance 1.2`: profile.vue 红点 badge **不包含 like 的未读数** —— 比如用户有 5 条 like + 3 条 feedback_replied, badge 显示 **3**（不是 8）
- [ ] `Acceptance 2`: 邮箱页有 4 分组，每组可独立折叠/展开
- [ ] `Acceptance 3`: 已读排在组内底部（created_at desc 时，未读优先）
- [ ] `Acceptance 4`: 点列表项 → `navigateTo` 跳详情页 + 该项标已读 + 红点未读 -1
- [ ] `Acceptance 5`: 全部已读 / 全部删除作用于 4 组全量
- [ ] `Acceptance 6`: 明信片页默认全开（不折叠），内容含管理员回复全文
- [ ] `Acceptance 7`: 红点消失条件：4 type 全 0 或用户手动全部已读
- [ ] `Acceptance 8`: 详情页 navigateBack 返回列表页，回到原滚动位置
- [ ] `Acceptance 9`: 后端事务：emitter 写通知 + stats 累加必须同事务
- [ ] `Acceptance 10`: 退出重进，未读数与列表项状态保留
- [ ] `Acceptance 11`: uniPush receive 时 App 前台红点 +1 + 邮箱页内新条目实时插入（不发 HTTP）
- [ ] `Acceptance 12`: 应用全程无 `setInterval / setTimeout` 形式的轮询（浏览器性能审计 / IDE grep 双重证）

---

## 3. 数据契约

### 3.1 `notifications.type` 白名单扩展（务实版）

**实际现状**（v1.2.2 自审确认，v1.2.10 加入"点赞不进邮箱"约束）：
| 值 | whitelist | 实际有 emitter | 本期动作 | 进邮箱? |
|----|-----------|--------------|----------|---------|
| `like` | ✅ | ✅ `socialService/asset_like_service.go:185` | 不动（保留原有 push 链路）| **❌ 不进（v1.2.10 你确认）** |
| `system` | ✅ | ❌ 零调用 | 不动（白名单预留位）| ❌ 不进 |
| `activity` | ✅ | ❌ 零调用 | **新增 emitter** | ✅ 进 |
| `feedback_replied` | ❌ | ❌ | **白名单 + emitter 都新增** | ✅ 进 |
| `report_resolved` | ❌ | ❌ | **白名单 + emitter 都新增** | ✅ 进 |
| `target_reported` | ❌ | ❌ | **白名单 + emitter 都新增** | ✅ 进 |

**"点赞不进邮箱"细则**（v1.2.10 你确认）:
- 后端：`socialService/asset_like_service.go:185` 的 `CreateNotification(type="like")` **保持不动**（你给的理由：用户已习惯点赞是手机通知栏+红点的旧体验,改动会影响其他下游如社交动态）
- 后端：`notification_stats.like_unread_count` 列**保留**,继续累加
- 前端 mailbox 4 GROUPS（§5.7）**不包含 like**（已经合规）
- 前端 profile.vue 📬 badge 显示 = `sum(unreadByType[inbox 4 类])`,**不包含 like / system** —— 用 Vuex getter 或 computed 过滤
- 前端 Vuex `REPLACE_UNREAD_BY_TYPE` 仍接受全 6 类（保持与 server 响应形状一致），**不展示≠不接收**

修改清单：
- `service/notification_service.go` `allowedTypes` map 加 3 个新 key（`feedback_replied / report_resolved / target_reported`）；`activity` 已在 map 中无需动
- `proto/notification.proto` `CreateNotificationRequest.type` 不动（已是 string）
- 4 处业务 emitter 真实接线（`activityService` 1-2 处、`moderationService` 3 处）—— 见 §3.3
- `socialService/asset_like_service.go` 保持原样（**不**改 like emitter,**不**加 inbox 路由分支）

### 3.2 `notification_stats` 表 migration（`backend/migrations/2026XXXX_add_mailbox_unread_counts.sql`）
```sql
-- 加 3 列 unread 计数 (default 0)
ALTER TABLE public.notification_stats
    ADD COLUMN IF NOT EXISTS feedback_replied_unread_count INT NOT NULL DEFAULT 0,
    ADD COLUMN IF NOT EXISTS report_resolved_unread_count   INT NOT NULL DEFAULT 0,
    ADD COLUMN IF NOT EXISTS target_reported_unread_count  INT NOT NULL DEFAULT 0;

-- 加触发器:在 INSERT 通知后自动累加对应列
-- (略,本版本用 service 层事务内手动累加,触发器列为下期优化)

-- 加索引: 按 type 拉列表 (已有 is_read+user_id 索引可复用)
-- 现无新索引需求

-- PG 序列同步 (按 CLAUDE.md 强制)
-- 本 migration 无 INSERT 语句, 不涉及序列同步
```

### 3.3 emitter 字段契约（`backend/services/moderationService/` 与 `activityService/`）

#### 3.3.1 `type=feedback_replied`
| 字段 | 来源 | 写入 |
|------|------|------|
| `user_id` | `feedbacks.user_id` | 收件人 (反馈提交者) |
| `star_id` | `feedbacks.star_id` 或 `0` | 必填(非空) |
| `type` | 字面量 `"feedback_replied"` | 写死 |
| `title` | "您的反馈已处理" | 模板 |
| `content` | **`feedbacks.reply_content` 全文**（≤ 4KB postgres text 兜底） | **信片主体** |
| `data` | `{feedback_id, category_code, original_title}` | 用于右侧 footer 元信息 |

触发点: `moderationService/service/feedback_service.go` 中"管理员填写回复"流程 (`status='replied'`, `reply_content!=NULL` 写入分支)。

#### 3.3.2 `type=report_resolved`
| 字段 | 来源 | 写入 |
|------|------|------|
| `user_id` | `reports.reporter_id` | |
| `star_id` | `reports.star_id` 或 `0` | |
| `type` | `"report_resolved"` | |
| `title` | "举报处理结果" | 模板 |
| `content` | **`reports.resolution_note` 全文**（NULL 时填"已处理"，无原文） | |
| `data` | `{report_id, resolved_action, target_type, target_id, category_code}` | |
| `target_id`(列) | `reports.id` | 用于反向定位 |

触发点: `moderationService/service/report_service.go` 中"`resolved_*` 字段全部非空"的提交分支。

#### 3.3.3 `type=target_reported`
| 字段 | 来源 | 写入 |
|------|------|------|
| `user_id` | **目标对象的所有者**（不是举报人） | 反查: assets/feedbacks.owner_user_id |
| `star_id` | 触发举报的 star_id | |
| `type` | `"target_reported"` | |
| `title` | "您的内容被举报" | |
| `content` | **`moderation_target_status.reason` 全文** | |
| `data` | `{report_id, target_type, target_id, action: 'warn'|'takedown'|'ban', reason_summary}` | |

触发点: `moderationService/service/target_status_service.go` 中"`WarnCount > 阈值自动处置"或"管理员手动处置" 写入分支。**只有 `action` 在 `'warn'/'takedown'/'ban'` 时才发通知**（`dismiss` 不发，避免打扰无辜作者）。

#### 3.3.4 `type=activity` 字段契约（**白名单已有，但零 emitter → 本期补建**）

⚠️ 自审发现：`allowedTypes` 已有 `activity`，但全仓 grep `CreateNotification(... Type: "activity"` 在 production 代码中**零命中**。本节是补建 emitter，不是补强。

| 字段 | 写入 |
|------|------|
| `title` | 活动标题（取自 `activities.title`） |
| `content` | 活动摘要 / 留言内容 |
| `data` | `{activity_id, message_id?}` |

**触发点**（本期新建 emitter）：
- `activityService/service/activity_message_service.go` —— 别人在你的活动留言 → 给活动创建者发 (`type=activity`)
- `activityService/service/activity_service.go` —— 活动开始 / 结束 → 给"我参与了该活动（购买过 / published_item_count>0）"的用户发

验证（grep `Type:\s*"activity"`）：
```bash
# 自审命令
grep -rn 'Type:\s*"activity"' backend/services/ --exclude="*_test*|*_mock*"
# 期: 命中 activity_message_service.go 和 activity_service.go 的 emitter 行
```

### 3.4 proto 调整
```protobuf
// proto/notification.proto

message UnreadCount {
  int32 like                 = 1;
  int32 system               = 2;
  int32 activity             = 3;
  int32 total                = 4;   // 总数(保留原字段号,不变)
  int32 feedback_replied     = 5;   // 新增(从 5 起追加,避免重编号破坏 wire 兼容)
  int32 report_resolved      = 6;
  int32 target_reported      = 7;
}

// ClearByType RPC (新)
service NotificationService {
  rpc ClearByType(ClearByTypeRequest) returns (ClearByTypeResponse) {
    option (google.api.http) = {
      delete: "/api/v1/notifications/clear"
    };
  }
}
message ClearByTypeRequest {
  // 枚举 string: activity / feedback_replied / report_resolved / target_reported / all
  string type = 1;
}
message ClearByTypeResponse {
  topfans.common.BaseResponse base = 1;
  int32 affected = 2;
}
```

---

## 4. 后端设计

### 4.1 handler / service / repository 三层（按 CLAUDE.md 强制）

#### 4.1.1 `notificationService` 改动清单

**`service/notification_service.go`**
- 修改 `allowedTypes` map，新增 3 个 key
- `ClearByType(ctx, userID, starID, ntype)` 新方法 → 事务内：`UPDATE is_deleted=true WHERE user_id=$1 AND star_id=$2 AND type=$3 AND is_deleted=false`；同步清零 `stats.<type>_unread_count`
- 现有 `MarkAllAsRead` 不变（已支持 3 个 type，扩到 6 个 key 由 `allowedTypes` 自动覆盖）

**`repository/notification_repository.go`**
- `ClearByType(ctx, tx, userID, starID, ntype)` 新方法
- `ListSystemActivity` 不动（按 type 过滤已支持）

**`repository/notification_stats_repository.go`**
- 加 3 列结构体字段（`GORM tags` 对应 DB schema）
- `IncrementByType / DecrementByType / Get` 三个方法**改为通用** —— 原 hard-code `like/system/activity` 列名改为根据 type 字符串映射列名或用条件 `CASE WHEN` SQL。

**`controller/notification_controller.go`** (gateway)
- 注册 `ClearByType` → `DELETE /api/v1/notifications/clear?type=...`

#### 4.1.2 `moderationService` 改动清单

`service/feedback_service.go` 中 "管理员回复反馈" 流程:
```go
// 注入 notificationClient (gRPC) - 由 main.go 初始化
type FeedbackService struct {
    db       *gorm.DB
    notifCli notification.NotificationServiceClient
}
```

在 `RepliedBy/RepliedAt/ReplyContent/Status='replied'` 写入后同步:
```go
// 事务提交后(避免回滚时通知已发出)
notifResp, err := s.notifCli.CreateNotification(ctx, &pb.CreateNotificationRequest{
    UserId: feedback.UserID,
    StarId: starIDZeroDefault(feedback.StarID),
    Type:   "feedback_replied",
    Title:  "您的反馈已处理",
    Content: *feedback.ReplyContent, // 全文
    Data: structpb.NewStruct(map[string]interface{}{
        "feedback_id":    feedback.ID,
        "category_code":  feedback.CategoryCode,
        "original_title": feedback.Title,
    }),
})
```
同样在 `report_service.go` 的 `Resolved` 流程 + `target_status_service.go` 的 `Warn/Takedown/Ban` 流程补对应 emitter（伪代码略，结构一致）。

### 4.2 数据库变更（迁移）

文件: `backend/migrations/2026XXXX_add_mailbox_unread_counts.sql`
- ALTER TABLE `notification_stats` 加 3 列（参见 §3.2）
- 不涉及新表 / 序列（避免触发 CLAUDE.md 的序列同步规则）

### 4.3 接口改动清单（汇总）

| 接口 | 动作 | DTO / 入参 | 出参 |
|------|------|-----------|------|
| `DELETE /api/v1/notifications/clear` | 新增 | `?type=activity\|feedback_replied\|report_resolved\|target_reported\|all` | `{ base, affected }` |
| `POST /api/v1/notifications/read-all` | 扩参 | `?type=...` 已支持 6 个值 | 同上 |
| `POST /internal/v1/notifications` | 不变 | `CreateNotificationRequest` | `CreateNotificationResponse` |

### 4.4 错误码（统一 error）

| 场景 | 错误 | code |
|------|------|------|
| type 不在白名单 | `INVALID_ARGUMENT` | 400 + 文案 "invalid notification type" |
| user 未登录 | `UNAUTHENTICATED` | 401 |
| 越权访问别人的通知 | `PERMISSION_DENIED` | 403 |
| type=clear 的 type=all 在生产灰度期间可能禁用 → 后端临时 409 | `FAILED_PRECONDITION` | 灰度期间 |

### 4.5 日志规范（按 CLAUDE.md 接口开发规范 §5）

- `CreateNotification`: 入口 INFO log `user_id/star_id/type/title_len/data_len`；失败 ERROR log（含 stacktrace）
- `ClearByType`: 入口 INFO log；事务失败 ERROR log
- `MarkAllAsRead` (事务内 stats): 失败 ERROR log（影响后续 unrea-count 准确性）

### 4.6 推送触发（沿用现有链路）
`CreateNotification` 成功后异步 goroutine → `uni_push_client.go` → 站内信 + 手机通知栏。**不动**，仅扩类型。

---

## 5. 前端设计

### 5.1 文件清单

| 路径 | 动作 |
|------|------|
| `pages.json` | 注册 `pages/mailbox/index` + `pages/mailbox/detail` 两页 |
| `pages/mailbox/index.vue` | 新建（列表页 / 4 分组可折叠） |
| `pages/mailbox/detail.vue` | 新建（明信片页） |
| `pages/mailbox/components/MailboxGroup.vue` | 新建（单分组列表组件） |
| `pages/mailbox/components/Postcard.vue` | 新建（明信片组件） |
| `pages/mailbox/composables/useMailboxCenter.js` | 新建（4 type 并发拉取 + 单条操作） |
| `store/modules/mailbox.js` | 新建（Vuex itemsByType / unreadByType / mutations） |
| `utils/api.js` | 加 6 个函数（`getNotificationsApi / getUnreadCountApi / markAsReadApi / markAllAsReadApi / deleteNotificationApi / clearNotificationsApi`） |
| `App.vue` | 加 `#ifdef APP-PLUS` 块注册 push receive/click 监听器（详见 §12.3） |

### 5.2 路由注册（CLAUDE.md 强约束）

`pages.json` 改动:
```json
{
  "path": "pages/mailbox/index",
  "style": { "navigationStyle": "custom", "app-plus": { "bounce": "none" } }
},
{
  "path": "pages/mailbox/detail",
  "style": { "navigationStyle": "custom", "app-plus": { "bounce": "none" } }
}
```

### 5.3 Vuex `store/modules/mailbox.js`

```js
// 简化示意
const state = () => ({
  unreadByType: {
    activity: 0,
    feedback_replied: 0,
    report_resolved: 0,
    target_reported: 0,
  },
  totalUnread: 0,
})

const actions = {
  /**
   * 收到 receive 推送时调用,本地同步未读数(payload 自带 unreads_by_type)
   * 见 §12.4
   */
  applyPushPayload({ commit, state, rootState }, payload) {
    if (!payload || !payload.unreads_by_type) return
    commit('REPLACE_UNREAD_BY_TYPE', payload.unreads_by_type)
    commit('SET_TOTAL_UNREAD', payload.total_unread || 0)
    // 若用户已在邮箱页,本地插入新条目(避免用户下次进邮箱才看到)
    if (rootState.mailbox.isInMailboxPage && payload.nid) {
      commit('PREPEND_ITEM', {
        type: payload.type,
        notification: {
          id: payload.nid,
          title: payload.title,
          content: payload.content,
          data: payload.data,
          is_read: false,
          created_at: Date.now()
        }
      })
    }
  },
  /** 用户在列表页 pages/mailbox/index.vue 的 onShow / 下拉刷新时拉一页,顺便对齐红点(stats) */
  async alignFromServerUnread({ commit }) {
    const resp = await getUnreadCountApi()
    commit('REPLACE_UNREAD_BY_TYPE', resp.data.counts)
  },
  /** 单条标已读时,本地减 1（已与后端 UPDATE 同步） */
  decrementOne({ commit }, { type }) {
    commit('DECREMENT_TYPE', type)
  },
}
```
- **入口**: `App.vue#onLaunch` 注册 `plus.push.addEventListener('receive', cb)`，cb 内 `dispatch('mailbox/applyPushPayload', payload)`，**完全不走 HTTP 轮询**。
- **兜底对齐**: 列表页 `pages/mailbox/index.vue` `onShow` 拉一页数据时并发触发 `alignFromServerUnread`，仅此 1 次。
- **不强求对齐**: 列表页 `pages/mailbox/index.vue` `onShow` 时拉一页 `getNotificationsApi`（拉数据本身）时，并发调一次 `alignFromServerUnread` 同步 stats，**仅一次**而非周期。

### 5.4 `utils/api.js` 新增（带注释模板）

> 注释风格与现有 `registerDeviceApi` 一致（块状中文注释 + 分隔行）。`request` 为项目内通用 uni.request 封装，封装函数中。

```js
// ==================== 通知查询(spec §1.3) ====================
// 本节 6 个函数均为本次新增 wrapper。前端原本只在 utils/api.js 暴露了
// registerDeviceApi / unregisterDeviceApi 两个推送设备注册接口,
// 通知本身的 list/unread/markRead/markAllRead/delete/clear 全部需要在
// 收件箱功能落地时补齐(参见 docs/superpowers/specs/2026-07-13-mailbox-inbox-design.md)。
//
// 鉴权:由 gateway AuthMiddleware 强制 JWT,无 token 自动 401,前端无需再校验。
// 响应统一: { code, message, data, base? },data 字段才是真正的 payload。

// getNotificationsApi —— 拉一页通知(用于列表页 onShow 并发 4 个 type / 详情页单补拉)
//
// 参数:
//   type   :必填,通知 type 枚举字符串
//             可选值: 'activity' | 'feedback_replied' | 'report_resolved'
//                    | 'target_reported' | 'like' | 'system'
//             (前 4 个是收件箱主要业务 type,后 2 个仅占位,本期产品不暴露)
//   tab    :可选,二级过滤器(如 like 类的"未读/全部")。收件箱功能本期不传。
//   page   :可选,1-based 页码;默认 1,后端兜底
//   pageSize:可选,默认 20,后端兜底最多 100
//
// 返回:Promise<{ data: { items: Notification[], unreadByType?, total, page, pageSize } }>
//
// 业务流:
//   ① 列表页 pages/mailbox/index.vue 的 onShow → Promise.all(4 type 各拉首页)
//   ② 详情页 pages/mailbox/detail.vue 找不到 store 命中时 → 单补拉 50 条找 nid
//
// 注意:
//   GET 参数必须走查询串(项目约定,见 utils/api.js 现有 GET 用法如
//   /api/v1/social/friends?page=&page_size=);不允许 data:{} 写法。
export function getNotificationsApi(params = {}) {
  const { type, tab = '', page = 1, pageSize = 20 } = params || {}
  const qs = new URLSearchParams({ type, page: String(page), page_size: String(pageSize) })
  if (tab) qs.append('tab', tab)
  return request({ url: `/api/v1/notifications?${qs}`, method: 'GET' })
}

// getUnreadCountApi —— 拉全局未读计数(主路径不调用,仅作为 push 不可达兜底)
//
// 参数:无
//
// 返回:Promise<{ data: { like, system, activity, feedback_replied,
//                        report_resolved, target_reported, total } }>
//
// 业务流:
//   列表页 onShow 拉数据页时,并发调一次对齐 stats;平时零调用(红点靠 uniPush
//   receive 事件 + payload.unreads_by_type 本地增量,见 §12)
export function getUnreadCountApi() {
  return request({ url: '/api/v1/notifications/unread-count', method: 'GET' })
}

// markAsReadApi —— 单条标已读(列表项点击 / 明信片底部 [✓标已读])
//
// 参数:
//   id:必填,notifications.id(整数)
//
// 返回:Promise<{ data: void }>;前端按 resp.code === 0 判断成败
//
// 业务流:
//   ① 列表项点击 → 调用成功后再 navigateTo 详情页
//   ② 明信片页 [✓标已读] → 调用成功后留在页(用户可能再看一眼)
//
// 注意:后端事务内 ① UPDATE notifications SET is_read=TRUE WHERE is_read=FALSE
//                       ② UPDATE notification_stats.<type>_unread_count -= 1
// 后端已幂等(同 id 多次点击不会重复 -1,因为 WHERE 已过滤 is_read=FALSE)
export function markAsReadApi(id) {
  return request({ url: `/api/v1/notifications/${id}/read`, method: 'POST' })
}

// markAllAsReadApi —— 按 type 全标已读(列表页顶部 [+全部已读] 触发 4 次并发)
//
// 参数:
//   type:必填,通知 type 字符串 (同 getNotificationsApi 的 type)
//
// 返回:Promise<{ data: { affected } }>
//
// 业务流:
//   列表页顶部 [+全部已读] → Promise.all(4 个 type 各 1 次) → 本地 store
//   全部 type unread 清 0 + 4 组 items.map(n => ({...n, is_read: true}))
//
// 注意:
//   type 走 URL 查询串(由 backend gateway controller 用 g.Query("type") 提取,
//   见 notification_controller.go:404)。不要写 data: { type },否则 400。
export function markAllAsReadApi(type) {
  return request({ url: `/api/v1/notifications/read-all?type=${encodeURIComponent(type)}`, method: 'POST' })
}

// deleteNotificationApi —— 单条软删(列表项长按 [删除] / 明信片页 [🗑删除])
//
// 参数:
//   id:必填,notifications.id
//
// 返回:Promise<{ data: void }>
//
// 业务流:
//   ① 列表项长按 ActionSheet 第二项 → 本地 store REMOVE_ITEM
//   ② 明信片页 [🗑删除] → 本地 store REMOVE_ITEM + setTimeout 500ms 后
//      uni.navigateBack() 回列表页(让用户看到"删除" toast 再跳)
//
// 注意:后端 is_deleted=TRUE 软删,不真删;统计/红点不受影响(只 decr 标已读数)
export function deleteNotificationApi(id) {
  return request({ url: `/api/v1/notifications/${id}`, method: 'DELETE' })
}

// clearNotificationsApi —— 按 type 软删(本期不直接调用,但留给"按 type 清空"场景)
//
// 参数:
//   type:必填,枚举字符串: activity | feedback_replied | report_resolved
//                          | target_reported | all
//
// 返回:Promise<{ data: { affected } }>
//
// 业务流(本期):
//   列表页 [全部删除] → 仅传 'all' 一键清 4 类 → 本地 store CLEAR_ALL
//
// 注意:本期实现是 1 次 type='all' 调用;若以后加"按 type 清"按钮,直接传对应字符串。
// 后端:DELETE /api/v1/notifications/clear?type=<x> (v1.1 新加接口,见 §4)
//      type 走查询串(gateway controller g.Query("type") 提取,与 read-all 同款)
export function clearNotificationsApi(type = 'all') {
  return request({ url: `/api/v1/notifications/clear?type=${encodeURIComponent(type)}`, method: 'DELETE' })
}
```

**注释规范要点**（沿用 utils/api.js 既有约定）:
- 每组（功能类）函数用 `// ==================== 功能名（spec 章节） ====================` 横线分隔
- 函数上方块状中文注释:`功能名 —— 用途 (触发场景) \n 参数: \n 返回: \n 业务流: \n 注意:`
- 不引入 JSDoc（项目未使用 JSDoc 格式）
- 函数体保持原 `request({ url, method, data })` 三件套
- 复杂字段（如 type 枚举）就地在注释里列字符串列表，不外链到 .d.ts

### 5.5 `pages/mailbox/index.vue` 列表页（Vue 3 `<script setup>`）

```vue
<template>
  <view class="mailbox-list">
    <CustomHeader title="收件箱" :showBack="true" />
    <view class="toolbar">
      <button class="btn-mark-all" @click="onMarkAllRead">[+全部已读]</button>
      <button class="btn-delete-all" @click="onClearAll">[+全部删除]</button>
    </view>

    <scroll-view scroll-y="true" class="list-scroll" @scrolltolower="onScrollLower">
      <MailboxGroup
        v-for="grp in GROUPS" :key="grp.type"
        :groupKey="grp.type"
        :label="grp.label"
        :collapsed="isCollapsed(grp.type)"
        :items="itemsByType[grp.type]"
        :unreadCount="unreadByType[grp.type] || 0"
        @toggle="toggleCollapsed(grp.type)"
        @select="onSelectItem"
        @long-press="onLongPress"
      />
      <view v-if="!hasAny && !loading" class="empty">暂无通知</view>
      <view v-if="loading" class="loading">加载中...</view>
      <view v-if="hasAny && !hasMore" class="no-more">没有更多了</view>
    </scroll-view>
  </view>
</template>

<script setup>
import { computed, onMounted, onShow } from 'vue'
import { useMailboxCenter } from '../composables/useMailboxCenter.js'

const {
  GROUPS, itemsByType, unreadByType,
  loading, hasAny, hasMore,
  loadAll, onScrollLower,
  onMarkAllRead, onClearAll,
  onSelectItem, onLongPress,
  isCollapsed, toggleCollapse,
} = useMailboxCenter()

onShow(() => { loadAll() })
</script>
```

### 5.6 `pages/mailbox/detail.vue` 明信片页（Vue 3 `<script setup>`）

```vue
<template>
  <view class="mailbox-detail">
    <CustomHeader title="明信片" :showBack="true" />
    <view v-if="notification" class="postcard-wrap">
      <Postcard
        :notification="notification"
        @mark-read="onMarkRead"
        @delete="onDeleteOne"
      />
    </view>
    <view v-else class="empty-detail">明信片不存在或已删除</view>
    <!-- 底部固定 toolbar: 单条 [✓标已读] + [🗑删除] -->
    <view v-if="notification" class="postcard-toolbar">
      <button
        v-if="!notification.is_read"
        class="btn-mark-read"
        @click="onMarkRead"
      >[✓ 标已读]</button>
      <button v-else class="btn-mark-read-disabled" disabled>[已读]</button>
      <button class="btn-delete" @click="onDeleteOne">[🗑 删除]</button>
    </view>
  </view>
</template>

<script setup>
import { ref, computed } from 'vue'
import { useStore } from 'vuex'
import { onLoad } from '@dcloudio/uni-app'
import { useMailboxCenter } from '../composables/useMailboxCenter.js'
import { getNotificationsApi } from '@/utils/api.js'

const store = useStore()
const { onMarkRead: mr, onDeleteOne: del } = useMailboxCenter()
const nid = ref(null)
const type = ref(null)

onLoad((options) => {
  nid.value = Number(options.nid)
  type.value = options.type
})

const notification = computed(() => {
  if (!nid.value || !type.value) return null
  // 优先从 store 取（已加载过的条目）
  const item = store.state.mailbox.itemsByType[type.value]?.find(n => n.id === nid.value)
  if (item) return item
  // store 没有则单条拉一次（杀进程后退 push 进来场景）
  loadOne()
  return store.state.mailbox.detailCache || null
})

async function loadOne() {
  const resp = await getNotificationsApi({ type: type.value, page: 1, page_size: 50 })
  const item = (resp.items || []).find(n => n.id === nid.value)
  if (item) store.commit('mailbox/SET_DETAIL_CACHE', item)
}

async function onMarkRead() {
  await mr(nid.value, type.value)
  uni.showToast({ title: '已标已读', icon: 'none' })
  // 留在本页（用户可能想再看一眼），也可选择 setTimeout 后 navigateBack
}

async function onDeleteOne() {
  await del(nid.value, type.value)
  uni.showToast({ title: '已删除', icon: 'none' })
  setTimeout(() => uni.navigateBack(), 500)
}
</script>
```

### 5.7 `useMailboxCenter.js`（组合式 API）

```js
import { computed } from 'vue'
import { useStore } from 'vuex'
import {
  getNotificationsApi, markAsReadApi, markAllAsReadApi,
  deleteNotificationApi, clearNotificationsApi
} from '@/utils/api.js'

const GROUPS = [
  { type: 'activity',         label: '活动通知' },
  { type: 'feedback_replied', label: '反馈回复' },
  { type: 'report_resolved',  label: '举报结果' },
  { type: 'target_reported',  label: '被举报' },
]

export function useMailboxCenter() {
  const store = useStore()

  const itemsByType   = computed(() => store.state.mailbox.itemsByType)
  const unreadByType  = computed(() => store.state.mailbox.unreadByType)
  const loading       = computed(() => store.state.mailbox.loading)
  const hasAny        = computed(() => GROUPS.some(g => (itemsByType.value[g.type] || []).length > 0))
  const hasMore       = computed(() => Object.values(store.state.mailbox.noMoreByType).some(v => !v))

  // 列表页 onShow 时并发 4 个 type 各拉首页
  async function loadAll() {
    store.commit('mailbox/SET_LOADING', true)
    try {
      await Promise.all(GROUPS.map(g =>
        getNotificationsApi({ type: g.type, page: 1, page_size: 20 })
          .then((resp) => {
            store.commit('mailbox/SET_ITEMS', { type: g.type, items: resp.items || [], sortUnreadFirst: true })
            store.commit('mailbox/SET_NO_MORE', { type: g.type, value: (resp.items || []).length < 20 })
            if (resp.unreadByType) store.commit('mailbox/REPLACE_UNREAD_BY_TYPE', resp.unreadByType)
          })
      ))
    } finally {
      store.commit('mailbox/SET_LOADING', false)
    }
  }

  function onScrollLower() {
    const target = GROUPS.find(g => !store.state.mailbox.noMoreByType[g.type])
    if (target) loadMore(target.type)
  }

  async function loadMore(type) {
    const page = Math.floor((itemsByType.value[type].length / 20) + 1)
    const resp = await getNotificationsApi({ type, page, page_size: 20 })
    store.commit('mailbox/APPEND_ITEMS', { type, items: resp.items || [] })
    store.commit('mailbox/SET_NO_MORE', { type, value: (resp.items || []).length < 20 })
  }

  async function onMarkRead(nid, type) {
    await markAsReadApi(nid)
    store.commit('mailbox/UPDATE_ITEM', { type, id: nid, patch: { is_read: true } })
    store.commit('mailbox/DECREMENT_TYPE', type)
    store.commit('mailbox/RESORT_ITEMS', type)  // 已读排后
  }

  async function onMarkAllRead() {
    await Promise.all(GROUPS.map(g => markAllAsReadApi(g.type)))
    store.commit('mailbox/MARK_ALL_READ')
  }

  async function onDeleteOne(nid, type) {
    await deleteNotificationApi(nid)
    store.commit('mailbox/REMOVE_ITEM', { type, id: nid })
  }

  async function onClearAll() {
    const ok = await new Promise((resolve) => {
      uni.showModal({ title: '提示', content: '清空所有通知?', success: (r) => resolve(r.confirm) })
    })
    if (!ok) return
    await clearNotificationsApi('all')
    store.commit('mailbox/CLEAR_ALL')
  }

  function onSelectItem(nid, type) {
    onMarkRead(nid, type)
    uni.navigateTo({ url: `/pages/mailbox/detail?nid=${nid}&type=${type}` })
  }

  function onLongPress(nid, type) {
    uni.showActionSheet({
      itemList: ['标已读', '删除'],
      success: (res) => {
        if (res.tapIndex === 0) onMarkRead(nid, type)
        else if (res.tapIndex === 1) onDeleteOne(nid, type)
      }
    })
  }

  function isCollapsed(type) {
    const saved = uni.getStorageSync('mailbox_collapsed') || {}
    return !!saved[type]
  }

  function toggleCollapse(type) {
    const saved = uni.getStorageSync('mailbox_collapsed') || {}
    saved[type] = !saved[type]
    uni.setStorageSync('mailbox_collapsed', saved)
  }

  return {
    GROUPS,
    itemsByType, unreadByType, loading, hasAny, hasMore,
    loadAll, onScrollLower, loadMore,
    onMarkRead, onMarkAllRead, onDeleteOne, onClearAll,
    onSelectItem, onLongPress,
    isCollapsed, toggleCollapse,
  }
}
```

### 5.8 Vuex `mailbox` module 关键 mutations (摘要)

```js
SET_ITEMS       (state, { type, items, sortUnreadFirst }) {
  const sorted = sortUnreadFirst
    ? [...items].sort((a, b) => (a.is_read === b.is_read) ? (b.created_at - a.created_at) : (a.is_read ? 1 : -1))
    : items
  state.itemsByType[type] = sorted
},
APPEND_ITEMS    (state, { type, items }) { state.itemsByType[type].push(...items) },
UPDATE_ITEM     (state, { type, id, patch }) {
  const arr = state.itemsByType[type]
  const i = arr.findIndex(n => n.id === id)
  if (i >= 0) arr[i] = { ...arr[i], ...patch }
},
REMOVE_ITEM     (state, { type, id }) {
  state.itemsByType[type] = state.itemsByType[type].filter(n => n.id !== id)
},
RESORT_ITEMS    (state, type) {
  state.itemsByType[type].sort((a, b) => (a.is_read === b.is_read) ? (b.created_at - a.created_at) : (a.is_read ? 1 : -1))
},
SET_NO_MORE     (state, { type, value }) { state.noMoreByType[type] = value },
DECREMENT_TYPE  (state, type) { state.unreadByType[type] = Math.max(0, (state.unreadByType[type] || 0) - 1) },
REPLACE_UNREAD_BY_TYPE (state, byType) { state.unreadByType = { ...state.unreadByType, ...byType } },
MARK_ALL_READ   (state) {
  state.unreadByType = { activity: 0, feedback_replied: 0, report_resolved: 0, target_reported: 0 }
  Object.keys(state.itemsByType).forEach(t => {
    state.itemsByType[t] = state.itemsByType[t].map(n => ({ ...n, is_read: true }))
  })
},
CLEAR_ALL       (state) {
  GROUPS.forEach(g => state.itemsByType[g.type] = [])
  state.unreadByType = {}
},
SET_DETAIL_CACHE (state, item) { state.detailCache = item }
```

### 5.9 样式（CSS / SCSS）

```scss
// pages/mailbox/index.vue 列表页
.mailbox-list {
  display: flex; flex-direction: column; height: 100vh; background: #f7f8fa;
  .toolbar {
    display: flex; justify-content: space-between; padding: 16rpx 24rpx;
    background: #fff; border-bottom: 1rpx solid #eee;
    .btn-mark-all, .btn-delete-all {
      font-size: 26rpx; padding: 12rpx 24rpx; border-radius: 32rpx;
      background: #5C40FF; color: #fff;
    }
    .btn-delete-all { background: #f5222d; }
  }
  .list-scroll { flex: 1; padding: 24rpx; }
  .empty, .loading, .no-more {
    text-align: center; color: #999; padding: 48rpx 0; font-size: 26rpx;
  }
}

// pages/mailbox/detail.vue 明信片页
.mailbox-detail {
  display: flex; flex-direction: column; height: 100vh; background: #f7f8fa;
  .postcard-wrap { flex: 1; padding: 24rpx; padding-bottom: 140rpx; }
  .empty-detail { padding: 80rpx; text-align: center; color: #999; }
  .postcard-toolbar {
    position: fixed; left: 0; right: 0; bottom: 0; height: 120rpx;
    display: flex; gap: 16rpx; padding: 16rpx 24rpx;
    background: #fff; border-top: 1rpx solid #eee;
    .btn-mark-read { flex: 1; background: #5C40FF; color: #fff; border-radius: 16rpx; font-size: 28rpx; }
    .btn-mark-read-disabled { flex: 1; background: #f0f0f0; color: #999; border-radius: 16rpx; font-size: 28rpx; }
    .btn-delete { flex: 1; background: #f5222d; color: #fff; border-radius: 16rpx; font-size: 28rpx; }
  }
}
```

### 5.10 CLAUDE.md 合规清单

- [x] Vue 3 组合式 API（`<script setup>`），不复用 `myReports/myFeedbacks` 的 Options API
- [x] 接口走 `utils/api.js`（不裸 `uni.request`）
- [x] 跨页状态走 Vuex (`mailbox` module) + 明信片页 onLoad 取 `nid/type` 从 store 取条目
- [x] 新页已注册（`index` / `detail` 两页路由）
- [x] `profile.vue` 服务与工具 section 加 📬 收件箱 service-button（参考同 section "新手指引/反馈" 等的视觉规范）
- [x] 不动任何 `setInterval / setTimeout` 轮询
- [x] 不动 `unpackage/dist/`
- [x] 移动端优先：list 页全宽 + tap push 到 detail 页全宽 + 列表页底部 [全部已读 / 全部删除] / 明信片页底部 [标已读 / 删除] 两套操作按钮
- [x] 列表操作 = 明信片操作覆盖: 4 个操作任何页面都能完成
- [x] 不长列表（明信片内容由后端控制长度）

---

## 6. 布局与可达性

### 6.1 布局策略（v1.2 修订：手机竖屏为主，放弃 master-detail）

经用户反馈"竖屏分栏两边都挤"，本期改为**两页路由**：

| 场景 | 页面 | 布局 |
|------|------|------|
| 进入收件箱 | `pages/mailbox/index.vue` | 全宽列表（4 分组可折叠），底部 [全部已读 / 全部删除] |
| 点列表项 | `pages/mailbox/detail.vue?nid=&type=` | 全宽明信片，底部 [标已读 / 删除] |

**为什么不做响应式分栏**：手机竖屏 50/50 两边都很挤（iPhone 默认宽 750rpx 远小于 pad 1024+）；iPad / 横屏以后真要做分栏，**Stage 2** 走 `manifest.json` 的 `transformPx` 自适应即可（YAGNI）。

### 6.2 横竖屏切换

- 两页路由不受横竖屏影响（始终全宽）
- `onWindowResize` 无需监听（不再用 `useMailboxLayout`）

### 6.3 可达性
- 列表项 `aria-label`：title + 时间 + 未读状态
- 长按 0.5s 触发 ActionSheet（ios 长按手势）
- 单色 + 图标双重提示未读（`●` 红点 + "未读" 字样）
- 屏幕阅读器读 title + 内容

---

## 7. 错误处理与边界

### 7.1 网络错
- 4 个 type 并发请求：任一失败 → 该 group 顶部显示 `[重新加载]`（独立 retry）
- 500/网络断：`uni.showToast` "网络失败" + 内联 error 状态

### 7.2 未登录
- `pages/mailbox/index` 入口：守卫 `if(!token) navigateBack()`
- profile.vue 服务与工具 section 加的 📬 按钮：v-if="userStore.token"（未登录用户看不到入口,与 profile 页面其他按钮一致）
- profile.vue `onShow` 触发 `dispatch('mailbox/refreshUnread')`（在 store 里再判一次 token,避免未登录调 API 401）
- profile.vue 红点 badge 显示值（v1.2.10 你确认）= 收件箱 4 类未读之和,**排除 like 和 system**:

```js
// store/modules/mailbox.js
getters: {
  // 收件箱 badge 用 —— 只算 4 类,不含 like / system
  inboxUnreadOnly(state) {
    const { activity = 0, feedback_replied = 0,
            report_resolved = 0, target_reported = 0 } = state.unreadByType
    return activity + feedback_replied + report_resolved + target_reported
  }
}

// pages/profile/profile.vue 引用
// import { useStore } from 'vuex'
const store = useStore()
const inboxUnread = computed(() => store.getters['mailbox/inboxUnreadOnly'])
// 模板: <text v-if="inboxUnread > 0" class="mailbox-badge">{{ inboxUnread }}</text>
```

- 边界: 当 4 类全 0 时 badge 隐藏(v-if);`totalUnread`(含 like)仅用于 inbox 内部 4 类分组展开角标,**不再用于 profile.vue 红点**

### 7.3 空态
- 全部 4 group 都为空 → 显示"暂无通知"大空态（带"去看看发现" 二级按钮跳广场）

### 7.4 越权
- 后端 `WHERE user_id=$1` 强制（已存在），前端不能传别人的 id

### 7.5 并发 / 节流（v1.2.6 加入节流说明）
- `markRead` 同一 id 多次点击: 后端 `UPDATE ... WHERE is_read=false` 自动幂等
- `clearAll` 4 type 并发: 事务独立, 各自累加 stats 清零
- **uniPush 推送节流三道防线**（详见 §12.7）:后端 **60s / (user,type)** 滑窗 + App **10s** 同 type 去抖 + Vuex 幂等，覆盖"管理员批量处理 → 用户手机狂震"的灾难场景

### 7.6 PG 序列同步（CLAUDE.md 强约束）
- 本设计**无 INSERT 手动指定 id 的 SQL 脚本**，均为 ALTER TABLE。**不触发序列同步规则**。
- 若手写测试 SQL：`SELECT setval('notifications_id_seq', (SELECT MAX(id) FROM notifications))` 写在文末。

### 7.7 边界
- `content` 长度上限 500 (`notification.content`)，`data` 长度 4KB
- `feedback_replied.content` 如果 `reply_content > 500` → 截断到 497 字符 + "..."
- `report_resolved.content` 如果 `resolution_note > 500` → 截断
- 明信片显示时: 全文已塞进 content, 直接渲染, 无超长问题

---

## 8. 测试计划

### 8.1 后端单测 (按 CLAUDE.md 接口开发规范 §9)

`backend/services/notificationService/service/notification_service_test.go`:
- `TestCreateNotification_FeedbackReplied` —— 验 type 白名单（activity/feedback_replied/report_resolved/target_reported 4 类），stats 累加对应列
- `TestCreateNotification_TargetReportedTypeRejected` —— 验未授权 / 错 type 报错
- `TestClearByType_PartialAll` —— 验 type=all 真清 4 类，type=single 限一类

`backend/services/moderationService/service/moderation_service_test.go` (新增):
- `TestFeedbackReplied_TriggersNotification` —— mock `notificationClient.CreateNotification` 收到 1 次调用，参数对得上（type=feedback_replied, content=reply_content 全文）
- `TestReportResolved_TriggersNotification` —— type=report_resolved, content=resolution_note
- `TestTargetReported_TriggersNotification` —— 只在 action ∈ {warn/takedown/ban} 时发，dismiss 不发

`backend/services/activityService/service/activity_emitter_test.go` (新增):
- `TestActivityMessage_TriggersActivityNotification` —— 别人在你活动下留言 → mock notificationClient.CreateNotification 收到 1 次 type=activity
- `TestActivityStartEnd_TriggersActivityNotification` —— 活动开始触发 → 收到 N 次 type=activity（N=参与该活动的用户数）

### 8.2 后端集成测试 (可选 / Stage 2)
- `cmd/integration/mailbox_test.go` —— 拉真 DB + 真 notification service, 事务回滚
- (本次 MVP 暂不强制, mock 已能覆盖)

### 8.3 前端手验清单（按 `share-impl-test-policy.md` 规则不写 vitest）

手验 case:
- [ ] 1. 登录账号 → 进入 `pages/profile/profile.vue` → "服务与工具" section 看到 📬 收件箱 按钮 + 红点 N badge
- [ ] 2. 点 📬 进入邮箱 → 4 分组 + 未读优先排前
- [ ] 3. 点列表项 → 右明信片同步，列表项 `● → ○`，红点 -1
- [ ] 4. 点明信片 `[✓标已读]` → 同上
- [ ] 5. 点 `全部已读` → 4 组全 `○`，红点 0
- [ ] 6. 点明信片 `[🗑删除]` → 单条消失
- [ ] 7. 点 `全部删除` → 4 组清空，出现"暂无通知"空态
- [ ] 8. 长按列表项 → 弹出 ActionSheet `[✓ / 🗑]`
- [ ] 9. 折叠分组 → 高度收起；`uni.setStorage` 记住
- [ ] 10. 退出重进 → 折叠状态保持
- [ ] 11. 列表页点列表项 → 跳详情页 + 该项标已读 → `navigateBack` 回到列表页 → 滚动位置不变
- [ ] 12. 详情页点 `[🗑 删除]` → 删除完成 → 500ms 后 `navigateBack` → 列表页该项消失
- [ ] 12.1. 横竖屏切换 → 两页路由不受影响（不重排，单页始终全宽）
- [ ] **13**. 模拟后端 emit notification（管理员回复反馈）→ **App 在前台** → 红点 +1 + 邮箱页内新条目实时插入（**网络面板观察 0 个 HTTP 请求**）
- [ ] **14**. App **后台** 时收到推送 → 系统通知栏弹通知 → 点通知栏 → 跳 `pages/mailbox/index?focus=<type>&nid=<id>`（列表页 onLoad 时定位到该 nid 项并自动显示其明信片）
- [ ] **15**. 关闭 App 网络 → 禁用 push → 用户进入列表页 → 列表页 `onShow` 拉一页 `getNotificationsApi` → 列表 + 红点对齐（**仅这一次**，不是周期）
- [ ] **16**. 全局搜索 `setInterval / setTimeout` → 仅命中既有业务代码（动画 / 计时器），**邮件模块 0 命中**
- [ ] **17**. 后端节流 + 聚合验证：手动在 30s 内连续触发 5 条 `feedback_replied` 通知（mock moderationService）→ 观察日志：第 1 条 mode=concrete 后 4 条 mode=summary;**summary 推送 title 应递增** "您有 2 条新反馈回复" → "您有 3 条..." → "您有 4 条..." → "您有 5 条新反馈回复"（v1.2.8 验证）;用户手机 5 次弹出，每次 title 数字递增;App 内 `unreads_by_type` 等于全量累加,`feedback_replied` 总数 +5
- [ ] **18**. App 端 10s 去抖：模拟 2 条 `feedback_replied` 推送 100ms 内先后进入 receive → App 只 commit 1 次 Vuex REPLACE（观察 Vue devtools）
- [ ] **19**. Vuex 幂等：手动 dispatch 2 次相同 nid 的 PREPEND_ITEM → 第 2 次早返回，列表 nid 不重复
- [ ] **20**. count 边界：手动清空 RateLimiter.pending 灌入 50 条 feedback_replied → 应见到 50 条 summary push,count 从 1 到 50 递增（验证 count 无上限泄漏）

### 8.4 Postman / curl 脚本
附在 §9 文档根。MVP 不强制交付。

---

## 9. 文档 / 运维

### 9.1 Swagger 注释
`backend/gateway/router/router.go` 已有 8 个通知接口的 swagger 注释路径，**新增 `DELETE /api/v1/notifications/clear` 同步加注释**。

### 9.2 README / Changelog
- 仓库 `README.md` 不动（产品文档）
- 仓库 changelog 由用户决定是否更新

### 9.3 数据库迁移文件命名
- `backend/migrations/2026XXXX_add_mailbox_unread_counts.sql`
- 提交: `git mv` 旧 migration 文件 + 新增, 单 commit `feat: 邮箱聚合收件箱 - notification_stats 加 3 列 unread 计数`

### 9.4 部署
详见 §11。

---

## 10. 目录变更

### 10.1 新增文件
> 仅列全新创建的文件；已有文件的修改在 §10.2。

```
frontend/
  pages/mailbox/
    index.vue                                  (新,列表页)
    detail.vue                                 (新,明信片页)
    components/
      MailboxGroup.vue                         (新)
      Postcard.vue                             (新)
    composables/
      useMailboxCenter.js                      (新)
  store/modules/
    mailbox.js                                 (新)

backend/
  migrations/
    2026XXXX_add_mailbox_unread_counts.sql     (新)
  services/notificationService/service/notification_service_test.go (新增 ClearByType 用例)
  services/moderationService/service/moderation_service_test.go (新增 3 emitter 用例)
  services/activityService/service/activity_emitter_test.go (新增 2 emitter 用例)
```

### 10.2 修改文件
> 现有文件的 diff；含 utils/api.js 的 6 个新函数。

```
frontend/
  pages.json                                   (注册 mailbox/index + mailbox/detail)
  App.vue                                      (#ifdef APP-PLUS 加 push receive/click 监听)
  pages/profile/profile.vue                    (v1.2.9 在 <!-- 服务与工具 --> section 加 📬 收件箱 service-button + 红点 badge + navigateTo + onShow 刷新 unread)
  utils/api.js                                 【6 新函数】getNotificationsApi / getUnreadCountApi / markAsReadApi / markAllAsReadApi / deleteNotificationApi / clearNotificationsApi

backend/
  proto/notification.proto                     (新增 ClearByType RPC + UnreadCount 3 列字段号 5/6/7)
  services/notificationService/
    repository/notification_repository.go       (新增 ClearByType)
    repository/notification_stats_repository.go(改通用 type 列名)
    service/notification_service.go            (扩 allowedTypes map 3 个新 key + ClearByType 业务方法 + triggerPush 内注入 unreads_by_type / total_unread 进 data map,见 §12.2 + 注入 §12.7 RateLimiter + v1.2.8 count 聚合 title 生成)
  pkg/push/uni_push_client.go                  (新增 RateLimiter 结构 + Allow() + windowMs + pending map + sentMode map + TypeChinese();Payload 结构不变)
  gateway/router/router.go                     (注册 DELETE /api/v1/notifications/clear)
  gateway/controller/notification_controller.go(ClearByType HTTP handler)
  services/moderationService/service/
    feedback_service.go                        (新 emitter: type=feedback_replied, content=reply_content)
    report_service.go                          (新 emitter: type=report_resolved, content=resolution_note)
    target_status_service.go                   (新 emitter: type=target_reported 仅 warn/takedown/ban)
  services/activityService/service/
    activity_message_service.go                (新 emitter: type=activity, 留言下发触发)
    activity_service.go                        (新 emitter: type=activity, 活动开始/结束触发)
```

### 10.3 不动文件
- `frontend/pages/profile/myReports.vue`
- `frontend/pages/profile/myFeedbacks.vue`

> 理由: 避免无关改动,遵循 CLAUDE.md 的"一个 commit 只做一件事"原则；这些文件已无下游引用，保留不影响新功能。

---

## 11. 部署与回滚

### 11.1 部署顺序
1. **数据库 migration**: 先 PG alter `notification_stats` 加 3 列（幂等 `IF NOT EXISTS`，重复执行无副作用）
2. **后端服务更新**:
   - `notificationService` 重启（迁移 + ClearByType RPC + 仓库改动）
   - `moderationService` 重启（3 处 emitter）
   - `activityService` 重启（1-2 处 emitter）
   - `gateway` 重启（路由注册 ClearByType）
3. **App 端**: 热更新 / 强制更新都可（无 schema breaking change）

### 11.2 灰度
- MVP 不做灰度（CLAUDE.md MVP 先行原则），全量上线
- 新接口 `DELETE /clear` 全量开放；若有线上问题，紧急禁用 router 注册（1 行 + 重启 gateway）

### 11.3 回滚
| 故障 | 回滚步骤 |
|------|---------|
| emitter 误发 | `moderationService` 撤回本次 commit 即可；同时 PG `DELETE FROM notifications WHERE type IN (...) AND created_at > '故障时间'` |
| `notification_stats` 3 列已上 | migration 加 `IF NOT EXISTS` 即可；不回退（数据无副作用）|
| ClearByType 误用 | 临时移除 router 路径（注释 + 重启） |

### 11.4 监控
- 推送数：维持现状，uniPush 通道不动
- 通知表写入速率：已有 prometheus on `notifRepo.Create`；如需要写 release notes 给运维

---

## 12. 实时通知机制（uniPush receive 驱动）

> 本节替代原"实时推送 / 广场 onShow 轮询"反例 —— 我们在移动端有更好的办法。

### 12.1 实现思路

- **后端通知写入即推送**：项目已接 `uni_push_client.go`，`CreateNotification` 成功时异步 emit payload 到 uniPush 通道。
- **App 端 `App.vue#onLaunch` 注册 `plus.push.addEventListener('receive', cb)`**：app 在前台时，uniPush 也走 receive 回调（不走通知栏）→ App 直接拿到 payload。
- **payload 已带 `unreads_by_type` 增量**：后端推送时把"按 type 的增量未读数"塞进 payload；App 拿到直接 update Vuex，**不发 HTTP 请求 / 无需轮询**。
- **不依赖定时器 / onShow 轮询**。事件驱动：① 后端 INSERT notification ② 推送 emit ③ App receive 回调 ④ Vuex commit。

### 12.2 后端推送 payload 字段契约

> ⚠️ **自审 v1.2.4 校正**：`uni_push_client.go:29` 的 `Payload.Data` 是 `map[string]interface{}`（JSON 对象），不是 JSON 字符串。
> App 端读 `msg.payload.data.notification_id` 等字段，不是 `msg.payload.nid`。
> 现有 `notification_service.go:211` 的 `triggerPush` 把 `notification_id / type / star_id` + 业务 `n.Data` JSON 反序列化后塞进 `data` map。
> 我们**新增** key `unreads_by_type` + `total_unread` 进 data map,语义零变化。

`backend/pkg/push/uni_push_client.go` 推送时 payload 整体结构:

```json
{
  "cids": ["cid-1", "cid-2"],
  "title": "您的反馈已处理",           // = notifications.title
  "content": "完整回复全文...",          // = notifications.content
  "request_id": "1700000000000_abcd",
  "data": {                          // map[string]interface{}, App 端核心读取
    "notification_id": 12345,       // = notifications.id (现有字段)
    "type": "feedback_replied",     // = notifications.type (现有字段)
    "star_id": 1,                   // = notifications.star_id (现有字段)
    "feedback_id": 1,               // = notifications.data.feedback_id (现有字段,来自业务 emitter)
    "category_code": "login",       // = notifications.data.category_code (现有字段)
    "original_title": "登录失败",     // = notifications.data.original_title (现有字段)
    "unreads_by_type": {            // 🆕 本期新增,APP 端本地 +1 不查 HTTP
      "activity": 8,
      "feedback_replied": 3,
      "report_resolved": 5,
      "target_reported": 2
    },
    "total_unread": 18              // 🆕 本期新增,等于 Σ unreads_by_type
  }
}
```

**后端组装时机**（在 `triggerPush` 内、`Send` 前）:
```go
// notification_service.go:175 triggerPush 内追加
stats, err := s.statsRepo.Get(cctx, n.UserID, n.StarID)  // stats 含 6 类 unread count
if err == nil {
    data["unreads_by_type"] = map[string]int{
        "like":              stats.LikeUnreadCount,
        "system":            stats.SystemUnreadCount,
        "activity":          stats.ActivityUnreadCount,
        "feedback_replied":  stats.FeedbackRepliedUnreadCount,
        "report_resolved":   stats.ReportResolvedUnreadCount,
        "target_reported":   stats.TargetReportedUnreadCount,
    }
    data["total_unread"] = stats.TotalUnreadCount
}
```

**为什么 user_id 不在 data 里**：`cids` 字段决定了推送谁；`data` 只放 App 端跳转 / 红点 / 详情展示需要的字段。

### 12.3 App.vue 初始化（`#ifdef APP-PLUS`）

```js
// #ifdef APP-PLUS
import { registerDeviceApi } from '@/utils/api.js'
import store from '@/store/index.js'

export default {
  onLaunch() {
    // 1. 拿 cid 上报
    uni.getPushClientId({
      success: (res) => {
        const platform = plus.os.name === 'iOS' ? 'ios'
                       : plus.os.name === 'Android' ? 'android' : 'harmony'
        registerDeviceApi({
          cid: res.cid, platform,
          appVersion: plus.runtime.version,
          deviceModel: plus.device.model
        })
      }
    })

    // 2. 注册 receive 监听器（前台 + 后台都触发）
    // msg.payload 是 uniCloud 推过来的整个 payload 字符串 (JSON),
    // 真正的业务字段都在 envelope.data 嵌套对象里 (见 §12.2)。
    // 注意:Vuex action 需要 title/content 用于 PREPEND_ITEM 显示新条目,
    //      这些字段在 envelope 顶层,所以打包 { data, title, content } 一起传。
    plus.push.addEventListener('receive', (msg) => {
      try {
        const envelope = JSON.parse(msg.payload || '{}')
        const data = envelope.data || {}
        store.dispatch('mailbox/applyPushPayload', {
          data,                                       // 内层业务字段(含 unreads_by_type / notification_id)
          title: envelope.title || '',               // 外层 title
          content: envelope.content || ''            // 外层 content
        })
      } catch (e) {
        console.error('[mailbox] receive payload parse failed', e)
      }
    })

    // 3. 注册 click 监听器（用户点通知栏条目时跳转邮箱）
    plus.push.addEventListener('click', (msg) => {
      try {
        const envelope = JSON.parse(msg.payload || '{}')
        const data = envelope.data || {}
        uni.navigateTo({
          url: `/pages/mailbox/index?focus=${data.type || ''}&nid=${data.notification_id || ''}`
        })
      } catch (e) {}
    })
  }
}
// #endif
```

> **关键自审点**(v1.2.4):`data` 必须从外层 envelope 里解,不能直接拿 envelope 当 data 用。原本(v1.2.3 前)的"applyPushPayload(payload)"写法会让 action 收到的永远是 `{cids, title, content, data, ...}` 外层,内层 `unreads_by_type` 永远拿不到。

### 12.4 Vuex `mailbox/applyPushPayload` action

```js
// store/modules/mailbox.js
//
// 收到 receive 推送时调用,本地同步未读数
//
// 参数 data = App.vue 解出的 envelope.data (见 §12.3),即:
//   {
//     notification_id, type, star_id,
//     feedback_id/category_code/original_title ... (业务字段),
//     unreads_by_type: { activity: 8, feedback_replied: 3, ... },
//     total_unread: 18
//   }
actions: {
  applyPushPayload({ commit, rootState }, { data, title = '', content = '' }) {
    if (!data || !data.unreads_by_type) return  // 不是通知类推送(可能 cids/系统消息)直接忽略

    // 1. 直接用 server 端投递的权威未读数覆盖本地(避免本地累计漂移)
    commit('REPLACE_UNREAD_BY_TYPE', data.unreads_by_type)
    commit('SET_TOTAL_UNREAD', data.total_unread || 0)

    // 2. 若用户在邮箱页,本地插入新条目(否则下次进邮箱才能看到)
    if (rootState.mailbox.isInMailboxPage && data.notification_id && data.type) {
      commit('PREPEND_ITEM', {
        type: data.type,
        notification: {
          id: data.notification_id,
          title: title || '',
          content: content || '',
          data: JSON.stringify(data),         // 业务字段 JSON 字符串
          is_read: false,
          created_at: Date.now()
        }
      })
    }
  }
}
```

> ✅ 参数从 envelope 改为 `{ data, title, content }` 由 App.vue 解 envelope 后打包传入。

### 12.5 边界场景

| 场景 | 行为 |
|------|------|
| 用户**禁用**了所有 push 通道（iOS 设置 / Android 自启动管理） | App 不触发 receive；用户进入邮箱页时拉一页 `GET /api/v1/notifications?type=...` 自然对齐（顺带把红点刷新） |
| App **后台** 时收到推送 | 系统通知栏显示；用户**点通知栏** → `click` 监听器 → 跳 `pages/mailbox/index?focus=type&nid=...`，列表页 onLoad 命中焦点项 → 自动 `navigateTo` 明信片页 |
| App **前台** 时收到推送 | 不弹系统通知栏（uniPush 默认），触发 receive 回调 → Vuex 更新 → 红点 +1 / 邮箱页若有此 type 在展示 → 实时插入 |
| App **杀进程** 后被推送唤醒 | 启动时 `App.vue#onLaunch` 触发 → 注册 receive + 拉一次 cid → 新推送按 receive 处理 |
| **多设备登录** | 每设备独立 cid，各自 receive；本设计按设备独立维护未读，最后一端以最后一次 receive 为准（写在 §12 老反例撤回说明里） |
| payload 解析失败 | `applyPushPayload` 内已 catch, 不影响后续推送 |

### 12.6 不在本期范围

- ❌ 邮件发送 / 真实 SMTP（"邮箱"语义是站内信）
- ❌ Tab 切换（已切到分组模式）
- ❌ 折叠/展开 明信片本身（明信片永远全开）
- ❌ 通知撤回 / 归档按钮
- ❌ 详情页跳转 (绕过 myReports/myFeedbacks/任何详情子页)
- ❌ WebSocket / SSE / 自建长连接 —— uniPush 已提供事件通道，本期不引新通道
- ❌ 推送通道替代方案调研（个推/HMS/miPush/oppoPush/vivoPush 都在 uniPush 后端，本设计透明）
- ❌ 定时器轮询 / `setInterval` / `setTimeout` 任何形式的"周期性请求"
- ❌ 跨设备未读数强同步（先按设备独立，最终一致性即可）

### 12.7 推送节流三道防线（v1.2.6 新增）

**问题场景**：管理员一次性处理 5 条举报 → 5 条 `CreateNotification` → 5 个 user_device 推送 → 用户手机**5 次**系统通知栏弹出 + 5 次震动 + 5 次 App receive 回调。这是灾难级 UX。

**目标**：
1. 手机通知栏**最多 1 次**系统提示（合并的多条用 summary 文案）
2. 红点始终精确（5 条全 1 +5）
3. 邮箱列表全（inbox 页 onShow 拉数据时仍是 5 条）
4. 零额外 HTTP / 零定时器

#### 第一道：后端推送合并（pkg/push 层）

文件: `backend/pkg/push/uni_push_client.go` 增 `RateLimiter` 结构（v1.2.8 加入 count 聚合）。

```go
// RateLimiter 节流器,key = "user_id:star_id:type"。
// 三个状态字段:
//   lastSent: key → lastSentUnixMilli         (窗口判定)
//   pending:  key → 该 key 本窗口累计         (聚合计数)
//   sentMode: key → 最近一次 Send 的模式      (concrete / summary)
//
// windowMs 默认 60000 (60s, 见 §12.7 调优日志)。
type RateLimiter struct {
    mu       sync.Mutex
    lastSent map[string]int64
    pending  map[string]int
    sentMode map[string]string
    windowMs int64
}

// Allow 判定本次推送应走的模式:
//   - key 首次出现 / 窗口已过 → mode=concrete, count=1, lastSent 重置
//   - key 在窗口内 → mode=summary, pending[key]++, count=pending[key]
func (r *RateLimiter) Allow(key string) (mode string, count int) {
    r.mu.Lock()
    defer r.mu.Unlock()
    now := time.Now().UnixMilli()
    last, ok := r.lastSent[key]
    if !ok || now-last >= r.windowMs {
        r.lastSent[key] = now
        r.pending[key] = 1
        r.sentMode[key] = "concrete"
        return "concrete", 1
    }
    r.pending[key]++
    r.sentMode[key] = "summary"
    return "summary", r.pending[key]
}

// TypeChinese 把 notification.type 映射到中文标签,summary title 用。
func TypeChinese(t string) string {
    switch t {
    case "activity":          return "活动通知"
    case "feedback_replied":  return "反馈回复"
    case "report_resolved":   return "举报结果"
    case "target_reported":   return "被举报"
    case "like":              return "点赞消息"
    case "system":            return "系统消息"
    default:                  return "通知"
    }
}
```

`notification_service.go:175 triggerPush` 内改造:
```go
key := fmt.Sprintf("%d:%d:%s", n.UserID, n.StarID, n.Type)
mode, count := s.rateLimiter.Allow(key)

title, content := n.Title, n.Content
if mode == "summary" {
    title = fmt.Sprintf("您有 %d 条新%s", count, push.TypeChinese(n.Type))
    content = "点击查看收件箱"
}

// data map 内 unreads_by_type/total_unread 仍真塞(§12.2 既有逻辑),summary 也带。
// summary 不塞 notification_id,App 端识别不到 nid 不做 PREPEND_ITEM。
```

**聚合展示示例**（管理员 5s 内批处理 5 条 feedback_replied，60s 窗口内）:
- t=0s: 模式=concrete, count=1, push `title="您的反馈已处理: 登录失败"`, `content="完整回复..."`
- t=5s: 模式=summary, count=2, push `title="您有 2 条新反馈回复"`, `content="点击查看收件箱"`
- t=15s: 模式=summary, count=3, push `title="您有 3 条新反馈回复"`, `content="点击查看收件箱"`
- t=30s: 模式=summary, count=4, push `title="您有 4 条新反馈回复"`, `content="点击查看收件箱"`
- t=50s: 模式=summary, count=5, push `title="您有 5 条新反馈回复"`, `content="点击查看收件箱"`
- t=60s: 窗口结束;next push (e.g. t=70s) 重新走 concrete 模式, count 重置 1

**Vuex 一致性**：5 次 push 都触发 App receive,每次都 REPLACE_UNREAD_BY_TYPE (idempotent,same server 值)。
未读条目进 inbox 页 onShow 时一并补全（onShow 一次拉 4 type 一页），用户在 inbox 内可见全部 5 条。

#### 第二道：App receive 去抖（App.vue）

`plus.push.addEventListener('receive', cb)` 内追加 10s 滑窗:
```js
const recentByType = {}  // { feedback_replied: 1700000000000, ... }
const DEBOUNCE_MS = 10000  // v1.2.6 调优:原 5s 偏短,改 10s 留足 buffer

plus.push.addEventListener('receive', (msg) => {
  try {
    const envelope = JSON.parse(msg.payload || '{}')
    const data = envelope.data || {}
    const t = data.type
    const now = Date.now()
    // 防抖:同 type 10s 内已 dispatch 跳过 (re-render 收敛)
    if (t && recentByType[t] && now - recentByType[t] < DEBOUNCE_MS) {
      return
    }
    if (t) recentByType[t] = now
    store.dispatch('mailbox/applyPushPayload', {
      data, title: envelope.title || '', content: envelope.content || ''
    })
  } catch (e) {}
})
```

summary push (没 `notification_id` 或没 `type`) 的 `applyPushPayload` 仍执行:更新 `unreads_by_type` + `total_unread`,**不**触发 PREPEND_ITEM (§12.4 action 内已判断 `data.notification_id && data.type`)。

#### 第三道：Vuex 幂等性保证

```js
// mutations
PREPEND_ITEM(state, { type, notification }) {
  const list = state.itemsByType[type] || []
  // 1) 防止同一 notification 被重复 prepend (uniPush 重发 / 网络重试)
  if (list.some(n => n.id === notification.id)) return
  // 2) 防止同 type 多条同时 prepend 时排序混乱:未读排前
  list.unshift(notification)
  list.sort((a, b) => (a.is_read === b.is_read) ? (b.created_at - a.created_at) : (a.is_read ? 1 : -1))
  state.itemsByType[type] = list
}

REPLACE_UNREAD_BY_TYPE(state, byType) {
  // server 端权威覆盖,不累加(防止 N 次 push 把一个 +1 算成 +N)
  state.unreadByType = { ...state.unreadByType, ...byType }
}
```

#### 节流参数可配化

`UniPushClient` 构造时通过外部 `pkg/config` 注入:
```yaml
push:
  rate_limit_window_ms: 60000       # (user, type) 节流窗口,默认 60s (v1.2.6 调优)
  app_debounce_ms: 10000            # App 端 receive 去抖,默认 10s (v1.2.6 调优)
```

V1 用硬编码也可,MVP 不强制配置化。

#### 边界场景(60s / 10s 配置)

| 场景 | 节流表现 |
|------|---------|
| 管理员 1 条 1 条处理(每条相隔 > 60s) | 全部 concrete push,无节流 |
| 管理员 1 次批量 5 条(30s 内完成) | 第 1 条 concrete,第 2-5 条 summary title 递增:**"您有 2 条新反馈回复" → 3 → 4 → 5**;手机 5 次弹出,每次 title 增长,用户能直观看到量级 |
| 管理员 5 分钟内分批处理 10 条 (每批思考 30s) | 10 条全部独立 concrete,因为间隔 > 60s 始终开启窗口 |
| App 在前台时 App receive 第 6 条 summary (10s 内多次) | App 内 `unreads_by_type` 准确更新 (REPLACE 幂等),仅第 1 次 commit PREPEND_ITEM;后续 receive 因为 10s 去抖被拦掉 |
| App 在后台时 receive 6 条 summary | 手机通知栏弹 5 次（concrete 1 + summary 4 title 递增）;App 进前台时 redDot 仍准确 |
| 用户 60s 后又来 1 条 | 上次 concrete 距今 > 60s,自动恢复 concrete 模式 (`pending[key]=1`,`sentMode` 重置) |
| 节流窗口内登出再登入 (换 cid) | 新 cid 不在 RateLimiter 历史里 → 视为新 key → 第一次 concrete (节流 key 是 user_id 所以换 cid 不影响) |
| **突增边界 case**:admin 用了 60s 节流期间登录另一台设备 | RateLimiter key = user:star:type 是 user 维度,不依赖 cid,所以换设备不会"skip" → 安全 |
| **节流模式可用 toggle 按钮**(Stage 2) | V1 不实现,用户粒度"勿扰模式"留给 Stage 2 |

> **"兜底一次性 HTTP" 说明**：用户在**列表页 `pages/mailbox/index.vue` `onShow`** 时拉 4 个 type 一页（这是数据本身的拉取，不是"轮询红点"）。**红点更新通道仍是 uniPush receive**，与本页拉取互不干涉；用户在 push 不可达环境进邮箱时，自然对齐。

---

## 13. 关键决策表

| 决策 | 选项 A | 选项 B (已选) | 原因 |
|------|--------|--------------|------|
| 数据源 | 新建 `inbox_messages` 单独存 | **扩 `notifications.type`** | 复用未读聚合 + 推送链路 |
| 后端接口 | 新增聚合 `/api/v1/inbox` | **按 type 调 4 次 `GET /api/v1/notifications`** | 4 路并发；零新查询路径 |
| 新页布局 | Tab 切换 | **两页路由（`index.vue` + `detail.vue`）** | 用户反馈竖屏分栏不好用，改单页路由（v1.2） |
| 已读排序 | created_at desc 默认 | **未读优先，已读排后** | 用户已选 |
| 全部操作范围 | 各 group 独立 | **4 group 全量** | 用户已选 |
| 响应式 | 竖屏真左右两栏 | **单页路由全宽，iPad 分栏留给 Stage 2** | 竖屏 50/50 两边都挤（v1.2） |
| Vuex | 不引入 | **引入 mailbox module** | 红点全局共享 + 详情页 onLoad 命中 store |
| 实时通知 | 广场 onShow 轮询 | **uniPush receive 事件 + payload 含 unreads_by_type** | 移动端零轮询（v1.1）|
| emitter 写入内容 | 引用 id 即可 | **content 塞详情全文** | 不跳转就够看 |
| myReports/myFeedbacks 文件 | 删除 | **保留旧文件，新流不引用** | 遵循"无无关改动" |
| emitter 触发点 | 同步立即 | **事务提交后异步** | 避免回滚时通知已发出 |
| POST DELETE 串行 | 串行 | **4 type 并发** | UX 快 |
| composer API 注释 | 手动维护 | **router 同写 swagger 注释** | 与项目约定一致 |
| **入口位置** | 广场 `Header.vue` 加 envelope icon + 红点 | **`pages/profile/profile.vue` `<!-- 服务与工具 -->` section 加 service-button + 红点 badge** | v1.2.9 你确认改到 profile.vue —— profile 是常驻入口,比广场 Header 更稳定 |
| **`like` 是否进邮箱** | 进（占 4 个 Tab 的 1 个） | **暂不进 v1.2.10**:后端 like emitter 保留,前端 4 GROUPS 本就不含 like,profile.vue badge 用 Vuex getter `inboxUnreadOnly` 排除 like/system | 你确认"点赞暂时不要推送到邮箱"—— 保留旧 push 体验,不影响社交动态等其他下游 |
| **`type=activity` 复用程度** | 复用 activityService 现有通知 | **白名单已有但零 emitter,本期新建 emitter** | v1.2.2 自审核对,grep 验证 |
| **推送节流** | 不节流,管理员批量处理时手机狂震 | **三道防线:后端 RateLimiter 60s + App 10s 去抖 + Vuex 幂等** | 用户反馈"管理员批处理手机 UX 灾难",v1.2.6 新增 §12.7(参数经用户确认 60s/10s) |
| **推送聚合 +N** | 5 条 5 次独立推送,用户看 5 张同样 title 的卡片 | **同 type 窗口内 summary title 拼 "您有 N 条新<type 中文>" 递增** | 用户希望"通知栏显示 +5"反馈 → v1.2.8 加 count,实现成本仅 RateLimiter 多一个 pending map|

---

## 14. 附:与旧 myReports/myFeedbacks 的关系

旧页面 (`pages/profile/myReports.vue`、`pages/profile/myFeedbacks.vue`)：
- **代码保留**, 不删除
- **下游入口不在新流引用**:
  - 旧 `profile.vue` 中"我的举报 / 我的反馈"菜单项 —— 是否同步隐藏交产品决定（提案: 隐藏，告知用户新位置）
- 旧 API (`getMyReportsApi / getMyFeedbacksApi`) 仍可用, 但邮件页面只用 `notifications` 接口

理由: CLAUDE.md 强调"一个 commit 只做一件事" + "无无关改动"，删除文件需独立 PR，本方案不夹带。

---

## 15. 变更日志

| 日期 | 版本 | 摘要 |
|------|------|------|
| 2026-07-13 | v1 | 初稿；与用户 4 轮澄清（数据源 / 后端方案 / 新页定位 / 后端聚合 / Tab vs 分组 / 操作按钮 / 折叠展开）后定稿 |
| 2026-07-13 | v1.1 | 用户反馈"只用移动端，不要事件轮询" → §12 反例重写为 uniPush receive 实现方案：① 后端推送 payload 带 `unreads_by_type`，② App.vue#onLaunch 注册 receive 监听器，③ Vuex `applyPushPayload` action 直接 +1，④ 去掉 `setInterval / onShow` 任何形式的轮询；同步更新 §1.3 / §5.3 Vuex actions / §8.3 手验 case 13-16 / §2 验收 Acceptance 11-12 |
| 2026-07-13 | v1.2 | 用户反馈"手机竖屏分栏两边都挤" → 放弃 master-detail 改为两页路由：① `pages/mailbox/index.vue` 全宽列表页 + `pages/mailbox/detail.vue` 全宽明信片页，`navigateTo` 跳转；② 删除 `useMailboxLayout.js`；③ §6 响应式分档表换为两页路由布局策略；④ 关键决策表新增"两页路由 / 单页路由全宽 iPad 分栏留给 Stage 2"；⑤ §10 文件清单同步（移除 layout，新增 detail.vue / App.vue / uni_push_client.go） |
| 2026-07-13 | v1.2.1 | 自审过一遍 → 文档头部版本号 v1.2；§1 关键决策 4 由 mailbox.vue → index.vue + detail.vue；§1 TL;DR 架构图 utils/api.js 补 clearNotificationsApi；§7.2 / §8.3 / §12.3 / §12.5 路径 mailbox → index；§5.3 / §12 兜底对齐描述改为"列表页 onShow 仅此 1 次"；§6.1 副标题"放弃 master-detail"明确指向 v1.2 修订 |
| 2026-07-13 | v1.2.2 | 用户核对后大幅修订"活动通知复用"误判：① §0 描述 + §1 决策 1 + §3.1 扩展表全部对齐 → `allowedTypes` 已有 activity/system/like 三值，但**生产代码只有 socialService 在 emit type=like**（asset_like_service.go:185），activity/system 是白名单预留位、零业务调用；② §3.3.4 标题由 "(已有) 字段补强" 改为 "白名单已有但零 emitter → 本期补建"，并给出 grep 自审命令；③ §0 实施路径补 `activityService 1-2 处 emitter 新增` 行（+0.3d）；④ §8.1 补 activity_emitter_test.go 两个用例；⑤ 整体口径与前端用户查到的"前端接口处没注释"对得上 —— API 路径是已有，问题在 **emit 上行不在 read 下行** |
| 2026-07-13 | v1.2.3 | 用户指出 §10.1 "新增文件"区下 backend 文件全标 "改" 是结构错位 → 重构 §10：① §10.1 仅列真正新增文件（frontend 6 新 + backend 4 新测试文件 + 1 migration）；② §10.2 改为全量"修改文件"清单，含 `utils/api.js` 的 6 新函数、proto/notification.proto 字段号 5/6/7 追加、所有 *_service.go 的 emitter 注入、pkg/push/uni_push_client.go payload 注入；③ 修正副本 §10.3 重复 |
| 2026-07-13 | v1.2.4 | 用户要求 review §5.4 注释模板 → 重写为带函数级中文块注释的版本：① 沿用现有 utils/api.js 的 `// ============` 分隔行 + 中文块注释风格（不引入 JSDoc）；② 每个函数注释分 5 段（功能名+用途、参数、返回、业务流、注意），描述触发场景、与后端事务的关系、本期是否调用；③ 文末补"注释规范要点" 让后续 reviewer 一致 |
| 2026-07-13 | v1.2.5 | 全局自审修正 3 项：① §5.4 GET 函数改用 URL 查询串而非 data:{}（对齐 utils/api.js 现有 GET 约定）；② markAllAsRead / clearNotifications 也改为查询串（对齐 backend gateway controller g.Query("type") 提取）；③ §12.2 payload 契约大幅修正：`Payload.Data` 是 `map[string]interface{}` 而非 JSON 字符串（核对 uni_push_client.go:29），所有 `unreads_by_type / total_unread` 字段在 envelope.data 内层、不是顶层；§12.3 App.vue 改为解 envelope 取 data + 打包 `{data, title, content}` 传 action；§12.4 action 参数从 envelope 改为 `{data, title, content}` 包；§10.2 同步说明 triggerPush 内修改（非 push 客户端） |
| 2026-07-14 | v1.2.6 | 用户指出"管理员批处理时不能一条一推送" → 新增 §12.7 推送节流三道防线：① 后端 `pkg/push/uni_push_client.go` 新增 RateLimiter (key=`user:star:type` 30s 滑窗)：首次 concrete、后续 summary "您有新通知"；② App.vue receive 内 5s 同 type 去抖；③ Vuex `PREPEND_ITEM` 按 id 去重 + `REPLACE_UNREAD_BY_TYPE` idempotent。同步：§0 实施路径 +0.3d、§1 决策 5、§7.5 并发章节加节流说明、§8.3 手验 case 17-19、§10 pkg/push 服务改动、§13 决策表加节流行 |
| 2026-07-14 | v1.2.7 | 用户指出"30s/5s 会不会太短" → 调优为 60s/10s（用户确认）：§12.7 RateLimiter.windowMs 默认值 30000→60000；App DEBOUNCE_MS 5000→10000；yaml 配置、§7.5、§8.3 case 17-18 表述、§13 决策表行同步；§12.7 边界场景表加 3 行（管理员分批 10 条 / 突增边界 case / Stage 2 切换按钮预留） |
| 2026-07-14 | v1.2.8 | 用户问"通知栏能不能显示 +5 这种聚合" → 选择按 type 聚合 + 动态 count：① RateLimiter 加 `pending map[key]int` + `sentMode map[key]string`;② Allow() 返回 (mode, count);③ 新增 TypeChinese() 把 type 映射为"反馈回复/举报结果/被举报/活动通知";④ triggerPush 内根据 mode 生成 title：`fmt.Sprintf("您有 %d 条新%s", count, TypeChinese(n.Type))`;⑤ 5 条 burst 示例 1+2+3+4+5 递增 title。同步：§0 实施路径 +0.1d、§1 决策 5、§8.3 case 17 升级 + case 20、§13 决策表新增 +N 行 |
| 2026-07-14 | v1.2.9 | 你确认入口位从广场 `Header.vue` 改到 `pages/profile/profile.vue` 的 `<!-- 服务与工具 -->` section：① §0 "技术侧"改为该 section 缺 📬 入口；② §1 关键决策 4 重写为"profile.vue 服务与工具 section 加 service-button + 红点 badge"(同 section 已有"新手指引/反馈/修改昵称" 等 6 个同类型按钮天然容纳)；③ §0 实施路径表 +1 行 `"profile.vue" 服务与工具 section 加 📬 收件箱 入口` 0.3d（替代原 Header.vue + square.vue 0.3d 行）；④ §1.4 前端页面表 "新增 showMailboxIcon" → 改 profile.vue "新增 📬 service-button + onShow 时刷新 unread badge"；⑤ Acceptance 1 改写为"profile.vue 服务与工具区看到 📬 按钮 + 红点 badge"+ Acceptance 1.1 onShow 刷新；⑥ §5.1 文件清单删 Header.vue + square.vue 两行,加 profile.vue 行；⑦ §5.10 合规清单同步；⑧ §7.2 未登录守卫改 profile.vue v-if="userStore.token";⑨ §10.2 修改文件同步（Header.vue/square.vue → profile.vue）；⑩ §13 决策表新增"入口位置"行 |
| 2026-07-14 | v1.2.10 | 你确认"点赞暂时不要推送到邮箱":① §3.1 表加"进邮箱?"列,`like` 标 ❌ 不进(其他仍是 ✅);② §3.1 加"点赞不进邮箱"备注段——后端 socialService/asset_like_service.go:185 保持不动,前端 4 GROUPS 本就不含 like(已合规);③ §1 关键决策表新增第 5 行"点赞不进邮箱"原因(保留旧 push 体验不影响社交动态);④ §2.1 Acceptance 1.2 新增"`like 5 + feedback_replied 3 = badge 显示 3 而不是 8`"用例;⑤ §7.2 补 badge 计算代码:Vuex getter `inboxUnreadOnly = activity + feedback_replied + report_resolved + target_reported` (排除 like + system),profile.vue 用此值;⑥ §13 决策表新增"`like` 是否进邮箱"行 |