M3-05 Notification Module #33

New Issue

wangdl · 2026-05-22T21:09:50+08:00

wangdl commented

2026-05-22 21:09:50 +08:00

目标

设计知习通知模块，为 C 端用户提供 App 推送、站内提醒以及为 Admin 提供到期提醒、成本提醒和任务失败通知。

背景说明

用户需要被提醒：今日复习任务、学习目标未达成、连续学习天数即将中断。Admin 需要被提醒：API Key 即将到期、成本超出预警线、导入任务大量失败。

Notification 模块管理通知渠道（Push/站内/邮件）、通知模板和用户通知偏好。

模块职责

本模块负责：
- 通知渠道管理（App Push / 站内消息 / 邮件预留）
- 通知模板管理
- 通知发送接口（供其他模块调用）
- 用户通知偏好管理
- 通知已读/未读管理
- 站内通知列表
本模块不负责：
- 通知的触发条件判断（各业务模块判断后调用 Notification 模块发送）
- 学习提醒的具体调度规则（走 Growth & Retention）
- 邮件服务器运维

候选数据对象

Notification（通知记录）
NotificationPreference（用户通知偏好）
NotificationChannel（渠道配置）
NotificationTemplate（通知模板）
PushToken（iOS/Web Push Token）

基础设施依赖判断

MySQL：是（通知记录和偏好）
Redis：需判断（批量推送队列）
BullMQ：是（批量推送异步执行）
Qdrant：否
AI Gateway：否
COS：否

API 设计

CAPI：
- 站内通知列表
- 标记已读
- 通知偏好设置
- 注册/更新 Push Token
AAPI：
- 通知模板管理
- 手动发送通知
- 通知发送日志

Domain Event 设计

NotificationSent
NotificationRead
NotificationPreferenceChanged

交付检查

是否需要 Prisma migration：是
是否需要 MySQL：是
是否需要 Redis：否（当前阶段使用 BullMQ 异步队列即可）
是否需要 BullMQ：是
是否需要 AI Gateway：否
是否需要 Cost 记录：否
是否需要 Admin 视图：是

验收标准

Notification / NotificationPreference / PushToken Prisma schema
通知发送接口设计（供其他模块调用）
站内通知 UI 方案（列表 + 未读标记）
Push 推送基础方案（iOS APNs 对接）
Admin 通知模板管理视图设计

禁止事项

禁止通知内容包含用户敏感数据
禁止 Push 推送在用户禁用后仍然发送
禁止通知发送阻塞主业务流程（应异步）

不建议当前阶段实现

邮件通知渠道
通知分组和摘要
通知发送时间智能调度（用户活跃时段）
A/B 测试通知文案

## 目标设计知习通知模块，为 C 端用户提供 App 推送、站内提醒以及为 Admin 提供到期提醒、成本提醒和任务失败通知。 ## 背景说明用户需要被提醒：今日复习任务、学习目标未达成、连续学习天数即将中断。Admin 需要被提醒：API Key 即将到期、成本超出预警线、导入任务大量失败。 Notification 模块管理通知渠道（Push/站内/邮件）、通知模板和用户通知偏好。 ## 模块职责 1. 本模块负责： - 通知渠道管理（App Push / 站内消息 / 邮件预留） - 通知模板管理 - 通知发送接口（供其他模块调用） - 用户通知偏好管理 - 通知已读/未读管理 - 站内通知列表 2. 本模块不负责： - 通知的触发条件判断（各业务模块判断后调用 Notification 模块发送） - 学习提醒的具体调度规则（走 Growth & Retention） - 邮件服务器运维 ## 候选数据对象 - Notification（通知记录） - NotificationPreference（用户通知偏好） - NotificationChannel（渠道配置） - NotificationTemplate（通知模板） - PushToken（iOS/Web Push Token） ## 基础设施依赖判断 - MySQL：是（通知记录和偏好） - Redis：需判断（批量推送队列） - BullMQ：是（批量推送异步执行） - Qdrant：否 - AI Gateway：否 - COS：否 ## API 设计 1. CAPI： - 站内通知列表 - 标记已读 - 通知偏好设置 - 注册/更新 Push Token 2. AAPI： - 通知模板管理 - 手动发送通知 - 通知发送日志 ## Domain Event 设计 - NotificationSent - NotificationRead - NotificationPreferenceChanged ## 交付检查 - [x] 是否需要 Prisma migration：是 - [x] 是否需要 MySQL：是 - [x] 是否需要 Redis：否（当前阶段使用 BullMQ 异步队列即可） - [x] 是否需要 BullMQ：是 - [x] 是否需要 AI Gateway：否 - [x] 是否需要 Cost 记录：否 - [x] 是否需要 Admin 视图：是 ## 验收标准 1. Notification / NotificationPreference / PushToken Prisma schema 2. 通知发送接口设计（供其他模块调用） 3. 站内通知 UI 方案（列表 + 未读标记） 4. Push 推送基础方案（iOS APNs 对接） 5. Admin 通知模板管理视图设计 ## 禁止事项 - 禁止通知内容包含用户敏感数据 - 禁止 Push 推送在用户禁用后仍然发送 - 禁止通知发送阻塞主业务流程（应异步） ## 不建议当前阶段实现 - 邮件通知渠道 - 通知分组和摘要 - 通知发送时间智能调度（用户活跃时段） - A/B 测试通知文案

