382 lines
20 KiB
Markdown
382 lines
20 KiB
Markdown
# Msg 沟通通知中台
|
||
|
||
> 版本：1.0（P5 完整实现）
|
||
> HTTP 端口：3007 / gRPC 端口：50056
|
||
> 设计文档：[02-architecture-design.md](./docs/02-architecture-design.md)
|
||
> 契约文档：[msg_contract.md](../../docs/architecture/issues/contracts/msg_contract.md)
|
||
|
||
## 职责
|
||
|
||
沟通通知限界上下文（P5），承担：
|
||
|
||
1. **多渠道通知分发**：站内信 / 邮件 / 短信 / 推送 / 微信（策略模式 `NotificationChannel` 抽象）
|
||
2. **事件驱动 fan-out**：消费 iam / core-edu / data-ana 共 12 类 Kafka 事件触发通知
|
||
3. **CQRS 读写分离**：MySQL 写模型 + Elasticsearch 全文检索 + Redis 位图（已读状态降级）
|
||
4. **Push Gateway 解耦**：通过 HTTP POST `/internal/push` 委托 push-gateway 推送实时通知（coord M4 仲裁豁免 gRPC）
|
||
5. **Outbox 事务性事件**：通知发送 / 已读 / 撤回 / 失败 4 类事件经 Outbox 模式投递到 Kafka
|
||
6. **幂等去重三层防线**：Redis SETNX + processed_events 表 + event_id UNIQUE INDEX
|
||
|
||
## 技术栈
|
||
|
||
| 层 | 技术 | 版本 |
|
||
| --------- | ----------------------------------------------------------- | ------ |
|
||
| 运行时 | Node.js | 22 |
|
||
| 框架 | NestJS（HTTP + gRPC 双协议 microservice） | 10 |
|
||
| 语言 | TypeScript（ESM 模式） | 5 |
|
||
| ORM | Drizzle ORM（函数式 `getDb()`） | latest |
|
||
| 写模型 | MySQL | 8.0 |
|
||
| 读模型 | Elasticsearch（safeIndex/safeSearch 降级） | 8 |
|
||
| 缓存/位图 | Redis（幂等去重 + 已读位图） | 7 |
|
||
| 消息 | Kafka（KafkaJS，producer + consumer） | 3.x |
|
||
| 可观测性 | pino + prom-client + OpenTelemetry SDK | — |
|
||
| ID | cuid2（varchar(32)） | — |
|
||
| 契约 | protobuf（`packages/shared-proto/proto/msg.proto`，17 RPC） | buf v2 |
|
||
|
||
## 架构分层
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
subgraph Gateway
|
||
AG[api-gateway]
|
||
end
|
||
subgraph BFF
|
||
TBFF[teacher-bff]
|
||
end
|
||
subgraph MsgService[msg service · HTTP:3007 + gRPC:50056]
|
||
HTTP[HTTP Controller]
|
||
GRPC[gRPC Controller · 3 Service 17 RPC]
|
||
SVC[Application Service · notifications/preferences/templates]
|
||
DISP[ChannelDispatcher · 策略模式]
|
||
CH[InApp/Email/SMS/Push/WeChat Channels]
|
||
KAFKA_C[KafkaConsumer · 12 类事件]
|
||
OUTBOX[OutboxPublisher · 4 类事件]
|
||
REPO[Repository · Drizzle]
|
||
ES[Elasticsearch 读模型]
|
||
REDIS[Redis 幂等/位图]
|
||
PUSH[Push Gateway Client · HTTP]
|
||
end
|
||
AG --> HTTP
|
||
TBFF --> GRPC
|
||
KAFKA_C --> SVC
|
||
SVC --> DISP
|
||
DISP --> CH
|
||
CH --> PUSH
|
||
SVC --> REPO
|
||
SVC --> ES
|
||
SVC --> REDIS
|
||
SVC --> OUTBOX
|
||
OUTBOX -->|publish| KT[(Kafka · edu.notification.*)]
|
||
KAFKA_K[(Kafka · edu.identity/teaching/insight.*)] --> KAFKA_C
|
||
```
|
||
|
||
## 模块结构
|
||
|
||
```
|
||
services/msg/src/
|
||
├─ notifications/ # 通知限界上下文
|
||
│ ├─ notifications.controller.ts # HTTP REST（10 端点）
|
||
│ ├─ notifications.service.ts # Application Service
|
||
│ ├─ notifications.repository.ts # Drizzle 数据访问
|
||
│ ├─ notifications.schema.ts # Drizzle 表定义（4 张表）
|
||
│ └─ notifications.dto.ts # Zod 验证 + DTO
|
||
├─ preferences/ # 用户偏好限界上下文
|
||
│ ├─ preferences.controller.ts # HTTP REST（2 端点）
|
||
│ ├─ preferences.service.ts
|
||
│ ├─ preferences.repository.ts
|
||
│ └─ preferences.dto.ts
|
||
├─ templates/ # 通知模板限界上下文
|
||
│ ├─ templates.controller.ts # HTTP REST（6 端点）
|
||
│ ├─ templates.service.ts
|
||
│ ├─ templates.repository.ts
|
||
│ └─ templates.dto.ts
|
||
├─ channels/ # 多渠道分发（策略模式）
|
||
│ ├─ channel.types.ts # NotificationChannelStrategy 接口
|
||
│ ├─ channel-dispatcher.service.ts # ChannelDispatcher 编排
|
||
│ ├─ in-app.channel.ts
|
||
│ ├─ email.channel.ts
|
||
│ ├─ sms.channel.ts
|
||
│ ├─ push.channel.ts # 走 PushGatewayClient
|
||
│ └─ wechat.channel.ts
|
||
├─ grpc/ # gRPC 入口（3 Service 17 RPC）
|
||
│ ├─ grpc.module.ts
|
||
│ ├─ notifications.grpc.controller.ts # 9 RPC
|
||
│ ├─ preferences.grpc.controller.ts # 2 RPC
|
||
│ └─ templates.grpc.controller.ts # 6 RPC
|
||
├─ config/ # 配置
|
||
│ ├─ env.ts # @t3-oss/env-nextjs + Zod
|
||
│ ├─ database.ts # getDb() 函数式
|
||
│ ├─ elasticsearch.ts # safeIndex/safeSearch 降级
|
||
│ └─ grpc.ts # gRPC microservice options
|
||
├─ middleware/
|
||
│ ├─ auth.middleware.ts # JWT 校验 + userId/roles 注入
|
||
│ └─ permission.guard.ts # @RequirePermission 3 个权限点
|
||
├─ shared/
|
||
│ ├─ errors/
|
||
│ │ ├─ application-error.ts # 13 个错误码
|
||
│ │ └─ global-error.filter.ts # GlobalErrorFilter
|
||
│ ├─ health/
|
||
│ │ └─ health.controller.ts # /healthz + /readyz（5 项依赖）
|
||
│ ├─ kafka/
|
||
│ │ ├─ kafka.client.ts # producer + consumer + isKafkaHealthy
|
||
│ │ ├─ kafka.consumer.ts # 12 类事件路由
|
||
│ │ └─ topic-map.ts # PRODUCER_TOPIC_MAP + CONSUMER_TOPICS
|
||
│ ├─ lifecycle/
|
||
│ │ └─ lifecycle.service.ts # DB/ES/Redis/Kafka/Outbox 生命周期
|
||
│ ├─ observability/
|
||
│ │ ├─ logger.ts # pino
|
||
│ │ ├─ metrics.ts # 15 个业务指标
|
||
│ │ └─ tracer.ts # OpenTelemetry SDK
|
||
│ ├─ outbox/
|
||
│ │ ├─ outbox.publisher.ts # 轮询 pending 投递 Kafka
|
||
│ │ ├─ outbox.repository.ts # findPending/markPublished/incrementRetry
|
||
│ │ ├─ outbox.service.ts # 事务内写入 outbox
|
||
│ │ └─ outbox.schema.ts # msg_outbox_events + processed_events
|
||
│ ├─ push/
|
||
│ │ └─ push-gateway.client.ts # HTTP POST /internal/push（M4 仲裁）
|
||
│ └─ redis/
|
||
│ ├─ redis.client.ts # getRedis/checkRedisConnection/closeRedis
|
||
│ └─ idempotency.guard.ts # checkAndMark（Redis SETNX + DB 降级）
|
||
├─ app.module.ts # 根 Module
|
||
└─ main.ts # HTTP + gRPC 双协议启动
|
||
```
|
||
|
||
## API 清单
|
||
|
||
### HTTP REST（18 端点）
|
||
|
||
#### Notifications（10 端点）
|
||
|
||
| 方法 | 路径 | 权限点 | 说明 |
|
||
| ------ | ---------------------------------------- | ----------------------- | ----------------- |
|
||
| POST | /notifications/send | MSG_NOTIFICATION_SEND | 单条发送 |
|
||
| POST | /notifications/batch | MSG_NOTIFICATION_SEND | 批量发送 |
|
||
| GET | /notifications/user/:userId | MSG_NOTIFICATION_READ | 列表（分页+过滤） |
|
||
| GET | /notifications/user/:userId/unread-count | MSG_NOTIFICATION_READ | 未读数 |
|
||
| PUT | /notifications/:id/read | MSG_NOTIFICATION_READ | 标记已读 |
|
||
| PUT | /notifications/batch/read | MSG_NOTIFICATION_READ | 批量已读 |
|
||
| PUT | /notifications/read-all | MSG_NOTIFICATION_READ | 全部已读 |
|
||
| GET | /notifications/search | MSG_NOTIFICATION_READ | ES 全文检索 |
|
||
| POST | /notifications/recall | MSG_NOTIFICATION_MANAGE | 撤回广播 |
|
||
| DELETE | /notifications/:id | MSG_NOTIFICATION_MANAGE | 删除 |
|
||
|
||
#### Preferences（2 端点）
|
||
|
||
| 方法 | 路径 | 权限点 | 说明 |
|
||
| ---- | ------------------------- | ----------------------- | -------- |
|
||
| GET | /preferences/user/:userId | MSG_NOTIFICATION_READ | 查询偏好 |
|
||
| PUT | /preferences/user/:userId | MSG_NOTIFICATION_MANAGE | 更新偏好 |
|
||
|
||
#### Templates（6 端点）
|
||
|
||
| 方法 | 路径 | 权限点 | 说明 |
|
||
| ------ | ----------------- | ----------------------- | -------- |
|
||
| GET | /templates | MSG_NOTIFICATION_MANAGE | 列表 |
|
||
| POST | /templates | MSG_NOTIFICATION_MANAGE | 创建 |
|
||
| GET | /templates/:id | MSG_NOTIFICATION_MANAGE | 查询 |
|
||
| PUT | /templates/:id | MSG_NOTIFICATION_MANAGE | 更新 |
|
||
| DELETE | /templates/:id | MSG_NOTIFICATION_MANAGE | 删除 |
|
||
| POST | /templates/render | MSG_NOTIFICATION_SEND | 渲染模板 |
|
||
|
||
### gRPC（3 Service / 17 RPC）
|
||
|
||
契约源：[`packages/shared-proto/proto/msg.proto`](../../packages/shared-proto/proto/msg.proto)
|
||
包名：`next_edu_cloud.msg.v1`
|
||
|
||
#### NotificationService（9 RPC）
|
||
|
||
| RPC | 权限点 | 说明 |
|
||
| --------------------- | ----------------------- | -------- |
|
||
| SendNotification | MSG_NOTIFICATION_SEND | 单条发送 |
|
||
| BatchSendNotification | MSG_NOTIFICATION_SEND | 批量发送 |
|
||
| ListNotifications | MSG_NOTIFICATION_READ | 列表 |
|
||
| GetUnreadCount | MSG_NOTIFICATION_READ | 未读数 |
|
||
| MarkAsRead | MSG_NOTIFICATION_READ | 标记已读 |
|
||
| BatchMarkAsRead | MSG_NOTIFICATION_READ | 批量已读 |
|
||
| MarkAllAsRead | MSG_NOTIFICATION_READ | 全部已读 |
|
||
| SearchNotifications | MSG_NOTIFICATION_READ | ES 检索 |
|
||
| RecallNotification | MSG_NOTIFICATION_MANAGE | 撤回 |
|
||
|
||
#### NotificationPreferenceService（2 RPC）
|
||
|
||
| RPC | 权限点 | 说明 |
|
||
| ----------------- | ----------------------- | -------- |
|
||
| GetPreferences | MSG_NOTIFICATION_READ | 查询偏好 |
|
||
| UpdatePreferences | MSG_NOTIFICATION_MANAGE | 更新偏好 |
|
||
|
||
#### NotificationTemplateService（6 RPC）
|
||
|
||
| RPC | 权限点 | 说明 |
|
||
| -------------- | ----------------------- | ---- |
|
||
| CreateTemplate | MSG_NOTIFICATION_MANAGE | 创建 |
|
||
| GetTemplate | MSG_NOTIFICATION_MANAGE | 查询 |
|
||
| ListTemplates | MSG_NOTIFICATION_MANAGE | 列表 |
|
||
| UpdateTemplate | MSG_NOTIFICATION_MANAGE | 更新 |
|
||
| DeleteTemplate | MSG_NOTIFICATION_MANAGE | 删除 |
|
||
| RenderTemplate | MSG_NOTIFICATION_SEND | 渲染 |
|
||
|
||
## Kafka 事件流
|
||
|
||
### 消费（12 类事件）
|
||
|
||
| Topic | 来源 | 触发通知 |
|
||
| --------------------------------- | -------- | --------------------------------------- |
|
||
| edu.identity.user.created | iam | 欢迎通知 |
|
||
| edu.identity.user.updated | iam | （幂等标记，无通知） |
|
||
| edu.identity.user.deleted | iam | （幂等标记，无通知） |
|
||
| edu.identity.user.role_changed | iam | 角色变更通知 |
|
||
| edu.identity.role.created | iam | （幂等标记，无通知） |
|
||
| edu.identity.role.updated | iam | 权限变更通知（fan-out affectedUserIds） |
|
||
| edu.teaching.exam.published | core-edu | 考试通知（fan-out studentIds） |
|
||
| edu.teaching.assignment.submitted | core-edu | 作业提交通知（教师） |
|
||
| edu.teaching.assignment.graded | core-edu | 作业批改通知（学生） |
|
||
| edu.teaching.grade.recorded | core-edu | 成绩录入通知 |
|
||
| edu.teaching.attendance.recorded | core-edu | 出勤异常通知（家长） |
|
||
| edu.insight.mastery.updated | data-ana | 学情预警通知 |
|
||
|
||
### 发布（4 类事件 · Outbox 模式）
|
||
|
||
| 事件类型 | Topic | 触发条件 |
|
||
| --------------------- | ------------------------- | ------------ |
|
||
| notification.sent | edu.notification.sent | 通知发送成功 |
|
||
| notification.read | edu.notification.read | 通知标记已读 |
|
||
| notification.recalled | edu.notification.recalled | 通知撤回 |
|
||
| notification.failed | edu.notification.failed | 通知发送失败 |
|
||
|
||
### 幂等去重
|
||
|
||
- **Redis SETNX**（首选）：`SETNX msg:event:{event_id} 1 EX 86400`
|
||
- **DB 降级**：`processed_events` 表 `event_id` UNIQUE INDEX
|
||
- **三层防线**：Redis → DB → 业务层 event_id 检查
|
||
|
||
## 数据库表
|
||
|
||
建表脚本：[`scripts/msg-init.sql`](../../scripts/msg-init.sql)
|
||
|
||
| 表 | 用途 | 关键索引 |
|
||
| ---------------------------- | ----------- | -------------------------------------------- |
|
||
| msg_notifications | 通知主表 | event_id UNIQUE / user_id+is_read / group_id |
|
||
| msg_notification_preferences | 用户偏好 | user_id+type UNIQUE |
|
||
| msg_notification_templates | 通知模板 | code UNIQUE |
|
||
| msg_notification_deliveries | 投递记录 | notification_id / status / next_retry_at |
|
||
| msg_outbox_events | Outbox 事件 | status+next_retry_at / topic |
|
||
| processed_events | 消费幂等 | event_id PK |
|
||
|
||
## 健康检查
|
||
|
||
| 端点 | 用途 | 检查项 |
|
||
| ------------ | --------- | -------------------------------------------------------------------- |
|
||
| GET /healthz | liveness | 仅进程状态 |
|
||
| GET /readyz | readiness | DB（关键）/ ES（可选）/ Redis（可选）/ Kafka / PushGateway（软失败） |
|
||
|
||
`/readyz` 返回结构：
|
||
|
||
```json
|
||
{
|
||
"status": "ok" | "degraded",
|
||
"service": "msg",
|
||
"timestamp": "2026-07-10T...",
|
||
"checks": {
|
||
"database": { "status": "ok" },
|
||
"elasticsearch": { "status": "ok" },
|
||
"redis": { "status": "ok" },
|
||
"kafka": { "status": "ok" },
|
||
"pushGateway": { "status": "skipped" }
|
||
}
|
||
}
|
||
```
|
||
|
||
## 可观测性
|
||
|
||
### Metrics（/metrics 端点 · 15 个指标）
|
||
|
||
| 指标 | 类型 | 标签 |
|
||
| -------------------------------------- | --------- | ------------------------ |
|
||
| msg_http_requests_total | Counter | method/route/status_code |
|
||
| msg_http_request_duration_seconds | Histogram | method/route |
|
||
| msg_grpc_requests_total | Counter | rpc_method/status |
|
||
| msg_notification_sent_total | Counter | type/channel/status |
|
||
| msg_notification_send_duration_seconds | Histogram | type/channel |
|
||
| msg_notification_failed_total | Counter | type/channel/error_code |
|
||
| msg_notification_read_total | Counter | type |
|
||
| msg_channel_dispatch_duration_seconds | Histogram | channel |
|
||
| msg_kafka_consumer_lag | Gauge | topic |
|
||
| msg_kafka_consumer_processed_total | Counter | topic/status |
|
||
| msg_idempotent_duplicate_total | Counter | topic |
|
||
| msg_outbox_pending_count | Gauge | — |
|
||
| msg_push_gateway_call_total | Counter | status |
|
||
| msg_push_gateway_call_duration_seconds | Histogram | — |
|
||
| msg_unread_count | Gauge | user_id |
|
||
|
||
### Tracer
|
||
|
||
- OpenTelemetry SDK + auto-instrumentations
|
||
- 服务名：`msg`
|
||
- OTLP exporter：`{OTEL_EXPORTER_OTLP_ENDPOINT}/v1/traces`
|
||
|
||
## 错误码
|
||
|
||
| 错误码 | HTTP | 触发条件 |
|
||
| ---------------------------- | ---- | ------------------------- |
|
||
| MSG_VALIDATION_ERROR | 400 | Zod 校验失败 |
|
||
| MSG_NOT_FOUND | 404 | 通知/偏好/模板不存在 |
|
||
| MSG_PERMISSION_DENIED | 403 | 权限不足 / 跨用户访问 |
|
||
| MSG_CONFLICT | 409 | 重复发送 / 状态机非法转换 |
|
||
| MSG_BUSINESS_ERROR | 422 | 业务规则违反 |
|
||
| MSG_DATABASE_ERROR | 500 | Drizzle 操作异常 |
|
||
| MSG_INTERNAL_ERROR | 500 | 未知异常 |
|
||
| MSG_ES_UNAVAILABLE | 503 | ES 不可用且无降级路径 |
|
||
| MSG_REDIS_UNAVAILABLE | 503 | Redis 不可用且无降级路径 |
|
||
| MSG_PUSH_GATEWAY_UNAVAILABLE | 503 | Push Gateway 不可用 |
|
||
| MSG_TEMPLATE_NOT_FOUND | 404 | 模板不存在 |
|
||
| MSG_TEMPLATE_RENDER_ERROR | 422 | 模板渲染失败（变量缺失） |
|
||
| MSG_RATE_LIMIT_EXCEEDED | 429 | 通知频率超限 |
|
||
|
||
## 开发
|
||
|
||
```bash
|
||
# 安装依赖（monorepo 根目录）
|
||
pnpm install
|
||
|
||
# 启动开发服务（HTTP:3007 + gRPC:50056）
|
||
pnpm --filter msg dev
|
||
|
||
# 构建产物
|
||
pnpm --filter msg build
|
||
|
||
# 启动生产服务
|
||
pnpm --filter msg start
|
||
```
|
||
|
||
## 环境变量
|
||
|
||
| 变量 | 默认值 | 必填 | 说明 |
|
||
| --------------------------- | ----------------- | ---- | -------------------------------------------- |
|
||
| PORT | 3007 | 否 | HTTP 端口 |
|
||
| GRPC_PORT | 50056 | 否 | gRPC 端口 |
|
||
| DATABASE_URL | — | 是 | MySQL 连接串 |
|
||
| REDIS_URL | — | 否 | Redis 连接串（未配置降级到 DB 去重） |
|
||
| JWT_SECRET | — | 否 | JWT 密钥（Gateway 已校验，可选） |
|
||
| JWT_ISSUER | next-edu-cloud | 否 | JWT 签发者 |
|
||
| KAFKA_BROKERS | localhost:9092 | 否 | Kafka broker 列表 |
|
||
| KAFKA_CLIENT_ID | msg-service | 否 | Kafka client ID |
|
||
| KAFKA_CONSUMER_GROUP_ID | msg-service-group | 否 | Kafka consumer group |
|
||
| ES_URL | — | 否 | Elasticsearch 地址（未配置则降级到 DB 查询） |
|
||
| PUSH_GATEWAY_URL | — | 否 | Push Gateway 地址（M4 仲裁 HTTP） |
|
||
| PUSH_INTERNAL_TOKEN | — | 否 | Push Gateway 内部鉴权 token |
|
||
| OTEL_EXPORTER_OTLP_ENDPOINT | — | 否 | OpenTelemetry OTLP endpoint |
|
||
| LOG_LEVEL | info | 否 | pino 日志级别 |
|
||
| NODE_ENV | development | 否 | 运行环境 |
|
||
| DEV_MODE | false | 否 | 开发模式（跳过权限校验） |
|
||
|
||
## 仲裁依据
|
||
|
||
- **M4**：Push Gateway 走 HTTP POST `/internal/push`，豁免 gRPC，鉴权头 `X-Internal-Key`
|
||
- **M5**：消费 topic 用 `edu.teaching.*` / `edu.identity.*` / `edu.insight.*`
|
||
- **G2**：/readyz 多依赖检查（DB/ES/Redis/Kafka/PushGateway）
|
||
- **G10**：getDb() 函数式（非类）
|
||
- **G11**：cuid2 ID（varchar(32)）
|
||
- **G12**：ESM 模式，相对 import 带 `.js` 后缀
|
||
- **G13**：仅类型导入用 `import type`
|
||
|
||
详见 [coord-final-decisions.md](../../docs/architecture/coord-final-decisions.md) + [president-final-rulings.md](../../docs/architecture/president-final-rulings.md)
|