系统通知机制

设计文档 · 2026-07-13 · Spec ③(系统通知)· 状态已评审定稿 · 配套实现计划见 notifications-plan.html

目标:App 内统一通知收件箱(顶栏铃铛 + 通知列表),覆盖六类内容:重要通知 / 新特性 / 新闻 / 到账(购买·邀请·任务奖励,个人定向)/ 版本 / 活动。
送达:App 内为主(打开/回前台拉取),邮件仅兜底「重要通知」且需显式指定;系统推送(APNs/FCM)明确二期。
决策(已定):单表 + audience(user_id 空=广播)· 已读用服务端 last_read_at 水位(多端同步)· 发版脚本联动插 version 公告 · 发布走 nodectl notice 子命令。
现状底子:GET /v1/notices 空壳已在(恒空列表);openapi 已有双语 Notice schema(需扩 type/link/unread);客户端占位屏/铃铛/五条 l10n 已备;jiu 无可参考实现(其通知为二期占位)。

1 · 类型口径(单一来源)

type	标签(zh/en)	受众	典型内容	生产方式
`important`	重要 / Important	广播(可定向)	服务条款、安全、合规、线路维护	nodectl(可 `--email`)
`feature`	功能 / Feature	广播	新增大阪线路、协议选择上线	nodectl
`news`	新闻 / News	广播	产品动态、博客	nodectl
`reward`	到账 / Credited	个人定向	购买开通 ×31 天、邀请注册 +3、首充 +7、TG 任务 +3	事件钩子自动(同事务)
`version`	版本 / Update	广播	vX.Y.Z 发布 + 要点;点击接更新流程	发版脚本联动
`promo`	活动 / Promo	广播	¥6 限购上线、邀请双倍周、年付折扣	nodectl

promo 与 feature/news 的边界:让用户「花钱/参与活动」的归 promo;产品功能上新归 feature;动态资讯归 news。类型集与客户端类型 pill、原型登记、l10n 标签三处须同集(L1 闸)。

2 · 数据流总览

3 · 数据模型(迁移 000026,sqlite/mysql 两套)

notices 新表:

列	类型	说明
`id`	PK 自增
`type`	CHECK/ENUM(六值)	`important\|feature\|news\|reward\|version\|promo`
`user_id`	bigint NULL	NULL=全员广播;非空=定向该用户(比字符串 audience 可索引);FK users(id)
`title_zh / title_en`	text	双语标题(内容仅 zh/en;ja/ko/ru/es 界面回落 en)
`body_zh / body_en`	text NULL	双语正文(Markdown;reward 类一行文案可空)
`link`	text NULL	可选动作(version 类点击接更新流程等)
`published_at`	datetime	排序与未读水位比较基准(Go 端算好传 ?)
`expires_at`	datetime NULL	到期自动不再下发(promo 常用)
`revoked_at`	datetime NULL	撤回(nodectl notice revoke)
`email_sent_at`	datetime NULL	邮件兜底幂等标记(同公告只发一轮)
索引:`(user_id, published_at)`;广播查询走 user_id IS NULL 分支

users 加一列:notices_read_at DATETIME NULL —— 已读水位:published_at > notices_read_at 即未读。不做逐条已读(YAGNI,水位方案多端同步且零关联表)。

4 · API(扩现有空壳 `accountAPI.ListNotices`)

端点	行为
`GET /v1/notices`(protected)	返回 `{notices:[…], unread_count}`:合并「`user_id IS NULL` + `user_id=me`」,过滤 `revoked_at IS NOT NULL` 与 `expires_at < now`,`published_at` 倒序 limit 50;每条含 `id/type/title_zh/title_en/body_zh/body_en/link/published_at/unread`(unread 服务端按水位算)。
`POST /v1/notices/read`(protected)	`UPDATE users SET notices_read_at=?`(now)。客户端打开通知列表时调,红点全端清零。

openapi:Notice schema 增 type/link/unread,响应对象增 unread_count(现有 id/title/body/published_at 必填保持兼容)。
不做独立未读计数端点——列表响应自带,客户端启动/回前台拉列表即得红点。

5 · 生产者(三路)

5.1 nodectl notice 子命令(手工发布,important/feature/news/promo)

nodectl notice add --type important --title-zh 线路维护通知 --title-en "Line Maintenance" \
  [--body-zh …] [--body-en …] [--link …] [--expires 2026-08-01] [--email]
nodectl notice list [--all]          # 含已撤回/过期
nodectl notice revoke <id>

接入方式沿 nodectl 既有模式(直连 DB 或管理通道,以现状为准);校验:type 合法、双语标题必填、--email 仅 important 可用。
发布/撤回写 audit_log(action notice_publish/notice_revoke)。

5.2 事件自动通知(reward 类,个人定向,同事务)

事件	接缝(既有事务内追加一条 INSERT)	文案模板(双语,服务端渲染入库)
购买开通	pay `webhook.settle`(Grant→MarkPaid 之后、Commit 前)	「已开通 Pro ·31 天 / Pro activated · 31 days」
邀请注册奖励(双方)	reward `OnRegister` 两次 Grant 后	「邀请奖励 +3 天已到账 / Invite reward +3 days credited」
首充奖励(双方)	reward `OnFirstPaidTx` 两次 Grant 后	「好友首购奖励 +7 天已到账 / …+7 days credited」
TG 任务	reward `ClaimTelegram` Grant 后 Commit 前	「任务奖励 +3 天已到账 / Task reward +3 days credited」

