docs: ai 协作文档体系重构与多 ai 仲裁结果落地

1.AI 协作文档体系重构(objections/worklines/contracts+matrix.md)

2.coord 仲裁文档(final-decisions/cross-review/final-rulings/orchestration)

3.各服务 01/02 文档补全

4.共享包初始化(shared-ts/shared-go/hooks/ui-components/ui-tokens)

5.Proto 契约补全

6.004 架构影响地图更新

7.端口分配表

8.设计规格文档

services/msg/docs/01-understanding.md

@@ -0,0 +1,191 @@
+# 模块理解确认书 — 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](../../../docs/architecture/ai-allocation.md)、[004 架构影响地图](../../../docs/architecture/004_architecture_impact_map.md)、[pending-features.md](../../../docs/architecture/roadmap/pending-features.md)、[known-issues.md](../../../docs/troubleshooting/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](../src/config/env.ts)）
+
+## 2. 我的限界上下文
+
+- **聚合职责**：管理 Notification（通知）聚合 + NotificationPreference（用户通知偏好）
+- **我的数据属于**：D5 沟通通知领域
+- **我不负责**：
+  - 不负责 WebSocket 长连接管理（由 push-gateway 承载）
+  - 不负责业务数据变更（仅消费事件触发通知）
+  - 不直接访问 core-edu / iam 的数据库
+- **现有骨架领域模块**（1 个，见 [msg/src](../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](../../../packages/shared-proto/proto/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](../src/shared/errors/application-error.ts)）
+- **权限点**（3 个，见 [permission.guard.ts](../src/middleware/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 服务）
+
+- [x] 权限装饰器 `@RequirePermission`（3 个 MSG_* 权限点，全部 Controller 方法已覆盖）
+- [x] 错误码前缀统一（`MSG_*`）
+- [x] logger / metrics / tracer 三支柱（已具备）
+- [x] `/healthz` 健康检查（HealthModule 已注册）
+- [⚠️] `/readyz`（**仅检查 DB `SELECT 1`，未检查 ES 连通性**，ES 故障时仍返回 ok）
+- [x] 优雅关闭 SIGTERM（main.ts 已处理：app.close → closeEs → closeDb → shutdownTracer）
+- [ ] 测试覆盖率 ≥ 80%（**当前 0%**，无测试文件）
+- [x] Dockerfile 多阶段构建（已具备）
+- [x] Zod 输入验证（Controller 用 `schema.parse(body)`；**GlobalErrorFilter 已识别 ZodError 返回 400**，见 [global-error.filter.ts](../src/shared/errors/global-error.filter.ts) L32-42，ai10 复核修正）
+- [x] 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](../src/shared/errors/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](../../../.trae/rules/project_rules.md) 与 [known-issues §2.2 classes 黄金模板](../../../docs/troubleshooting/known-issues.md)
+
+| 服务 | 权限装饰器      | 错误码前缀 | 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](./02-architecture.md)：
+   - msg 模块架构设计文档（含通知渠道抽象策略模式、ES 降级查询、Kafka 消费幂等、push-gateway 推送协议、通知模板、已读/未读状态管理）
+3. 阶段 2 设计完成后同步更新 README（修正 §M10 文档脱节问题）
+
+---
+
+**AI Agent**: ai10 (msg)
+**Coordinator**: coord-ai
+**Branch**: 单仓库并行模式（直接 push main）