fix: code compliance audit and fix across all services
NestJS (6 services): implement @RequirePermission decorator with SetMetadata+Reflector, register APP_GUARD globally, fix as assertions to type guards, add explicit return types, fix import type for express, fix /metrics implicit any, replace native Error with ApplicationError, remove typeorm remnants, register LifecycleService. teacher-bff: add logger, ApplicationError, GlobalErrorFilter, forward real userId to downstream, log downstream failures, migrate health controller to shared/health. Go (2 services): interface to any, doc comments, CORS dev whitelist, JWT secret fail-fast, push-gateway internal API auth, metrics and readyz endpoints, remove dead code. Python (2 services): lifespan return type, dev_mode to bool, data-ana APIRouter, ai POST body model, ClickHouse async wrapping.
This commit is contained in:
SpecialX
269
docs/architecture/ai05-phase1-understanding.md
Normal file
269
docs/architecture/ai05-phase1-understanding.md
Normal file
@@ -0,0 +1,269 @@
|
||||
# ai05 阶段 1 交付物：模块理解确认书
|
||||
|
||||
> AI 标识：ai05
|
||||
> 负责模块：content（P4）、msg（P5）
|
||||
> 阶段：架构设计外包 · 阶段 1（全局理解）
|
||||
> 日期：2026-07-09
|
||||
> 关联文档：[ai-allocation.md](./ai-allocation.md)、[004 架构影响地图](./004_architecture_impact_map.md)、[pending-features.md](./roadmap/pending-features.md)、[known-issues.md](../troubleshooting/known-issues.md)
|
||||
|
||||
---
|
||||
|
||||
## 模块理解确认书 — content
|
||||
|
||||
### 1. 我在架构中的位置
|
||||
|
||||
- **层级**：业务微服务层（L5），DDD 限界上下文
|
||||
- **业务领域**：D4 内容资源领域（004 §1.1b）
|
||||
- **上游**（谁调用我）：
|
||||
- teacher-bff（3003）：教学场景聚合，教师查教材/知识点/题库
|
||||
- student-bff（学习场景，P3 起）：学生查学习路径、知识点前置
|
||||
- ai（Python，P5）：gRPC 查询知识点/题库用于 AI 出题（004 §4.1 `AI -.gRPC.-> Content`，§9.3 AI 辅助出题流程）
|
||||
- **下游**（我调用谁）：
|
||||
- MySQL（写模型主库，独占）
|
||||
- Neo4j（知识图谱，前置依赖图）
|
||||
- Elasticsearch（题库全文检索，P4 后续补充，当前未实现）
|
||||
- **通信方式**：
|
||||
- 当前：HTTP REST（Controller，无 gRPC controller）
|
||||
- 目标态（004 §4.1 / pending-features P4）：gRPC 暴露 `TextbookService` + `KnowledgeGraphService`
|
||||
- Kafka：消费 core-edu 教学内容变更通知（004 §4.1 `CoreEdu -.事件.-> Content`）；发布 `edu.content.question.published`（004 §7.2）
|
||||
- **端口**：3005（见 [content env.ts](../../services/content/src/config/env.ts)）
|
||||
|
||||
### 2. 我的限界上下文
|
||||
|
||||
- **聚合职责**：管理 Textbook（教材）、Chapter（章节）、KnowledgePoint（知识点）、Question（题库）四个聚合
|
||||
- **我的数据属于**：D4 内容资源领域
|
||||
- **我不负责**：
|
||||
- 不负责学情分析（D6，由 data-ana 承载）
|
||||
- 不负责考试/作业/成绩（D3，由 core-edu 承载）
|
||||
- 不负责通知分发（D5，由 msg 承载）
|
||||
- 不直接访问 core-edu / iam / msg 的数据库
|
||||
- **现有骨架领域模块**（4 个，见 [content/src](../../services/content/src)）：
|
||||
- `textbooks/`：教材 CRUD（5 端点）
|
||||
- `chapters/`：章节 CRUD（5 端点，按 textbook 查询）
|
||||
- `knowledge-points/`：知识点 CRUD + Neo4j 知识图谱（7 端点，含前置链路查询/添加）
|
||||
- `questions/`：题库 CRUD（5 端点，4 种题型校验）
|
||||
|
||||
### 3. 我与外部的契约
|
||||
|
||||
- **消费的 proto message**（从 shared-proto）：
|
||||
- 无直接消费其他服务 proto；通过 Kafka 事件接收 core-edu 教学内容变更（事件契约见 `events.proto`）
|
||||
- **暴露的契约**（见 [content.proto](../../packages/shared-proto/proto/content.proto)，包名 `next_edu_cloud.content.v1`）：
|
||||
- `TextbookService`：CreateTextbook / GetTextbook / ListTextbooks
|
||||
- `KnowledgeGraphService`：GetPrerequisites / GetLearningPath
|
||||
- **当前实现均为 REST，gRPC controller 未实现**（proto 已定义待迁移）
|
||||
- **事件契约**：
|
||||
- 发布：`edu.content.question.published`（题库新增/发布，消费者 AI、ES，见 004 §7.2）
|
||||
- 消费：core-edu 教学内容变更事件（004 §4.1，具体 topic 待 core-edu ai03 设计确认）
|
||||
- **错误码前缀**：`CONTENT_*`（CONTENT_VALIDATION_ERROR / NOT_FOUND / PERMISSION_DENIED / CONFLICT / BUSINESS_ERROR / DATABASE_ERROR / INTERNAL_ERROR，见 [application-error.ts](../../services/content/src/shared/errors/application-error.ts)）
|
||||
- **权限点**（16 个，见 [permission.guard.ts](../../services/content/src/middleware/permission.guard.ts)）：
|
||||
- `CONTENT_TEXTBOOK_{CREATE,READ,UPDATE,DELETE}`
|
||||
- `CONTENT_CHAPTER_{CREATE,READ,UPDATE,DELETE}`
|
||||
- `CONTENT_QUESTION_{CREATE,READ,UPDATE,DELETE}`
|
||||
- `CONTENT_KNOWLEDGE_POINT_{CREATE,READ,UPDATE,DELETE}`
|
||||
|
||||
### 4. 我的技术栈
|
||||
|
||||
- 语言：TypeScript 5.6（ESM 模式，相对 import 带 `.js` 后缀）
|
||||
- 框架：NestJS 10
|
||||
- ORM：Drizzle ORM 0.31 + mysql2 3.11
|
||||
- 知识图谱：neo4j-driver 5.23（PREREQUISITE_OF 关系，Cypher 查询深度 1..5）
|
||||
- 全文检索：Elasticsearch（**待引入**，env.ts 预留 ES_URL 但 package.json 未装 @elastic/elasticsearch）
|
||||
- 可观测：pino logger + prom-client metrics + OpenTelemetry tracer（三支柱已具备）
|
||||
- 消息总线：Kafka（**待引入**，pending-features P4 未明确要求 content 发事件，但 004 §7.2 列了 `edu.content.question.published`）
|
||||
|
||||
### 5. 我的阶段归属
|
||||
|
||||
- **P4 内容分析阶段**（pending-features §P4）：
|
||||
- 教材/章节/知识点 CRUD（仅 CRUD，不实现检索）+ 知识图谱查询（Neo4j）+ 题库 CRUD（不实现检索）
|
||||
- MySQL schema：textbooks / chapters / knowledge_points / questions
|
||||
- Neo4j 数据：知识点前置依赖图（从 MySQL 同步）
|
||||
- CDC 链路：Debezium 监听 MySQL binlog → Kafka → data-ana 消费写 ClickHouse
|
||||
- **退出标准**：教师查看知识图谱前置依赖（Neo4j 秒级返回）→ 学生查看学情诊断（ClickHouse 宽表 5s 内返回）→ CDC 链路延迟 < 5s
|
||||
- **依赖上游**：P1 黄金模板 classes（横切关注点对齐）、P3 core-edu（教学内容变更事件，待 ai03 设计确认 topic）
|
||||
|
||||
### 6. 我需要对齐的黄金模板项（对照 classes 服务）
|
||||
|
||||
- [x] 权限装饰器 `@RequirePermission`（16 个 CONTENT_* 权限点，全部 Controller 方法已覆盖）
|
||||
- [x] 错误码前缀统一（`CONTENT_*`）
|
||||
- [x] logger / metrics / tracer 三支柱（已具备）
|
||||
- [x] `/healthz` 健康检查（HealthModule 已注册）
|
||||
- [⚠️] `/readyz`（**仅检查 DB `SELECT 1`，未检查 Neo4j 连通性**，Neo4j 故障时仍返回 ok）
|
||||
- [x] 优雅关闭 SIGTERM（main.ts 已处理：closeNeo4j → closeDb → shutdownTracer）
|
||||
- [ ] 测试覆盖率 ≥ 80%（**当前 0%**，无测试文件）
|
||||
- [x] Dockerfile 多阶段构建（已具备）
|
||||
- [⚠️] Zod 输入验证（questions 用 service 层手动 if 校验抛 ValidationError，**非 Controller 层 schema.parse**）
|
||||
- [x] GlobalErrorFilter 统一兜底
|
||||
|
||||
### 7. 现有骨架差距与待决策（提请 coord 仲裁）
|
||||
|
||||
| # | 差距 | 影响 | 提请决策 |
|
||||
| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
|
||||
| C1 | **ES 完全未实现**：env.ts 预留 ES_URL 但无 @elastic/elasticsearch 依赖、无 config/elasticsearch.ts、无 service 调用 | P4 退出标准要求题库检索，pending-features 注明"P4 仅 CRUD，P5 引入 ES" | 确认 content 的 ES 检索归属 P4 还是 P5（004 §2.2 列 ES 使用者为 Content、AI） |
|
||||
| C2 | **无 Outbox / Kafka**：骨架无 shared/outbox/，无 Kafka producer/consumer | 004 §7.2 列 `edu.content.question.published` 事件需发布 | 确认 content 是否需 Outbox（iam 无 Outbox，core-edu 有） |
|
||||
| C3 | **README 与实现脱节**：README 声称 `TextbooksService.createKnowledgeGraph` 和 `getPrerequisites`，源码中 createKnowledgeGraph 不存在，getPrerequisites 在 KnowledgePointsService | 文档误导 | 阶段 2 设计需同步修正 README |
|
||||
| C4 | **gRPC 未实现**：proto 定义了 TextbookService/KnowledgeGraphService，但无 gRPC controller | pending-features P4 未强制 gRPC，004 §4.1 目标态 gRPC | 确认 P4 是否启用 gRPC（ai03 提请统一决策） |
|
||||
| C5 | **schema 定义分散**：textbooks.schema.ts 定义 3 张表（textbooks/chapters/knowledgePoints），chapters/knowledge-points schema 仅 re-export；questions.schema.ts 独立 | 维护成本 | 阶段 2 设计统一 schema 归属 |
|
||||
| C6 | **DB 连接模式与 iam 不一致**：content 用模块级 `const db`，iam 用 `getDb()` 函数式懒加载 | 测试 mock 困难 | coord 已在 known-issues 记录"db 常量导出对齐黄金模板"，需确认统一方向 |
|
||||
| C7 | **表时间戳不统一**：textbooks/questions 有 created_at+updated_at，chapters/knowledge_points 无时间戳 | 审计追踪缺失 | 阶段 2 设计补齐 |
|
||||
| C8 | **无外键约束**：questions.knowledge_point_id → knowledge_points.id 等无 Drizzle 外键 | 引用完整性靠应用层 | 阶段 2 设计评估是否加外键 |
|
||||
| C9 | **addPrerequisite 降级策略不一致**：safeCreateNode 非阻塞（Neo4j 失败仅 warn），addPrerequisite 在 Neo4j 不可用时抛 InternalError | 行为不一致 | 阶段 2 设计统一降级策略 |
|
||||
| C10 | **proto 包名**：实际 `next_edu_cloud.content.v1`，project_rules §5 规定 `edu.content.v1` | 命名规范不一致 | **coord 仲裁**（ai03 已提请） |
|
||||
|
||||
---
|
||||
|
||||
## 模块理解确认书 — msg
|
||||
|
||||
### 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](../../services/msg/src/config/env.ts)）
|
||||
|
||||
### 2. 我的限界上下文
|
||||
|
||||
- **聚合职责**：管理 Notification（通知）聚合 + NotificationPreference（用户通知偏好）
|
||||
- **我的数据属于**：D5 沟通通知领域
|
||||
- **我不负责**：
|
||||
- 不负责 WebSocket 长连接管理（由 push-gateway 承载）
|
||||
- 不负责业务数据变更（仅消费事件触发通知）
|
||||
- 不直接访问 core-edu / iam 的数据库
|
||||
- **现有骨架领域模块**（1 个，见 [msg/src](../../services/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](../../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](../../services/msg/src/shared/errors/application-error.ts)）
|
||||
- **权限点**（3 个，见 [permission.guard.ts](../../services/msg/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 多阶段构建（已具备）
|
||||
- [⚠️] Zod 输入验证（Controller 用 `schema.parse(body)`，**但 ZodError 未在 GlobalErrorFilter 特殊处理，走默认 500 而非 400**）
|
||||
- [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/ | msg 作为通知中心，发送通知后可能需发事件（如 NotificationSent） | 确认 msg 是否需 Outbox（iam 无，core-edu 有） |
|
||||
| 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 未特殊处理**：GlobalErrorFilter 未识别 ZodError，走默认 500 | 输入校验错误返回码错误（500 而非 400） | 阶段 2 设计 GlobalErrorFilter 补 ZodError 分支（iam 已有可参考） |
|
||||
| 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 包名**：实际 `next_edu_cloud.msg.v1`，project_rules §5 规定 `edu.msg.v1` | 命名规范不一致 | **coord 仲裁**（ai03 已提请） |
|
||||
|
||||
---
|
||||
|
||||
## 三、服务审计表 — ai05
|
||||
|
||||
> 审计标准对照 [project_rules §3](../../.trae/rules/project_rules.md) 与 [known-issues §2.2 classes 黄金模板](../troubleshooting/known-issues.md)
|
||||
|
||||
| 服务 | 权限装饰器 | 错误码前缀 | logger | metrics | tracer | /healthz | /readyz | 优雅关闭 | 测试覆盖率 | Dockerfile |
|
||||
| ------- | ---------------- | -------------- | ------- | -------------- | ------------------------------- | -------- | ------------------- | --------------------- | ---------- | ---------- |
|
||||
| content | ✅ 16 端点全覆盖 | ✅ `CONTENT_*` | ✅ pino | ✅ prom-client | ✅ OTel + auto-instrumentations | ✅ | ⚠️ 仅 DB 不查 Neo4j | ✅ closeNeo4j→closeDb | 0% | ✅ |
|
||||
| msg | ✅ 6 端点全覆盖 | ✅ `MSG_*` | ✅ pino | ✅ prom-client | ✅ OTel + auto-instrumentations | ✅ | ⚠️ 仅 DB 不查 ES | ✅ closeEs→closeDb | 0% | ✅ |
|
||||
|
||||
---
|
||||
|
||||
## 四、跨模块契约对齐提请（coord 交叉审查）
|
||||
|
||||
### 4.1 接口一致性检查
|
||||
|
||||
| 本服务声明 | 对方服务声明 | 是否匹配 | 备注 |
|
||||
| --------------------------------------------------------- | ------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------ |
|
||||
| ai05 content: 暴露 KnowledgeGraphService.GetPrerequisites | ai06 ai: 调 content 查知识点（004 §9.3） | ⚠️ 待确认 | ai06 设计文档需确认调用签名 |
|
||||
| ai05 content: 暴露 TextbookService.ListTextbooks | ai03 teacher-bff: 聚合 content 查教材（004 §4.1） | ⚠️ 待确认 | ai03 设计文档需确认调用 |
|
||||
| ai05 content: 发布 `edu.content.question.published` | ai06 ai: 消费题库事件（004 §7.2 消费者 AI） | ⚠️ 待确认 | ai06 设计需确认是否消费 |
|
||||
| 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 端点 |
|
||||
|
||||
### 4.2 全局冲突检查
|
||||
|
||||
| 检查项 | 检查结果 | 备注 |
|
||||
| -------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 端口不冲突 | ✅ content 3005、msg 3007 | 与 iam(3002)/classes(3001)/teacher-bff(3003)/core-edu(3004)/data-ana(3006)/ai(3008) 不冲突 |
|
||||
| Topic 不重复 | ⚠️ 待汇总 | content 发布 `edu.content.question.published`；msg 仅消费不发布 |
|
||||
| 错误码前缀不重叠 | ✅ `CONTENT_*` / `MSG_*` 唯一 | 与 iam `IAM_*` / core-edu `CORE_EDU_*` 不重叠 |
|
||||
| Proto message 不遗漏 | ⚠️ 待确认 | events.proto 无 NotificationEvent，若 msg 发事件需补充；content.proto 缺 Update/Delete/分页（对比 classes.proto 有 page_token） |
|
||||
| proto 包名规范 | ⚠️ 不一致 | 实际 `next_edu_cloud.<domain>.v1`，规则要求 `edu.<domain>.v1`，**提请 coord 仲裁**（ai03 已提请） |
|
||||
|
||||
### 4.3 待 coord 仲裁的决策项
|
||||
|
||||
1. **proto 包名统一**：`next_edu_cloud.*` vs `edu.*`（影响全部 proto，需 coord 决策）
|
||||
2. **gRPC 启用时机**：P4/P5 是否启用 gRPC controller，还是继续 REST（影响 content/msg/iam/core-edu 全部服务）
|
||||
3. **content ES 检索归属**：P4（pending-features 注明"P4 仅 CRUD，P5 引入 ES"）vs 004 §2.2（列 ES 使用者 Content、AI）—— 需明确 content 何时引入 ES
|
||||
4. **content Outbox**：是否需要（004 §7.2 列 content 发事件，但 pending-features P4 未要求）
|
||||
5. **msg Outbox**：是否需要（msg 仅消费事件触发通知，是否需发 NotificationSent 事件）
|
||||
6. **msg Redis 引入**：env.ts 预留 REDIS_URL 但无依赖，幂等去重用 Redis SETNX 还是 DB 唯一索引
|
||||
7. **events.proto 补充**：若 msg 发事件需追加 NotificationEvent message
|
||||
|
||||
---
|
||||
|
||||
## 五、下一步
|
||||
|
||||
1. **等待 coord 审核本确认书**（§4 跨模块契约对齐 + §4.3 仲裁项）
|
||||
2. coord 放行后进入**阶段 2：模块架构设计文档**，按 ai-allocation.md §7 模板产出：
|
||||
- content 模块架构设计文档（含 Neo4j 图模型、ES 索引 mapping、题库 CRUD API、与 ai 的 gRPC 接口、教材/章节结构树）
|
||||
- msg 模块架构设计文档（含通知渠道抽象策略模式、ES 降级查询、Kafka 消费幂等、push-gateway 推送协议、通知模板、已读/未读状态管理）
|
||||
3. 阶段 2 设计完成后同步更新 README（修正 §C3/M10 文档脱节问题）
|
||||
Reference in New Issue
Block a user