2ba4250165
- monorepo: pnpm workspace + go.work + pyproject.toml + commitlint/husky - infra: docker-compose (minimal + full profiles) + init-sql + prometheus - arch-scan: multi-language scanner skeleton (TS/Go/Python/Proto) - shared-proto: buf v2 + classes.proto (ClassService CRUD contract) - api-gateway: Go/Gin + JWT HS256 auth + reverse proxy + request ID - classes: NestJS golden template (error system + observability + middleware + CRUD + tests) - teacher-portal: Next.js + paper-feel UI design system - CI/CD: 4 workflows (go/ts/py/proto) - docs: migration guide + project_rules + coding-standards + git-workflow + ui-design-system + 004 + 9 module READMEs + known-issues + spec/plan migration + roadmap
106 lines
3.1 KiB
Markdown
106 lines
3.1 KiB
Markdown
# msg 消息通知服务
|
||
|
||
> 版本：0.1（骨架）
|
||
> 日期：2026-07-07
|
||
> 状态：P5 待交付
|
||
> 关联文档：[架构影响地图](../../architecture/004_architecture_impact_map.md)
|
||
|
||
---
|
||
|
||
## 1. 模块职责
|
||
|
||
msg 是消息通知限界上下文，管理 Message、Notification、Announcement 聚合。
|
||
消费各服务领域事件，触发多渠道通知投递（站内信、邮件、短信、App 推送）。
|
||
与 push-gateway 协作建立 WebSocket/SSE 长连接，实现实时消息推送。
|
||
|
||
---
|
||
|
||
## 2. 技术栈
|
||
|
||
| 类别 | 技术 | 版本 | 用途 |
|
||
|------|------|------|------|
|
||
| 语言 | TypeScript | 5.5+ | 类型安全 |
|
||
| 框架 | NestJS | 10.x | 依赖注入、模块化 |
|
||
| ORM | Drizzle ORM | 0.31+ | 数据访问 |
|
||
| 数据库 | MySQL | 8.x | 消息持久化 |
|
||
| 缓存 | Redis | 7.x | 未读计数、会话 |
|
||
| 队列 | Kafka | - | 事件消费 |
|
||
| 模板 | Handlebars | - | 通知模板渲染 |
|
||
| 校验 | Zod | 3.23+ | 运行时校验 |
|
||
|
||
---
|
||
|
||
## 3. 架构图
|
||
|
||
```mermaid
|
||
graph TB
|
||
K[(Kafka)] -->|消费事件| MSG[msg 服务]
|
||
MSG --> DISP[Dispatcher<br/>渠道分发]
|
||
MSG -->[(MySQL<br/>消息持久化)]
|
||
MSG -->[(Redis<br/>未读计数)]
|
||
DISP --> INAPP[站内信]
|
||
DISP --> EMAIL[邮件]
|
||
DISP --> SMS[短信]
|
||
DISP --> PUSH[push-gateway<br/>实时推送]
|
||
MSG -.事件.-> K2[(Kafka<br/>edu.msg.*)]
|
||
```
|
||
|
||
> 待 P5 交付时补充完整的分层架构图与多渠道分发图。
|
||
|
||
---
|
||
|
||
## 4. 核心流程图
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant K as Kafka
|
||
participant MSG as msg
|
||
participant PG as push-gateway
|
||
participant U as 用户
|
||
|
||
K->>MSG: edu.teaching.exam.published
|
||
MSG->>MSG: 创建 Notification 记录
|
||
MSG->>MSG: Dispatcher 渠道分发
|
||
MSG->>PG: gRPC Push(userId, payload)
|
||
PG->>U: WebSocket 实时推送
|
||
MSG->>MSG: 更新未读计数（Redis）
|
||
```
|
||
|
||
> 待 P5 交付时补充：广播通知流程、通知模板渲染流程、未读计数同步流程。
|
||
|
||
---
|
||
|
||
## 5. 对外契约
|
||
|
||
- **gRPC 服务**：MessageService、NotificationService、AnnouncementService（待 P5 定义 protobuf）
|
||
- **消费事件**：`edu.identity.user.*`、`edu.teaching.*`、`edu.insight.*`
|
||
- **发布事件**：`edu.msg.notification.sent`、`edu.msg.announcement.published`
|
||
- **数据库表**：messages、notifications、announcements、notification_templates、outbox
|
||
|
||
> 待 P5 交付时补充完整 protobuf 定义与表结构。
|
||
|
||
---
|
||
|
||
## 6. 依赖关系
|
||
|
||
- **上游**：teacher-bff、student-bff、parent-bff、push-gateway（gRPC 推送调用）
|
||
- **下游**：MySQL、Redis、Kafka、外部邮件/短信网关
|
||
- **跨服务**：消费所有业务事件触发通知；与 push-gateway 协作实时推送
|
||
|
||
---
|
||
|
||
## 7. 架构约束
|
||
|
||
1. 通知投递必须至少一次语义，失败重试 3 次
|
||
2. 通知模板必须使用 Handlebars 渲染，禁止字符串拼接
|
||
3. 未读计数必须 Redis 实时维护，异步同步 MySQL
|
||
4. 广播通知必须分批投递，避免瞬时流量冲击
|
||
|
||
> 待 P5 交付时补充完整约束清单。
|
||
|
||
---
|
||
|
||
## 8. 架构决策
|
||
|
||
> 待 P5 交付时补充 ADR 记录，预计包括：多渠道分发策略、模板引擎选型、推送可靠性保证、广播限流策略。
|