MeowOS-For-R3P2/NOTIFICATION_SYSTEM.md

MeowOS 通知系统设计（M2 通知存储 + 分发，阶段 B/D 前置）

状态：设计稿定稿讨论中（2026-08-29，用户已给定多数决策）。按 FREWORKS §4/附C + 用户约定，遵循 freedesktop.org 通知规范。实施前仅剩"应用配额"细节待深入讨论（见 §7）。

1. 定位

• MeowOS 通知中心的后端（存储+分发），是阶段 B 通知中心 UI + 阶段 D（M2 通知存储）的前提。
• 生产者 = MeowAPP（原生 IPC）+ 系统事件（系统抽象为 App） + 外部桌面 app（D-Bus 桥）。

2. 通知标准（freedesktop.org Desktop Notifications，用户约定）

遵循 org.freedesktop.Notifications（D-Bus 接口），字段严格按标准：

• app_name（来源应用名）
• replaces_id（更新/替换通知 id；0=新建）
• app_icon（图标，指 icon name 或 path）
• summary（标题，单行）
• body（正文，可多行）
• actions[]（按钮，可选；动作回调）
• hints{}（提示，含 x-canonical-*/progress/图片数据等；我们用 hints 传 target Activity、进度 percent 等）
• expire_timeout（超时 ms；-1=常驻/ONGOING，0=不自动过期）
• 返回新版通知 id。

MeowOS 扩展：hints 内加 MeowOS 专有键（如 meow.target_activity、meow.progress）用于通知中心点击跳转/进度条显示。媒体通知走 MPRIS（org.mpris.MediaPlayer2，另行）。

3. 双接口（FREWORKS 附C，已定）

1. 原生 IPC：MeowAPP 经 AF_UNIX socket 发 MSG_NOTIFY（FREWORKS §4 通定协议 0x0020）+ MSG_NOTIFY_ACK(0x0021)/DISMISS(0x0022)/LIST(0x0023)。
2. D-Bus 桥 meow_notify_dbus（独立小守护，链 libdbus/GDBus，系统总线注册 org.freedesktop.Notifications）：收到标准 Notify() → 经 MeowOS IPC 后端入通知存储；后端关闭/动作 → 回发信号。libdbus-1/libdbus-glib/libgio 已确认可用。

4. 通知数据结构（存内存 + 转储）

每通知字段（对齐 freedesktop + MeowOS）：

id(uint32) / app_name / app_icon / summary / body / actions[] / hints{}
expire_timeout / created_ms / dismissed / ongoing(bool)
target_activity(可选, 来自 hints) / progress(可选 int) / urgency(0-3, 缺省 NORMAL)

统一从 IPC/D-Bus 两路解析入该结构。app_icon（SDK icon）：空时按 app_id 回退该 app 默认图标（launcher 由 app.json icon 提供；通知中心 UI 兜底）。

5. 存储分层（用户已定 2026-08-29）

• 关键配置优先板载：设置类（notify.* 配额等）存板载 /usr/data/meow/settings.conf（B2a），确保无卡时系统正常工作。
• 实时通知 → 本地内存（板载，动态分配/ring）。progress 实时进度 → 仅改内存活跃槽（用户定案 2026-08-30）；落盘快照只在创建时/结束(100% 或 dismiss)，避免每条 live 写卡。
• 超时/转储 → TF 卡 MeowOS/notifications/（系统约定：系统文件统一放 MeowOS/ 下，非 MeowData/——MeowData 是应用专属数据根）（转储区，appended 日志行 CSV，见 §8）。
• 无 TF 卡可运行（本地内存态即可，不依赖卡；TF 卡在时才转储）。转储/日志类是可降级数据（无卡用 /tmp 回退），配置类永远板载。
• 本地数据清理策略：
  • 关机/重启前 → 清理本地内存通知数据（正常关机路径）。
  • 异常关机（重启后）→ 开机时识别并清理本地残留。
• TF 卡转储区：保留最新 10MB（ring/截断），不被电源事件清理（持久留存）。

6. 通知生命周期（FREWORKS §4 已定，作参考）

• 内存态：每应用配额（待讨论 §7），满丢最旧；ttl 过期（1s 粒度）；ONGOING 常驻（服务死随清）。
• 转储：超时/入 TF 卡区。

7. 【已定】应用配额（用户拍板，2026-08-29）

• 每个 App 最多申请 4 个通知类型（category）。
• 每个类型活跃（未过期）通知上限 4 条。
• 媒体通知除外：单个 App 只允许保留 1 个媒体通知；允许多个媒体 App 同时（多应用同时播放场景），UI/逻辑后期处理好。
• 数据类型：notify.category(App 声明用哪些类型，≤4) / notify.category_quota(每类型 4，默认)。
• 系统事件：系统也抽象为 App（app_id=system），同样走配额（系统通知也占"系统"App 的类型/条数配额）。
• 配额只管内存活跃态；转储到 TF 的历史不受配额限制（只受 10MB 总量）。