同事务不变量:通知与发放同 COMMIT/同回滚——用户看到「到账」通知 ⟺ 权益真到账,零孤儿通知(与钱路既有纪律一致)。实现为 reward/notices 侧一个 InsertNoticeTx(ctx, tx, userID, type, …) 小函数,各接缝一行调用。

5.3 发版联动(version 类)

scripts/ci/release-client.sh 在推 version.yaml 到 pangolin1 后,追加一步经 ssh 调 nodectl notice add --type version --title-zh "vX.Y.Z 已发布" …(版本号/要点来自 tag 与 release notes)。
客户端 version 类行点击 → 走现有 update_provider/更新流程(link 承载)。

6 · 邮件兜底

范围:仅 important 且发布时显式 --email;广播=遍历 active 用户逐发,定向=单发。复用现有 SMTP mailer(auth/mailer.go 同款配置)。
幂等:notices.email_sent_at 置位后不重发;发送失败记日志继续(best-effort,不阻塞发布)。用户量增大后再演进为队列(明确非本期)。
模板一套双语合排(邮件不受 App 单显铁律约束):标题 + 正文 + 「在 App 内查看」。

7 · 客户端

noticesProvider(AsyncNotifier,照 update_provider 惯例):启动延迟数秒首拉 + 回前台重拉;缓存内存;unread_count>0 驱动铃铛红点(替换现在两处硬编码 hasUnread: true——content_top_bar 与 account_page)。
通知页真实化(notifications_page):删静态示例;行 = 类型 pill + 标题 + 相对时间(复用 relativeTime 单源)+ 未读点;点击行内展开正文(Markdown 降级纯文本渲染即可);进入页面即调 POST /read 清红点;空态用现有 notifEmpty;version 类行尾「去更新」动作接现有更新流程。
l10n:类型标签补 notifTypeReward / notifTypeVersion / notifTypePromo(六语);通知内容按 App 语言取 zh 或 en 字段(非中即英)。
原型先行(铁律):动代码前先统一两端原型通知视图——现状桌面用文字 pill、移动用图标,不一致;统一为「类型 pill + 未读点」桌面式(移动同构),并补 reward/version/promo 三类示例行 + 展开态;同一提交回填两份原型。

8 · 边界(YAGNI,本期不做)

不做 APNs/FCM 系统推送(二期;大陆 FCM 可达性另议)。
不做逐条已读 / 通知偏好按类型开关 / 管理后台页。
不做六语内容(内容 zh/en,其余界面语言回落 en)。
不做 openapi 描述里的「多镜像签名静态 JSON 副本」(意图保留,后续抗封锁专项再做)。
不做邮件队列/重试体系(现量级直发 + email_sent_at 幂等够用)。

9 · 测试要点

查询合并:广播+定向合并、他人定向不可见;revoked/expired 过滤;limit 50;倒序。
未读水位:read 前后 unread/unread_count 变化;新公告晚于水位再变未读;多“设备”(两次会话)读同一水位。
同事务:TG 领奖/首充/注册奖励成功 → reward 通知在;Grant 失败回滚 → 通知不留(孤儿为零);购买开通同款。
nodectl:类型校验、--email 限 important、revoke 后列表即消失、audit_log 两 action。
邮件:仅 important+--email 触发;email_sent_at 幂等(重复执行不再发);失败不阻塞发布。
客户端:红点由 unread_count 驱动(0 不显);进入列表调 read 后红点清;空态;version 行动作;golden(通知页多主题)。
双 DB:迁移 up/down round-trip;时间 Go 端传 ?。

10 · 涉及文件(实现锚点)

# 后端
server/migrations/{mysql,sqlite}/000026_notices.{up,down}.sql   # notices 表 + users.notices_read_at
server/internal/notices/                    # 新包:store(查询合并/水位/InsertNoticeTx)+ service(邮件兜底)+ handler
server/internal/httpapi/account.go          # ListNotices 空壳替换为真实现(或移交 notices 包)
server/internal/reward/service.go           # OnRegister/OnFirstPaidTx/ClaimTelegram 接 InsertNoticeTx
server/internal/pay/webhook.go              # settle 接购买开通通知
server/cmd/nodectl/                          # notice add/list/revoke 子命令
scripts/ci/release-client.sh                 # 发版联动插 version 公告
server/api/openapi.yaml                      # Notice schema 扩 type/link/unread + /notices/read
# 客户端
design/prototype/screens/{ui-desktop,ui-mobile}.html  # 原型先行:两端通知视图统一 + 三类新示例
client/lib/state/notices_provider.dart       # 新:拉取/未读/read
client/lib/services/notices_api.dart         # 新:GET /v1/notices + POST /read
client/lib/screens/notifications_page.dart   # 占位 → 真实
client/lib/widgets/{notification_bell,content_top_bar}.dart + screens/account_page.dart  # 红点接 provider
client/lib/l10n/                              # notifTypeReward/Version/Promo 六语

下一步:writing-plans 出逐任务实现计划(md 真相源 + HTML 阅读版),Subagent 驱动执行。与邀请奖励设计(Spec ②)的「奖励事件接缝」在 5.2 节正式接通。