Edu/services/msg/docs/01-understanding.md

模块理解确认书 — msg

AI 标识：ai05（初版）→ ai10（复核修订，按 ai-allocation.md §3.2 重新分配） 负责模块：msg（P5） 阶段：架构设计外包 · 阶段 1（全局理解） 初版日期：2026-07-09 复核修订日期：2026-07-09（ai10 接手后修正 3 处失实条目 M2/M8/M12，并补充 ai-allocation §5 缺失项） 关联文档：ai-allocation.md、004 架构影响地图、pending-features.md、known-issues.md

---

1. 我在架构中的位置

• 层级：业务微服务层（L5），DDD 限界上下文
• 业务领域：D5 沟通通知领域（004 §1.1b）
• 上游（谁调用我）：
  • teacher-bff / student-bff / parent-bff：聚合层调 msg 查询用户通知列表、发送通知
  • api-gateway：REST 转发通知请求
  • Kafka：消费 core-edu / iam 事件触发通知（004 §4.1 CoreEdu -.事件.-> Msg、IAM -.事件.-> Msg）
• 下游（我调用谁）：
  • MySQL（写模型主库，独占）
  • Elasticsearch（全文检索，已实现 safeSearch）
  • push-gateway（gRPC 推送通道，004 §4.1 PushGW → Msg，当前用 fetch POST /internal/push 降级）
• 通信方式：
  • 当前：HTTP REST（Controller，无 gRPC controller）
  • 目标态（004 §4.1 / pending-features P5）：gRPC 暴露 NotificationService
  • Kafka：消费 core-edu（ExamPublished/HomeworkGraded/GradeRecorded）、iam（UserRegistered）事件（004 §7.3）
• 端口：3007（见 msg env.ts）

2. 我的限界上下文

• 聚合职责：管理 Notification（通知）聚合 + NotificationPreference（用户通知偏好）
• 我的数据属于：D5 沟通通知领域
• 我不负责：
  • 不负责 WebSocket 长连接管理（由 push-gateway 承载）
  • 不负责业务数据变更（仅消费事件触发通知）
  • 不直接访问 core-edu / iam 的数据库
• 现有骨架领域模块（1 个，见 msg/src）：
  • notifications/：通知 CRUD + ES 全文检索 + Push Gateway 推送 + 用户偏好（6 端点）

3. 我与外部的契约

• 消费的 proto message（从 shared-proto）：
  • 消费 events.proto 的事件 message（ClassEvent/ExamEvent/HomeworkEvent/GradeEvent）
  • events.proto 当前无 NotificationEvent，若 msg 发事件需补充
• 暴露的契约（见 msg.proto，包名 next_edu_cloud.msg.v1）：
  • NotificationService：SendNotification / ListNotifications / MarkAsRead / SearchNotifications
  • 当前实现均为 REST，gRPC controller 未实现
• 事件契约：
  • 消费（004 §7.2 / §7.3）：
    • edu.identity.user.created / edu.identity.user.updated（IAM 发，msg 发欢迎通知）
    • edu.teaching.exam.published（core-edu 发，msg 推送考试通知给学生）
    • edu.teaching.assignment.submitted（core-edu 发，msg 通知教师）
    • edu.teaching.grade.recorded（core-edu 发，msg 通知学生）
    • edu.insight.mastery.updated（data-ana 发，msg 触发预警）
  • 发布：无明确（pending-features 未要求 msg 发事件）
• 错误码前缀：MSG_*（MSG_VALIDATION_ERROR / NOT_FOUND / PERMISSION_DENIED / CONFLICT / BUSINESS_ERROR / DATABASE_ERROR / INTERNAL_ERROR，见 application-error.ts）
• 权限点（3 个，见 permission.guard.ts）：
  • MSG_NOTIFICATION_SEND、MSG_NOTIFICATION_READ、MSG_NOTIFICATION_MANAGE