8. 转储规则（用户拍板，2026-08-29）

• 通知创建 10 秒后自动转储到 TF 卡（无论是否过期/被清）——通知中心显示"最近 10 秒内活跃" + TF 归档历史。
• 正常电源事件（关机/重启）触发清除板载通知数据之前：先转储所有未上卡的通知，再清除板载。
• 异常关机：开机时清理板载残留通知数据。
• TF 卡转储区 MeowOS/notifications/：保留最新 10MB（ring/截断），不被电源事件清理（持久留存）。
• 转储格式（定案 #6，M2.5x）：MeowOS/notifications/ 写为 appended 日志行（每条通知一行，CSV 风格：id,app_id,分类,标题,时间,…），按总大小滚动截断（保留最新 10MB）。与既有「10s 转储」衔接：创建 10s 后即按此格式追加一行 [源:用户 2026-08-30]。
• CSV 列（模型补全，2026-08-30）：timestamp,id,app_id,app_icon,category,urgency,progress,title,body,target_activity,ongoing,media,dismissed（urgency 0-3、progress 当前值 -1=无；app_icon=SDK icon，空→app 图标回退）。
• progress 落盘规则（模型补全，用户定案）：里程碑落盘——快照只在创建时 + 结束(100% 或 dismiss) 触发；实时进度（meow_notify_update_progress → MSG_NOTIFY_PROGRESS）仅改内存活跃槽，不每帧落盘。
• 启动时清板载 + 清内存通知表：开机（含异常关机后）清理板载残留通知数据，并清空内存通知表（在既有「异常关机：开机时清理板载残留」基础上补充内存表一并清）；正常关机/重启前先转储未上卡通知再清板载（沿用既有规则）[源:用户 2026-08-30]。
• 无 TF 卡：系统可运行（内存态通知即可），不依赖卡。

9. 通知中心 UI（阶段 B）—— 归属定案 [源:2026-08-30]

• 渲染主体 = 系统进程（meow_launcherd），非 APP：通知中心 UI 由系统进程负责渲染（复用 SDK 控件/状态栏基底）；APP 进程不渲染通知中心（系统级控件仅内部，见 MEOW_APP_SDK §6.1 ③、FRAMEWORK_DESIGN §10.2）。
• 数据来源：通知列表经 IPC 从通知存储/通知服务读（如 MSG_NOTIFY_LIST 重同步、target_activity/progress/icon 等字段），launcher 只做 UI 呈现与手势，不各画各的。
• 交互：状态栏下滑展开（用户已定）；上滑 / 点面板外关；左缘返回关（与全局左缘返回/顶部滑条按起始位置分流，见 spec-ref §5.1）。列表显示通知（app 图标 + summary + body + target Activity），点击按路由表解析跳转（M3 导航栈），下拉关闭/清除。
• 协议/约束：遵守 freedesktop 字段（summary/body/app_icon/actions/hints/expire_timeout/replaces_id）、配额（每 App 4 类型×每类型 4、媒体单例）、TTL、转储（10s + MeowOS/notifications/ 10MB ring）、urgency/icon/progress（见 §5-§8）。
• 依赖：M2 存储 + M3 导航栈（点击跳转）+ SDK 控件基座。阶段 B 进行中。（叠加/与播放器帧备份的互斥边界见 DEV_NOTES #16。）
• App 前台变体（跨进程，[源:2026-08-30]）：全屏 App 前台时，App 进程内顶部下滑也能唤起通知中心——App 进程只检测手势并经 IPC 上报（MSG_NOTIF_OPEN，见 FRAMEWORK_DESIGN §10.5），通知中心仍由 launcher 渲染（SIGSTOP App+读回其帧+叠加 run_notif_center+接管输入+关闭恢复），符合本节「渲染主体=系统进程（launcher）」。 仍遵守 freedesktop 字段/配额/TTL/urgency/icon/progress（§5-§8），数据在 launcher meow_notif 直读，不跨进程传全量。

10. 分步实施建议

1. M2a 通知存储 + 原生 IPC：按上面的配额（category 级）+ TTL 10s 转储钩子 + 系统事件源（系统作 App）。→ 可先落地。
2. M2b D-Bus 桥 meow_notify_dbus（org.freedesktop.Notifications 桥接）。
3. M2c 转储 TF 卡 + 10MB 保留 + 关机前转储/开机清理。
4. M5 通知中心 UI（阶段 B）+ media 通知(MPRIS)。