wangdl added this to the M3：学习复习闭环（P2） milestone 2026-05-22 21:09:50 +08:00

wangdl self-assigned this 2026-05-22 21:09:50 +08:00

wangdl commented

2026-05-24 15:53:52 +08:00

✅ M3-05 实施完成

原有基础

Notification 模型、Worker（BullMQ）、Service/Controller/Repository 此前已有。

本 Issue 新增

模块	说明
`NotificationPreference`	用户通知偏好（reviewReminder/learningReminder/streakAlert/pushEnabled/quietHours）
`PushToken`	iOS/Web Push Token 注册与管理
`NotificationTemplate`	通知模板 CRUD（Admin）

领域事件（3 个）

NotificationSent → send() 调用时发布
NotificationRead → markRead() 调用时发布
NotificationPreferenceChanged → updatePreferences() 调用时发布

CAPI 端点（新增）

端点	方法	说明
`/api/notifications`	GET	通知列表（含 unreadCount）
`/api/notifications/:id/read`	POST	标记单条已读
`/api/notifications/read-all`	POST	全部标记已读
`/api/notifications/preferences`	GET	获取通知偏好
`/api/notifications/preferences`	PATCH	更新通知偏好
`/api/notifications/push-tokens`	GET	已注册 Push Token 列表
`/api/notifications/push-tokens`	POST	注册 Push Token
`/api/notifications/push-tokens/:token`	DELETE	移除 Push Token

AAPI 端点（新增）

端点	方法	说明
`/admin-api/notifications/templates`	GET	通知模板列表
`/admin-api/notifications/templates`	POST	创建通知模板
`/admin-api/notifications/templates/:id`	PATCH	更新通知模板
`/admin-api/notifications/templates/:id`	DELETE	删除通知模板
`/admin-api/notifications/send-log`	GET	通知发送日志

异步发送机制

其他模块通过 NotificationsService.send() 或 NotificationWorker（BullMQ）异步发送通知，不阻塞主业务流程。

E2E（test/m3.e2e-spec.ts）

11 tests: notification list (with unreadCount), mark all read, preferences get/update, push token register/list/remove, admin template CRUD, send log, and 401 auth checks.

npx jest --config ./test/jest-e2e.json test/m3.e2e-spec.ts  # 29 passed, 1 pre-existing failure

## ✅ M3-05 实施完成 ### 原有基础 Notification 模型、Worker（BullMQ）、Service/Controller/Repository 此前已有。 ### 本 Issue 新增 | 模块 | 说明 | |------|------| | `NotificationPreference` | 用户通知偏好（reviewReminder/learningReminder/streakAlert/pushEnabled/quietHours） | | `PushToken` | iOS/Web Push Token 注册与管理 | | `NotificationTemplate` | 通知模板 CRUD（Admin） | ### 领域事件（3 个） ``` NotificationSent → send() 调用时发布 NotificationRead → markRead() 调用时发布 NotificationPreferenceChanged → updatePreferences() 调用时发布 ``` ### CAPI 端点（新增） | 端点 | 方法 | 说明 | |------|------|------| | `/api/notifications` | GET | 通知列表（含 unreadCount） | | `/api/notifications/:id/read` | POST | 标记单条已读 | | `/api/notifications/read-all` | POST | 全部标记已读 | | `/api/notifications/preferences` | GET | 获取通知偏好 | | `/api/notifications/preferences` | PATCH | 更新通知偏好 | | `/api/notifications/push-tokens` | GET | 已注册 Push Token 列表 | | `/api/notifications/push-tokens` | POST | 注册 Push Token | | `/api/notifications/push-tokens/:token` | DELETE | 移除 Push Token | ### AAPI 端点（新增） | 端点 | 方法 | 说明 | |------|------|------| | `/admin-api/notifications/templates` | GET | 通知模板列表 | | `/admin-api/notifications/templates` | POST | 创建通知模板 | | `/admin-api/notifications/templates/:id` | PATCH | 更新通知模板 | | `/admin-api/notifications/templates/:id` | DELETE | 删除通知模板 | | `/admin-api/notifications/send-log` | GET | 通知发送日志 | ### 异步发送机制其他模块通过 `NotificationsService.send()` 或 `NotificationWorker`（BullMQ）异步发送通知，不阻塞主业务流程。 ### E2E（test/m3.e2e-spec.ts） 11 tests: notification list (with unreadCount), mark all read, preferences get/update, push token register/list/remove, admin template CRUD, send log, and 401 auth checks. ```bash npx jest --config ./test/jest-e2e.json test/m3.e2e-spec.ts # 29 passed, 1 pre-existing failure ```

wangdl closed this issue

2026-06-06 14:43:16 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: wangdl/api-server#33