4. 我的技术栈

• 语言：TypeScript 5.6（ESM 模式）
• 框架：NestJS 10
• ORM：Drizzle ORM 0.31 + mysql2 3.11
• 全文检索：@elastic/elasticsearch 8.15（已实现 safeIndex/safeSearch，无 mapping 定义，依赖动态 mapping）
• 消息总线：kafkajs 2.2（已装依赖但无 consumer/producer 代码，env.ts 有 KAFKA_BROKERS 默认值）
• 推送：fetch POST 到 push-gateway /internal/push（降级模式，PUSH_GATEWAY_URL 未配置或失败时跳过）
• 幂等去重：Redis（env.ts 预留 REDIS_URL 但无 redis 客户端依赖，pending-features P5 要求 event_id 去重）
• 可观测：pino + prom-client + OpenTelemetry（三支柱已具备）

5. 我的阶段归属

• P5 沟通与 AI 阶段（pending-features §P5）：
  • 会话/消息 CRUD + 调 Push Gateway 推送 + 通知偏好
  • 多渠道（站内/SMS/邮件/微信），沿用旧项目 dispatcher 模式
  • Elasticsearch 题库全文检索（从 MySQL 同步）
• 退出标准：教师发广播通知 → 全在线学生实时收到（Push Gateway）→ AI 辅助出题流式返回 → 题库全文检索 < 200ms
• 依赖上游：P1 黄金模板 classes、P3 core-edu（事件来源）、P5 push-gateway（推送通道，ai01 设计）、P5 ai（无直接依赖）

6. 我需要对齐的黄金模板项（对照 classes 服务）

• 权限装饰器 @RequirePermission（3 个 MSG_* 权限点，全部 Controller 方法已覆盖）
• 错误码前缀统一（MSG_*）
• logger / metrics / tracer 三支柱（已具备）
• /healthz 健康检查（HealthModule 已注册）
• [⚠️] /readyz（仅检查 DB SELECT 1，未检查 ES 连通性，ES 故障时仍返回 ok）
• 优雅关闭 SIGTERM（main.ts 已处理：app.close → closeEs → closeDb → shutdownTracer）
• 测试覆盖率 ≥ 80%（当前 0%，无测试文件）
• Dockerfile 多阶段构建（已具备）
• Zod 输入验证（Controller 用 schema.parse(body)；GlobalErrorFilter 已识别 ZodError 返回 400，见 global-error.filter.ts L32-42，ai10 复核修正）
• GlobalErrorFilter 统一兜底

7. 现有骨架差距与待决策（提请 coord 仲裁）

