faaaf29f67
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.设计规格文档
30 KiB
30 KiB
AI 工作顺序协同规划
版本：1.0 日期：2026-07-09 决策者：coord（经用户确认） 适用范围：Edu 项目 16 个 AI（ai01-ai16）+ coord 关联文档：coord-final-decisions.md、ai-allocation.md、004 §16、issues.md
0. 背景
coord-final-decisions.md 强制"首次实现即最终方案，不分阶段"，但实际执行中存在工作先后排序问题：
- teacher-bff 裁决"P2 起 GraphQL + gRPC 调下游"，但 core-edu P3 才启用 gRPC → P2 启动时 teacher-bff 调谁？
- shared-ts Outbox 工具包谁建？什么时候建？iam P2 即用
- parent-bff P4 依赖 iam.GetChildrenByParent，iam 何时补全？
本文档规划 AI 工作顺序协同，尽量保证并行，有依赖的才串行，并识别"跨度过大"问题记录到 issues.md。
1. 协同原则
| # | 原则 | 说明 |
|---|---|---|
| 1 | 批次并行 | 同批次 AI 可同时启动，互不阻塞 |
| 2 | 批次间串行 | 下批次依赖上批次产出，必须等待 |
| 3 | coord 前置 | coord 负责的 proto 契约 / 工具包 / 端口表必须在 AI 启动前就位 |
| 4 | 双向依赖协调 | 同批次内有双向依赖的 AI（如 BFF ⟷ Portal schema 契约），coord 仲裁第一版契约后并行 |
| 5 | 跨阶段扩展例外 | BFF 跨阶段补 gRPC 调用是允许的例外（因下游服务按阶段启用本身合理），不视为"中间过渡方案" |
| 6 | 疑问记录 | AI 觉得有疑问（前置依赖、跨度过大）可在 issues.md 记录，coord 统一解决 |
2. 批次总览
| 批次 | 阶段 | 可并行 AI 数 | 关键产出 | 跨度过大风险 |
|---|---|---|---|---|
| 0 | 全 AI 启动前 | coord 独立 | proto 契约 + shared-ts Outbox + 端口表统一 | shared-ts Outbox 工具包遗漏（已修正） |
| 1 | P2 | 4（ai01/ai06 + ai03⟷ai13） | iam gRPC + teacher-bff GraphQL + teacher-portal MF shell | 高（teacher-bff 调下游断裂，见 issues #4） |
| 2 | P3 | 4（ai08 + ai04⟷ai14 + ai07 交接 + ai03 扩展） | core-edu gRPC + student-bff GraphQL | 中（student-bff 调 content/data-ana 断裂） |
| 3 | P4 | 5（ai09/ai11 + ai05⟷ai15 + ai03/ai04 扩展） | content gRPC + data-ana gRPC + parent-bff GraphQL | 中（teacher-bff 跨阶段改造） |
| 4 | P5 | 4（ai10⟷ai02 + ai12 + ai03 扩展） | msg gRPC + ai gRPC + push-gateway HTTP | 低（核心依赖已前置解决） |
| 5 | P6 | 1+（ai16 + 持续优化） | admin-portal MVP + P6 硬化 | 低 |
3. 批次 0：coord + ai13 协同完成（全 AI 启动前）
总裁裁决 §6.2 最终版：批次 0 共 15 项任务，coord 负责 0.1-0.14，ai13 负责 0.15。 完成期限：3-5 天。批次 0 全部完成后才启动批次 1（见总裁裁决 §4.1 批次 0 完成信号机制）。
3.1 批次 0 详细任务清单（15 项）
| # | 责任方 | 任务 | 完成信号 | 阻塞批次 |
|---|---|---|---|---|
| 0.1 | coord | pnpm run arch:scan 更新 arch.db |
arch.db 已更新 | — |
| 0.2 | coord | 修订 coord-cross-review.md（补 coord 交叉审查结论） | 文档已更新 | — |
| 0.3 | coord | 补全 iam.proto 8 RPC（GetViewports / GetEffectivePermissions / GetEffectiveAccess / Logout / GetPublicKey / BatchGetUsers / GetEffectiveDataScope / GetChildrenByParent） |
proto 文件已提交 | 批次 1（ai06） |
| 0.4 | coord | 建立 shared-ts Outbox 工具包（含设计草案 + 实现，@edu/shared-ts/outbox） |
packages/shared-ts/src/outbox/ 已建立 | 批次 1（ai06） |
| 0.5 | coord | 补全 content.proto（ChapterService / QuestionService.* / TextbookService.ListTextbooks） |
proto 文件已提交 | 批次 3（ai09） |
| 0.6 | coord | 补全 msg.proto 基础（5 RPC + NotificationPreferenceService + NotificationTemplateService + 3 message） |
proto 文件已提交 | 批次 4（ai10） |
| 0.7 | coord | 补全 analytics.proto 基础 |
proto 文件已提交 | 批次 3（ai11） |
| 0.8 | coord | 补全 core_edu.proto（AttendanceService / GetClassesByTeacher / BatchGetClasses） |
proto 文件已提交 | 批次 2（ai08） |
| 0.9 | coord | buf.gen.yaml 补 gRPC 插件 |
buf generate 可运行 | 批次 1+ |
| 0.10 | coord | 补全 events.proto（含 AuditEvent message，总裁裁决 §5.5） |
proto 文件已提交 | 批次 5（ai16 admin-portal 审计日志） |
| 0.11 | coord | analytics.proto 扩展（4 端 Dashboard + Warning + MasteryDistribution + SubscribeMasteryUpdate Stream RPC） |
proto 文件已提交 | 批次 3（ai11） |
| 0.12 | coord | 补全 ai.proto（GenerateLessonPlan / StreamGenerateQuestion） |
proto 文件已提交 | 批次 4（ai12） |
| 0.13 | coord | 补全 msg.proto（5 RPC + NotificationPreferenceService + NotificationTemplateService + 3 message） |
proto 文件已提交 | 批次 4（ai10） |
| 0.14 | coord | 建立 packages/shared-go 包骨架（tracer/logger/jwks/env 4 模块的接口定义 + 默认实现，总裁裁决 §2.13） |
packages/shared-go/ 已建立 | 批次 1（ai01 Gateway 接入） |
| 0.15 | ai13 | 建立 packages/ui-tokens + packages/ui-components + packages/hooks 骨架（总裁裁决 §2.12） |
3 个 packages 已建立 | 批次 1（ai13 teacher-portal） |
3.2 批次 0 完成信号机制（总裁裁决 §4.1）
- coord 维护"批次 0 任务进度表"：在 ai-work-orchestration.md §3.1 表格"完成信号"列勾选
- 批次 0 全部 15 项完成后，coord 发布批次 1 启动公告（在本文件 §9 时间线末尾追加"批次 0 已完成，批次 1 启动"）
- 建立"前置依赖就绪检查清单"：coord 在批次 1/2/3/4/5 启动前逐项确认
- 批次 1 启动条件：0.1-0.15 全部完成 + teacher-bff GraphQL schema 第一版仲裁完成 + MF shell 暴露清单仲裁完成
4. 批次 1：P2 并行批
4.1 前置条件
- 批次 0 中 0.1-0.7 全部就位
4.2 可并行 AI（4 个 + 1 双向依赖对）
| AI | 服务 | 核心工作 | 依赖 | 产出 |
|---|---|---|---|---|
| ai01 | api-gateway | 补 GW_ 前缀 + /parent 路由 + W1-W8 整改 | 独立 | /parent 路由块 |
| ai06 | iam | gRPC server 50052 + 8 RPC + iam_student_guardians 表 + DB 驱动 PermissionGuard + AuthMiddleware + shared-ts Outbox 接入 | 批次 0.3 + 0.4 | iam gRPC 50052 可用（含 GetChildrenByParent） |
| ai03 ⟷ ai13 | teacher-bff ⟷ teacher-portal | GraphQL schema 契约双向依赖，coord 仲裁第一版 schema 后并行 | ai03 依赖 ai06 gRPC；ai13 依赖 ai03 schema | teacher-bff GraphQL endpoint + DownstreamClient 抽象 + teacher-portal MF shell |
4.3 协调点
- ai03 ⟷ ai13 GraphQL schema：coord 在批次 1 启动前仲裁 schema 第一版（含 Query/Mutation 清单），ai03 实现 server，ai13 实现 client，同步开发
- ai03 DownstreamClient 抽象：ai03 P2 必须产出可复用的 DownstreamClient 抽象（B8 裁决），供 ai04/ai05 复用，coord 验收时检查
4.4 跨度过大问题（见 issues.md #4-#8）
- teacher-bff P2 只能 gRPC 调 iam，调 core-edu/content/data-ana/ai/msg 全部断裂 → 见 issues #4
- teacher-bff 跨阶段持续改造与"不分阶段"原则矛盾 → 见 issues #5（coord 已裁定为例外）
5. 批次 2：P3 并行批
5.1 前置条件
- 批次 1 完成（iam gRPC 50052 + GetChildrenByParent 已就绪）
- 批次 0 中 0.8-0.9 全部就位（core_edu.proto + buf.gen.yaml gRPC 插件）
5.2 可并行 AI（4 个 + 1 双向依赖对 + 1 交接）
| AI | 服务 | 核心工作 | 依赖 | 产出 |
|---|---|---|---|---|
| ai08 | core-edu | 合并 classes + gRPC server 50053 + AttendanceService + GetClassesByTeacher + BatchGetClasses + C1-C11 整改 | ai07 classes 黄金模板代码 | core-edu gRPC 50053 可用；classes 服务下线 |
| ai07 | classes | 在 ai08 启动前完成 classes 代码交接 | — | classes 代码交接完成 |
| ai04 ⟷ ai14 | student-bff ⟷ student-portal | GraphQL schema 契约双向依赖 | ai04 依赖 ai06 gRPC + ai08 gRPC + ai03 DownstreamClient 抽象；ai14 依赖 ai04 schema + ai13 MF 共享组件 | student-bff GraphQL endpoint + student-portal MF remote |
| ai03 | teacher-bff | P3 扩展，补 gRPC 调 core-edu 50053 | ai08 core-edu gRPC | teacher-bff gRPC 调 core-edu 链路打通 |
5.3 协调点
- ai07 → ai08 classes 交接：ai07 在 ai08 启动前完成 classes 代码交接（C1 裁决"P3 开始前直接合并"）
- ai04 ⟷ ai14 GraphQL schema：coord 仲裁 student-bff schema 第一版
- ai03 跨阶段扩展：ai03 P3 补 gRPC 调 core-edu（跨阶段扩展例外，见 issues #5）
5.4 跨度过大问题
- student-bff P3 仍无法 gRPC 调 content / data-ana（P4 才启用）→ 见 issues #6
6. 批次 3：P4 并行批
6.1 前置条件
- 批次 0 中 0.10-0.11 全部就位（content.proto + analytics.proto 补全）
- 批次 2 完成（core-edu gRPC 50053 可用）
- iam.GetChildrenByParent 已就绪（批次 1 已完成）
6.2 可并行 AI（5 个 + 1 双向依赖对 + 2 跨阶段扩展）
| AI | 服务 | 核心工作 | 依赖 | 产出 |
|---|---|---|---|---|
| ai09 | content | gRPC server 50054 + ChapterService + QuestionService proto 补全（N3 裁决 P4 即补，不等到 P5）+ N1-N5 整改 | 批次 0.10 | content gRPC 50054 可用（含 QuestionService） |
| ai11 | data-ana | gRPC server 50055 + 4 端 Dashboard + Warning + MasteryDistribution + SubscribeMasteryUpdate Stream + D1-D5 整改 | 批次 0.11 | data-ana gRPC 50055 可用 |
| ai05 ⟷ ai15 | parent-bff ⟷ parent-portal | GraphQL schema 契约双向依赖 | ai05 依赖 iam.GetChildrenByParent（已就绪）+ core-edu gRPC + ai03 DownstreamClient 抽象 | parent-bff GraphQL endpoint + parent-portal MF remote |
| ai03 | teacher-bff | P4 扩展，补 gRPC 调 content + data-ana | ai09 + ai11 | teacher-bff gRPC 调 content + data-ana 链路打通 |
| ai04 | student-bff | P4 扩展，补 gRPC 调 content + data-ana | ai09 + ai11 | student-bff gRPC 调 content + data-ana 链路打通 |
6.3 协调点
- ai05 ⟷ ai15 GraphQL schema：coord 仲裁 parent-bff schema 第一版
- ai03 / ai04 跨阶段扩展：补 gRPC 调 content + data-ana（跨阶段扩展例外）
- coord 验收 ai09 P4：强制检查 QuestionService RPC 已落地（阻塞 ai12 P5 出题）
6.4 跨度过大问题
- teacher-bff P4 仍需扩展 gRPC 调 ai（P5）+ msg（P5）→ 见 issues #6
7. 批次 4：P5 并行批
7.1 前置条件
- 批次 0 中 0.12-0.13 全部就位（ai.proto + msg.proto 补全）
- 批次 3 完成（content.QuestionService RPC 已补全 + content gRPC 50054 可用）
7.2 可并行 AI（4 个 + 1 双向依赖对 + 1 跨阶段扩展）
| AI | 服务 | 核心工作 | 依赖 | 产出 |
|---|---|---|---|---|
| ai10 ⟷ ai02 | msg ⟷ push-gateway | HTTP /internal/push 契约双向依赖 | ai10 依赖批次 0.13；ai02 独立 | msg gRPC 50056 + push-gateway HTTP /internal/push |
| ai12 | ai | gRPC server 50058 + GenerateLessonPlan + StreamGenerateQuestion + Prompt DB 存储 + FastAPI BackgroundTasks + A1-A8 整改 + 调 content.QuestionService + 调 core-edu.ExamService.GetExam + 调 data-ana | 批次 0.12 + content.QuestionService（已就绪）+ core-edu gRPC（已就绪）+ data-ana gRPC（已就绪） | ai gRPC 50058 可用 |
| ai03 | teacher-bff | P5 扩展，补 gRPC 调 ai + msg | ai10 + ai12 | teacher-bff gRPC 调 ai + msg 链路打通（全部下游 gRPC 调用完成） |
7.3 协调点
- ai10 ⟷ ai02 HTTP /internal/push 契约：coord 仲裁第一版接口契约（path/body/status code），ai02 优先 1-2 天启动 /internal/push 端点，ai10 后启动调用方
- ai12 跨服务调用：调 content.QuestionService（已就绪）+ core-edu.ExamService.GetExam（已就绪）+ data-ana（已就绪），无阻塞 ✓
7.4 无跨度过大问题
- 核心依赖已通过前置裁决解决（content.QuestionService P4 补全、core-edu P3 启用、data-ana P4 启用）
8. 批次 5：P6 并行批
8.1 前置条件
- 批次 4 完成
8.2 可并行 AI（1 个 + 持续优化）
| AI | 服务 | 核心工作 | 依赖 | 产出 |
|---|---|---|---|---|
| ai16 | admin-portal | MF remote + 管理端路由骨架 + P6+ 评估 X1-X10 事项 | events.proto（P6 实施时补 admin 8 topic） | admin-portal MVP |
| 其他 AI | 持续优化 | /readyz 补下游探针、Python ErrorFilter 对齐等 §16.7.6 持续项 | — | 各服务 P6 硬化完成 |
8.3 跨度过大问题
- admin-portal 8 个新 Kafka topic 在 P6 实施时才补 events.proto message → 见 issues #14
9. 批次时间线（总裁裁决 §6.1 最终版）
总裁裁决最终版：总时间线 49-64 天（约 10-13 周）。 实际进度以各 AI 交付为准，但批次启动必须满足前置条件（见各批次 §1-§7 前置条件章节）。
| 批次 | 阶段 | 预计工作日 | 参与 AI | 关键里程碑 | 启动条件 |
|---|---|---|---|---|---|
| 批次 0 | coord 前置 | 3-5 天 | coord（0.1-0.14）+ ai13（0.15） | proto 契约 + shared-ts Outbox + shared-go + packages 骨架 | 本裁决发布后立即 |
| 批次 1 | P2 | 7-10 天 | ai01 + ai06 + ai03⟷ai13 | iam P2.1 + teacher-bff Must Have + teacher-portal P2 + Gateway 路由 | 批次 0 全部完成 |
| 批次 2 | P3 | 7-10 天 | ai08 + ai07 交接 + ai04⟷ai14 + ai03 扩展 | core-edu gRPC 50053 + student-bff + student-portal P3（7 页）+ teacher-bff P3 扩展 | 批次 1 P2.1 完成 + ai03 DownstreamClient 抽象就绪 |
| 批次 3 | P4 | 10-12 天 | ai09 + ai11 + ai05⟷ai15 + ai03/ai04 扩展 | content gRPC 50054 + data-ana gRPC 50055 + parent-bff + parent-portal P4 + teacher/student-bff P4 扩展 | 批次 2 完成 |
| 批次 4 | P5 | 12-15 天 | ai10⟷ai02 + ai12 + ai03 扩展 | msg gRPC 50056 + push-gateway + ai 服务 + teacher-bff P5 扩展 + 通知功能启用 | 批次 3 完成 |
| 批次 5 | P6 | 10-12 天 | ai16 + 持续优化 | admin-portal + 审计日志 + iam P2.2 补全 + 持续优化 | 批次 4 完成 |
总时间线：49-64 天（约 10-13 周）
9.1 批次启动前 coord 仲裁清单
| 批次 | 仲裁内容 | 完成期限 |
|---|---|---|
| 批次 1 | teacher-bff GraphQL schema 第一版（含 admin 命名空间）+ MF shell 暴露清单（含 GraphQL client 单例） | 批次 1 启动前 |
| 批次 2 | student-bff GraphQL schema 第一版 | 批次 2 启动前 |
| 批次 3 | parent-bff GraphQL schema 第一版 | 批次 3 启动前 |
| 批次 4 | /internal/push 契约（采纳 ai02 02 §4.2 作为第一版） | 批次 4 启动前 |
| 批次 5 | admin-portal schema 命名空间（复用 teacher-bff GraphQL endpoint） | 批次 5 启动前 |
9.2 批次完成信号
新流程（2026-07-09 起）：批次排期详见 issues/workline.md，仲裁异议详见 issues/coord.md。各 AI 在
issues/[模块名]_workline.md维护自己模块的甘特图。
- 批次 0 已完成：✅ 2026-07-09 coord 完成全部 14 项任务（0.1-0.14）+ ai13 完成 0.15 并回写。批次 1 启动公告：批次 0 全部就绪，批次 1（P2）正式启动。
- 0.1 arch:scan ✅（TS 14 模块 / Go 2 模块 / Proto 297 契约）
- 0.2 coord-cross-review.md 修订 ✅（§8 总裁裁决落实记录）
- 0.3 iam.proto 8 RPC ✅（12 RPC 总计）
- 0.4 shared-ts Outbox 工具包 ✅（6 文件，typecheck/lint 零错误）
- 0.5 content.proto ✅（4 service / 22 RPC）
- 0.6/0.13 msg.proto ✅（3 service / 13 RPC）
- 0.7/0.11 analytics.proto ✅（12 RPC 含 Stream）
- 0.8 core_edu.proto ✅（5 service，+ClassService +AttendanceService）
- 0.9 buf.gen.yaml gRPC 插件 ✅（go + python）
- 0.10 events.proto AuditEvent ✅（9 message）
- 0.12 ai.proto ✅（6 RPC，+GenerateLessonPlan +StreamGenerateQuestion）
- 0.14 shared-go 包骨架 ✅（tracer/logger/jwks/env 4 模块）
- 0.15 packages 骨架 ✅ ai13 已完成并回写（known-issues.md L677 + 03-long-term-architecture.md §14.1）：
- ui-tokens：coord 建立（colors/typography/spacing/shadows）
- ui-components：ai13 建立（cn/ErrorBoundary/Loading/Empty/RequirePermission 5 组件）
- hooks：ai13 建立（useAuth/usePermission/useViewports/useApi/useA11yId/useAriaLive/useToast/useTraceId 8 hooks + types）
- ISSUE-036-ai13 已闭合（删除 REST→GraphQL 过渡方案，替换为 GraphQL 客户端架构最终方案）
- 批次 1 已完成：⏳
- 批次 2 已完成：⏳
- 批次 3 已完成：⏳
- 批次 4 已完成：⏳
- 批次 5 已完成：⏳
10. coord 验收清单
每个批次完成时，coord 必须验收以下项：
10.1 批次 1 验收（P2）
- iam gRPC 50052 可用，8 个 RPC 全部实现
- iam.GetChildrenByParent 已落地（阻塞 parent-bff P4）
- iam_student_guardians 表已建立
- iam 已接入 shared-ts Outbox 工具包
- teacher-bff GraphQL endpoint 可用
- teacher-bff DownstreamClient 抽象已产出（供 ai04/ai05 复用）
- teacher-portal MF shell + 共享组件已产出
- api-gateway /parent 路由块已配置
- api-gateway 错误码已补 GW_ 前缀
10.2 批次 2 验收（P3）
- core-edu gRPC 50053 可用
- AttendanceService + GetClassesByTeacher + BatchGetClasses 已实现
- classes 服务已下线，代码合并到 core-edu
- student-bff GraphQL endpoint 可用
- student-portal MF remote 接入完成
- teacher-bff gRPC 调 core-edu 链路打通
10.3 批次 3 验收（P4）
- content gRPC 50054 可用
- content.QuestionService RPC 已落地（阻塞 ai P5 出题）
- data-ana gRPC 50055 可用
- parent-bff GraphQL endpoint 可用
- parent-portal MF remote 接入完成
- teacher-bff / student-bff gRPC 调 content + data-ana 链路打通
10.4 批次 4 验收（P5）
- msg gRPC 50056 可用
- ai gRPC 50058 可用
- push-gateway HTTP /internal/push 可用
- teacher-bff gRPC 调 ai + msg 链路打通（全部下游 gRPC 调用完成）
- ai 调 content.QuestionService + core-edu.ExamService.GetExam + data-ana 链路打通
10.5 批次 5 验收（P6）
- admin-portal MVP 可用
- admin 8 个新 Kafka topic + events.proto message 已补
- 各服务 P6 硬化完成（/readyz 下游探针、Python ErrorFilter 对齐等）
11. AI 疑问记录机制
各 AI 在执行过程中若发现以下问题，必须记录到 docs/issues.md：
- 前置依赖未就绪：本 AI 工作依赖的上游产出未到位
- 跨度过大：裁决要求的工作跨度超出当前阶段合理范围
- 裁决冲突：发现 coord-final-decisions.md 内部或与其他文档冲突
- 契约不明确：与协作 AI 的接口契约未协调清楚
- 工作归属不明：某项工作应该由谁负责不明确
11.1 记录格式（见 issues.md 模板）
### ISSUE-XXX: <问题标题>
- **提请 AI**：aiXX
- **类别**：前置依赖未就绪 / 跨度过大 / 裁决冲突 / 契约不明确 / 工作归属不明
- **阶段**：P2/P3/P4/P5/P6
- **问题描述**：<详细描述>
- **影响**：<对工作的影响>
- **建议方案**：<AI 建议的解决方案>
- **状态**：待 coord 仲裁 / coord 已裁决 / 已解决
- **coord 裁决**：<coord 的裁决结果（coord 填写）>
11.2 coord 处理流程
- AI 在 issues.md 追加问题记录（状态：待 coord 仲裁）
- coord 定期（每批次结束）统一仲裁，填写 coord 裁决字段
- 状态改为"coord 已裁决"
- AI 按 coord 裁决执行，完成后状态改为"已解决"
12. 变更记录
| 日期 | 变更 | 决策者 |
|---|---|---|
| 2026-07-09 | 初始创建，规划批次 0-5 + 14 个已识别问题（见 issues.md） | coord（用户确认） |