# 通知系统实现方案

> 创建时间：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 相关配置 |