xiner/Edu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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.设计规格文档
This commit is contained in:
SpecialX
2026-07-10 12:58:22 +08:00
parent 2a2a56f541
commit faaaf29f67
120 changed files with 23201 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

356
docs/architecture/ai-work-orchestration.md Normal file
View File

@@ -0,0 +1,356 @@
# AI 工作顺序协同规划
> 版本：1.0
> 日期：2026-07-09
> 决策者：coord（经用户确认）
> 适用范围：Edu 项目 16 个 AI（ai01-ai16）+ coord
> 关联文档：[coord-final-decisions.md](./coord-final-decisions.md)、[ai-allocation.md](./ai-allocation.md)、[004 §16](./004_architecture_impact_map.md)、[issues.md](../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](../issues.md)。
---
## 1. 协同原则
| # | 原则 | 说明 |
| --- | ------------------ | -------------------------------------------------------------------------------------------- |
| 1 | **批次并行** | 同批次 AI 可同时启动，互不阻塞 |
| 2 | **批次间串行** | 下批次依赖上批次产出，必须等待 |
| 3 | **coord 前置** | coord 负责的 proto 契约 / 工具包 / 端口表必须在 AI 启动前就位 |
| 4 | **双向依赖协调** | 同批次内有双向依赖的 AI（如 BFF ⟷ Portal schema 契约），coord 仲裁第一版契约后并行 |
| 5 | **跨阶段扩展例外** | BFF 跨阶段补 gRPC 调用是**允许的例外**（因下游服务按阶段启用本身合理），不视为"中间过渡方案" |
| 6 | **疑问记录** | AI 觉得有疑问（前置依赖、跨度过大）可在 [issues.md](../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）
1. **coord 维护"批次 0 任务进度表"**：在 ai-work-orchestration.md §3.1 表格"完成信号"列勾选
2. **批次 0 全部 15 项完成后，coord 发布批次 1 启动公告**（在本文件 §9 时间线末尾追加"批次 0 已完成，批次 1 启动"）
3. **建立"前置依赖就绪检查清单"**：coord 在批次 1/2/3/4/5 启动前逐项确认
4. **批次 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](../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/workline.md)，仲裁异议详见 [issues/coord.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](../issues.md)：
1. **前置依赖未就绪**：本 AI 工作依赖的上游产出未到位
2. **跨度过大**：裁决要求的工作跨度超出当前阶段合理范围
3. **裁决冲突**：发现 coord-final-decisions.md 内部或与其他文档冲突
4. **契约不明确**：与协作 AI 的接口契约未协调清楚
5. **工作归属不明**：某项工作应该由谁负责不明确
### 11.1 记录格式（见 issues.md 模板）
```markdown
### ISSUE-XXX: <问题标题>
- **提请 AI**：aiXX
- **类别**：前置依赖未就绪 / 跨度过大 / 裁决冲突 / 契约不明确 / 工作归属不明
- **阶段**：P2/P3/P4/P5/P6
- **问题描述**：<详细描述>
- **影响**：<对工作的影响>
- **建议方案**：<AI 建议的解决方案>
- **状态**：待 coord 仲裁 / coord 已裁决 / 已解决
- **coord 裁决**：<coord 的裁决结果（coord 填写）>
```
### 11.2 coord 处理流程
1. AI 在 issues.md 追加问题记录（状态：待 coord 仲裁）
2. coord 定期（每批次结束）统一仲裁，填写 coord 裁决字段
3. 状态改为"coord 已裁决"
4. AI 按 coord 裁决执行，完成后状态改为"已解决"
---
## 12. 变更记录
| 日期 | 变更 | 决策者 |
| ---------- | -------------------------------------------------------- | ----------------- |
| 2026-07-09 | 初始创建，规划批次 0-5 + 14 个已识别问题（见 issues.md） | coord（用户确认） |