feat: 添加 points_audit_ledger 及 JSON 字段 Pydantic Schema 约束

2026-04-10 12:28:18 +08:00
parent 46513829cd
commit 0ac8b81a66
34 changed files with 2595 additions and 1757 deletions
@@ -0,0 +1,784 @@
+# 通知系统实现方案
+
+> 创建时间：2026-04-10
+> 状态：已评审
+
+## 1. 需求理解
+
+### 1.1 核心问题
+当前项目（觅爻签问 App）没有通知系统，需要从零建设。核心需求包括：
+- 通知中心（通知列表/收件箱）
+- 用户通知存储与读取
+- 已读/已看状态追踪
+- 系统推送触达（APNs/FCM）
+- 前台实时通知同步
+- 新版本通知、活动通知等业务通知类型
+
+### 1.2 通知类型区分
+
+| 类型 | 说明 | 当前状态 |
+|------|------|----------|
+| 应用内通知记录 | 存储在 DB 的通知数据 | **不存在** |
+| 系统推送通知 | 通过 APNs/FCM 发送 | **不存在** |
+| 前台实时同步 | App 打开时实时拉取 | **不存在** |
+| 本地通知 | App 本地触发的通知 | **不存在** |
+| 已看状态 | 用户是否打开过通知详情 | **未设计** |
+| 已读状态 | 用户是否标记为已读 | **未设计** |
+| 推送触达 | 消息是否成功送达设备 | **未设计** |
+
+### 1.3 系统边界
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Flutter App                           │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────┐  │
+│  │ 本地通知  │  │ 推送接收  │  │ 通知中心  │  │ Badge  │  │
+│  └──────────┘  └──────────┘  └──────────┘  └─────────┘  │
+└───────────────┬─────────────────────┬───────────────────┘
+                │                     │
+                │  REST API           │ Supabase Realtime
+                ▼                     ▼
+┌───────────────────────────────────────────────────────────┐
+│                      Backend (FastAPI)                     │
+│  ┌────────────┐  ┌────────────┐  ┌────────────────────┐   │
+│  │ 通知写入   │  │ Fanout     │  │ 推送发送 (APNs/FCM)│   │
+│  └────────────┘  └────────────┘  └────────────────────┘   │
+└───────────────┬─────────────────────┬───────────────────────┘
+                │                     │
+                ▼                     ▼
+┌─────────────────────────┐  ┌─────────────────────────────┐
+│    PostgreSQL (Supabase) │  │    Redis / Supabase        │
+│  ┌──────────────────┐   │  │    Realtime                │
+│  │ notifications    │   │  │  ┌─────────────────────┐  │
+│  │ notification_    │   │  │  │ user:{id}:notif:new  │  │
+│  │ receipts         │   │  │  └─────────────────────┘  │
+│  │ user_push_       │   │  └─────────────────────────────┘
+│  │ devices           │   │
+│  └──────────────────┘   │
+└─────────────────────────┘
+                │
+                ▼
+┌─────────────────────────┐
+│   Push Provider         │
+│  (APNs / FCM / 备用)    │
+└─────────────────────────┘
+```
+
+---
+
+## 2. 现有代码调研结果
+
+### 2.1 已发现的相关模块
+
+#### Flutter 端
+
+| 路径 | 说明 |
+|------|------|
+| `apps/lib/features/settings/presentation/screens/privacy_notification_settings_screen.dart` | 通知设置页面（占位 UI） |
+| `apps/lib/features/settings/data/models/profile_settings.dart` | `NotificationSettings`（`allowNotifications`, `allowVibration`） |
+| `apps/lib/features/home/presentation/screens/home_screen.dart:204` | 通知图标（点击显示 `featurePending`） |
+
+#### 后端
+
+| 路径 | 说明 |
+|------|------|
+| `backend/src/schemas/shared/user.py:44` | `NotificationSettings` schema |
+| `backend/src/v1/users/service.py` | 用户服务（含 settings 更新） |
+| `backend/src/v1/users/router.py` | 用户路由 |
+| `backend/src/services/base/supabase.py` | Supabase 服务封装 |
+| `backend/src/core/config/settings.py` | 配置管理 |
+
+#### 数据库迁移
+
+| 文件 | 说明 |
+|------|------|
+| `backend/alembic/versions/20260403_0002_user_points_chat_schema.py` | profiles, sessions, messages 表 |
+| `backend/alembic/versions/20260407_0001_update_notification_settings.py` | 通知设置默认值 |
+
+### 2.2 已有能力
+
+1. **Profile + Settings 系统**：`profiles.settings` 是 JSONB，可扩展存储通知偏好
+2. **用户认证**：Supabase Auth 完整
+3. **数据库迁移框架**：Alembic 已建立
+4. **后台任务**：Taskiq (基于 Redis)
+5. **日志系统**：已集成 structlog
+6. **API 模式**：Pydantic schemas, RFC7807 错误格式
+
+### 2.3 当前缺口
+
+| 缺口 | 说明 |
+|------|------|
+| 通知数据模型 | 无 `notifications` 表 |
+| 推送设备管理 | 无 `user_push_devices` 表 |
+| 通知状态追踪 | 无 `user_notifications` 状态字段体系 |
+| 推送服务集成 | 无 APNs/FCM/备用推送集成 |
+| Flutter 通知中心 | 无通知列表页面 |
+| Flutter 推送接收 | 无 firebase_messaging 等依赖 |
+| Supabase Realtime | 未用于通知同步 |
+| 未读数 Badge | 未实现 |
+
+### 2.4 潜在冲突或风险
+
+1. **AGENTS.md 约束**：`apps/AGENTS.md` 明确要求通知相关代码放在 `core/notification/` 和 `shared/widgets/notification/`，需要遵循
+2. **现有 Settings 结构**：`NotificationSettings` 只有两个布尔字段，未来需要扩展
+3. **数据库 JSONB 查询**：`profiles.settings` 使用 GIN 索引，但通知列表不适合放 JSONB
+
+---
+
+## 3. 当前架构判断
+
+### 3.1 推荐架构：混合推送 + 实时同步（Broadcast 主通道）
+
+**推荐方案：Supabase Realtime Broadcast（前台）+ APNs/FCM（后台/离线）**
+
+**原因**：
+1. App 打开时（前台）：使用 Broadcast 推送状态变化，避免直接依赖 `postgres_changes` 在高并发下的 RLS 扫描压力
+2. App 关闭时（后台/离线）：通过 APNs/FCM 触达设备
+3. 两条链路统一写入 `user_notifications`，状态由服务端收敛，客户端只上报回执
+
+**不适合当前项目的方案**：
+
+| 方案 | 不适合原因 |
+|------|------------|
+| 纯轮询 | 电量/服务器压力大，不优雅 |
+| WebSocket 直连 | 需要自己维护连接，复杂度高 |
+| 仅本地通知 | 无法触达离线用户 |
+| 仅 APNs/FCM | 无法查看历史通知列表 |
+
+### 3.2 职责划分
+
+| 组件 | 职责 |
+|------|------|
+| `notifications` 表 | 存储通知内容，永久记录 |
+| `user_notifications` 表 | 追踪每个用户对每条通知的状态 |
+| `notification_push_attempts` 表 | 追踪推送每次尝试和失败原因 |
+| `user_push_devices` 表 | 存储设备 token |
+| Supabase Realtime | 前台实时通知同步 |
+| APNs/FCM | 后台/离线推送 |
+
+---
+
+## 4. 推荐实现方案
+
+### 4.1 数据模型设计
+
+#### 4.1.1 `notifications` 表
+
+```sql
+CREATE TABLE notifications (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    type VARCHAR(32) NOT NULL,          -- 'system'|'activity'|'version'|'social'
+    priority SMALLINT DEFAULT 0,        -- 0=normal, 1=high
+    title TEXT NOT NULL,
+    body TEXT NOT NULL,
+    data JSONB,                          -- 透传数据（deeplink 等）
+    action_url TEXT,
+    expires_at TIMESTAMPTZ,             -- 过期时间，NULL=永不过期
+    created_at TIMESTAMPTZ DEFAULT now(),
+    deleted_at TIMESTAMPTZ
+);
+
+-- 索引
+CREATE INDEX ix_notifications_type ON notifications(type);
+CREATE INDEX ix_notifications_created_at ON notifications(created_at DESC);
+```
+
+#### 4.1.2 `user_notifications` 表（用户通知记录 + 状态）
+
+```sql
+CREATE TABLE user_notifications (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id UUID NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
+    notification_id UUID NOT NULL REFERENCES notifications(id) ON DELETE CASCADE,
+    dedupe_key TEXT NOT NULL,            -- 幂等键（建议: campaign_id:user_id 或业务事件ID）
+
+    -- 状态字段
+    is_read BOOLEAN DEFAULT FALSE,       -- 已读（点击进入详情）
+    is_seen BOOLEAN DEFAULT FALSE,       -- 已看（列表中曝光）
+    is_opened BOOLEAN DEFAULT FALSE,     -- 从推送打开（客户端回执）
+    read_at TIMESTAMPTZ,
+    seen_at TIMESTAMPTZ,
+    opened_at TIMESTAMPTZ,
+
+    -- 推送状态（服务端可验证状态，不直接使用 delivered 语义）
+    push_state SMALLINT DEFAULT 0,      -- 0=queued, 1=sent, 2=provider_ack, 3=failed
+    push_provider VARCHAR(16),          -- apns|fcm
+    push_error_code TEXT,
+    push_sent_at TIMESTAMPTZ,
+    push_provider_ack_at TIMESTAMPTZ,
+
+    created_at TIMESTAMPTZ DEFAULT now(),
+    updated_at TIMESTAMPTZ DEFAULT now(),
+    deleted_at TIMESTAMPTZ,
+
+    UNIQUE(user_id, dedupe_key)
+);
+
+-- 索引
+CREATE INDEX ix_user_notifications_user_id ON user_notifications(user_id);
+CREATE INDEX ix_user_notifications_user_unread ON user_notifications(user_id, is_read) WHERE deleted_at IS NULL;
+CREATE INDEX ix_user_notifications_created_at ON user_notifications(created_at DESC);
+CREATE INDEX ix_user_notifications_user_seen ON user_notifications(user_id, is_seen) WHERE deleted_at IS NULL;
+CREATE INDEX ix_user_notifications_push_state ON user_notifications(push_state) WHERE deleted_at IS NULL;
+```
+
+#### 4.1.3 `user_push_devices` 表
+
+```sql
+CREATE TABLE user_push_devices (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id UUID NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
+    device_token TEXT NOT NULL,          -- APNs/FCM token
+    device_type VARCHAR(16) NOT NULL,    -- 'ios'|'android'
+    push_provider VARCHAR(32) NOT NULL,  -- 'apns'|'fcm'|'huawei'|'xiaomi'
+    app_version TEXT,
+    locale VARCHAR(16),
+
+    is_active BOOLEAN DEFAULT TRUE,
+    last_used_at TIMESTAMPTZ DEFAULT now(),
+    created_at TIMESTAMPTZ DEFAULT now(),
+    updated_at TIMESTAMPTZ DEFAULT now(),
+    deleted_at TIMESTAMPTZ,
+
+    UNIQUE(user_id, device_token, push_provider)
+);
+
+-- 索引
+CREATE INDEX ix_user_push_devices_user_id ON user_push_devices(user_id);
+CREATE INDEX ix_user_push_devices_token ON user_push_devices(device_token);
+CREATE INDEX ix_user_push_devices_active ON user_push_devices(user_id, is_active) WHERE deleted_at IS NULL;
+```
+
+#### 4.1.4 `notification_push_attempts` 表（推送尝试日志）
+
+```sql
+CREATE TABLE notification_push_attempts (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_notification_id UUID NOT NULL REFERENCES user_notifications(id) ON DELETE CASCADE,
+    provider VARCHAR(16) NOT NULL,          -- apns|fcm
+    attempt_no SMALLINT NOT NULL,
+    request_id TEXT,
+    result SMALLINT NOT NULL,               -- 0=sent, 1=provider_ack, 2=failed, 3=timeout
+    error_code TEXT,
+    error_detail TEXT,
+    created_at TIMESTAMPTZ DEFAULT now()
+);
+
+CREATE INDEX ix_notification_push_attempts_un_id ON notification_push_attempts(user_notification_id, created_at DESC);
+```
+
+#### 4.1.5 状态字段说明
+
+| 字段 | 含义 | 触发条件 |
+|------|------|----------|
+| `is_seen` | 用户在列表中看到该通知 | 列表滚动曝光（停留 > 1秒）或拉取 |
+| `is_read` | 用户点击进入详情 | 点击通知项 |
+| `is_opened` | 用户从系统通知打开 App | 客户端上报 open 回执 |
+| `push_state=sent` | 推送请求已发出 | 服务端调用 APNs/FCM 成功返回 |
+| `push_state=provider_ack` | 平台确认接收 | APNs/FCM Provider 级确认 |
+| `push_state=failed` | 推送失败 | 服务端重试耗尽或不可恢复错误 |
+
+> 注意：`provider_ack` 不等价于“用户已看到通知”。用户可见性必须以 `is_opened`/`is_seen`/`is_read` 为准。
+
+### 4.2 后端 API 设计
+
+#### 4.2.1 通知路由 (`backend/src/v1/notifications/`)
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/api/v1/notifications` | 获取当前用户通知列表 |
+| GET | `/api/v1/notifications/unread-count` | 获取未读数 |
+| PATCH | `/api/v1/notifications/{id}/seen` | 标记为已看 |
+| PATCH | `/api/v1/notifications/{id}/read` | 标记为已读 |
+| PATCH | `/api/v1/notifications/mark-all-read` | 全部已读 |
+| DELETE | `/api/v1/notifications/{id}` | 删除通知 |
+
+#### 4.2.2 设备路由 (`backend/src/v1/push/`)
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| POST | `/api/v1/push/devices` | 注册/更新设备 token |
+| DELETE | `/api/v1/push/devices/{id}` | 删除设备 |
+| GET | `/api/v1/push/devices` | 获取用户设备列表 |
+
+### 4.3 Flutter 端设计
+
+#### 4.3.1 目录结构（遵循 AGENTS.md）
+
+```
+apps/lib/
+├── core/
+│   └── notification/                    # NEW
+│       ├── models/
+│       │   ├── notification.dart
+│       │   └── push_device.dart
+│       ├── services/
+│       │   ├── notification_service.dart
+│       │   └── push_service.dart
+│       └── repositories/
+│           └── notification_repository.dart
+├── features/
+│   └── notifications/                   # NEW
+│       ├── data/
+│       │   ├── apis/notification_api.dart
+│       │   └── repositories/notification_repository_impl.dart
+│       ├── presentation/
+│       │   ├── screens/notification_center_screen.dart
+│       │   ├── widgets/notification_item.dart
+│       │   └── bloc/notification_bloc.dart
+├── shared/
+│   └── widgets/
+│       └── notification/               # NEW
+│           ├── notification_badge.dart
+│           └── notification_toast.dart
+```
+
+#### 4.3.2 通知中心流程
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│ App 打开 / HomeScreen                                        │
+│  1. 初始化时连接 Supabase Realtime 私有频道                     │
+│  2. 监听 Broadcast 通知事件                                    │
+│  3. 实时更新本地列表和未读数 Badge                              │
+└──────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌──────────────────────────────────────────────────────────────┐
+│ NotificationCenterScreen                                      │
+│  1. 首次进入 → 调用 GET /api/v1/notifications                 │
+│  2. 滚动曝光 → 调用 PATCH /api/v1/notifications/{id}/seen    │
+│  3. 点击通知 → 调用 PATCH /api/v1/notifications/{id}/read    │
+│  4. 下拉刷新 → 重新拉取列表                                     │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### 4.4 实时同步方案
+
+**Supabase Realtime 职责**：
+- 当用户在另一设备读取通知时，当前设备实时更新 `is_read` / `is_seen` / `is_opened` 状态
+- 仅做前台状态分发，不承担离线触达
+
+**推荐通道：Broadcast（私有频道）**
+
+```text
+DB update(user_notifications)
+  -> trigger 调用 realtime.broadcast_changes(...)
+  -> channel: user:{user_id}:notifications
+  -> Flutter 收到事件并更新本地缓存
+```
+
+**为什么不用 postgres_changes 作为主通道**：
+- 在订阅规模扩大时，`postgres_changes` 会放大 RLS 评估开销
+- Broadcast 在通知场景下更可控，可按用户私有频道精准下发
+
+```dart
+final channel = supabase.channel(
+  'user:${userId}:notifications',
+  opts: const RealtimeChannelConfig(private: true),
+);
+
+channel.onBroadcast(
+  event: 'notification_changed',
+  callback: (payload) {
+    // 更新本地状态和 Badge
+  },
+).subscribe();
+```
+
+### 4.5 推送发送流程（Outbox + Worker）
+
+```
+┌─────────────┐     ┌──────────────────┐     ┌─────────────────┐
+│ 业务触发    │────▶│ DB 事务写入      │────▶│ push_outbox      │
+│ (后台任务)  │     │ notifications +  │     │ pending 事件      │
+└─────────────┘     │ user_notifications│     └────────┬────────┘
+                    └──────────────────┘              │
+                                                      ▼
+                                           ┌─────────────────┐
+                                           │ Fanout Worker   │
+                                           │ 读取 outbox      │
+                                           └────────┬────────┘
+                                                    │
+                  ┌─────────────────────────────────┼─────────────────────────────────┐
+                  │                                 │                                 │
+                  ▼                                 ▼                                 ▼
+          ┌──────────────┐                 ┌──────────────┐                 ┌──────────────┐
+          │ Broadcast    │                 │ APNs / FCM   │                 │ 重试 / DLQ   │
+          │ 前台增量同步  │                 │ 离线触达       │                 │ 指数退避      │
+          └──────────────┘                 └──────────────┘                 └──────────────┘
+```
+
+### 4.6 幂等、重试与失败处理
+
+#### 4.6.1 幂等策略
+
+- 每次业务发通知必须携带 `dedupe_key`
+- `UNIQUE(user_id, dedupe_key)` 保证重复投递不会生成多条记录
+- `PATCH /read`、`PATCH /seen` 必须幂等，重复调用返回 200 且不重复更新统计
+
+#### 4.6.2 重试策略
+
+- 可重试错误：超时、5xx、429
+- 不可重试错误：token invalid、payload invalid、认证失败
+- 退避策略：`30s -> 2m -> 10m -> 1h`，最多 4 次
+- 超过上限进入 DLQ，由运维任务定时重放或人工处理
+
+#### 4.6.3 失败模式清单
+
+| 场景 | 风险 | 方案 |
+|------|------|------|
+| 推送平台短时不可用 | 批量失败 | Outbox + 指数退避 + DLQ |
+| 客户端重复上报 read | 状态抖动/统计偏差 | 幂等更新 + 仅首次写时间戳 |
+| 多设备并发 read/seen | 最终状态不一致 | 单条记录原子更新 + `updated_at` 冲突检测 |
+| Realtime 断连 | UI 未及时同步 | 前台重连后触发增量拉取（按 `updated_at`） |
+
+### 4.7 版本通知与活动通知
+
+#### 4.7.1 版本通知
+
+- 触发条件：用户登录时检测到 App 版本低于最新版本
+- 写入方式：后台任务扫描所有用户，批量写入 `user_notifications`
+- `notification.type = 'version'`
+
+#### 4.7.2 活动通知
+
+- 触发条件：运营后台或定时任务触发
+- 目标用户：可按标签/行为筛选
+- `notification.type = 'activity'`
+
+### 4.8 权限与安全策略
+
+#### RLS 设计
+
+```sql
+-- user_notifications
+ALTER TABLE user_notifications ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY auth_select ON user_notifications FOR SELECT
+  USING (auth.uid() = user_id AND deleted_at IS NULL);
+
+CREATE POLICY auth_update ON user_notifications FOR UPDATE
+  USING (auth.uid() = user_id)
+  WITH CHECK (auth.uid() = user_id);
+
+-- user_push_devices
+ALTER TABLE user_push_devices ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY auth_all ON user_push_devices FOR ALL
+  USING (auth.uid() = user_id AND deleted_at IS NULL)
+  WITH CHECK (auth.uid() = user_id);
+```
+
+#### 信任边界
+
+- 客户端不能创建通知主记录，通知内容仅由服务端写入
+- 客户端只能操作自己的 `seen/read/open` 回执和设备 token
+- `owner_id/user_id` 必须来自 JWT `sub`，禁止客户端传入
+- 管理后台发通知接口必须走服务角色鉴权，不暴露给普通用户 token
+
+### 4.9 可观测性与运行指标
+
+| 指标 | 目标/SLO | 备注 |
+|------|----------|------|
+| 通知写入成功率 | >= 99.9% | 5 分钟窗口 |
+| 推送发送成功率（sent） | >= 99.5% | 按 provider 分维度 |
+| 推送 provider_ack 延迟 P95 | < 3s | 仅平台确认链路 |
+| 前台实时同步延迟 P95 | < 1s | Broadcast 收包到 UI 更新 |
+| read API P95 | < 150ms | 排除网络抖动 |
+
+日志要求：每次通知发送链路打通 `trace_id`（创建 -> outbox -> provider -> 回执）。
+
+### 4.10 NOT in scope（本阶段不做）
+
+- 厂商通道（小米/华为）深度集成
+- 通知模板多语言管理后台
+- 通知 A/B 实验平台
+- 全量历史归档/冷热分层
+
+---
+
+## 5. 分阶段落地计划
+
+### 第一阶段：最小可用通知中心（MVP 收敛）
+
+**目标**：在 App 内显示通知列表，支持标记已读
+
+**改动范围**：
+- Backend: `notifications` 表 + API
+- Flutter: 通知中心页面 + Repository
+
+**主要任务**：
+1. 创建 `notifications` 和 `user_notifications` 表
+2. 实现 `GET /api/v1/notifications` API
+3. 实现 `PATCH /api/v1/notifications/{id}/read` API
+4. Flutter 通知中心页面（列表 + 标记已读）
+5. 未读数 Badge（在 HomeScreen 通知图标上显示红点）
+6. 完成协议文档：`docs/protocols/notification/notification-protocol.md`
+7. 完成基础测试（见第 7 节）
+
+**依赖项**：无
+
+**风险点**：
+- 无推送，通知需要后台手动写入 DB
+- 不支持实时同步，多设备体验差
+
+**验收标准**：
+- [ ] 能看到通知列表
+- [ ] 点击通知能标记为已读
+- [ ] 未读通知有 Badge 提示
+- [ ] 已读/未读状态在下拉刷新后正确
+- [ ] 越权访问被拒绝（用户 A 无法读写用户 B 通知）
+- [ ] read 接口重复调用幂等
+
+---
+
+### 第二阶段：接入系统推送
+
+**目标**：支持离线推送通知
+
+**改动范围**：
+- Backend: `user_push_devices` 表 + Push Service
+- Flutter: 推送接收 + 设备注册
+
+**主要任务**：
+1. 创建 `user_push_devices` 表
+2. 实现 `POST /api/v1/push/devices` API（注册 token）
+3. 集成 firebase_messaging（Android）/ apns（iOS）
+4. 实现 Push Sending Service（APNs/FCM SDK）+ Outbox Worker
+5. Flutter 端：获取 FCM/APNs token 并注册
+6. 服务端发送后更新 `push_state`，客户端仅上报 open/read/seen 回执
+7. 落地重试与 DLQ
+
+**依赖项**：
+- 第一阶段完成
+- Firebase 项目配置（Android）
+- APNs 证书/Key（iOS）
+
+**风险点**：
+- APNs/FCM 配置复杂
+- 推送送达率不稳定（特别是国内 Android）
+
+**验收标准**：
+- [ ] 离线设备能收到推送
+- [ ] 点击推送能打开对应通知详情
+- [ ] 推送状态（sent/provider_ack/failed）正确回写
+- [ ] provider 短时故障时消息可自动重试并可追踪
+
+---
+
+### 第三阶段：实时同步与统计
+
+**目标**：多设备实时同步 + 完整状态追踪
+
+**改动范围**：
+- Backend: Supabase Realtime + 状态统计
+- Flutter: Realtime 订阅 + 曝光追踪
+
+**主要任务**：
+1. Supabase Realtime Broadcast 私有频道接入
+2. 实现 `seen` 状态（曝光追踪）
+3. 添加统计接口（送达率、点击率）
+4. Flutter 端：列表滚动时标记 `seen`
+5. 版本通知、活动通知的后台写入逻辑
+6. 断线重连后的增量拉取机制（按 `updated_at`）
+
+**依赖项**：
+- 第二阶段完成
+- Supabase Realtime 已启用
+
+**风险点**：
+- Realtime 连接数限制（根据 plan）
+- 曝光追踪可能影响性能
+
+**验收标准**：
+- [ ] 一设备读取通知，另一设备实时更新
+- [ ] 列表曝光能正确标记 `seen`
+- [ ] 能查看送达/点击统计
+- [ ] Realtime 断连恢复后不丢状态更新
+
+---
+
+## 6. 建议改动清单
+
+### 6.1 新增/修改的表
+
+| 表名 | 操作 | 说明 |
+|------|------|------|
+| `notifications` | 新增 | 通知模板表 |
+| `user_notifications` | 新增 | 用户通知记录+状态 |
+| `user_push_devices` | 新增 | 设备 token 存储 |
+| `notification_push_attempts` | 新增 | 推送尝试日志 |
+| `profiles` | 修改 | 暂不改，优先在线计算 unread_count |
+
+### 6.2 新增后端模块
+
+| 路径 | 说明 |
+|------|------|
+| `backend/src/v1/notifications/` | 通知路由+服务+仓库 |
+| `backend/src/v1/push/` | 推送设备路由+服务 |
+| `backend/src/services/push/` | APNs/FCM 发送服务 |
+| `backend/src/services/push/outbox_worker.py` | 推送 outbox 消费与重试 |
+| `backend/src/models/notification.py` | 通知 ORM 模型 |
+| `backend/src/models/notification_push_attempt.py` | 推送尝试日志模型 |
+| `backend/src/schemas/notification.py` | Pydantic schemas |
+
+### 6.3 新增 Flutter 模块
+
+| 路径 | 说明 |
+|------|------|
+| `apps/lib/core/notification/` | 通知核心逻辑 |
+| `apps/lib/features/notifications/` | 通知功能模块 |
+| `apps/lib/shared/widgets/notification/` | 通知 UI 组件 |
+
+### 6.4 新增接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/api/v1/notifications` | 通知列表 |
+| GET | `/api/v1/notifications/unread-count` | 未读数 |
+| PATCH | `/api/v1/notifications/{id}/seen` | 标记已看 |
+| PATCH | `/api/v1/notifications/{id}/read` | 标记已读 |
+| PATCH | `/api/v1/notifications/mark-all-read` | 全部已读 |
+| DELETE | `/api/v1/notifications/{id}` | 删除通知 |
+| POST | `/api/v1/notifications/{id}/opened` | 上报从推送打开 |
+| POST | `/api/v1/push/devices` | 注册设备 |
+| DELETE | `/api/v1/push/devices/{id}` | 删除设备 |
+
+### 6.5 新增配置项
+
+```env
+# .env
+ERYAO_PUSH__APNS_KEY_ID=xxx
+ERYAO_PUSH__APNS_TEAM_ID=xxx
+ERYAO_PUSH__APNS_KEY_PATH=/path/to/key.p8
+ERYAO_PUSH__FCM_SERVER_KEY=xxx
+ERYAO_PUSH__ENABLED=true
+```
+
+### 6.6 Flutter 依赖（pubspec.yaml）
+
+```yaml
+dependencies:
+  firebase_messaging: ^15.0.0     # FCM
+  flutter_local_notifications: ^18.0.0  # 本地通知
+  supabase_flutter: ^2.5.0      # Supabase 客户端（含 Realtime）
+```
+
+### 6.7 协议文档（先于实现）
+
+```text
+docs/protocols/notification/
+├── notification-protocol.md          # 数据模型、字段语义、兼容策略
+├── notification-api-protocol.md      # API 请求/响应、错误码
+└── notification-realtime-protocol.md # Broadcast payload 与版本约束
+```
+
+---
+
+## 7. 测试策略（必须随阶段落地）
+
+### 7.1 测试框架
+
+- 后端：`pytest` + `pytest-asyncio`（见 `pyproject.toml`）
+- Flutter：单测 + Widget 测试 + 关键链路集成测试
+
+### 7.2 覆盖图（关键分支）
+
+```text
+Create Notification
+  -> validate payload
+    -> invalid type [unit]
+    -> expires_at in past [unit]
+  -> fanout target users
+    -> empty target set [unit]
+    -> partial user write failed [integration]
+  -> write user_notifications (dedupe)
+    -> first write success [unit]
+    -> duplicate dedupe_key [unit]
+  -> enqueue outbox
+    -> enqueue success [integration]
+    -> enqueue failed rollback [integration]
+
+Push Worker
+  -> send provider
+    -> sent/provider_ack [integration]
+    -> timeout retry [integration]
+    -> permanent failure to DLQ [integration]
+
+User Callback
+  -> PATCH seen/read/opened
+    -> own record success [api]
+    -> cross-user forbidden [api/security]
+    -> repeat call idempotent [api]
+
+Realtime
+  -> broadcast receive update [integration]
+  -> reconnect + incremental pull [e2e]
+```
+
+### 7.3 最低覆盖要求
+
+- 新增后端核心分支（通知创建、状态更新、重试）语句覆盖率 >= 90%
+- 安全相关路径（越权、伪造 user_id、非法 token）必须 100% 有测试
+- 每个阶段必须包含至少 1 条回归测试，防止旧行为被破坏
+
+### 7.4 回归测试强制项
+
+1. 同一通知重复发送不应生成重复 `user_notifications`
+2. `mark-all-read` 与单条 `read` 并发时，最终状态一致
+3. Realtime 中断后恢复，未读数与服务端一致
+4. 无效/过期 token 不应导致消息丢失（进入失败态并可重试）
+
+---
+
+## 8. 最终推荐
+
+### 8.1 推荐总体方案
+
+**采用 Supabase Realtime Broadcast（前台）+ APNs/FCM（后台/离线）的混合方案**
+
+### 8.2 推荐原因
+
+1. **用户体验最优**：前台实时同步，多设备状态一致
+2. **离线可达**：通过 APNs/FCM 触达离线用户
+3. **扩展性更稳**：Broadcast 规避高并发下 `postgres_changes` 的权限扫描放大
+4. **状态语义更准确**：`provider_ack` 与用户可见状态分离，统计更可信
+5. **项目适配**：Supabase 已在用，Realtime 只是扩展使用
+
+### 8.3 不确定点
+
+| 问题 | 推断依据 |
+|------|----------|
+| 是否已有 Firebase 项目 | 未在代码库中找到 `google-services.json` 或 Firebase 配置 |
+| 是否已有 APNs 证书 | 未在代码库中找到证书文件 |
+| 国内 Android 推送需求 | 国内 Android ROM 需要厂商通道（如小米、华为），建议预留 |
+
+### 8.4 实施优先级排序
+
+| 优先级 | 阶段 | 说明 |
+|--------|------|------|
+| **P0** | 第一阶段 | MVP：通知列表 + 标记已读 |
+| **P1** | 第一阶段 | 未读数 Badge |
+| **P2** | 第二阶段 | 推送接入（Android FCM 先，iOS APNs 后） |
+| **P3** | 第三阶段 | Realtime 同步 |
+| **P4** | 第三阶段 | 曝光追踪 + 统计 |
+
+### 8.5 关键约束提醒
+
+1. **遵循 AGENTS.md**：通知代码放在 `core/notification/` 和 `shared/widgets/notification/`
+2. **Error Swallowing**：所有异常必须传播，禁止静默捕获
+3. **Protocol 先行**：新建通知相关协议文档在 `docs/protocols/notification/`
+4. **渐进演进**：不废弃现有 `NotificationSettings`，而是扩展它
+
+---
+
+## 附录：推断依据
+
+| 信息点 | 推断依据 |
+|--------|----------|
+| 无通知表 | 所有 migration 文件中均未发现 `notifications` 相关表 |
+| 无推送集成 | `pubspec.yaml` 无 firebase_messaging / apns 相关依赖 |
+| 无 Realtime 通知 | Supabase Service 仅用于 Storage，未配置 Realtime |
+| AGENTS.md 约束 | `apps/AGENTS.md` 明确提到 "Reminder/Notification Rewrite Boundary" |
+| 推送服务配置 | `settings.py` 无任何 APNs/FCM 相关配置 |