#	差距	影响	提请决策
M1	Kafka 消费未实现：装了 kafkajs 但无 consumer 代码，无 shared/kafka/ 目录	004 §7.3 列 msg 消费 5 类事件（ExamPublished/HomeworkGraded/GradeRecorded/UserRegistered/MasteryUpdated）	阶段 2 设计需补 Kafka consumer + 幂等去重
M2	无 Outbox：骨架无 shared/outbox/	004 §7.2 明确 msg 生产 edu.notification.events（NotificationRequested，消费者 push-gateway），ai10 复核：msg 必须有 Outbox（004 §7.2/§7.3 已定义，原"无明确"判断失实）	阶段 2 设计补 Outbox（参照 core-edu outbox.publisher.ts）
M3	ES 无 mapping 定义：依赖动态 mapping，索引名 "notifications" 硬编码在 service	检索质量不稳定，索引管理缺失	阶段 2 设计补 mapping + ensureIndex
M4	无独立 repository：notifications.service.ts 直接用 db，无 repository 抽象	与黄金模板分层不一致（iam 有 repository）	阶段 2 设计补 repository 层
M5	Redis 未引入：env.ts 预留 REDIS_URL 但无 redis 客户端依赖	pending-features P5 要求 event_id 去重（Redis SETNX 或 DB 唯一索引）	阶段 2 设计决策：Redis SETNX vs DB 唯一索引
M6	createBatch 无事务/无批量优化：for 循环串行调 send，无批量 INSERT	性能瓶颈（广播场景）	阶段 2 设计改为批量 INSERT
M7	NotificationsModule 缺 exports：notifications.module.ts 无 exports: [NotificationsService]	未来 BFF 注入受阻	阶段 2 设计补 exports
M8	ZodError 未特殊处理（ai10 复核：已修复，失实条目）：GlobalErrorFilter 已识别 ZodError 返回 400（见 global-error.filter.ts L32-42）	无（已修复）	✅ 已修复，无需处理
M9	gRPC 未实现：proto 定义了 NotificationService，但无 gRPC controller	pending-features P5 未强制 gRPC	确认 P5 是否启用 gRPC（ai03 提请统一决策）
M10	README 与实现脱节：README API 表标 POST /notifications/:id/read，实际是 PUT；漏 batch/user/:userId/user/:userId/page 端点；声称"消费 Kafka 事件"但无代码	文档误导	阶段 2 设计同步修正 README
M11	main.ts 与 LifecycleService 重复关闭资源：两者都调 closeDb/closeEs	重复关闭可能报错（虽有 try-catch）	阶段 2 设计统一关闭逻辑到 LifecycleService
M12	proto 包名不一致（ai10 复核：失实条目）：实际 next_edu_cloud.msg.v1 完全符合 project_rules §5 next_edu_cloud.<domain>.v1 规范（coord 已裁决采用 next_edu_cloud.* 格式）	无（命名正确）	✅ 命名正确，无需处理

---

服务审计表 — ai10（msg 复核）

审计标准对照 project_rules §3 与 known-issues §2.2 classes 黄金模板

服务	权限装饰器	错误码前缀	logger	metrics	tracer	/healthz	/readyz	优雅关闭	测试覆盖率	Dockerfile
msg	✅ 6 端点全覆盖	✅ MSG_*	✅ pino	✅ prom-client	✅ OTel + auto-instrumentations	✅	⚠️ 仅 DB 不查 ES	⚠️ main.ts 与 LifecycleService 重复关闭	0%	✅

ai10 复核结论（ai-allocation §5 设计重点对照）

ai-allocation.md §5 对 ai10（msg）明确列出 6 项设计重点，对照现有骨架：

ai-allocation §5 设计重点	现状	阶段 2 是否需设计
通知渠道抽象（站内信/邮件/短信，策略模式）	❌ 无抽象，硬编码	✅ 必须
ES 降级查询策略（DB 不可用时走 ES 索引）	❌ 仅 ES 降级，无 DB 降级到 ES	✅ 必须
Kafka 消费幂等设计（event_id 去重 via Redis SETNX）	❌ 无 Kafka 代码	✅ 必须
与 ai02（push-gateway）的推送通道协议（gRPC）	⚠️ 用 fetch POST 降级，无 gRPC	✅ 需 gRPC 化
通知模板管理（模板 CRUD + 变量替换）	❌ 无模板模块	✅ 必须
已读/未读状态管理（Redis 位图）	❌ 仅 DB boolean	✅ 必须

新增差距（ai10 补充，原 ai05 文档遗漏）：

