c179af64a6
coord.md 新增 ARB-019/020/021 三章仲裁章节，修正 ARB-001。 - coord.md: 新增 ARB-019/020/021（student/parent/admin-portal 24 项） - coord.md: 修正 ARB-001（admin P2 预留/schema 文件名/classes 数据源） - 004 §4: 依赖图加 PBFF→DataAna+Msg - 004 §7.2: push-gateway→Redis 软失败标注 - 004 §11.4: 错误码前缀矩阵（11 服务+i18n key） - 004 §11.5: ActionState 信封规范（降级模式方案 B） - matrix §1: 依赖矩阵加 PBFF 边 - matrix §2: 移除 api-gateway 为 iam gRPC 消费方 - matrix §4: admin-portal→teacher-bff - matrix §5: 移除 /sse+鉴权头统一 - matrix §6: 错误码表补 i18n key 列 - 15 个 issue.md: 仲裁结论回写 - push-gateway_contract: 移除 /sse+鉴权头改 X-Internal-Token - packages/contracts: 新建包 ADMIN_* 权限点常量 AI: coord
207 lines
16 KiB
Markdown
207 lines
16 KiB
Markdown
# content 问题记录
|
||
|
||
> 负责人：ai09
|
||
> 关联：[coord.md](../coord.md)、[contracts/content_contract.md](../contracts/content_contract.md)、[../../services/content/docs/01-understanding.md](../../../services/content/docs/01-understanding.md)、[../../services/content/docs/02-architecture-design.md](../../../services/content/docs/02-architecture-design.md)
|
||
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态
|
||
|
||
---
|
||
|
||
## §0 已有仲裁核查（2026-07-10 复核）
|
||
|
||
> 复核依据：[coord-final-decisions.md §3.3](../../coord-final-decisions.md) N1-N5、[01-understanding.md §A](../../../services/content/docs/01-understanding.md) ai09 复核记录
|
||
|
||
### 0.1 coord-final-decisions.md N1-N5 核查
|
||
|
||
| 编号 | 仲裁结论 | 02-architecture-design.md 落实位置 | 核查结果 |
|
||
| ---- | -------------------------------------------- | ----------------------------------------------- | --------- |
|
||
| N1 | P4 首次实现即启用 gRPC server 50054 | §1.2 入口 HTTP 3005 / gRPC 50054；§4.2 gRPC API | ✅ 已落实 |
|
||
| N2 | 首次实现即检查 DB/Neo4j/Kafka | §6.6 /readyz 多依赖检查 | ✅ 已落实 |
|
||
| N3 | P4 即补全 QuestionService proto（不等到 P5） | §4.2.4 QuestionService 6 RPC | ✅ 已落实 |
|
||
| N4 | 首次实现即对齐 ActionState | §4.3 错误响应结构 success/error 信封 | ✅ 已落实 |
|
||
| N5 | P4 首次实现即补全 ChapterService | §4.2.2 ChapterService 3 RPC | ✅ 已落实 |
|
||
|
||
### 0.2 01-understanding.md §A 已裁决项核查
|
||
|
||
| 原编号 | 仲裁结论 | 02-architecture-design.md 落实位置 | 核查结果 |
|
||
| ------ | ------------------------------------------ | ------------------------------------------------------- | --------- |
|
||
| C2 | P4 必须引入 Outbox（004 §12.2 强制条款） | §3.1.5 content_outbox_events 表 + §5.4 Outbox Publisher | ✅ 已落实 |
|
||
| C4 | P4 必须实现 gRPC controller | §4.2 gRPC API（4 个 Service） | ✅ 已落实 |
|
||
| C10 | proto 包名保持 `next_edu_cloud.content.v1` | —（保持现状） | ✅ 已落实 |
|
||
|
||
### 0.3 核查结论
|
||
|
||
N1-N5 与 C2/C4/C10 共 8 项已有仲裁**全部在 02-architecture-design.md 中正确落实**，无遗漏、无偏离。
|
||
|
||
---
|
||
|
||
## §1 新提请异议（2026-07-10 ai09 复审）
|
||
|
||
### ISSUE-001-ai09：REST 端点设计文档与现有实现不一致
|
||
|
||
- **提请方**：ai09
|
||
- **日期**：2026-07-10
|
||
- **类型**：契约不明确
|
||
- **描述**：02-architecture-design.md §4.1 列出的 REST API 与现有源码实现存在三处偏差：
|
||
1. **knowledge-points 列表**：设计文档为 `GET /knowledge-points?chapterId=`（query 参数），源码 [knowledge-points.controller.ts](../../../services/content/src/knowledge-points/knowledge-points.controller.ts) 实现为 `GET /knowledge-points/chapter/:chapterId`（path 参数）
|
||
2. **knowledge-points 删除前置**：设计文档列 `DELETE /knowledge-points/:id/prerequisites/:prereqId`，源码未实现该端点
|
||
3. **chapters 列表**：设计文档为 `GET /chapters?textbookId=`，源码实现为 `GET /chapters/textbook/:textbookId`
|
||
- **建议方案**：以设计文档为目标态（query 参数 + 补 DELETE prerequisite 端点），在 P4 重构时统一对齐。但需 coord 确认是否允许 API 路径变更（影响 teacher-bff 消费方）。
|
||
- **状态**：待 coord 仲裁
|
||
|
||
### ISSUE-002-ai09：content 发布事件 topic 命名策略与契约文档不一致
|
||
|
||
- **提请方**：ai09
|
||
- **日期**：2026-07-10
|
||
- **类型**：契约不明确
|
||
- **描述**：事件 topic 命名存在两种策略冲突：
|
||
- **02-architecture-design.md §5.1 + §5.3 TOPIC_MAP**：每个事件类型独立 topic（`edu.content.textbook.created` / `edu.content.question.published` 等共 12 个 topic）
|
||
- **contracts/content_contract.md §1.4 + matrix.md §4**：按聚合根聚合 topic（`edu.content.knowledge_point.events` / `edu.content.question.events` 共 2 个 topic，事件类型用 `action` 字段区分）
|
||
- **events.proto**：未定义 KnowledgePointEvent / QuestionEvent message（仅 ClassEvent/ExamEvent/HomeworkEvent/GradeEvent）
|
||
- **建议方案**：采用**聚合 topic + action 字段**策略（与契约文档、matrix.md、events.proto ClassEvent 模式一致），原因：
|
||
1. 与 core-edu 既有模式（edu.exam.events / edu.homework.events 等）一致
|
||
2. 减少 topic 数量（12 → 4），降低 Kafka 集群元数据压力
|
||
3. 消费方按 action 字段过滤，订阅灵活性更高
|
||
4. 需补 `KnowledgePointEvent` / `QuestionEvent` / `TextbookEvent` / `ChapterEvent` proto message
|
||
- **状态**：待 coord 仲裁
|
||
|
||
### ISSUE-003-ai09：Textbook/Chapter 事件在契约文档遗漏
|
||
|
||
- **提请方**：ai09
|
||
- **日期**：2026-07-10
|
||
- **类型**：契约不明确
|
||
- **描述**：02-architecture-design.md §5.1 列出 4 类 textbook 事件 + 1 类 chapter 事件，但 contracts/content_contract.md §1.4 仅列出 knowledge_point 与 question 两类事件，Textbook/Chapter 事件未登记。matrix.md §4 也仅列 kp + question。导致下游（data-ana）无法感知教材/章节变更。
|
||
- **建议方案**：在 contract.md 与 matrix.md 补登记 `edu.content.textbook.events`（action: created/updated/published/archived）与 `edu.content.chapter.events`（action: created/updated/deleted）。若 coord 认为教材/章节无需对外发事件，则在 design doc §5.1 删除相关事件。
|
||
- **状态**：待 coord 仲裁
|
||
|
||
### ISSUE-004-ai09：gRPC RPC 数量三方文档不一致
|
||
|
||
- **提请方**：ai09
|
||
- **日期**：2026-07-10
|
||
- **类型**：契约不明确
|
||
- **描述**：content gRPC RPC 数量在三处文档不一致：
|
||
|
||
| Service | 02-architecture-design.md §4.2 | contracts/content_contract.md §1.1 | matrix.md §2 |
|
||
| --------------------- | ------------------------------ | ---------------------------------- | ------------ |
|
||
| TextbookService | 5（含 Update/Delete 新增） | 3（无 Update/Delete） | 18（总数） |
|
||
| ChapterService | 3（Create/List/Get） | 4（含 Update，无 Delete） | — |
|
||
| KnowledgeGraphService | 4 | 4 | — |
|
||
| QuestionService | 6（无 Publish/Search） | 7（含 Publish/Search） | — |
|
||
| **合计** | **18** | **18** | **18** |
|
||
- design doc 缺 QuestionService.PublishQuestion / SearchQuestions（contract 有）
|
||
- contract 缺 TextbookService.Update/Delete（design doc 有）
|
||
- design doc ChapterService 缺 Update（contract 有）；contract ChapterService 缺 Delete（design doc 也缺）
|
||
|
||
- **建议方案**：以 contract.md 为契约唯一源（已对齐 matrix.md 18 RPC 总数），反向修正 design doc：
|
||
1. TextbookService 补 Update/Delete（与 contract 对齐）
|
||
2. ChapterService 补 Update + Delete（design doc + contract 都缺 Delete，需补）
|
||
3. QuestionService 补 PublishQuestion + SearchQuestions（与 contract 对齐）
|
||
4. 最终 RPC 总数：TextbookService 5 + ChapterService 5 + KnowledgeGraphService 4 + QuestionService 7 = **21 RPC**（需同步更新 matrix.md §2 的 18 → 21）
|
||
- **状态**：待 coord 仲裁
|
||
|
||
### ISSUE-005-ai09：core-edu → content 失效事件 topic 无定义
|
||
|
||
- **提请方**：ai09
|
||
- **日期**：2026-07-10
|
||
- **类型**：前置依赖缺失
|
||
- **描述**：02-architecture-design.md §5.2 列出 content 消费 `edu.teaching.content.invalidated`（待 ai03 确认 topic），但：
|
||
1. events.proto 无 ContentInvalidatedEvent message
|
||
2. matrix.md §4 未登记该 topic
|
||
3. core-edu 设计文档（ai08）未明确发布该事件
|
||
4. 01-understanding.md §5 也标注"具体 topic 待 core-edu ai03 设计确认"——此处 ai03 疑为笔误，core-edu 实际由 ai08 负责
|
||
- **建议方案**：content 不主动消费 core-edu 失效事件（content 是上游内容提供方，core-edu 是消费方），删除 §5.2 中该条目；若确有联动需求，由 core-edu 主动调用 content gRPC UpdateQuestion 状态变更，而非事件驱动。
|
||
- **状态**：待 coord 仲裁
|
||
|
||
### ISSUE-006-ai09：文档结尾"直接 push main"与项目规则冲突
|
||
|
||
- **提请方**：ai09
|
||
- **日期**：2026-07-10
|
||
- **类型**：其他
|
||
- **描述**：01-understanding.md 末尾与 02-architecture-design.md 末尾均标注 `Branch: 单仓库并行模式（直接 push main）`，但 [project_rules §8 Git 工作流](../../../../.trae/rules/project_rules.md) 明确规定：
|
||
- §8：分支开发，AI 不得自行切换/创建/合并分支
|
||
- §14.3：AI 禁止 `git merge`、`git push origin main`
|
||
- 当前 worktree 分支为 `feat-review-content-module-docs-WAIyMA`
|
||
- **建议方案**：删除两份文档末尾"单仓库并行模式（直接 push main）"字样，改为 `Branch: feat-review-content-module-docs-WAIyMA（分支开发，提交后通知人类合并）`。
|
||
- **状态**：待 coord 仲裁
|
||
|
||
### ISSUE-007-ai09：questions 表 created_by 字段迁移风险
|
||
|
||
- **提请方**：ai09
|
||
- **日期**：2026-07-10
|
||
- **类型**：其他
|
||
- **描述**：02-architecture-design.md §3.1.4 questions 表新增 `created_by varchar(32) NOT NULL`，但现有 [questions.schema.ts](../../../services/content/src/questions/questions.schema.ts) 无该字段，且现有数据无 created_by 值。schema 迁移时 NOT NULL 约束会导致历史数据迁移失败。
|
||
- **建议方案**：迁移期间先用 `created_by varchar(32) NULL`，数据回填后再加 NOT NULL 约束；或为新数据强制要求 created_by（应用层校验），历史数据用 `'system'` 默认值回填。
|
||
- **状态**：待 coord 仲裁
|
||
|
||
### ISSUE-008-ai09：设计文档缺缓存策略与 API 版本化策略
|
||
|
||
- **提请方**：ai09
|
||
- **日期**：2026-07-10
|
||
- **类型**：其他
|
||
- **描述**：02-architecture-design.md 未涉及两个长远架构必备项：
|
||
1. **缓存策略**：[env.ts](../../../services/content/src/config/env.ts) 已预留 `REDIS_URL`，但 design doc 未设计缓存层（教材树/知识点树是典型读多写少场景，应缓存）
|
||
2. **API 版本化**：REST 端点无 `/v1/` 前缀（matrix.md §5 显示 api-gateway 路由为 `/api/v1/teacher/*`，但 content 自身端点 `/textbooks` 无版本号），未来破坏性变更无版本隔离机制
|
||
- **建议方案**：
|
||
1. P4 在 design doc §6 补"缓存策略"小节：教材树/章节树 Redis 缓存 + 失效策略（Outbox 事件触发缓存失效）
|
||
2. P4 在 design doc §4 补"API 版本化"说明：REST 端点统一加 `/v1/` 前缀（gRPC 用 proto package version）
|
||
- **状态**：待 coord 仲裁
|
||
|
||
### ISSUE-009-ai09：knowledge-points schema 实际缺 difficulty/metadata 字段
|
||
|
||
- **提请方**：ai09
|
||
- **日期**：2026-07-10
|
||
- **类型**：其他
|
||
- **描述**：02-architecture-design.md §3.1.3 knowledge_points 表列出 `difficulty tinyint NOT NULL DEFAULT 3` 与 `metadata json NULL`，但实际 [textbooks.schema.ts](../../../services/content/src/textbooks/textbooks.schema.ts) 中 `knowledgePoints` 表仅含 id/chapterId/title/description 四个字段，无 difficulty 与 metadata。01-understanding.md C7 提到"时间戳缺失"但未提到 difficulty/metadata 缺失。
|
||
- **建议方案**：P4 schema 迁移时一并补齐 difficulty + metadata + created_at + updated_at（与 design doc §3.1.3 对齐）。
|
||
- **状态**：待 coord 仲裁
|
||
|
||
### ISSUE-010-ai09：Neo4j Sync Worker 与 ES Sync Worker 在 P4 阶段不必要
|
||
|
||
- **提请方**：ai09
|
||
- **日期**：2026-07-10
|
||
- **类型**：工作量超批
|
||
- **描述**：02-architecture-design.md §1.1 分层图将 Neo4j Sync Worker 与 ES Sync Worker 并列展示，但：
|
||
1. ES 在 P5 才引入，ES Sync Worker 在 P4 不必要
|
||
2. 当前 [knowledge-points.service.ts](../../../services/content/src/knowledge-points/knowledge-points.service.ts) 的 `safeCreateNode` 是同步双写（业务事务内写 Neo4j），与 design doc §0.1 第 3 条"禁止业务事务内同步双写"原则冲突
|
||
3. P4 应改为 Outbox 事件驱动异步同步 Neo4j，但 design doc §1.1 图中 Neo4j Sync Worker 的输入源同时画了"Kafka Consumer"与"CONSUMER"，链路不清晰
|
||
- **建议方案**：
|
||
1. §1.1 图中明确标注 ES Sync Worker 为 P5 组件（虚线或灰显）
|
||
2. §1.1 图中 Neo4j Sync Worker 的输入仅来自 content 自身 Outbox 事件（不消费 core-edu 事件）
|
||
3. P4 任务 T6 明确"重构 knowledge-points.service.ts：移除 safeCreateNode 同步写，改为发 Outbox 事件"
|
||
- **状态**：待 coord 仲裁
|
||
|
||
---
|
||
|
||
## §2 待 coord 仲裁项汇总
|
||
|
||
| # | 标题 | 阻塞性 | 状态 |
|
||
| --- | ---------------------------------------- | ------------------- | ------------- |
|
||
| 001 | REST 端点设计与实现不一致 | 🟡 P4 重构时对齐 | 待 coord 仲裁 |
|
||
| 002 | 事件 topic 命名策略冲突（独立 vs 聚合） | 🔴 阻塞 Outbox 实现 | 待 coord 仲裁 |
|
||
| 003 | Textbook/Chapter 事件在契约文档遗漏 | 🟡 契约完整性 | 待 coord 仲裁 |
|
||
| 004 | gRPC RPC 数量三方文档不一致 | 🔴 阻塞 proto 修改 | 待 coord 仲裁 |
|
||
| 005 | core-edu → content 失效事件 topic 无定义 | 🟢 建议删除 | 待 coord 仲裁 |
|
||
| 006 | "直接 push main"与项目规则冲突 | 🟡 文档修正 | 待 coord 仲裁 |
|
||
| 007 | questions.created_by 迁移风险 | 🟡 schema 迁移 | 待 coord 仲裁 |
|
||
| 008 | 缓存策略与 API 版本化策略缺失 | 🟢 长远架构 | 待 coord 仲裁 |
|
||
| 009 | knowledge-points schema 实际缺字段 | 🟡 P4 schema 迁移 | 待 coord 仲裁 |
|
||
| 010 | Sync Worker 链路与 P4 阶段不必要 | 🟡 设计澄清 | 待 coord 仲裁 |
|
||
|
||
---
|
||
|
||
## §3 仲裁结论（2026-07-10 coord）
|
||
|
||
> 详见 [coord.md §5 ARB-005](../coord.md#5-arb-005content-模块-10-项-issue-仲裁)
|
||
|
||
| ISSUE | 仲裁结论 | 执行方 |
|
||
| ----- | ------------------------------------------------------------------------------ | -------------------------------- |
|
||
| 001 | ✅ P4 重构统一 query 参数风格 + 补 DELETE prerequisite 端点 | ai09 |
|
||
| 002 | ✅ 采用聚合 topic + action 字段策略（4 聚合 topic） | ai09 + coord |
|
||
| 003 | ✅ 补登记 edu.content.textbook.events + chapter.events | ai09 已补 + coord 同步 matrix.md |
|
||
| 004 | ✅ 统一为 21 RPC（Textbook 5 + Chapter 5 + KG 4 + Question 7） | ai09 + coord |
|
||
| 005 | ✅ 删除 core-edu 失效事件条目；联动改用 gRPC 调用 | ai09 |
|
||
| 006 | ✅ 遵循总裁裁决（trunk-based development）；措辞优化 | ai09 |
|
||
| 007 | ✅ `created_by varchar(32) NOT NULL DEFAULT 'system'` | ai09 |
|
||
| 008 | ✅ P4 补缓存策略 + API 版本化说明 | ai09 |
|
||
| 009 | ✅ P4 迁移补齐 difficulty/metadata/created_at/updated_at | ai09 |
|
||
| 010 | ✅ ES Sync Worker 标 P5；Neo4j Sync Worker 仅 Outbox 输入；移除 safeCreateNode | ai09 |
|