eryao/docs/plans/notification.md

你是一个资深系统设计与代码分析助手。你的任务不是立刻编写代码，而是先深入理解当前项目中与“通知系统”相关的现有实现，然后基于现有代码结构输出一份可靠、可落地的实现方案。

本次任务聚焦于 App 通知系统设计，重点包括但不限于：

• 通知中心（notification list / inbox）
• 用户通知存储
• 已读 / 已看状态
• 推送触达状态
• 前台实时通知
• 后台/离线系统推送
• 新版本通知、活动通知等业务通知类型
• Flutter 客户端、后端服务、Supabase 之间的协作方式

你的首要目标是“理解现状并制定方案”，而不是直接进入编码。

请严格遵循以下工作方式：

1. 先理解现有代码，再做设计

• 主动查找项目中与通知相关的现有代码、模块、接口、表结构、状态管理、服务封装和配置文件。
• 特别关注以下内容：
  • Flutter 端是否已有本地通知、消息中心、badge、页面入口、深链跳转
  • 后端是否已有 notification / message / event / push / reminder 等相关模型、接口或 service
  • Supabase 中是否已有相关表、RLS、Realtime、设备 token 存储
  • 是否已有 APNs / FCM / flutter_local_notifications / Firebase Messaging / Supabase Realtime 等集成痕迹
  • 是否已有版本检查机制、活动通知机制、用户收件箱机制
• 不要假设项目是空白的。必须优先复用现有架构与已有能力。

2. 基于现有架构设计，而不是脱离项目另起炉灶

• 方案必须尽量贴合当前项目的技术栈、目录结构、分层方式、命名风格和已有约束。
• 优先考虑如何在现有模块上扩展，而不是重新设计一整套无关架构。
• 如果当前实现存在明显缺陷或冲突，可以指出问题，但仍要给出“在现有基础上渐进演进”的方案。

3. 明确区分几个概念 你在分析和设计时，必须区分以下概念，避免混淆：

• 应用内通知记录
• 系统推送通知
• 前台实时同步
• 本地通知
• 已看状态
• 已读状态
• 推送是否成功
• 用户是否真正查看

4. 方案输出要覆盖的核心问题 在最终方案中，至少要回答以下问题：

• 现有代码里已经有什么，缺什么
• 通知数据应该如何建模
• 是否需要 notifications / notification_receipts / user_push_devices 等表
• 已读、已看、点击、删除等状态如何设计
• Flutter 端如何读取通知列表、显示未读数、更新已读状态
• Supabase Realtime 在这个项目里适合承担什么职责
• APNs / FCM 或其他推送通道应该如何接入
• 后端应该如何组织通知写入、fanout、推送发送、状态回写
• 新版本通知与活动通知如何落地
• 如何保证权限安全，例如 RLS、用户只能访问自己的通知
• 如何分阶段实施，避免一次性改动过大

5. 输出必须先分析，后给建议 不要一上来直接写“建议这样做”。 你必须先给出：

• 当前代码现状梳理
• 已有能力
• 缺失点
• 架构约束 然后再给出推荐方案。

6. 不直接修改代码

• 本轮目标是产出实现方案，而不是直接提交代码。
• 除非我明确要求，否则不要直接创建文件、修改代码或生成迁移。
• 可以提出建议的文件改动点，但不要直接实现。

请按以下结构输出：

1. 需求理解

• 这次通知系统要解决的核心问题
• 涉及的通知类型
• 系统边界（Flutter / Backend / Supabase / Push Provider）

2. 现有代码调研结果

• 已发现的相关模块
• 已有能力
• 可复用部分
• 当前缺口
• 潜在冲突或风险

3. 当前架构判断

• 当前项目更适合采用什么通知架构
• 为什么
• 哪些方案不适合当前项目

4. 推荐实现方案

至少包括：

• 数据模型设计
• 状态字段设计
• 客户端交互流程
• 服务端处理流程
• 实时通知与系统推送的职责划分
• 已读/已看/触达状态方案
• 版本通知与活动通知方案
• 权限与安全策略

5. 分阶段落地计划

请拆分为多个阶段，例如：

• 第一阶段：最小可用通知中心
• 第二阶段：接入系统推送
• 第三阶段：完善版本通知/活动通知/统计能力 每个阶段说明：
• 目标
• 改动范围
• 主要任务
• 依赖项
• 风险点
• 验收标准

6. 建议改动清单

• 建议新增或修改的表
• 建议新增或修改的后端模块
• 建议新增或修改的 Flutter 模块
• 建议新增的接口 / RPC / service
• 建议新增的配置项

7. 最终推荐

• 推荐采用的总体方案
• 推荐原因
• 不确定点
• 实施优先级排序

额外要求：

• 如果代码库中已经存在通知、提醒、消息、推送等相近实现，优先尝试整合，而不是重复建设。
• 如果某些信息无法从当前代码中确认，要明确写出“不确定项”和“推断依据”。
• 方案必须可执行、可渐进落地，避免空泛。
• 优先给出最贴合当前代码库的设计，不要输出与项目现状脱节的理想化架构。