#	差距	影响
M13	无通知模板模块：缺 msg_notification_templates 表、模板 CRUD、变量替换、i18n	ai-allocation §5 强制要求
M14	无渠道策略抽象：send 方法硬编码 channel 判断，无 ChannelStrategy 接口	多渠道扩展困难（未来加微信/钉钉需改核心）
M15	无 Redis 位图已读/未读：isRead 仅 DB boolean，无 unread 计数缓存	高频未读数查询打 DB，广播场景性能瓶颈
M16	无 DB→ES 降级读路径：仅有 ES→空降级，无 DB 故障时走 ES 读模型	ai-allocation §5 要求 DB 不可用走 ES 索引
M17	无投放记录表：缺 msg_notification_deliveries（per-channel 投递状态）	无法追踪邮件/短信投递成功失败
M18	无幂等键：send 无 idempotencyKey 参数，重复请求会重复发通知	客户端重试导致重复通知
M19	无通知优先级/分类：缺 priority/category 字段	无法区分紧急通知与普通通知，无法按类退订
M20	无调度/延迟发送：缺 scheduledAt 字段与调度器	未来定时通知、每日摘要无法支持
M21	权限模型过简：仅 3 个权限点，硬编码 ROLE_PERMISSIONS	应对齐 iam 的 RBAC + DataScope（DATA_SCOPE=SELF/ALL）

---

跨模块契约对齐提请（coord 交叉审查）

接口一致性检查（msg 相关）

本服务声明	对方服务声明	是否匹配	备注
ai05 msg: 消费 edu.teaching.exam.published	ai03 core-edu: 发布考试事件	⚠️ 待确认	ai03 提请 topic 命名统一（004 edu.teaching.exam.published vs core-edu 代码 edu.exam.events）
ai05 msg: 消费 edu.identity.user.created	ai02 iam: 发布用户创建事件	⚠️ 待确认	ai02 设计需确认 topic
ai05 msg: 调 push-gateway /internal/push	ai01 push-gateway: 暴露推送端点	✅ 已实现	msg 当前用 fetch POST，push-gateway 已有 /internal/push 端点

全局冲突检查（msg 相关）

检查项	检查结果	备注
端口不冲突	✅ msg 3007	与 iam(3002)/classes(3001)/teacher-bff(3003)/core-edu(3004)/content(3005)/data-ana(3006)/ai(3008) 不冲突
Topic 不重复	⚠️ 待汇总	msg 仅消费不发布
错误码前缀不重叠	✅ MSG_* 唯一	与 iam IAM_* / core-edu CORE_EDU_* / content CONTENT_* 不重叠
Proto message 不遗漏	⚠️ 待确认	events.proto 无 NotificationEvent，若 msg 发事件需补充
proto 包名规范	⚠️ 不一致	实际 next_edu_cloud.<domain>.v1，规则要求 edu.<domain>.v1，提请 coord 仲裁（ai03 已提请）

待 coord 仲裁的决策项（msg 相关）

1. proto 包名统一：next_edu_cloud.* vs edu.*（ai10 复核：coord 已裁决 next_edu_cloud.*，本项目全部 proto 已采用，无需再仲裁）
2. gRPC 启用时机：P4/P5 是否启用 gRPC controller，还是继续 REST（影响 content/msg/iam/core-edu 全部服务）
3. msg Outbox：是否需要（ai10 复核：004 §7.2 已明确 msg 生产 edu.notification.events，必须有 Outbox，无需仲裁）
4. msg Redis 引入：env.ts 预留 REDIS_URL 但无依赖，幂等去重用 Redis SETNX 还是 DB 唯一索引（ai10 倾向 Redis SETNX + DB 唯一索引双保险，待 coord 确认 Redis 是否纳入 P5 基础设施）
5. events.proto 补充：msg 发 NotificationRequested 事件需追加 NotificationEvent message（coord 维护 proto）

---

下一步

1. 等待 coord 审核本确认书（ai10 复核修订完成，进入阶段 2）
2. 进入阶段 2：模块架构设计文档，按 ai-allocation.md §7 模板产出 02-architecture.md：
   • msg 模块架构设计文档（含通知渠道抽象策略模式、ES 降级查询、Kafka 消费幂等、push-gateway 推送协议、通知模板、已读/未读状态管理）
3. 阶段 2 设计完成后同步更新 README（修正 §M10 文档脱节问题）

---

AI Agent: ai10 (msg) Coordinator: coord-ai Branch: 单仓库并行模式（直接 push main）