# AI 协同问题记录（历史归档，不再新增）

> 版本：1.2（归档版）
> 日期：2026-07-09
> 维护者：coord（统一仲裁）+ 各 AI（提请问题）
> 关联文档：[coord-final-decisions.md](./architecture/coord-final-decisions.md)、[ai-work-orchestration.md](./architecture/ai-work-orchestration.md)、[coord-cross-review.md](./architecture/coord-cross-review.md)、[004 §16](./architecture/004_architecture_impact_map.md)、[port-allocation.md](../infra/port-allocation.md)

---

## ⚠️ 迁移说明（2026-07-09）

**本文件已归档，不再新增问题。** 新流程如下：

- **提请异议**：各 AI 在 `docs/architecture/issues/[模块名]_issue.md` 写入
- **仲裁结果**：coord 汇总到 `docs/architecture/issues/coord.md`
- **工作排期**：各 AI 在 `docs/architecture/issues/[模块名]_workline.md` 写入甘特图
- **总工作安排**：coord 汇总到 `docs/architecture/issues/workline.md`

**新流程文件**：

- [issues/coord.md](./architecture/issues/coord.md) — coord 仲裁结果汇总
- [issues/workline.md](./architecture/issues/workline.md) — 总工作安排
- [issues/[模块名]_issue.md](./architecture/issues/) — 各模块异议
- [issues/[模块名]_workline.md](./architecture/issues/) — 各模块工作排期

**本文件保留作为历史问题追溯**，其中的 70+ issue（ISSUE-001 ~ ISSUE-066）裁决结果见 [president-final-rulings.md](./architecture/president-final-rulings.md) §10 问题索引表。

---

## 0. 使用说明（历史，仅适用于 2026-07-09 前提请的问题）

### 0.1 谁可以提请问题

任何 AI（ai01-ai16）在执行 coord-final-decisions.md + ai-work-orchestration.md 过程中，发现以下问题**必须**记录到本文件：

1. **前置依赖未就绪**：本 AI 工作依赖的上游产出未到位
2. **跨度过大**：裁决要求的工作跨度超出当前阶段合理范围
3. **裁决冲突**：发现 coord-final-decisions.md 内部或与其他文档冲突
4. **契约不明确**：与协作 AI 的接口契约未协调清楚
5. **工作归属不明**：某项工作应该由谁负责不明确
6. **文档同步遗漏**：coord 已裁决但文档未同步更新（v1.1 新增类别）

### 0.2 记录格式

```markdown
### ISSUE-XXX: <问题标题>

- **提请 AI**：aiXX（<服务名>）
- **类别**：前置依赖未就绪 / 跨度过大 / 裁决冲突 / 契约不明确 / 工作归属不明 / 文档同步遗漏
- **阶段**：P2/P3/P4/P5/P6
- **问题描述**：<详细描述，含相关裁决条款编号或文档引用>
- **影响**：<对工作的影响，含阻塞的阶段>
- **建议方案**：<AI 建议的解决方案>
- **状态**：待 coord 仲裁 / coord 已裁决 / 已解决
- **coord 裁决**：<coord 的裁决结果（coord 填写）>
```

### 0.3 处理流程

1. AI 在本文件"待仲裁问题"区追加问题记录，编号自增（ISSUE-001, ISSUE-002...），状态：待 coord 仲裁
2. coord 定期（每批次结束）统一仲裁，填写"coord 裁决"字段，状态改为"coord 已裁决"
3. AI 按 coord 裁决执行，完成后状态改为"已解决"，移到"已解决问题"区

### 0.4 编号规则

- ISSUE-001 ~ ISSUE-014：coord 初始识别的 14 个问题
- ISSUE-015 ~ ISSUE-022：ai08 复审 coord 仲裁后新增的 8 个文档同步遗漏/契约不明确问题（2026-07-09）
- ISSUE-023 ~ ISSUE-066：各 AI（ai02/ai03/ai04/ai05/ai06/ai08/ai09/ai10/ai11/ai13/ai14/ai15/ai16）复审后提请的 44 个问题（含编号冲突，见 §0.5）

### 0.5 总裁最终裁决索引

> 所有 ISSUE-001 ~ ISSUE-066 的"coord 裁决"字段已由总裁最终裁决覆盖。
> 查询裁决结果请先查阅 [president-final-rulings.md](./architecture/president-final-rulings.md)。
> 本文件保留所有 issues 原始内容作为问题追溯，编号冲突通过 `ISSUE-XXX-<提请AI>` 格式唯一定位（见 president-final-rulings.md §10）。

### 0.6 编号冲突说明

> 以下编号被多个 AI 重复使用，原始内容保留不删除：
>
> - ISSUE-024 / ISSUE-025：ai11 与 ai09 重复
> - ISSUE-028 / ISSUE-029 / ISSUE-030：ai04 与 ai11 重复
> - ISSUE-031：ai04 与 ai15 重复
> - ISSUE-032 ~ ISSUE-035：ai03 与 ai15 重复
> - ISSUE-036：ai03 与 ai13 重复
> - ISSUE-044 ~ ISSUE-048：ai16 与 ai06 重复
>
> 引用时必须使用 `ISSUE-XXX-<提请AI>` 格式（如 `ISSUE-024-ai11`、`ISSUE-024-ai09`）。

---

## 1. 待仲裁问题

> 以下问题由 coord 与 ai08 复审后识别，待用户/coord 统一仲裁。
>
> **注**：ISSUE-001 ~ ISSUE-014 中大部分已被 coord 通过 `ai-work-orchestration.md` + `coord-final-decisions.md` 实质解决，但 issues.md v1.0 状态字段未回填，下方已补全 coord 裁决。剩余未解决问题（#13、#14）与新问题（#15-#22）仍待仲裁。

### ISSUE-001: iam gRPC server 启用时机三处文档冲突

- **提请 AI**：coord
- **类别**：裁决冲突 + 文档同步遗漏
- **阶段**：P2
- **问题描述**：
  - `coord-final-decisions.md` I1：iam **P2 即启用** gRPC server 50052
  - `port-allocation.md` §3（行 42）：iam **P2 启用 gRPC server**（已修正 ✓）
  - `port-allocation.md` §5（行 77）：iam 50052 仍标注 **"P3 启用"**（未修正 ✗）—— **同文档内部冲突**
  - `004 §16.7.3` P3 启动前整改清单：已删除 iam gRPC 项（已修正 ✓）
  - `004 §16.7.2` P2 启动前整改清单：已含 iam P2 即启用 gRPC（已修正 ✓）
- **影响**：开发 AI 若查看 port-allocation.md §5 会误以为 iam gRPC P3 才启用，与 I1 裁决冲突
- **建议方案**：修正 `port-allocation.md` §5（行 77）将 iam 阶段从 "P3" 改为 "P2"
- **状态**：coord 已裁决（待文档修正）
- **coord 裁决**：iam P2 即启用 gRPC server 50052（I1 裁决为准），需修正 port-allocation.md §5

### ISSUE-002: shared-ts Outbox 工具包未列入 P2 整改清单

- **提请 AI**：coord
- **类别**：工作归属不明
- **阶段**：P2
- **问题描述**：
  - `coord-final-decisions.md` I2：直接建 shared-ts Outbox 工具包，iam 首次实现即用
  - `004 §16.7.2` P2 启动前整改清单：已补充第 4 项"coord 建立 shared-ts Outbox 工具包"（已修正 ✓）
  - `ai-work-orchestration.md` §3.1 0.4：已列入 coord 批次 0 待办（已修正 ✓）
- **影响**：原问题已通过文档修正解决，但 issues.md 状态未回填
- **建议方案**：状态改为"已解决"
- **状态**：coord 已裁决（实质已解决）
- **coord 裁决**：已补充 §16.7.2 第 4 项，列入 ai-work-orchestration §3.1 0.4

### ISSUE-003: 004 §4.2 gRPC 启用阶段矩阵与 B2 裁决冲突

- **提请 AI**：coord
- **类别**：裁决冲突
- **阶段**：P2
- **问题描述**：
  - `004 §4.2`：P2 不启用 gRPC，P3 iam + core-edu 启用
  - `coord-final-decisions.md` I1：iam P2 即启用 gRPC server
  - `coord-final-decisions.md` §5.3（行 216）：iam P2 启用（已修正 ✓）
- **影响**：004 §4.2 与 coord-final-decisions §5.3 冲突
- **建议方案**：修正 004 §4.2 矩阵，iam 行改为 "P2 启用"
- **状态**：coord 已裁决（待 004 文档修正）
- **coord 裁决**：iam P2 启用 gRPC（I1 裁决为准），需修正 004 §4.2

### ISSUE-004: teacher-bff P2 "首次实现即 gRPC 调下游"与下游服务分阶段启用矛盾

- **提请 AI**：coord
- **类别**：跨度过大
- **阶段**：P2
- **问题描述**：
  - B2 裁决要求 teacher-bff 首次实现即 gRPC 调 iam/core-edu/content/data-ana/msg/ai 全部下游
  - 但 core-edu P3 / content P4 / data-ana P4 / ai P5 / msg P5 才启用 gRPC server
- **影响**：P2 启动 teacher-bff 时，5 个下游 gRPC 端点不存在
- **建议方案**：明确"BFF 跨阶段扩展下游 gRPC 调用"是允许的例外
- **状态**：coord 已裁决
- **coord 裁决**：采纳方案 C，"BFF 跨阶段扩展下游"是允许的例外（见 ai-work-orchestration.md §1 原则 5）

### ISSUE-005: teacher-bff 跨阶段持续改造与"不分阶段"裁决原则矛盾

- **提请 AI**：coord
- **类别**：跨度过大
- **阶段**：P2-P5
- **问题描述**：
  - teacher-bff P2 调 iam；P3 补 core-edu；P4 补 content + data-ana；P5 补 ai + msg
  - 每阶段都要返工补 gRPC 调用，违反"首次实现即最终方案，不分阶段"
- **影响**：teacher-bff 代码在每个阶段都要改 DownstreamClient
- **建议方案**：明确"BFF 跨阶段扩展下游"是允许的例外
- **状态**：coord 已裁决
- **coord 裁决**：同 ISSUE-004，跨阶段扩展例外（ai-work-orchestration.md §1 原则 5）

### ISSUE-006: student-bff P3 同样存在跨度过大问题

- **提请 AI**：coord
- **类别**：跨度过大
- **阶段**：P3
- **问题描述**：
  - ai04 student-bff P3 启动时，content（P4）/ data-ana（P4）gRPC 未启用
  - student-bff P3 只能 gRPC 调 iam + core-edu
- **影响**：student-bff P3 调 content / data-ana 断裂
- **建议方案**：同 ISSUE-004
- **状态**：coord 已裁决
- **coord 裁决**：同 ISSUE-004，跨阶段扩展例外

### ISSUE-007: BFF DownstreamClient 抽象回写 teacher-bff 的时间点

- **提请 AI**：coord
- **类别**：前置依赖未就绪
- **阶段**：P3
- **问题描述**：
  - B8 裁决：DownstreamClient 抽象回写 teacher-bff，3 个 BFF 统一使用
  - ai04 student-bff P3 启动 + ai05 parent-bff P4 启动均依赖此抽象
- **影响**：ai04 P3 / ai05 P4 启动可能被阻塞
- **建议方案**：ai03 P2 必须产出可复用的 DownstreamClient 抽象
- **状态**：coord 已裁决
- **coord 裁决**：ai03 P2 必须产出 DownstreamClient 抽象，coord 验收时检查（ai-work-orchestration.md §4.3）

### ISSUE-008: teacher-portal P2 改造为 urql/apollo 的工作量

- **提请 AI**：coord
- **类别**：跨度过大
- **阶段**：P2
- **问题描述**：
  - F9 裁决：P2 起 BFF 用 GraphQL，前端用 urql/apollo
  - teacher-portal 已实现 REST 风格代码，P2 需改造为 GraphQL 客户端
- **影响**：ai13 P2 工作量增大，schema 契约协调成本高
- **建议方案**：明确 ai13 P2 整改范围，coord 仲裁 schema 第一版
- **状态**：coord 已裁决（机制已建立）
- **coord 裁决**：ai-work-orchestration.md §4.3 已明确"coord 在批次 1 启动前仲裁 schema 第一版"；ai13 P2 范围限 client 改造 + MF shell + 共享组件抽取

### ISSUE-009: parent-bff P4 依赖 iam.GetChildrenByParent（I6 裁决 iam P2 即补全）

- **提请 AI**：coord
- **类别**：前置依赖未就绪
- **阶段**：P4
- **问题描述**：
  - I6 裁决：iam P2 即补全 iam_student_guardians 表 + GetChildrenByParent RPC + GET /iam/children
  - §16.7.4 P4 启动前整改清单：ai05 parent-bff 落地 P4 MVP（依赖 iam GetChildrenByParent）
- **影响**：若 iam P2 完成补全，则 parent-bff P4 无阻塞 ✓
- **建议方案**：coord 在批次 1 验收 iam 时强制检查 GetChildrenByParent 已落地
- **状态**：coord 已裁决
- **coord 裁决**：coord 批次 1 验收时强制检查 GetChildrenByParent（ai-work-orchestration.md §10.1）

### ISSUE-010: ai12 ai P5 调 content.QuestionService 的 proto 补全时机冲突

- **提请 AI**：coord
- **类别**：裁决冲突 + 文档同步遗漏
- **阶段**：P4-P5
- **问题描述**：
  - `coord-final-decisions.md` N3：QuestionService proto **P4 即补全**（不等到 P5）
  - `004 §16.7.5` P5 启动前整改清单（行 1345）：仍列"ai09 content 补 QuestionService RPC（阻塞 ai 出题）"—— **未删除 ✗**
  - `004 §16.7.4` P4 启动前整改清单（行 1337）：仅列"ChapterService / TextbookService.ListTextbooks"，**未列 QuestionService ✗**
  - `ai-work-orchestration.md` §6.3：已明确"coord 验收 ai09 P4：强制检查 QuestionService RPC 已落地"（已修正 ✓）
- **影响**：004 §16.7.4 与 §16.7.5 与 N3 裁决三处冲突；ai09 P4 若按 §16.7.4 执行可能不补 QuestionService，导致 ai12 P5 阻塞
- **建议方案**：
  1. 004 §16.7.4（行 1337）补充"+ QuestionService"
  2. 004 §16.7.5（行 1345）删除 QuestionService 项
- **状态**：coord 已裁决（待 004 文档修正）
- **coord 裁决**：QuestionService proto P4 即补全（N3 裁决为准），需修正 004 §16.7.4 + §16.7.5

### ISSUE-011: ai12 ai P5 调 core-edu.ExamService.GetExam 的方向修正

- **提请 AI**：coord
- **类别**：契约不明确
- **阶段**：P5
- **问题描述**：
  - §16.2 接口一致性 #5：core-edu §7 写"调 ai.ExamService.GetExam"方向反了，应为 ai 调 core-edu.ExamService.GetExam
  - core-edu P3 启用 gRPC，含 ExamService
- **影响**：ai P5 调 core-edu.ExamService.GetExam 无阻塞 ✓
- **建议方案**：coord 验收 ai08 core-edu P3 时检查 ExamService.GetExam 已落地
- **状态**：coord 已裁决
- **coord 裁决**：ai-work-orchestration.md §7.3 已明确"ai12 调 core-edu.ExamService.GetExam（已就绪）"；coord 批次 2 验收 ai08 时检查

### ISSUE-012: msg P5 调 push-gateway HTTP /internal/push 的时序协调

- **提请 AI**：coord
- **类别**：契约不明确
- **阶段**：P5
- **问题描述**：
  - M4 裁决：msg 调 push-gateway 用 HTTP POST /internal/push
  - ai10 msg 和 ai02 push-gateway 都 P5 启动
- **影响**：若两者同时启动，msg 调用时 push-gateway /internal/push 可能未就绪
- **建议方案**：ai02 优先 1-2 天启动 /internal/push 端点，ai10 后启动调用方
- **状态**：coord 已裁决
- **coord 裁决**：ai-work-orchestration.md §7.3 已明确"ai02 优先 1-2 天启动，ai10 后启动；coord 仲裁第一版接口契约"

### ISSUE-013: BFF P2-P4 不订阅 Kafka，家长通知实时性如何保证

- **提请 AI**：coord
- **类别**：跨度过大
- **阶段**：P4
- **问题描述**：
  - B7 裁决：P2-P4 BFF 不订阅 Kafka，P5 push-gateway 落地后再订阅
  - parent-bff P4 阶段家长通知如何实时推送？
- **影响**：parent-bff P4 阶段家长端只能轮询查询通知，体验差；且 msg P5 才启用
- **建议方案**：parent-bff 通知相关功能推迟到 P5（msg + push-gateway 就绪后）
- **状态**：**待 coord 仲裁**（未解决）
- **coord 裁决**：（待填写）

### ISSUE-014: admin-portal P6 + 8 个新 Kafka topic 时序

- **提请 AI**：coord
- **类别**：跨度过大
- **阶段**：P6
- **问题描述**：
  - X2 裁决：admin-portal 8 个新 Kafka topic + events.proto message 在 P6 实施时补
  - 若 iam / 其他服务在 P6 前需发布审计事件，则无 topic 可发
- **影响**：admin-portal P6 启动前无审计事件 topic；若 iam 提前发审计事件则阻塞
- **建议方案**：明确审计事件归属（iam vs audit-service，X3 待 P6 仲裁）
- **状态**：**待 coord 仲裁**（未解决，待 P6 评估）
- **coord 裁决**：（待 P6 仲裁时填写）

---

### ISSUE-015: port-allocation.md §3 与 §5 关于 iam gRPC 启用阶段冲突

- **提请 AI**：ai08（core-edu）
- **类别**：文档同步遗漏
- **阶段**：P2
- **问题描述**：
  - `port-allocation.md` §3（行 42）：iam 50052 标注 "P2 启用 gRPC server（I1 裁决，2026-07-09 修正）"
  - `port-allocation.md` §5（行 77）：iam 50052 仍标注 "IamService（P3 启用） | P3"
  - **同一文档内部 §3 与 §5 冲突**
- **影响**：开发 AI 查阅 §5 会误以为 iam gRPC P3 才启用，与 I1 裁决（P2 启用）冲突，可能导致 ai03 teacher-bff P2 不敢 gRPC 调 iam
- **建议方案**：修正 §5（行 77）将 iam 阶段从 "P3" 改为 "P2"，暴露 Service 改为 "IamService（P2 启用）"
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-016: 004 §16.7.4 P4 清单未列 content QuestionService（与 N3 裁决冲突）

- **提请 AI**：ai08（core-edu）
- **类别**：裁决冲突 + 文档同步遗漏
- **阶段**：P4
- **问题描述**：
  - `coord-final-decisions.md` N3：QuestionService proto **P4 即补全**（不等到 P5）
  - `004 §16.7.4` P4 启动前整改清单（行 1337）：仅列"ChapterService / TextbookService.ListTextbooks"，**未列 QuestionService**
  - `004 §16.7.5` P5 启动前整改清单（行 1345）：仍列"ai09 content 补 QuestionService RPC（阻塞 ai 出题）"—— **应删除未删除**
  - `ai-work-orchestration.md` §6.3：已明确"coord 验收 ai09 P4：强制检查 QuestionService RPC 已落地"（已修正 ✓）
- **影响**：004 §16.7.4 与 §16.7.5 与 N3 裁决三处冲突；ai09 P4 若按 §16.7.4 执行可能不补 QuestionService，导致 ai12 P5 出题阻塞
- **建议方案**：
  1. 004 §16.7.4（行 1337）补充"+ QuestionService"
  2. 004 §16.7.5（行 1345）删除 QuestionService 项
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-017: 14 个 issues 状态字段未回填 coord 裁决

- **提请 AI**：ai08（core-edu）
- **类别**：文档同步遗漏
- **阶段**：全阶段
- **问题描述**：
  - coord 已通过 `ai-work-orchestration.md` + `coord-final-decisions.md` 实质解决了 ISSUE-001 ~ ISSUE-012 中的大部分问题
  - 但 `issues.md` v1.0 中 14 个问题的"coord 裁决"字段全部为"（待填写）"，状态全部为"待 coord 仲裁"
  - 本次 v1.1 已补全 #1-#12 的 coord 裁决，但需 coord 确认
- **影响**：开发 AI 无法知道这些问题是否已解决，可能重复提请；coord 仲裁记录不完整
- **建议方案**：coord 审核 v1.1 补全的裁决字段，确认后状态改为"coord 已裁决"
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-018: shared-ts Outbox 工具包设计未明确

- **提请 AI**：ai08（core-edu）
- **类别**：契约不明确
- **阶段**：P2
- **问题描述**：
  - `coord-final-decisions.md` I2：直接建 shared-ts Outbox 工具包，iam 首次实现即用
  - `ai-work-orchestration.md` §3.1 0.4：列入 coord 批次 0 待办
  - 但工具包的 **接口设计、表结构、Relay Worker 实现机制** 均未明确：
    - Outbox 表 schema 是各服务自建还是 shared-ts 提供 migration？
    - Relay Worker 是 shared-ts 提供可注入的 NestJS Provider 还是各服务自行实现？
    - 接口签名（如 `OutboxService.publish(eventType, payload, options)`）是什么？
    - 事务边界如何保证（业务表 + outbox 表同事务）？
- **影响**：coord 批次 0 实施时设计不完整，iam P2 接入可能延迟；各服务接入方式不一致
- **建议方案**：coord 在批次 0 启动前产出 `packages/shared-ts/src/outbox/` 设计草案，含：
  1. Outbox 表 schema（Drizzle migration）
  2. `OutboxRepository` 接口（publish / markPublished / markFailed / getPending）
  3. `OutboxRelayWorker` 可注入 Provider（含轮询/批量/重试/指数退避）
  4. 事务使用示例（业务表 + outbox 同事务）
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-019: GraphQL schema 第一版仲裁机制未明确

- **提请 AI**：ai08（core-edu）
- **类别**：契约不明确
- **阶段**：P2
- **问题描述**：
  - `ai-work-orchestration.md` §4.3：coord 在批次 1 启动前仲裁 schema 第一版
  - 但 **schema 仲裁的具体流程、参与方、schema 存放位置、版本管理** 均未明确：
    - schema 第一版由谁起草（coord / ai03 / ai13）？
    - schema 存放在哪个仓库路径（`packages/shared-ts/graphql/schema.graphql`？各 BFF 各自维护？）？
    - Query/Mutation 清单的覆盖范围（teacher-bff 第一版含哪些 Query/Mutation）？
    - schema 演进的版本管理（SDL-first vs code-first）？
- **影响**：批次 1 启动时可能因 schema 仲裁延迟；ai03 与 ai13 并行开发时 schema 契约可能不一致
- **建议方案**：coord 在批次 0 结束前产出 GraphQL schema 仲裁规范：
  1. 存放位置：`packages/shared-ts/graphql/` 统一管理
  2. 起草方：coord 起草 schema 骨架，ai03/ai04/ai05 各自补充
  3. 覆盖范围：teacher-bff v1 含用户/班级/考试/作业相关 Query/Mutation
  4. 版本管理：SDL-first（schema.graphql），配合 graphql-codegen 生成 TS 类型
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-020: BFF 跨阶段扩展例外的验收标准未明确

- **提请 AI**：ai08（core-edu）
- **类别**：契约不明确
- **阶段**：P2-P5
- **问题描述**：
  - `ai-work-orchestration.md` §1 原则 5：BFF 跨阶段扩展下游是允许的例外
  - 但 **"扩展"的验收标准** 未明确：
    - 是否允许修改 DownstreamClient 接口签名？
    - 是否允许新增 RPC 调用（如 P3 补 `core-edu.ExamService.GetExam`）？
    - 是否允许重构下游调用配置（如新增 gRPC endpoint）？
    - 扩展时是否需要重新评审 schema 契约？
    - "扩展"与"中间过渡方案"的边界在哪里？
- **影响**：ai03/ai04/ai05 跨阶段扩展时可能产生争议；coord 验收时无统一标准
- **建议方案**：明确"跨阶段扩展"的允许范围：
  1. 允许：新增下游 gRPC 调用（新增 RPC 方法到 DownstreamClient）
  2. 允许：新增下游配置（gRPC endpoint）
  3. 禁止：修改已有 RPC 调用的签名或返回类型
  4. 禁止：删除已实现的 RPC 调用（除非下游服务下线）
  5. 扩展时须更新 BFF 的 02-architecture-design.md 下游调用矩阵
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-021: "不分阶段"原则与"批次时间线"表述易混淆

- **提请 AI**：ai08（core-edu）
- **类别**：裁决冲突（表述歧义）
- **阶段**：全阶段
- **问题描述**：
  - `coord-final-decisions.md` §0.1：**"不分阶段"** —— 最终方案在服务首次落地时即采用，不得以"阶段未到"为由先实现简化版
  - `ai-work-orchestration.md` §9：**批次时间线** —— 批次 0（2-3 天）→ 批次 1（5-7 天）→ 批次 2（5-7 天）→ ...
  - 两者字面冲突，但实际语义不同：
    - "不分阶段"指 **代码实现不分阶段重构**（禁止 P2 简化版 → P3 重构）
    - "批次"指 **工作先后排序**（因依赖关系需串行）
  - 但文档表述易让开发 AI 误解为"既说不分阶段又分批次"矛盾
- **影响**：开发 AI 可能误解"不分阶段"含义，或质疑批次规划的合理性
- **建议方案**：在 `coord-final-decisions.md` §0.1 补充澄清：
  > "不分阶段"指 **代码实现层面禁止中间过渡方案**；"批次"指 **工作先后排序层面**因服务依赖需串行。两者不冲突：批次规划保证下游就绪后再启动上游，不分阶段保证每个服务首次实现即最终方案。
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-022: core-edu AttendanceService proto 补全责任方不明

- **提请 AI**：ai08（core-edu）
- **类别**：工作归属不明
- **阶段**：P3
- **问题描述**：
  - `coord-final-decisions.md` C4：P3 首次实现即补全 proto + 实现
  - `ai-work-orchestration.md` §3.2 0.8：**coord 负责**补全 core_edu.proto（AttendanceService / GetClassesByTeacher / BatchGetClasses）
  - `coord-cross-review.md` §6 整改 #14：**ai03 负责** core_edu.proto 补 Attendance 域 + core-edu 02 文档
  - `004 §16.7.3` P3 启动前（行 1331）：ai08 core-edu 启用 gRPC server + 补 AttendanceService
  - **三处责任方不一致**：coord（orchestration）/ ai03（cross-review）/ ai08（004 §16.7.3）
- **影响**：proto 补全责任方不明，可能 ai08 等 coord、coord 等 ai03；proto 契约与实现可能脱节
- **建议方案**：明确分工：
  1. **coord 负责 proto 契约定义**（core_edu.proto 补 AttendanceService + GetClassesByTeacher + BatchGetClasses 的 message + RPC 签名）
  2. **ai08 负责 proto 实现**（基于 coord 定义的 proto 生成 TS 代码 + 实现 AttendanceService 业务逻辑）

3. 修正 `coord-cross-review.md` §6 #14 责任方从 ai03 改为 coord（proto）+ ai08（实现）

- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-032: B2 裁决 P2 阶段 teacher-bff Dashboard Query Resolver 实现方式未明确

- **提请 AI**：ai03（teacher-bff）
- **类别**：契约不明确
- **阶段**：P2
- **问题描述**：
  - `coord-final-decisions.md` B2：teacher-bff 首次实现即 gRPC 调下游（iam/core-edu/content/data-ana/msg/ai 全部 gRPC）
  - `ai-work-orchestration.md` §1.5 + ISSUE-004/005 已确立"跨阶段扩展例外"原则：P2 仅 gRPC 调 iam，P3-P5 逐步补 gRPC 调用
  - 但 **P2 阶段 teacher-bff 的 Dashboard Query Resolver 应返回什么数据未明确**：
    1. P2 仅 iam gRPC 可用，core-edu（P3）/ data-ana（P4）/ content（P4）gRPC 全部未启用
    2. Dashboard Query 通常聚合"班级数 / 学生数 / 今日作业 / 待批改 / 教学进度"等多源数据
    3. 若 P2 Resolver 只返回 iam 用户信息 → GraphQL schema 看起来"空壳"，前端无法联调
    4. 若 P2 Resolver 返回 mock 数据 → 违反"不分阶段"原则（mock → 真实重构）
    5. 若 P2 不实现 Dashboard Query → GraphQL endpoint 不完整，ai13 前端无 schema 可调
- **影响**：ai03 P2 GraphQL schema 第一版设计阻塞，ai13 P2 前端联调阻塞
- **建议方案**：
  1. **GraphQL schema 设计完整**（含全部 Query/Mutation 字段定义），P2 即定型，后续不重构
  2. **Resolver 实现**：P2 阶段 Dashboard Query Resolver 内部仅调 iam gRPC（返回用户基础信息 + 角色），未启用的下游字段（班级数 / 作业数等）返回 `null` + `extensions.warning = "field_unavailable_in_p2"`
  3. **P3-P5 扩展**：按"跨阶段扩展例外"原则，在 Resolver 内逐步补 gRPC 调用，将 null 字段替换为真实数据
  4. **ai13 前端**：P2 联调时对 null 字段做 UI 降级展示（如"数据加载中"或隐藏模块）
  5. **此方案不违反"不分阶段"**：schema 即最终方案，Resolver 内部数据源扩展属于"跨阶段扩展例外"
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-033: B4 越权防御校验 teacherId 与班级关系在 P2 阶段实现方式未明确

- **提请 AI**：ai03（teacher-bff）
- **类别**：契约不明确
- **阶段**：P2
- **问题描述**：
  - `coord-final-decisions.md` B4：teacher-bff 强制自我越权防御，校验 teacherId 与班级关系
  - 但 **P2 阶段 core-edu gRPC 未启用**（C2 裁决 P3 才启用 50053），无法调 `GetClassesByTeacher(teacherId)` 验证 teacherId 是否拥有该 classId
  - P2 阶段 teacher-bff 的越权防御应如何实现未明确：
    1. 方案 A：P2 跳过越权防御，P3 补真实校验（违反 B4"首次实现即防御"）
    2. 方案 B：P2 用本地配置文件映射 teacherId → classIds（mock 数据，违反"不分阶段"）
    3. 方案 C：P2 调 iam gRPC 的 `GetEffectiveAccess(userId, resource, action)` 间接校验（需 iam 补此 RPC 的数据源，但 iam 不掌握班级关系）
    4. 方案 D：P2 越权防御接口先抽象（AuthorizationGuard），P2 内部实现为"允许全部"（开发模式），P3 替换为真实 core-edu gRPC 调用
- **影响**：ai03 P2 越权防御实现方式未定，可能导致 P2 安全漏洞或 P3 返工
- **建议方案**：
  1. 采用 **方案 D**：P2 抽象 `AuthorizationGuard` 接口（`canAccessClass(userId, classId): Promise<boolean>`），P2 内部实现为"DEV_MODE 放行 + 生产拒绝"（保守策略）
  2. **Redis 缓存**：P3 接入 core-edu gRPC 后，`GetClassesByTeacher` 结果缓存到 Redis（key: `authz:teacher:{teacherId}:classes`，TTL 5min），AuthorizationGuard 优先查缓存
  3. **此方案不违反"不分阶段"**：Guard 接口即最终方案，P2→P3 仅替换内部实现（属"跨阶段扩展例外"）
  4. 需 coord 确认：P2 阶段生产环境若 Guard 全部拒绝，是否影响 teacher-bff P2 端到端验证？
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-034: G2 /readyz 检查全部下游依赖在 P2 阶段不可行

- **提请 AI**：ai03（teacher-bff）
- **类别**：跨度过大
- **阶段**：P2
- **问题描述**：
  - `coord-final-decisions.md` G2：/readyz 首次实现即检查全部下游依赖（DB SELECT 1 / Redis PING / Kafka 连接 / gRPC 下游可达）
  - `coord-final-decisions.md` B2：teacher-bff 首次实现即 gRPC 调 iam/core-edu/content/data-ana/msg/ai 全部下游
  - 但 **P2 阶段 teacher-bff 仅能 gRPC 调 iam**（core-edu P3 / content P4 / data-ana P4 / msg P5 / ai P5 才启用 gRPC server）
  - 若 P2 /readyz 严格检查全部 6 个下游 gRPC 可达性 → 5 个下游必然失败 → /readyz 永远返回 503 → K8s readinessProbe 失败 → Pod 永不就绪
- **影响**：ai03 P2 teacher-bff Pod 无法就绪，批次 1 验收失败
- **建议方案**：
  1. **/readyz 探针列表按阶段扩展**（属"跨阶段扩展例外"）：
     - P2：DB + Redis + iam gRPC 50052（3 项）
     - P3：+ core-edu gRPC 50053（4 项）
     - P4：+ content gRPC 50054 + data-ana gRPC 50055（6 项）
     - P5：+ ai gRPC 50058 + msg gRPC 50056（8 项）
  2. **实现方式**：`DownstreamHealthCheck` 注册表模式，每个下游注册 `IamHealthCheck` / `CoreEduHealthCheck` 等独立探针，按阶段启用
  3. **此方案不违反 G2**：G2 要求"首次实现即检查下游依赖"，ai03 P2 即检查 P2 可达的下游（iam），后续阶段扩展探针注册表（属"跨阶段扩展例外"）
  4. 需 coord 确认：G2 裁决是否允许"探针列表按阶段扩展"，还是要求 P2 /readyz 必须检查全部 6 个下游（即使未启用）？
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-035: §5.2 接口命名 GetTeacherDashboard（无 Stats 后缀）需 ai03 回写 02 文档

- **提请 AI**：ai03（teacher-bff）
- **类别**：文档同步遗漏
- **阶段**：P2
- **问题描述**：
  - `coord-final-decisions.md` §5.2 接口命名统一：调用方 data-ana，被调方 teacher-bff，统一命名 **GetTeacherDashboard**（无 Stats 后缀）
  - ai03 的 `services/teacher-bff/docs/02-architecture-design.md` 有 **4 处** 使用 `GetTeacherDashboardStats`（含 Stats 后缀）：
    - L230：`DataAnaClient gRPC adapter | 调用 data-ana:50055（AnalyticsService + GetTeacherDashboardStats 待 ai11 补）`
    - L475：`GET | /teacher/dashboard/stats | 仪表盘统计（data-ana GetTeacherDashboardStats，待 ai11 补 proto）`
    - L1269：`调用 | data-ana | gRPC 50055（P4+） | GetTeacherDashboardStats（建议新增） | 仪表盘统计 | P4 | ❌ 待 coord 仲裁`
    - L1463：`6 | data-ana 补 GetTeacherDashboardStats RPC | 仪表盘统计聚合 | 建议新增 | P4`
  - 按 `coord-final-decisions.md` §7.2 回写义务：ai03 收到裁决后 3 个工作日内回写 02 文档
- **影响**：ai03 02 文档与裁决不一致，coord 验收时不通过；ai11 data-ana 若按 ai03 文档命名会与裁决冲突
- **建议方案**：
  1. ai03 立即执行回写：将 4 处 `GetTeacherDashboardStats` 替换为 `GetTeacherDashboard`
  2. 同步检查 `GetStudentDashboard` / `GetParentDashboard` / `GetAdminDashboard` 命名（§5.2 裁决统一无 Stats 后缀）
  3. 回写完成后在 known-issues.md 工作经验日志追加记录
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-036: ai03 P2 工作量激增，建议明确最小交付范围

- **提请 AI**：ai03（teacher-bff）
- **类别**：跨度过大
- **阶段**：P2
- **问题描述**：
  - ai03 原 P2 计划（5 项）：GraphQL endpoint + DownstreamClient 抽象 + 5 个核心 Query + iam gRPC 调用 + Redis 缓存
  - 对齐 `coord-final-decisions.md` + `ai-work-orchestration.md` 后，ai03 P2 实际工作项激增至 **17 项**：
    1. GraphQL Yoga server 搭建（B1）
    2. DataLoader 集成（B1）
    3. DownstreamClient 抽象 + iam gRPC client（B2 + B8）
    4. AuthMiddleware 越权防御抽象（B4 + ISSUE-033）
    5. /readyz 探针注册表 + iam 探针（G2 + ISSUE-034）
    6. /healthz liveness（G3）
    7. pino 结构化日志（G4）
    8. /metrics 端点 + 基础业务指标（G5）
    9. OTel SDK + OTLP exporter（G6）
    10. Zod 全量验证（G7）
    11. GlobalErrorFilter + ActionState 信封（G8）
    12. 优雅关闭 SIGTERM（G9）
    13. getDb() 统一（G10）
    14. cuid2 ID（G11）
    15. ESM import .js 后缀（G12）
    16. import type（G13）
    17. BFF_TEACHER_ 错误码前缀（B5 + G14）
    18. Redis 5-30s 短缓存（B6）
    19. 回写 02 文档（§7.2 + ISSUE-035）
  - 批次 1 时间线 5-7 天，ai03 单 AI 完成 19 项工作风险高
- **影响**：ai03 P2 延期风险高 → 阻塞 ai04 P3（依赖 DownstreamClient）+ ai05 P4（依赖 DownstreamClient）+ ai13 P2（依赖 schema）
- **建议方案**：
  1. coord 明确 ai03 P2 **最小交付范围**（Must Have）：
     - GraphQL endpoint + schema 第一版（阻塞 ai13）
     - DownstreamClient 抽象 + iam gRPC（阻塞 ai04/ai05）
     - AuthMiddleware 越权防御抽象（B4）
     - 回写 02 文档（§7.2）
  2. 可延后项（Should Have，P2 末期或 P3 初期补）：
     - OTel tracer（G6，P2 可降级为 logger-only）
     - /metrics 业务指标（G5，P2 仅暴露 process metrics）
     - DataLoader 集成（B1，P2 可先用普通 resolver）
  3. 通用质量项（Nice to Have，P3 持续补）：
     - Zod 全量验证（G7，P2 先校验核心 Query）
     - 优雅关闭（G9，P2 可简化为 HTTP close）
  4. 需 coord 确认：是否允许 ai03 P2 按上述分级交付，还是必须 19 项全做？
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-059: BFF_TEACHER_FORBIDDEN_RESOURCE vs BFF_TEACHER_PERMISSION_DENIED 错误码语义区分

- **提请 AI**：ai03（teacher-bff）
- **类别**：契约不明确
- **阶段**：P2
- **问题描述**：
  - `coord-final-decisions.md` B3：BFF 豁免 @RequirePermission（权限由 Gateway JWT + 下游服务负责），BFF 仅校验 x-user-id 存在
  - `coord-final-decisions.md` B4：全部 BFF 强制自我越权防御（teacher-bff 校验 teacherId 与班级关系）
  - `coord-final-decisions.md` B5 + G14：错误码前缀 BFF_TEACHER_
  - 但 **越权防御失败时返回哪个错误码未明确**：
    1. 场景 A：teacherId=A 访问 classId=B（B 不属于 A）→ 越权防御拦截
    2. 场景 B：JWT 中 teacherId=A，但请求 body 中传 teacherId=C（身份冒用）→ 身份校验失败
    3. 场景 C：x-user-id header 缺失 → BFF 拒绝请求
  - 这 3 个场景是否共用一个错误码，还是区分？
    - 若共用 `BFF_TEACHER_FORBIDDEN` → 前端无法区分"无权访问"vs"身份异常"
    - 若区分 `BFF_TEACHER_FORBIDDEN_RESOURCE`（场景 A）+ `BFF_TEACHER_PERMISSION_DENIED`（场景 B）+ `BFF_TEACHER_UNAUTHORIZED`（场景 C）→ 需 coord 仲裁命名
  - 此外，B3 裁决"BFF 豁免 @RequirePermission"是否意味着 BFF **完全不返回权限相关错误码**？还是 BFF 仍需返回越权防御错误码（只是不做权限决策）？
- **影响**：ai03 P2 错误码设计阻塞，前端 i18n key 命名阻塞（F4 裁决 error.bffTeacher.*）
- **建议方案**：
  1. **明确 3 类错误码**（BFF 越权防御专用，非权限决策）：
     - `BFF_TEACHER_UNAUTHORIZED`：x-user-id 缺失或无效（HTTP 401）
     - `BFF_TEACHER_FORBIDDEN_RESOURCE`：teacherId 与资源无归属关系（HTTP 403，场景 A）
     - `BFF_TEACHER_IDENTITY_MISMATCH`：JWT teacherId 与请求 body teacherId 不一致（HTTP 403，场景 B）
  2. **B3 裁决澄清**：BFF 豁免 @RequirePermission 指不做"功能权限决策"（如"能否查看仪表盘"），但必须做"数据权限防御"（如"只能看自己的班级"）
  3. **i18n key**（对齐 F4）：
     - `error.bffTeacher.unauthorized`
     - `error.bffTeacher.forbidden_resource`
     - `error.bffTeacher.identity_mismatch`
  4. 需 coord 确认错误码命名 + HTTP 状态码映射
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

---

## 2. 已解决问题

（暂无）

---

## 2.5 ai11 补充的待仲裁问题（ISSUE-026 ~ ISSUE-030）

> 以下问题由 ai11（data-ana）在审核 coord-final-decisions.md 后提请，与上方 ai09 的 ISSUE-023 ~ ISSUE-025 编号不冲突（ai09 的 3 个问题在下方"已解决问题"区之前）。

### ISSUE-026: ClickHouse DDL 目录 infra/clickhouse/ddl/ 归属不明（D3 裁决 vs project_rules §14.2）

- **提请 AI**：ai11（data-ana）
- **类别**：裁决冲突
- **阶段**：P4
- **问题描述**：
  - `coord-final-decisions.md` D3 裁决："直接建 infra/clickhouse/ddl/"
  - `project_rules.md` §14.2："infra/ 由 SRE AI 专门负责，业务 AI 不直接修改"
  - 冲突：D3 要求 ai11 直接建 infra/clickhouse/ddl/ 目录，但 §14.2 禁止业务 AI 修改 infra/
  - data-ana 02-architecture-design.md §3 已设计 5 张宽表完整 DDL（student_dashboard_view / student_errors / mastery_snapshot / attendance_logs / ai_usage_log），但 DDL 文件的创建归属不明确
- **影响**：阻塞 D3 落地——ai11 不确定是否可以直接在 infra/clickhouse/ddl/ 下创建文件
- **建议方案**：明确分工——ai11 提供 DDL 内容（已在 02 文档 §3 设计完毕），SRE AI 负责创建 infra/clickhouse/ddl/ 目录 + DDL 文件 + 部署执行脚本；或 coord 授权 ai11 在 infra/clickhouse/ddl/ 下创建纯 DDL .sql 文件（不涉及部署脚本）
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-027: analytics.proto 扩展（D4）交付时间不明确，阻塞 ai11 P4 gRPC 实现

- **提请 AI**：ai11（data-ana）
- **类别**：前置依赖未就绪
- **阶段**：P4
- **问题描述**：
  - `coord-final-decisions.md` D4 裁决："P4 即补全 analytics.proto：4 端 Dashboard + Warning + MasteryDistribution + SubscribeMasteryUpdate Stream RPC"
  - `coord-final-decisions.md` §5.1 明确 analytics.proto 补全期限为"P4 启动前"
  - 当前 analytics.proto 仅 3 个 RPC（GetClassPerformance / GetStudentWeakness / GetLearningTrend），缺少 7 个新 RPC + 对应 message 定义
  - coord 具体何时补全不明确，ai11 无法规划 gRPC server 实现时间
  - proto 补全是阻塞性契约——没有 proto 就无法用 buf generate 生成 Python gRPC 代码
- **影响**：ai11 P4 gRPC server 实现被阻塞，无法启动 gRPC 相关开发（10 个 RPC 实现 + server-streaming）
- **建议方案**：coord 明确 analytics.proto 补全的具体日期/批次节点；ai11 在等待期间可先实现 HTTP 端点 + CDC 消费者 + ClickHouse DDL 等不依赖 proto 的工作
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-028: warning.triggered topic 登记状态不明确（D5 声称已登记但 004 §7.2 未找到独立 topic）

- **提请 AI**：ai11（data-ana）
- **类别**：契约不明确
- **阶段**：P4
- **问题描述**：
  - `coord-final-decisions.md` D5 裁决："warning.triggered topic 已登记，004 §7.2 + events.proto MasteryEvent"
  - 004 §7.2（line 656-657）仅登记了 `edu.insight.mastery.updated` 和 `edu.insight.ai.usage`，**未找到 `edu.insight.warning.triggered` 独立 topic**
  - events.proto MasteryEvent（line 115-124）用 `action` 字段区分 `mastery.updated` / `warning.triggered`，暗示两者复用同一 topic
  - 问题不明确：warning.triggered 是独立 topic（`edu.insight.warning.triggered`）还是复用 `edu.insight.mastery.updated` topic（通过 action 字段区分）？
  - 若复用同一 topic，consumer 需按 action 过滤；若独立 topic，consumer 需订阅两个 topic
- **影响**：ai11 发布 WarningTriggered 事件时 topic 名不明确，msg 服务（P5）消费预警事件时订阅 topic 不明确
- **建议方案**：coord 明确二选一：
  - 方案 A（独立 topic）：004 §7.2 补登 `edu.insight.warning.triggered`，events.proto 拆分为 MasteryEvent + WarningEvent 两个 message
  - 方案 B（复用 topic）：维持现状，明确 warning.triggered 复用 `edu.insight.mastery.updated` topic，consumer 按 action 字段路由；D5 描述修正为"复用 mastery.updated topic，非独立登记"
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-029: data-ana /readyz 检查 iam gRPC 依赖 iam GetEffectiveDataScope RPC 落地验证

- **提请 AI**：ai11（data-ana）
- **类别**：前置依赖未就绪
- **阶段**：P4
- **问题描述**：
  - `coord-final-decisions.md` G2 裁决："/readyz 首次实现即检查全部下游依赖（DB / Redis / Kafka / gRPC 下游可达）"
  - data-ana 下游 gRPC 依赖：iam 50052（GetEffectiveDataScope RPC）
  - `coord-final-decisions.md` I1 裁决：iam P2 即启用 gRPC server 50052
  - `004 §15.3 #5` 裁决：iam P4 补全 GetEffectiveDataScope gRPC
  - 问题：I1 说 iam P2 启用 gRPC server，但 GetEffectiveDataScope RPC 是否在 P2 同步落地？还是仅 gRPC server 启用但 RPC 逐步补全？
  - 若 GetEffectiveDataScope 在 P4 才补全，data-ana P4 启动时 /readyz 检查 iam gRPC 可达但 RPC 不可用，应如何处理？
- **影响**：data-ana P4 启动时 /readyz 检查 iam gRPC 的深度不明确（仅 ping 端口 vs 调用 RPC）；DataScope 过滤功能依赖此 RPC
- **建议方案**：
  - coord 验收 iam P2 时强制检查 GetEffectiveDataScope RPC 已落地（不仅仅是 gRPC server 启用）
  - data-ana /readyz 分两级检查：L1 ping iam 50052 端口可达（基础就绪）；L2 调用 GetEffectiveDataScope 返回有效（深度就绪）。L1 失败 ready=false，L2 失败 degraded=true
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-030: 降级模式在 ActionState 信封中的表达方式存在语义矛盾

- **提请 AI**：ai11（data-ana）
- **类别**：契约不明确
- **阶段**：P4（影响全部 Python 服务 data-ana / ai）
- **问题描述**：
  - `coord-final-decisions.md` D1 + G8 裁决：首次实现即对齐 ActionState，成功 `{success: true, data: T}` / 失败 `{success: false, error: {code, message, details?, traceId?}}`
  - `coord-final-decisions.md` §0.1 设计原则 + 02-architecture-design.md §4.3：降级 `degraded` 作为 `error.details.degraded` 子字段
  - 02-architecture-design.md §4.3 ActionState.ok() 实现：降级时 `success=True` 但 `error` 字段不为 None（有 DATA_ANA_DEGRADED 错误码）
  - **语义矛盾**：ActionState 规范暗示 `success=true` 时 `error` 应为 null（成功即无错误），但降级模式下 `success=true` 且 `error` 有值，违反"成功无错误"的直觉语义
  - 当前 main.py 3 个端点降级时返回 `{success: True, data: {degraded: True}}`，degraded 在 data 内部，与 D1 裁决的"degraded 作为 error.details 子字段"冲突
- **影响**：全部 Python 服务（data-ana / ai）的降级响应格式不明确；BFF 消费端如何判断降级（检查 success 还是检查 error.details.degraded）不明确
- **建议方案**：coord 明确降级模式在 ActionState 中的标准表达，三选一：
  - 方案 A（success=true + error 有值）：维持 02 文档 §4.3 设计，明确"success=true 时 error 可有可无，有 error 表示降级但非失败"，BFF 消费端检查 `error.details.degraded` 判断降级
  - 方案 B（success=true + error=null + data 内 degraded 字段）：降级时 `success=true, error=null, data.degraded=true`，BFF 检查 `data.degraded` 判断降级（最简单，但 data 类型需统一加 degraded 字段）
  - 方案 C（success=false + error 有值）：降级视为"部分失败"，`success=false, error.code=DATA_ANA_DEGRADED`，BFF 检查 `success` 判断降级（但 HTTP 状态码应为 200 还是 503 不明确）
  - ai11 倾向方案 B（data 内 degraded 字段），因最符合"成功返回数据但质量降级"的语义
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

---

## 3. ai09 补充的待仲裁问题（ISSUE-023 ~ ISSUE-025）

> 以下问题由 ai09（content）在审核 coord-final-decisions.md 后提请。

### ISSUE-023: content /readyz 检查项与 P5 ES 引入的时序冲突

- **提请 AI**：ai09（content）
- **类别**：裁决冲突
- **阶段**：P4
- **问题描述**：
  - `coord-final-decisions.md` N2 裁决：content `/readyz` 首次实现即检查 DB/Neo4j/Kafka
  - `coord-final-decisions.md` G2 通用裁决：首次实现即检查**全部下游依赖**（DB SELECT 1 / Redis PING / Kafka 连接 / gRPC 下游可达）
  - 我的 `services/content/docs/02-architecture-design.md` §3.3 设计 ES 索引（ik_max_word 分词 + dense_vector embedding），但 §8.2 演进路线将 ES 全文检索列为 **P5 阶段交付物**（与 pending-features.md P5 引入 ES 一致）
  - G2 通用裁决列出的"全部下游依赖"未明确是否包含 ES
  - 若 P4 /readyz 强制检查 ES，则 ES 未启动时 content `/readyz` 一直 unhealthy，`infra/docker-compose.deploy.yml` 的 `depends_on: service_healthy` 会阻断整个部署链
  - Redis 同理：我的设计 P4 引入 Redis 缓存（§3.4 读写分离策略），但 P4 阶段是否启用 Redis 仍待确认
- **影响**：P4 阶段 /readyz 实现策略不明确，可能导致 P4 阶段容器无法通过健康检查，阻塞 docker-compose.deploy.yml 部署链
- **建议方案**：明确 /readyz 检查项随阶段演进策略，按 ENV 动态拼接：
  - **P4 阶段**：检查 MySQL + Neo4j + Kafka（3 项，ES_URL 未配置则跳过 ES 检查）
  - **P5 阶段**：扩展 ES 健康检查（4 项，ES_URL 存在时才检查）
  - 实现方式：检查项数组通过 ENV 过滤（`if (env.ES_URL) checks.push(checkES)`），未配置的依赖跳过不报错
  - 同时建议 G2 通用裁决补充"未引入依赖跳过"豁免条款
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-024: content ES Projector 实现位置未明确（影响 P5 实施细节）

- **提请 AI**：ai09（content）
- **类别**：工作归属不明
- **阶段**：P5
- **问题描述**：
  - 我的 `services/content/docs/02-architecture-design.md` §5.4 设计 Outbox Publisher 模式：业务事务内写 `content_outbox_events` 表，独立 Publisher 投递到 Kafka
  - §3.3 设计 ES 索引 mapping（ik_max_word + dense_vector embedding），§8.2 将 ES 数据同步列为 P5 交付物
  - 但 ES Projector（消费 content 自身领域事件，同步 ES 索引）的实现位置未明确：
    - 方案 A：在 content 服务内部实现（`shared/sync/es-sync.worker.ts`），与 Neo4j Sync Worker 同构
    - 方案 B：由 shared-ts 通用 Projector 工具包承载（与 Outbox Publisher 同样抽象到 shared-ts）
  - I2 裁决"shared-ts Outbox 工具包"由 coord 建立，但未明确是否包含 ES Projector
  - ISSUE-018 提请"shared-ts Outbox 工具包 API 契约未明确"，本问题是其延伸：ES Projector 是否属于该工具包范围
- **影响**：P5 阶段 ES 同步实现归属不明，可能造成重复实现或遗漏；与 shared-ts 工具包范围边界不清
- **建议方案**：建议方案 A（content 内部实现 ES Projector），理由：
  - ES mapping 是 content 特有的（questions/knowledge_points 索引结构、ik_max_word 分词、dense_vector embedding 都是 content 业务特定）
  - 通用 Projector 难以抽象（不同服务的索引 mapping、字段映射、向量生成策略都不同）
  - 与 Neo4j Sync Worker 同构便于 content 内部一致性（一对 Sync Worker 模式）
  - shared-ts 仅承载通用的 Outbox Publisher（Kafka producer 通用能力），特定 Projector 由各服务自实现
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-025: Neo4j 知识图谱同步是否属于"派生数据事件"豁免 Outbox

- **提请 AI**：ai09（content）
- **类别**：裁决冲突
- **阶段**：P4
- **问题描述**：
  - `004 §12.2` 通信约束：派生数据事件豁免 Outbox 强制条款（coord 已仲裁）
  - `project_memory.md` Hard Constraints：派生数据事件豁免 Outbox 模式要求
  - 我的 `02-architecture-design.md` §5.4 设计 content 强制 Outbox（content 领域事件不属派生数据，已对齐 004 §12.2）
  - §5.4 同时设计 Neo4j Sync Worker：消费 content 自身领域事件（如 `KnowledgePointCreated` / `Updated` / `Deleted` / `PrerequisiteAdded`），异步同步知识图谱节点到 Neo4j
  - 关键问题：**Neo4j 知识图谱同步是否属于"派生数据事件"？**
    - 若属于派生数据：Neo4j 同步走 Kafka consumer 直接消费即可（消费 content 主领域事件，无需再走一次 Outbox）
    - 若不属于派生数据：Neo4j 同步必须走 Outbox（content 双重 Outbox 设计，复杂度大幅增加）
  - 我的当前设计倾向：**Neo4j 知识图谱是 MySQL 主数据的派生读模型**（CQRS 读模型），知识图谱节点是从 knowledge_points / kp_prerequisites 表派生而来，故 Neo4j 同步走 Kafka consumer 即可，主领域事件仍走 Outbox
- **影响**：P4 事件设计实现策略不明确，影响 Outbox 表设计、Kafka consumer 实现与事件流程
- **建议方案**：明确裁决 Neo4j 知识图谱属于"派生数据读模型"，理由：
  - Neo4j 节点数据完全从 MySQL 的 knowledge_points / kp_prerequisites 表派生
  - Neo4j 是读模型（图查询优化），MySQL 是写模型（权威源）
  - 符合 CQRS 读写分离原则
  - 实现方式：content 主领域事件走 Outbox → Kafka，Neo4j Sync Worker 作为 Kafka consumer 消费这些事件并同步图谱（无需独立 Outbox）
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-028: ai04 02-architecture-design.md 与 coord B1（GraphQL）+ B2（gRPC）裁决冲突需回写

- **提请 AI**：ai04（student-bff + parent-bff）
- **类别**：裁决冲突（文档回写义务）
- **阶段**：P3
- **问题描述**：
  - `coord-final-decisions.md` §0.1 强制覆盖声明：各 AI 收到本文档后 3 个工作日内回写 02-architecture-design.md，删除"中间过渡方案"，对齐最终方案
  - `coord-final-decisions.md` B1 裁决：P2 起直接 GraphQL（GraphQL Yoga + DataLoader）
  - `coord-final-decisions.md` B2 裁决：首次实现即 gRPC 调用下游
  - ai04 的 `services/student-bff/docs/02-architecture-design.md` 与上述裁决存在 **2 项重大冲突**：
    1. **B1 冲突（API 风格）**：
       - §4 API 设计决策表决策为"P3 阶段先 REST，P4+ 统一升级时再考虑 GraphQL"
       - §9.2 演进路线规划 P3 REST → P4 REST+缓存 → P5+ REST+gRPC 混合 → P6+ GraphQL（可选）
       - §9.5 决策表第 1 项明确选 A（REST）
       - 与 B1"P2 起直接 GraphQL"冲突，属典型的"中间过渡方案"
    2. **B2 冲突（对下游通信）**：
       - §1.1 模块分层图 DownstreamClient 标注"HTTP / gRPC P3+"混合
       - §7 交互矩阵全部标注"HTTP→gRPC P3+/P4+/P5+"
       - §9.3 协议演进规划 P3 HTTP REST → P4 HTTP+gRPC 混合 → P5 HTTP+gRPC+SSE
       - §9.3 DownstreamClient 设计为"根据 env.IamUseGrpc=true/false 切换协议"
       - 与 B2"首次实现即 gRPC"冲突，属典型的"中间过渡方案"
  - 另有 1 项表述待更新（非冲突）：
    - §1.3 写"改进点是否回写 teacher-bff 由 coord 仲裁"，但 coord 已裁决 B8 回写；§9.5 决策表第 9 项已选 B（回写），内容一致仅表述需更新
- **影响**：
  - ai04 违反 coord-final-decisions §0.1 回写义务，coord 验收时不通过
  - 若不回写，ai04 P3 启动时按 REST + HTTP fetch 实现 → 后期必废弃重写（与用户"直接使用最好的方式"指示矛盾）
  - student-bff GraphQL schema 需与 ai14 student-portal 双向协调（见 ISSUE-030）
- **建议方案**：
  1. ai04 立即执行回写（在批次 0/1 等待期间完成，不阻塞 P3 启动）：
     - §4 API 设计决策表：决策改为 B（GraphQL），删除"P3 先 REST"
     - §1.1 模块分层图：DownstreamClient 调用全部改为 gRPC（删除"HTTP / gRPC P3+"混合标注）
     - §7 交互矩阵：协议列全部改为 gRPC（删除"HTTP→gRPC"演进标注）
     - §8 外部依赖表：删除"当前走 REST，proto 补全后切换 gRPC"表述，改为"gRPC 调用，依赖 proto 补全"
     - §9.2 演进路线：删除 REST→GraphQL 演进描述，改为"P3 起 GraphQL，与 teacher-bff 对齐"
     - §9.3 协议演进：删除 HTTP→gRPC 演进描述，改为"P3 起 gRPC（iam + core-edu），P4 扩展 gRPC（content + data-ana），P5 扩展 gRPC（msg + ai）"——属跨阶段扩展例外（已裁决）
     - §9.5 决策表第 1 项：改为 B（GraphQL）
     - §1.3：更新为"按 B8 裁决回写 teacher-bff，DownstreamClient 抽象由 ai03 P2 产出，ai04 复用"
     - §9.3：删除"根据 env 切换协议"设计，改为"统一 gRPC"
  2. 回写完成后 ai04 自行验证 + 在 known-issues.md 工作经验日志追加记录
  3. 回写不阻塞 P3 启动（批次 2 启动前完成即可）
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-029: ai04 P3 启动前置依赖确认（4 项强阻塞）

- **提请 AI**：ai04（student-bff + parent-bff）
- **类别**：前置依赖未就绪
- **阶段**：P3
- **问题描述**：
  - 按 `ai-work-orchestration.md` §5.1，批次 2（P3）启动前置条件：
    1. 批次 1 完成（iam gRPC 50052 + GetChildrenByParent 已就绪）
    2. 批次 0 中 0.8-0.9 全部就位（core_edu.proto + buf.gen.yaml gRPC 插件）
  - 按 `coord-final-decisions.md` B1 + B2 + B8，ai04 student-bff P3 启动实际依赖 **4 项强阻塞前置**：
    1. **批次 0.8 core_edu.proto 补全**（AttendanceService / GetClassesByTeacher / BatchGetClasses）— ⏳ 待办，直接阻塞 student-bff gRPC 调 core-edu
    2. **批次 0.9 buf.gen.yaml gRPC 插件**（grpc/node 插件）— ⏳ 待办，直接阻塞 gRPC 代码生成（shared-ts 目录不存在问题已识别）
    3. **ai03 teacher-bff P2 产出的 DownstreamClient 抽象**（B8 裁决，3 个 BFF 统一使用）— 依赖批次 1 完成，ISSUE-007 已识别此风险
    4. **ai08 core-edu gRPC server 50053 启用**（C2 裁决 P3 首次实现即启用）— 依赖 ai07 classes 代码交接 + ai08 实现
  - 另有 2 项非强阻塞但影响功能完整性的依赖：5. ai06 iam gRPC 50052 + GetChildrenByParent（I1 + I6 裁决，批次 1 交付）— student-bff 调 iam 取学生身份 + 视口 6. coord 仲裁 student-bff GraphQL schema 第一版（见 ISSUE-030）
  - **连锁风险**：若 4 项强阻塞任一延期，ai04 P3 启动延期，进而阻塞 ai14 student-portal P3（依赖 ai04 schema）
- **影响**：批次 2（P3）整体延期风险；ai04 / ai14 启动信号失效
- **建议方案**：
  1. coord 明确批次 2 启动信号机制：批次 0.8 + 0.9 完成 + 批次 1 验收通过（含 ai03 DownstreamClient 抽象 + ai08 core-edu gRPC 50053 可用）后发布批次 2 启动公告
  2. ai04 在批次 1 期间（等待期）完成 ISSUE-028 回写 + student-bff GraphQL schema 草案（供 coord 仲裁）
  3. 建议建立"前置依赖就绪检查清单"，coord 在批次 2 启动前逐项确认
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-030: ai04⟷ai14 student-bff GraphQL schema 第一版仲裁时机

- **提请 AI**：ai04（student-bff + parent-bff）
- **类别**：契约不明确
- **阶段**：P3
- **问题描述**：
  - `coord-final-decisions.md` B1 裁决：P2 起直接 GraphQL
  - `ai-work-orchestration.md` §5.2 规划 ai04⟷ai14 双向依赖（student-bff GraphQL schema 契约）
  - `ai-work-orchestration.md` §5.3 协调点："coord 仲裁 student-bff schema 第一版"
  - 参照批次 1 ai03⟷ai13 模式（§4.3）："coord 在批次 1 启动前仲裁 schema 第一版"
  - ISSUE-019（ai08 提请）已识别 GraphQL schema 仲裁机制未明确，本 issue 为 ai04 视角的批次 2 同类问题
  - **未明确的问题**：
    1. student-bff GraphQL schema 第一版仲裁时机：是批次 1 结束后立即（批次 2 启动前）？还是批次 2 启动后消耗 P3 工作时间？
    2. 仲裁过程是否阻塞 ai04 / ai14 并行开发？（若 schema 未定，ai04 无法实现 resolver，ai14 无法实现 client query）
    3. schema 仲裁应包含哪些内容（Query/Mutation 清单 + 类型定义 + 权限点 + DataScope 标注）？
    4. 是否复用 ai03 teacher-bff 的 schema 模式（如分页 / 错误信封 / DataScope 透传约定）？
- **影响**：若 schema 仲裁未在批次 2 启动前完成，ai04 和 ai14 无法并行开发，浪费 P3 早期时间
- **建议方案**：
  1. 将 student-bff GraphQL schema 第一版仲裁纳入批次 1 收尾（coord 在批次 1 验收时同步仲裁 schema），P3 启动前必须完成 schema 文档
  2. schema 仲裁内容对齐 ai03 teacher-bff 模式：Query/Mutation 清单 + 类型定义 + 权限点（F7 规范）+ DataScope 标注 + 分页/排序约定 + 错误信封映射
  3. ai04 在批次 1 等待期起草 schema 草案（基于 02-architecture-design.md §4 的 21 端点映射为 GraphQL operations），提交 coord 仲裁
  4. ai14 在批次 1 等待期同步起草 client query 清单，与 ai04 草案对齐
  5. coord 仲裁后 ai04 / ai14 P3 启动即并行实现 server/client
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-031: issues.md ISSUE-024/025 编号冲突（ai11 与 ai09 重复）

- **提请 AI**：ai04（student-bff + parent-bff）
- **类别**：工作归属不明（文档规范）
- **阶段**：全阶段
- **问题描述**：
  - 当前 issues.md §1 待仲裁问题区存在编号冲突：
    - ISSUE-024（ai11 data-ana，ClickHouse DDL 目录归属）位于 line 397
    - ISSUE-024（ai09 content，ES Projector 实现位置）位于 line 508 — **与 ai11 重复**
    - ISSUE-025（ai11 data-ana，analytics.proto 扩展交付时间）位于 line 412
    - ISSUE-025（ai09 content，Neo4j 派生数据豁免）位于 line 530 — **与 ai11 重复**
  - 各 AI 引用 ISSUE-024/025 时无法确定指 ai11 还是 ai09，coord 仲裁时可能遗漏
  - 此问题与 ai07 此前提请的编号冲突问题同类（该版本已被 ai08 重写覆盖，但新冲突再次出现）
- **影响**：编号引用混乱，coord 仲裁时可能漏处理某个 AI 的问题
- **建议方案**：
  1. ai09 的两个问题重新编号为 ISSUE-032（ES Projector）、ISSUE-033（Neo4j 派生数据），本编号冲突记录保留 ISSUE-031
  2. 或 coord 统一重新编号全部 ISSUE-015+，确保连续无重复
  3. 建议 §0.4 编号规则补充"各 AI 提请前先 Grep 确认最大编号，自增不重复"
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-042: M2 msg /readyz 强依赖 PushGateway 与 P5 同批次启动时序冲突

- **提请 AI**：ai10（msg）
- **类别**：前置依赖未就绪（跨服务 /readyz 强依赖）
- **阶段**：P5
- **问题描述**：
  - `coord-final-decisions.md` M2 裁决：msg `/readyz` 首次实现即检查 DB/ES/Redis/Kafka/PushGateway
  - `ai-work-orchestration.md` §7.2 批次 4（P5）：ai10⟷ai02 双向依赖，ai02 优先 1-2 天启动 /internal/push 端点，ai10 后启动
  - 矛盾点：
    1. M2 把 PushGateway 列为 msg /readyz 的强依赖项 → 若 PushGateway 未就绪，msg /readyz 永远返回 503 → K8s readinessProbe 失败 → msg Pod 不接收流量
    2. ISSUE-012 裁决的"ai02 优先 1-2 天启动"只能缓解**接口契约**就绪问题，不能缓解 PushGateway **Pod 完全 Ready**（含自身 /readyz 通过）的时序问题
    3. 即使 ai02 的 /internal/push 端点代码已实现，PushGateway 服务本身的 Pod 启动 + 健康检查通过 + 进入 Service 端点仍需时间（容器拉镜像 + 启动 + probes 通过，K8s 默认 initialDelaySeconds=30 + periodSeconds=10 + successThreshold=1，最坏情况 40+ 秒）
    4. 若 msg 与 PushGateway 同批次部署（docker compose up 同时启动），msg 的 /readyz 在 PushGateway Pod Ready 前会持续失败
    5. ISSUE-034（ai03 提请，G2 /readyz 检查全部下游在 P2 不可行）已识别同类问题；本 issue 是 msg /readyz 与 P5 PushGateway 同批次时序冲突（注：issues.md 编号严重冲突，ISSUE-034 在不同区域可能指不同问题，coord 待整理）
  - 与 ISSUE-012 的差异：
    - ISSUE-012 关注**接口契约**就绪（ai02 实现端点）
    - 本 issue 关注**Pod 运行时**就绪（PushGateway Pod 进入 Service 端点）
    - 两者时序风险不同，需分别处理
- **影响**：
  - msg Pod 在 PushGateway 未就绪时无法进入 Service 端点，无法接收 teacher-bff / student-bff 的 gRPC 调用
  - 连锁阻塞 ai03 teacher-bff P5 扩展（B2 裁决 gRPC 调 msg）
  - 连锁阻塞 ai04 student-bff P5 扩展
  - docker compose up 同时启动时，msg 可能因 /readyz 失败被 compose 标记为 unhealthy，影响 `depends_on: { condition: service_healthy }` 链
- **建议方案**：
  - **方案 A（推荐，符合裁决精神）**：M2 裁决保留"PushGateway 列入 /readyz 检查项"，但允许**软失败**——
    - /readyz 检查 PushGateway 时，HTTP 调用 `/healthz` 失败仅记录 `warning` 级别日志，**不返回 503**，仍返回 200
    - 仅当 DB/ES/Redis/Kafka（msg 自身强依赖）失败时才返回 503
    - PushGateway 失败时 msg 仍可接收 gRPC 调用（推送降级为本地 DLQ + 重试，不影响通知发送主流程）
    - 理由：PushGateway 是"末端投递"依赖，msg 主流程（接收事件 + 入库 + ES 索引 + 已读标记）不依赖 PushGateway，仅 ChannelStrategy.PushStrategy 投递环节依赖
  - **方案 B**：M2 修订为"首次实现检查 DB/ES/Redis/Kafka，PushGateway 检查推迟到 P5 ai02 完成后启用"——但违反"不分阶段"原则
  - **方案 C**：保持 M2 裁决不变，docker-compose.deploy.yml 中 msg 显式 `depends_on: { push-gateway: { condition: service_healthy } }`——但会引入循环依赖风险（若 push-gateway 反向依赖 msg 的某些场景）
  - **ai10 倾向方案 A**，理由：
    1. 符合 G2"首次实现即检查全部下游依赖"精神（仍检查，只是失败处理策略不同）
    2. 符合"通知基础设施"定位（PushGateway 不可用时通知流程应降级而非完全拒绝服务）
    3. 与 02-architecture.md §6.4 优雅关闭策略一致（关闭顺序 HTTP→DB→Redis→Kafka，PushGateway 不在关闭链中，因属外部服务）
    4. 与 ISSUE-034 ai03 建议方案思路一致（软失败 + 降级）
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-043: 004 §7.2 表格 `edu.notification.events` 与 §16.3.2 + G16 裁决不同步（文档同步遗漏）

- **提请 AI**：ai10（msg）
- **类别**：裁决冲突（文档内部不同步）
- **阶段**：全阶段
- **问题描述**：
  - `coord-final-decisions.md` G16 裁决：Kafka topic 命名统一 `edu.<domain>.<aggregate>.<action>`，**禁止 `edu.notification.events` 抽象名**
  - `004_architecture_impact_map.md` §7.2 Kafka topic 路由表 L658 仍保留：
    ```
    | `edu.notification.events` | 通知事件 | Msg | push-gateway |
    ```
  - `004_architecture_impact_map.md` §16.3.2 Topic 命名冲突（coord 交叉审查裁决）已明确：
    ```
    - `edu.notification.events` → 统一为 `edu.notification.<action>`（具体动作）
    ```
  - **矛盾**：§7.2 表格（"代码现状"应反映）与 §16.3.2 裁决（"设计意图"）不同步，§7.2 仍用旧抽象名
  - `004_architecture_impact_map.md` §7.2 强制约束 L672 已写"领域事件必须遵循 `edu.<domain>.<aggregate>.<action>` 格式，禁止 `edu.exam.events` 这类按表名分组的命名"——但 §7.2 表格自身的 `edu.notification.events` 违反此约束
  - **未明确的 msg 设计影响**：
    1. ai10 msg 02-architecture.md §5 已设计 msg 发布 3 个事件：`edu.notification.sent` / `edu.notification.read` / `edu.notification.recalled`（符合 G16 + §16.3.2 裁决）
    2. 但 004 §7.2 表格仍写 `edu.notification.events`（抽象名）→ 若 ai10 严格按 004 §7.2 表格实现，会与 G16 裁决冲突
    3. push-gateway（ai02）消费方按 004 §7.2 表格订阅 `edu.notification.events` → 若 msg 发布 `edu.notification.sent`，push-gateway 收不到事件
  - 与已知 topic 命名问题的差异：
    - 已知问题（core-edu TOPIC_MAP 用 `edu.exam.events`）：关注**发布方代码**与 004 §7.2 新约定不一致（代码 vs 文档）
    - 本 issue：关注 `004 §7.2` **表格自身**与 §16.3.2 裁决不同步（文档内部矛盾）
    - 两者都是 topic 命名同步问题，但责任主体不同（core-edu 代码 vs 004 文档）
- **影响**：
  - ai10 msg 实现发布事件时不确定 topic 命名应遵循 004 §7.2 表格（抽象名）还是 §16.3.2 裁决（具体动作名）
  - 若 ai10 按 02-architecture.md §5 设计（具体动作名）→ 与 004 §7.2 表格不一致 → coord 验收时可能要求"对齐 004 §7.2"
  - 若 ai10 按 004 §7.2 表格（抽象名）→ 违反 G16 + §16.3.2 裁决 → 仲裁冲突
  - 连锁影响 push-gateway（ai02）消费方订阅 topic 不一致
- **建议方案**：
  - coord 修订 004 §7.2 表格 L658，将 `edu.notification.events` 替换为 3 条具体动作 topic：
    ```
    | `edu.notification.sent`     | 通知发送 | Msg | push-gateway、DataAna |
    | `edu.notification.read`     | 通知已读 | Msg | DataAna              |
    | `edu.notification.recalled` | 通知撤回 | Msg | DataAna              |
    ```
    （消费方列表参照 ai10 02-architecture.md §5.2 已设计的消费方，coord 可调整）
  - 同步修订 004 §7.2 表格中其他仍用抽象名的条目（若有）
  - 在 §7.2 表格下方追加注释"本表已对齐 §16.3.2 裁决，禁止抽象名 `edu.*.events`"
  - ai10 待 004 §7.2 修订后对照 02-architecture.md §5 验证一致性
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

---

### ISSUE-044: admin-portal BFF 归属不明（004 §1.2 无 admin-bff，F9 裁决 BFF 用 GraphQL）

- **提请 AI**：ai16（admin-portal）
- **类别**：工作归属不明
- **阶段**：P6
- **问题描述**：
  - `coord-final-decisions.md` F9 裁决：P2 起 BFF 用 GraphQL，前端用 urql/apollo
  - `004 §1.2` 服务清单列 3 个 BFF：teacher-bff（ai03）/ student-bff（ai04）/ parent-bff（ai05），**无 admin-bff**
  - `ai-allocation.md` §3.2：ai16 = admin-portal，无对应 admin-bff 服务
  - ai16 的 `apps/admin-portal/docs/02-architecture-design.md` §4.1 描述：复用 teacher-portal Shell 暴露的 ApiClient（REST 风格）调 iam/core-edu/data-ana
  - **冲突**：F9 裁决 BFF 用 GraphQL，但 admin-portal 没有 BFF，数据获取路径未定义
  - **三种可能方案**：
    1. 新建 admin-bff 服务（ai16 或 coord 负责），暴露 GraphQL endpoint
    2. 复用 teacher-bff 的 GraphQL endpoint，admin-portal 作为 client 接入（需 ai03 预留 admin schema 命名空间）
    3. admin-portal 跳过 BFF 层，直接调下游服务 gRPC（违反 BFF 聚合原则）
- **影响**：admin-portal P6 启动时数据获取路径不明，阻塞 admin-portal MVP 实现
- **建议方案**：采纳方案 2（复用 teacher-bff），理由：
  1. admin 操作低 QPS，无需独立 BFF 实例
  2. 减少 ai16 工作量（无需新建服务）
  3. 需 ai03 P2 预留 admin schema 命名空间（如 `admin.*` Query/Mutation）
  4. coord 在批次 1 启动前仲裁 schema 第一版时纳入 admin 命名空间
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-045: admin-portal 错误码前缀缺失（G14 清单 13 个前缀未列 ADMIN_ 也未列 SCHOOL_）

- **提请 AI**：ai16（admin-portal）
- **类别**：裁决冲突
- **阶段**：P6
- **问题描述**：
  - `coord-final-decisions.md` G14 裁决：错误码前缀清单 13 个：`GW_/IAM_/CORE_EDU_/CONTENT_/MSG_/DATA_ANA_/AI_/PUSH_/BFF_TEACHER_/BFF_STUDENT_/BFF_PARENT_/CLASSES_`
  - ai16 的 `apps/admin-portal/docs/02-architecture-design.md` §6.2 错误码清单定义 `ADMIN_` + `SCHOOL_` 两个新前缀
  - §12.4 错误码前缀表标注 `ADMIN_` 和 `SCHOOL_` 为"❌ 待新增（coord 仲裁）"
  - **G14 清单未列 `ADMIN_` 也未列 `SCHOOL_`**，admin-portal 错误码命名归属不明
  - admin-portal 涉及 3 类业务：用户/角色管理（iam 域）、学校设置、组织管理，是否分别用 IAM_/SCHOOL_/ORG_ 前缀还是统一 ADMIN_？
- **影响**：admin-portal P6 错误码设计阻塞，前端 i18n key 命名阻塞（F4 裁决 error.<service>.<code>）
- **建议方案**：
  1. G14 清单补充 `ADMIN_` 前缀（合并 SCHOOL_ 入 ADMIN_，因学校设置属 admin 业务子域）
  2. ORG 管理也归入 ADMIN_ 前缀（统一 admin 域）
  3. 错误码命名：`ADMIN_<RESOURCE>_<ERROR>`（如 `ADMIN_SCHOOL_NOT_FOUND`、`ADMIN_ORG_DUPLICATE_NAME`）
  4. i18n key：`error.admin.*`（对齐 F4 规范）
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-046: admin-portal 权限点命名与 F7 规范的契合度（F7 例子未带服务前缀，ai16 用带前缀命名）

- **提请 AI**：ai16（admin-portal）
- **类别**：契约不明确
- **阶段**：P6
- **问题描述**：
  - `coord-final-decisions.md` F7 裁决：权限点统一 `<RESOURCE>_<ACTION>`（如 DASHBOARD_VIEW、EXAM_READ、GRADE_READ），数据范围用后缀 _OWN/_CHILD
  - ai16 的 `apps/admin-portal/docs/02-architecture-design.md` §6.1 权限表 27 路由，使用 **带服务前缀** 命名：
    - `ADMIN_DASHBOARD_VIEW`
    - `IAM_USER_READ` / `IAM_ROLE_MANAGE`
    - `SCHOOL_SETTING_READ`
    - `ORG_MANAGE`
  - **冲突**：F7 例子 `DASHBOARD_VIEW` 未带服务前缀，ai16 用 `ADMIN_DASHBOARD_VIEW` 带前缀
  - F7 裁决文本未明确"权限点是否允许服务前缀作为命名空间"
  - 若 F7 严格禁止前缀 → admin-portal 27 个权限点需重命名（如 `ADMIN_DASHBOARD_VIEW` → `DASHBOARD_VIEW`）
  - 若 F7 允许前缀 → 当前命名有效，但需明确前缀规则（哪些资源需带前缀）
- **影响**：admin-portal P6 权限点设计阻塞，前端 usePermission() 调用阻塞
- **建议方案**：
  1. F7 允许服务前缀作为命名空间（避免不同域同名资源冲突，如 `CONTENT_QUESTION_READ` vs `CORE_EDU_QUESTION_READ`）
  2. 命名规则：`[<SERVICE>_]<RESOURCE>_<ACTION>[_<SCOPE>]`，SERVICE 可选
  3. admin-portal 权限点统一加 `ADMIN_` 前缀（与错误码前缀对齐，见 ISSUE-033）
  4. 跨服务资源（如调 iam 用户管理）保留 iam 前缀（`IAM_USER_READ`），admin 自身资源用 `ADMIN_` 前缀
  5. 需 coord 确认：admin-portal 调下游服务（iam/core-edu/data-ana）的权限点校验由谁负责？（admin-portal 校验还是下游校验？）
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-047: admin-portal GraphQL 客户端复用 Shell 还是独立引入（ai16 文档 §4.1 描述 REST，未提及 GraphQL）

- **提请 AI**：ai16（admin-portal）
- **类别**：契约不明确
- **阶段**：P6
- **问题描述**：
  - `coord-final-decisions.md` F9 裁决：前端用 urql/apollo
  - `coord-final-decisions.md` F10 裁决：暴露 AppShell 整体，各 Remote 自行决定内部布局
  - ai16 的 `apps/admin-portal/docs/02-architecture-design.md` §4.1 描述：复用 teacher-portal Shell 暴露的 ApiClient（REST 风格），未提及 GraphQL 客户端
  - **冲突**：F9 要求前端用 GraphQL 客户端（urql/apollo），但 ai16 文档设计为 REST ApiClient
  - **未明确**：
    1. admin-portal 作为 MF Remote 接入 teacher-portal Shell，是否复用 Shell 暴露的 GraphQL client 单例？
    2. 若复用 → ai13 P2 teacher-portal MF shell 必须暴露 GraphQL client（urql/apollo createClient 单例）
    3. 若独立引入 → admin-portal 自行 createClient，需配置 GraphQL endpoint URL
    4. GraphQL endpoint URL 是 teacher-bff 的 /graphql 还是其他？
- **影响**：admin-portal P6 GraphQL 接入阻塞，需 ai13 P2 在 MF shell 中预留 GraphQL client 暴露接口
- **建议方案**：
  1. 复用 Shell 暴露的 GraphQL client 单例（urql createClient 实例，配置 teacher-bff /graphql endpoint）
  2. ai13 P2 teacher-portal MF shell 设计中增加暴露 GraphQL client（除原有 ApiClient REST 外）
  3. ai16 在 admin-portal 02 文档 §4.1 回写：将 "复用 ApiClient (REST)" 改为 "复用 Shell 暴露的 GraphQL client 单例"
  4. 需 coord 在批次 1 启动前仲裁 MF shell 暴露清单（增加 GraphQL client 项）
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-048: admin-portal 审计日志与 iam 审计事件归属耦合（X3 待 P6 仲裁但 events.proto message 未补）

- **提请 AI**：ai16（admin-portal）
- **类别**：前置依赖未就绪
- **阶段**：P6
- **问题描述**：
  - `coord-final-decisions.md` X3 裁决：审计日志归属待 P6 仲裁
  - `coord-final-decisions.md` X2 裁决：admin-portal 8 个新 Kafka topic + events.proto message 在 P6 实施时补
  - `ai-work-orchestration.md` §8.2：ai16 依赖仅"events.proto（P6 实施时补 admin 8 topic）"
  - **冲突**：
    1. X3 待 P6 仲裁审计日志归属（iam vs audit-service vs admin-portal 自身）
    2. 若审计日志归属 iam → iam 需发布审计事件，但 events.proto 无 AuditEvent message
    3. 若审计日志归属 admin-portal → admin-portal 需消费各服务事件并写入审计表，但 8 个新 topic 未定义
    4. 若审计日志归属独立 audit-service → 需新建服务，超出 ai16 范围
  - **时序问题**：X3 仲裁在 P6 启动时进行，但 admin-portal MVP 依赖审计日志功能（管理员操作需可追溯）
- **影响**：admin-portal P6 审计日志功能阻塞，admin 操作无法追溯，违反企业级审计要求
- **建议方案**：
  1. coord P6 启动前明确审计日志归属：建议归 iam（iam 已掌握用户/角色数据，审计事件天然属 iam 域）
  2. events.proto 补 `AuditEvent` message（actor_user_id / action / resource_type / resource_id / before / after / ip / user_agent / trace_id / created_at）
  3. 新增 topic `edu.iam.audit.created`（统一审计事件 topic，不按操作类型分）
  4. admin-portal 作为 consumer 订阅 `edu.iam.audit.created`，写入 ClickHouse 审计表（或 MySQL 审计表）
  5. admin-portal 8 个新 Kafka topic 重新评估：若审计归 iam，admin-portal 仅需 1 个 audit consumer topic，无需 8 个
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

---

## 2. 已解决问题

> coord 仲裁后 AI 执行完成的问题移到此处。

（暂无）

---

## 3. coord 仲裁记录

> coord 每批次结束后统一仲裁，记录在此。

### 3.1 ai08 复审批次（2026-07-09）

**复审范围**：coord-cross-review.md + coord-final-decisions.md + ai-work-orchestration.md + issues.md v1.0 + port-allocation.md + 004 §16

**复审结论**：

| 维度           | 评估                                                                                                                                              |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **仲裁可行性** | 高。80+ 项裁决技术方案清晰，对齐黄金模板，依赖关系明确。C1-C11 core-edu 专项裁决全部可落地。                                                      |
| **仲裁影响**   | 中。直接影响 ai08 的裁决 11 项（C1-C11），全部已裁决无阻塞。间接影响（iam gRPC / content QuestionService / buf.gen.yaml）依赖 coord 批次 0 就绪。 |
| **文档同步**   | **差**。14 个 issues 状态未回填（ISSUE-017）；port-allocation.md §3 与 §5 冲突（ISSUE-015）；004 §16.7.4 与 §16.7.5 与 N3 裁决冲突（ISSUE-016）。 |
| **契约明确性** | 中。shared-ts Outbox 工具包设计未明确（ISSUE-018）；GraphQL schema 仲裁机制未明确（ISSUE-019）；AttendanceService proto 责任方不明（ISSUE-022）。 |
| **批次规划**   | 高。批次 0-5 规划合理，依赖关系清晰，跨阶段扩展例外原则已建立。                                                                                   |
| **遗留风险**   | 低-中。ISSUE-013（parent-bff P4 通知）+ ISSUE-014（admin-portal P6 topic）未解决，但不阻塞当前批次。                                              |

**新增 8 个问题**（ISSUE-015 ~ ISSUE-022）已登记到"待仲裁问题"区，待 coord 仲裁。

**建议 coord 优先处理**：

1. **P0**：ISSUE-015（port-allocation.md §5 修正）+ ISSUE-016（004 §16.7.4/§16.7.5 修正）—— 文档冲突，立即修正
2. **P0**：ISSUE-022（AttendanceService proto 责任方）—— 阻塞 ai08 P3 启动
3. **P1**：ISSUE-018（shared-ts Outbox 设计）+ ISSUE-019（GraphQL schema 仲裁机制）—— 阻塞批次 0/1 启动
4. **P2**：ISSUE-017（issues 状态回填）+ ISSUE-020（跨阶段扩展验收标准）+ ISSUE-021（表述澄清）—— 文档完善
5. **P3**：ISSUE-013（parent-bff P4 通知）+ ISSUE-014（admin-portal P6 topic）—— 待后续批次评估

---

### 3.2 ai09 复审批次（2026-07-09）

**复审范围**：coord-final-decisions.md（content 部分 N1-N5）+ ai-work-orchestration.md（批次 3 P4）+ 我的 services/content/docs/02-architecture-design.md（§3.3/§5.4/§8.2/§9.3）+ ISSUE-010（QuestionService proto 补全时机）

**复审结论**：

| 维度           | 评估                                                                                                                                                                                                                                                           |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **仲裁可行性** | 高。N1-N5 五项直接裁决技术方案清晰，对齐黄金模板（classes），依赖关系明确（前置批次 0.10 content.proto 补全）。我的 02 文档已设计完整 gRPC（§4.2，3 service 13 RPC）/ Outbox（§5.4）/ Neo4j Sync Worker（§5.4）/ 错误信封（§6.2），N1-N5 裁决全部可落地。      |
| **仲裁影响**   | 中。直接影响 ai09 的裁决 5 项（N1-N5），全部已对齐无阻塞。间接影响：P4 工作量增加（gRPC server 实现 + QuestionService 完整实现 + Outbox + Neo4j Sync Worker + /readyz 多依赖扩展）；coord 验收 P4 时强制检查 QuestionService RPC 已落地（阻塞 ai12 P5 出题）。 |
| **文档同步**   | 中。我的 02 文档 §9.3 待 coord 仲裁项 6 项中：5 项已被 coord 裁决覆盖（Outbox 启用→004 §12.2 / proto 包名→G17 / DB 模式→G10 / ID 策略→G11 / QuestionService proto→N3），1 项未裁决（content ES 启用时机）。需回写 02 文档移除已裁决项。                        |
| **契约明确性** | 中。ES Projector 实现位置未明确（ISSUE-024）；Neo4j 知识图谱同步是否属派生数据豁免 Outbox 未明确（ISSUE-025）；/readyz 检查项与 P5 ES 引入时序冲突（ISSUE-023）。                                                                                              |
| **批次规划**   | 高。批次 3 P4 规划合理，前置依赖清晰：批次 0.10 content.proto 补全（coord 负责）+ 批次 2 完成（core-edu gRPC 50053 可用）+ iam.GetChildrenByParent 已就绪（批次 1 已完成）。ai09 P4 与 ai11 data-ana P4 可并行。                                               |
| **遗留风险**   | 低。3 个新提请问题（ISSUE-023/024/025）均不阻塞 P4 启动（可按建议方案实现，待 coord 仲裁确认）。ai12 P5 出题依赖 ai09 P4 QuestionService RPC 落地，已通过 ai-work-orchestration.md §6.3 验收点明确。                                                           |

**新增 3 个问题**（ISSUE-023 ~ ISSUE-025）已登记到"待仲裁问题"区，待 coord 仲裁。

**建议 coord 优先处理**：

1. **P1**：ISSUE-025（Neo4j 知识图谱派生数据裁决）—— 影响 P4 Outbox 表设计与事件流程实现，建议优先裁决
2. **P1**：ISSUE-023（/readyz 检查项与 P5 ES 时序冲突）—— 影响 P4 /readyz 实现策略，建议补充 G2 豁免条款
3. **P2**：ISSUE-024（ES Projector 实现位置）—— 影响 P5 实施细节，P4 阶段不阻塞，建议 P5 启动前裁决

---

### 3.3 ai04 复审批次（2026-07-09）

**复审范围**：coord-cross-review.md + coord-final-decisions.md（BFF 专项 B1-B8 + 通用 G1-G17）+ ai-work-orchestration.md（批次 2 P3 + 批次 3 P4）+ port-allocation.md + 我的 services/student-bff/docs/02-architecture-design.md（§1/§4/§7/§8/§9）+ ISSUE-006/007（已识别的 ai04 相关问题）

**复审结论**：

| 维度           | 评估                                                                                                                                                                                                                                                                                                                                                        |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **仲裁可行性** | 高。B1-B8 八项 BFF 专项裁决技术方案清晰，GraphQL Yoga + DataLoader + gRPC + DownstreamClient 抽象均为成熟方案。B3/B4/B5/B6/B7 五项与我的 02 文档设计完全一致（BFF 豁免 @RequirePermission / 强制自我越权防御 / BFF_STUDENT_ 前缀 / Redis 短缓存 / P2-P4 不订阅 Kafka）。B1/B2 两项与我的设计冲突但方案本身可行（见 ISSUE-028）。B8 回写裁决与我的建议一致。 |
| **仲裁影响**   | 中-高。直接影响 ai04 的裁决 8 项（B1-B8）：5 项已对齐无阻塞，2 项需回写（B1 GraphQL / B2 gRPC，见 ISSUE-028），1 项表述待更新（B8）。间接影响：P3 工作量增加约 30-40%（引入 GraphQL Yoga + DataLoader + gRPC client + proto 生成代码），但通过复用 ai03 P2 产出的 DownstreamClient 抽象可部分抵消。parent-bff P4 同样受 B1-B8 影响，回写时需一并处理。      |
| **文档同步**   | **差**。我的 02-architecture-design.md 存在 2 项重大冲突未回写（B1/B2，见 ISSUE-028），违反 coord-final-decisions §0.1 回写义务。01-understanding.md + 02-audit.md 的错误码前缀已在阶段 2 修正为 BFF_STUDENT_（与 B5 一致）。                                                                                                                               |
| **契约明确性** | 中。student-bff GraphQL schema 第一版仲裁时机未明确（ISSUE-030，与 ISSUE-019 同类）；DownstreamClient 抽象 API 契约依赖 ai03 P2 产出（ISSUE-007/029）；batch 0.8 core_edu.proto + 0.9 buf.gen.yaml gRPC 插件为强阻塞前置（ISSUE-029）。                                                                                                                     |
| **批次规划**   | 高。批次 2 P3 规划合理：ai04⟷ai14 双向依赖 + ai08 core-edu 交接 + ai03 跨阶段扩展。跨阶段扩展例外原则（批次规划原则 5）已解决 ISSUE-006（student-bff P3 调 content/data-ana 断裂），ai04 接受此裁决。                                                                                                                                                       |
| **遗留风险**   | 中。B7 裁决 P2-P4 BFF 不订阅 Kafka → student-bff P3-P4 学生通知无法实时推送（与 ISSUE-013/023 同类），需推迟到 P5；B2 裁决首次实现即 gRPC 但 content/data-ana P4 才启用 → student-bff P3 仅能 gRPC 调 iam+core-edu，P4 扩展调 content+data-ana（跨阶段扩展例外）。                                                                                          |

**新增 4 个问题**（ISSUE-028 ~ ISSUE-031）已登记到"待仲裁问题"区，待 coord 仲裁。

**ai04 对 coord 仲裁的整体评判**：

1. **B1 GraphQL 裁决可行性：中-高**
   - 优点：GraphQL Yoga + DataLoader 是成熟方案，ai03 teacher-bff P2 已先行，ai04 P3 可复用 ai03 的 schema 模式和 resolver 模式
   - 风险：ai04⟷ai14 双向依赖需 coord 仲裁 schema 第一版（ISSUE-030），若仲裁不及时将阻塞并行开发
   - 工作量影响：相比原 REST 设计，需引入 GraphQL Yoga + DataLoader + schema 定义 + resolver 实现，工作量增加约 30-40%
   - 阻塞依赖：依赖 ai03 P2 产出的 GraphQL server 模式 + DownstreamClient 抽象（B8 裁决）

2. **B2 gRPC 裁决可行性：中（受限于下游启用阶段）**
   - 优点：gRPC 性能优于 HTTP，proto 契约强类型，与 004 §3.2 "服务间通过 gRPC 通信"一致
   - 风险：student-bff P3 只能 gRPC 调 iam + core-edu（批次 1/2 启用），调 content/data-ana 需等到 P4，调 msg/ai 需等到 P5 → 跨阶段扩展
   - 已被 ISSUE-006 + 批次规划原则 5（跨阶段扩展例外）解决，ai04 接受此裁决
   - 工作量影响：需引入 @grpc/grpc-js + proto 生成代码 + gRPC client 封装，相比 HTTP fetch 工作量增加；但通过复用 ai03 DownstreamClient 抽象可降低
   - 阻塞依赖：批次 0.8（core_edu.proto 补全）+ 0.9（buf.gen.yaml gRPC 插件）+ ai08 core-edu gRPC 50053 启用（ISSUE-029）

3. **B8 DownstreamClient 回写裁决可行性：高**
   - 优点：统一三端 BFF 抽象，避免技术栈分裂，与我的 02 文档 §9.5 决策第 9 项建议一致
   - 风险：ai04 P3 启动严格依赖 ai03 P2 产出可复用的 DownstreamClient 抽象（ISSUE-007 已识别）
   - 工作量影响：ai04 复用 ai03 抽象，自身工作量减少；但需等待 ai03 P2 完成，存在时序依赖

4. **批次 0 前置条件对 ai04 P3 启动的影响**
   - 0.3 iam.proto 8 RPC：批次 1 完成即可（ai06 P2 实现），不直接阻塞 ai04 P3
   - 0.4 shared-ts Outbox：B7 裁决 P2-P4 BFF 不订阅 Kafka，故 ai04 P3 不需要 Outbox，不阻塞
   - 0.8 core_edu.proto 补全：**直接阻塞 ai04 P3**（student-bff 调 core-edu 需 proto）
   - 0.9 buf.gen.yaml gRPC 插件：**直接阻塞 ai04 P3**（gRPC 代码生成）

5. **ISSUE-006 / ISSUE-007 对 ai04 的影响**
   - ISSUE-006（student-bff P3 调 content/data-ana 断裂）：已被批次规划原则 5 解决（跨阶段扩展例外），ai04 接受此裁决，P3 仅实现 iam+core-edu 调用，P4 扩展 content+data-ana
   - ISSUE-007（DownstreamClient 抽象时间点）：已被 B8 + 批次 1 验收解决，但 ai04 P3 启动前需确认 ai03 P2 已产出（ISSUE-029 强化此依赖确认）

**建议 coord 优先处理**：

1. **P0**：ISSUE-028（02 文档回写）—— ai04 自行执行回写，coord 验收时确认，不阻塞但需优先完成
2. **P1**：ISSUE-029（P3 前置依赖确认）+ ISSUE-030（GraphQL schema 仲裁时机）—— 阻塞批次 2 启动，建议批次 1 收尾时一并解决
3. **P2**：ISSUE-031（编号冲突）—— 文档规范，建议 coord 统一重新编号

**ai04 回写义务承诺**：

按 coord-final-decisions §7.1 要求，ai04 将在 3 个工作日内（批次 0/1 等待期间）回写 02-architecture-design.md：

- 删除 B1 冲突（REST → GraphQL）
- 删除 B2 冲突（HTTP fetch → gRPC）
- 更新 B8 表述（回写 teacher-bff）
- 回写后自行验证 + known-issues.md 工作经验日志追加记录

---

## 4. 变更记录

| 日期       | 变更                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | 决策者 |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| 2026-07-09 | 初始创建，登记 coord 识别的 14 个问题（ISSUE-001 ~ ISSUE-014）                                                                                                                                                                                                                                                                                                                                                                                                                                                 | coord  |
| 2026-07-09 | v1.1：ai08 复审 coord 仲裁后，补全 #1-#12 的 coord 裁决字段；新增 ISSUE-015 ~ ISSUE-022 共 8 个文档同步遗漏/契约不明确问题；新增 §3.1 ai08 复审批次记录                                                                                                                                                                                                                                                                                                                                                        | ai08   |
| 2026-07-09 | v1.2：ai09 复审 coord 仲裁（content 部分 N1-N5）后，新增 ISSUE-023 ~ ISSUE-025 共 3 个 content 服务相关问题（/readyz 时序冲突 / ES Projector 位置 / Neo4j 派生数据裁决）；新增 §3.2 ai09 复审批次记录                                                                                                                                                                                                                                                                                                          | ai09   |
| 2026-07-09 | v1.3：ai04 复审 coord 仲裁（BFF 专项 B1-B8 + 通用 G1-G17）后，新增 ISSUE-028 ~ ISSUE-031 共 4 个问题（02 文档 B1/B2 冲突回写 / P3 前置依赖确认 / GraphQL schema 仲裁时机 / 编号冲突）；新增 §3.3 ai04 复审批次记录（含仲裁可行性/影响评判）                                                                                                                                                                                                                                                                    | ai04   |
| 2026-07-09 | v1.3：ai15 复审 coord 仲裁（parent-portal 部分）后，新增 ISSUE-031 ~ ISSUE-035 共 5 个问题（相对路径错误 / REST vs GraphQL / 通知偏好 P4 落地冲突 / "不分阶段"原则违反 / issues.md 结构混乱）；新增 §3.3 ai15 复审批次记录                                                                                                                                                                                                                                                                                     | ai15   |
| 2026-07-09 | v1.4：ai10 复审 coord 仲裁（msg 专项 M1-M5 + 通用 G9/G10/G11/G16/G17 + 契约 §5.1）后，新增 ISSUE-042 ~ ISSUE-043 共 2 个问题（M2 PushGateway /readyz 强依赖时序冲突 / 004 §7.2 表格 edu.notification.events 与 G16 裁决不同步）；新增 §3.6 ai10 复审批次记录（含仲裁可行性/影响评判 + ai10 工作顺序规划）                                                                                                                                                                                                      | ai10   |
| 2026-07-09 | v1.4：ai13 复审 coord 仲裁（teacher-portal 部分 F1-F12 + G14/G15）后，新增 ISSUE-036 ~ ISSUE-041 共 6 个问题（03 文档 REST→GraphQL 演进策略冲突 / GraphQL schema 契约协调机制 / MF AppShell GraphQL client 单例 / packages 建立时机 / P2 功能范围 / 评估总结）；新增 §2.7 ai13 待仲裁问题区 + §3.4 ai13 复审批次记录（含仲裁可行性/影响评判 + 回写义务承诺）                                                                                                                                                   | ai13   |
| 2026-07-09 | v1.5：ai03 复审 coord 仲裁（BFF 专项 B1-B8 + 通用 G1-G17 + §5.2 接口命名）后，新增 ISSUE-032 ~ ISSUE-036 + ISSUE-059 共 6 个问题（Dashboard Query Resolver P2 执行方式 / 越权防御 P2 实现 / /readyz P2 探针范围 / GetTeacherDashboard 命名回写 / P2 工作量分级 / BFF_TEACHER 错误码语义区分）；新增 §3.5 ai03 复审批次记录（含仲裁可行性/影响评判 + 回写义务承诺）                                                                                                                                             | ai03   |
| 2026-07-09 | v1.6：ai16 复审 coord 仲裁（前端 4 portal F1-F12 + 通用 G14/G16 + X2/X3/X6 待 P6+ 事项）后，新增 ISSUE-044 ~ ISSUE-048 共 5 个问题（admin-portal BFF 归属不明 / 错误码前缀 ADMIN_ 缺失 / 权限点命名前缀规则 / GraphQL client 复用方式 / 审计日志归属耦合）；新增 §3.6 ai16 复审批次记录（含仲裁可行性/影响评判 + 回写义务承诺）；复审确认 issues.md 文件结构严重混乱（line 567 标题嵌入 / §2 出现 3 次 / §3.4 出现 3 次 / ISSUE-023~041 多处冲突），建议 coord P0 优先重构                                     | ai16   |
| 2026-07-09 | v1.7：ai14 复审 coord 仲裁（student-portal 部分 F1-F12 + BFF 专项 B1-B8 + 批次 2 P3 规划）后，新增 ISSUE-063 ~ ISSUE-066 共 4 个问题（02 文档 REST vs GraphQL 回写义务 / F7 权限点命名风格不一致 / P3 功能范围受限 7 页 / 通知功能推迟 P5）；新增 §2.8 ai14 待仲裁问题区 + §3.8 ai14 复审批次记录（含 6 维度仲裁可行性/影响评判 + 5 项裁决逐条评估 + 回写义务承诺）；复审确认 issues.md 文件结构严重混乱（ISSUE-035 ai15 已提请，ai14 再次确认编号冲突 ISSUE-044~047 三方冲突 + ISSUE-059 ai03/ai14 双方冲突） | ai14   |

---

## 2.6 ai15 补充的待仲裁问题（ISSUE-031 ~ ISSUE-035）

> 以下问题由 ai15（parent-portal）在审核 coord-final-decisions.md + ai-work-orchestration.md + coord-cross-review.md + issues.md 后提请。

### ISSUE-031: coord-final-decisions.md + ai-work-orchestration.md 相对路径错误（ai-allocation.md 链接失效）

- **提请 AI**：ai15（parent-portal）
- **类别**：文档同步遗漏
- **阶段**：全阶段
- **问题描述**：
  - `docs/architecture/coord-final-decisions.md` L7 关联文档引用：`[ai-allocation.md](./architecture/ai-allocation.md)`
  - `docs/architecture/ai-work-orchestration.md` L7 关联文档引用：`[ai-allocation.md](./architecture/ai-allocation.md)`
  - **实际验证**：`ai-allocation.md` 位于 `docs/architecture/ai-allocation.md`（[Glob 确认](file:///e:/Desktop/Edu/docs/architecture/ai-allocation.md)）
  - 两份文档自身位于 `docs/architecture/` 目录下，引用 `./architecture/ai-allocation.md` 会解析为 `docs/architecture/architecture/ai-allocation.md`（多一层 `architecture/`，路径不存在）
  - 正确路径应为 `./ai-allocation.md`
- **影响**：开发 AI 点击链接跳转 404，无法快速定位 AI 分配表；coord 交叉审查时可能遗漏 ai-allocation.md 的分工信息
- **建议方案**：修正两份文档 L7 的相对路径：
  - `coord-final-decisions.md` L7：`[ai-allocation.md](./architecture/ai-allocation.md)` → `[ai-allocation.md](./ai-allocation.md)`
  - `ai-work-orchestration.md` L7：`[ai-allocation.md](./architecture/ai-allocation.md)` → `[ai-allocation.md](./ai-allocation.md)`
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-032: ai15 parent-portal API 契约 REST 假设与 F9 GraphQL 裁决冲突（文档回写义务）

- **提请 AI**：ai15（parent-portal）
- **类别**：裁决冲突（文档回写义务）
- **阶段**：P4
- **问题描述**：
  - `coord-final-decisions.md` F9 裁决"P2 起 BFF 用 GraphQL，前端用 urql/apollo"
  - `coord-final-decisions.md` B1 裁决"P2 起直接 GraphQL（GraphQL Yoga + DataLoader）"
  - ai15 的 `apps/parent-portal/docs/02-architecture-design.md` §4 API 设计基于 REST 假设：
    - §436 消费 parent-bff `GET /parent/viewports`、`GET /parent/children`、`POST /parent/switch-child`、`GET /parent/notifications`、`PUT /parent/notification-preferences`（REST 端点）
    - §455 假设"ai05 parent-bff 提供 REST 端点"
    - §505 后端契约表标注 parent-bff REST 端点
    - §244/§246/§283 API 请求层用 REST fetch 封装（`api.get`/`api.put`），未引入 GraphQL client（urql/apollo）
  - §476 ai15 自己已识别"GraphQL vs REST"问题，但建议"P4 用 REST，后续若 BFF 切 GraphQL 再引入 urql"——**这违反"不分阶段"原则**
- **影响**：parent-portal P4 启动时，若 parent-bff（ai05）按 GraphQL 裁决实现，则 parent-portal 的 API 请求层、TanStack Query 集成、错误处理均需重构。ai15 需在 P4 启动前回写 02-architecture-design.md §4
- **建议方案**：ai15 在 P4 启动前回写 02-architecture-design.md：
  1. §4 引入 urql/apollo client（复用 Shell 暴露的 GraphQL Provider，与 teacher-portal ai13 对齐）
  2. §436/§455/§505 REST 端点路径改为 GraphQL operation name
  3. TanStack Query 与 GraphQL 集成（query key 命名不变，fetcher 改为 GraphQL query/mutation）
  4. 错误处理对齐 GraphQL error 格式（ActionState 信封 + GraphQL errors 数组映射）
  5. 与 ai05 协调 parent-bff GraphQL schema 第一版（coord 仲裁，参照 teacher-bff schema 模式）
  6. §476 删除"P4 用 REST 后续切 GraphQL"过渡方案描述
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-033: ai15 parent-portal 通知偏好 P4 落地与 B7 裁决冲突（msg P5 才启用）

- **提请 AI**：ai15（parent-portal）
- **类别**：裁决冲突（功能推迟）
- **阶段**：P4
- **问题描述**：
  - `coord-final-decisions.md` B7 裁决"P2-P4 BFF 不订阅 Kafka，P5 push-gateway 落地后再订阅"
  - `coord-final-decisions.md` M1 裁决：msg 服务 P5 启用
  - ai15 的 `02-architecture-design.md` 设计了通知偏好功能（P4 落地）：
    - §14 通知偏好数据模型细化（三维矩阵：事件类型 × 渠道 × 接收时机）
    - §15 详细组件设计（通知偏好设置页面）
    - §16 跨标签同步实现
    - §244 `api.put("/api/v1/parent/notification-preferences", prefs)` PUT 接口
    - §283 mutation 后 invalidate
    - §314 `/parent/preferences` 路由权限点 `NOTIFICATION_READ_OWN`
  - **冲突**：通知偏好功能需要 msg 服务存储偏好 + 消费 Kafka 事件触发通知，但 msg P5 才启用，B7 裁决 P2-P4 BFF 不订阅 Kafka → P4 阶段通知偏好功能无法完整落地
  - 与 ISSUE-013（coord 提请的通用问题）相关，但 ai15 从 parent-portal 具体设计角度补充：通知偏好设置页面的 UI 可以 P4 落地，但后端持久化 + 事件触发必须推迟到 P5
- **影响**：parent-portal P4 阶段通知偏好功能只能实现前端 UI（表单 + 校验），无法持久化到后端（msg P5 才启用）；家长设置偏好后无实际效果（无事件触发通知）
- **建议方案**：明确 parent-portal 通知偏好功能阶段归属：
  - **P4 阶段**：通知偏好设置页面 UI + 表单校验（react-hook-form + zodResolver），偏好暂存前端 localStorage（降级方案），不调后端 API
  - **P5 阶段**：parent-bff 接入 msg 服务 GraphQL mutation `updateNotificationPreferences`，偏好持久化到 msg DB，Kafka 事件触发通知推送
  - ai15 在 02-architecture-design.md §14/§15/§33 实施路线图中标注通知偏好功能 P5 归属
  - 与 ISSUE-013 合并处理：parent-bff / student-bff 通知相关功能统一推迟到 P5
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-034: ai15 parent-portal §476 "P4 用 REST 后续切 GraphQL"违反"不分阶段"原则

- **提请 AI**：ai15（parent-portal）
- **类别**：裁决冲突（"不分阶段"原则违反）
- **阶段**：P4
- **问题描述**：
  - `coord-final-decisions.md` §0.1 裁决原则："不分阶段"——最终方案在服务首次落地时即采用，不得以"阶段未到"为由先实现简化版
  - `coord-final-decisions.md` F9 裁决：P2 起 BFF 用 GraphQL，前端用 urql/apollo
  - ai15 的 `02-architecture-design.md` §476 明确写道："**建议：P4 用 REST，后续若 BFF 切 GraphQL 再引入 urql**"
  - 这是典型的"前期简化 → 后期重构"过渡方案，直接违反 §0.1 "不分阶段"原则
  - ai15 在审计补全时已识别此问题（见 ISSUE-032），但未自行修正，需 coord 仲裁确认是否必须 P4 即 GraphQL
- **影响**：若 ai15 P4 按 REST 实现，P5+ 切 GraphQL 时需重构 API 请求层 + TanStack Query 集成 + 错误处理，违反"首次实现即最终方案"
- **建议方案**：
  1. ai15 P4 启动前回写 §476，删除"P4 用 REST 后续切 GraphQL"过渡方案描述
  2. P4 即引入 urql/apollo client（对齐 F9 裁决），与 ai05 parent-bff GraphQL schema 同步开发
  3. coord 仲裁 parent-bff GraphQL schema 第一版（参照 teacher-bff schema 模式，见 ISSUE-019）
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-035: issues.md 文件结构严重混乱（多个 §2/§3 标题 + ISSUE 编号多处冲突）

- **提请 AI**：ai15（parent-portal）
- **类别**：工作归属不明（文档规范）
- **阶段**：全阶段
- **问题描述**：
  - issues.md 当前文件结构严重混乱，经 ai15 完整审查发现以下问题：
    1. **3 个 `## 2. 已解决问题` 标题**：L399/L657/L829（重复的章节标题）
    2. **2 个 `## 3.` 标题**：L757 `## 3. ai09 补充的待仲裁问题` + L837 `## 3. coord 仲裁记录`（章节编号冲突）
    3. **ISSUE-023 编号冲突**：ai09（content）和 ai11（data-ana）都用了 ISSUE-023~025
    4. **ISSUE-026~030 编号冲突**：ai11 在 §1 待仲裁区提了 ISSUE-023~~027（L397-484），又在 §2.5 区提了 ISSUE-026~~030（L663-753），内容重复
    5. **L567 格式错误**：`## 2. 已解决问题ISSUE-023: ClickHouse DDL...`（章节标题与 issue 标题合并在一行）
    6. **ai09 的 ISSUE-023~025 被放在"已解决问题"区**（L567-655），但状态是"待 coord 仲裁"，区域归属错误
    7. **ai11 的问题被分到两处**：§1 区有 ISSUE-023~~027（L397-484），§2.5 区有 ISSUE-026~~030（L663-753），同一 AI 的问题分散在两个区域
  - 当前实际 ISSUE 编号使用情况（经 ai15 完整核查）：
    - ISSUE-001~014：coord（14 个，§1 区）
    - ISSUE-015~022：ai08（8 个，§1 区）
    - ISSUE-023~027：ai11 第一组（5 个，§1 区 L397-484）
    - ISSUE-023~025：ai09（3 个，§3 区 L757-825，但内容也在 §2 区 L567-655 重复）
    - ISSUE-026~028：ai03（3 个，§1 区 L487-563）
    - ISSUE-026~030：ai11 第二组（5 个，§2.5 区 L663-753）
    - ISSUE-031~035：ai15（5 个，本区域）
- **影响**：
  - 各 AI 引用 ISSUE 编号时无法确定指哪个（如"见 ISSUE-023"可能是 ai09 content /readyz 问题，也可能是 ai11 ClickHouse DDL 问题）
  - coord 仲裁时可能遗漏某些问题（分散在多个区域）
  - 文件结构混乱降低可信度，新 AI 查阅时困惑
- **建议方案**：coord 统一整理 issues.md：
  1. **合并重复区域**：将 §2.5 / §3 / §2（重复的）合并到 §1 待仲裁问题区
  2. **重新编号**（建议）：
     - ISSUE-001~014：coord（保留）
     - ISSUE-015~022：ai08（保留）
     - ISSUE-023~025：ai09（保留，从"已解决问题"区移到 §1）
     - ISSUE-026~~030：ai11（统一为一组，删除 §1 区的重复 ISSUE-023~~027）
     - ISSUE-031~~033：ai03（从原 ISSUE-026~~028 重编号）
     - ISSUE-034~~038：ai15（从原 ISSUE-031~~035 重编号）
  3. **修正格式错误**：L567 章节标题与 issue 标题分离
  4. **删除重复的 `## 2.` / `## 3.` 标题**，只保留一个
  5. 在 §0.4 编号规则中补充："各 AI 提请问题前必须先读取 issues.md 最大编号，从最大编号+1 开始；新增问题统一追加到 §1 待仲裁问题区末尾"
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

---

## 3.3 ai15 复审批次（2026-07-09）

**复审范围**：coord-final-decisions.md（parent-portal 相关 F1-F12 + parent-bff B1-B8）+ ai-work-orchestration.md（批次 3 P4）+ coord-cross-review.md + issues.md v1.2 + ai15 自身 `apps/parent-portal/docs/02-architecture-design.md`（§4/§14/§15/§16/§33/§476）

**复审结论**：

| 维度           | 评估                                                                                                                                                                                                                                                                     |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **仲裁可行性** | 高。F1-F12 前端裁决 + B1-B8 BFF 裁决技术方案清晰，对齐黄金模板。parent-portal P4 启动依赖清晰（iam.GetChildrenByParent 批次 1 就绪 + core-edu gRPC 批次 2 就绪 + ai05 parent-bff GraphQL schema coord 仲裁）。ai15 的 02 文档 v2 已补全 7 章长远架构，与裁决大部分对齐。 |
| **仲裁影响**   | 中。直接影响 ai15 的裁决 12 项（F1-F12），全部已对齐无阻塞。间接影响：parent-portal P4 需引入 GraphQL client（F9 裁决，ISSUE-032/034）；通知偏好功能需拆分 P4 UI + P5 后端（B7 裁决，ISSUE-033）。ai15 需在 P4 启动前回写 02 文档（删除 REST 假设 + 过渡方案描述）。     |
| **文档同步**   | 中。coord-final-decisions.md + ai-work-orchestration.md 相对路径错误（ISSUE-031）；issues.md 文件结构严重混乱（ISSUE-035）；ai15 自身 02 文档 §476 过渡方案需删除（ISSUE-034）。                                                                                         |
| **契约明确性** | 中。parent-bff GraphQL schema 第一版仲裁机制未明确（ISSUE-019，ai08 已提请）；parent-portal 通知偏好 P4 落地范围需明确（ISSUE-033）。                                                                                                                                    |
| **批次规划**   | 高。批次 3 P4 规划合理，前置依赖清晰：批次 1 完成（iam.GetChildrenByParent 就绪）+ 批次 2 完成（core-edu gRPC 50053 可用）+ ai05 parent-bff 与 ai15 parent-portal 双向依赖通过 coord 仲裁 schema 第一版解决。                                                            |
| **遗留风险**   | 低-中。ISSUE-032/033/034 需 ai15 P4 启动前回写 02 文档；ISSUE-035 issues.md 结构混乱需 coord 统一整理。均不阻塞 P4 启动（可在批次 0 等待期间完成回写）。                                                                                                                 |

**新增 5 个问题**（ISSUE-031 ~ ISSUE-035）已登记到 §2.6 区，待 coord 仲裁。

**建议 coord 优先处理**：

1. **P0**：ISSUE-035（issues.md 结构混乱）—— 影响全部 AI 查询效率，建议 coord 立即整理
2. **P1**：ISSUE-032（parent-portal REST vs GraphQL）+ ISSUE-034（"不分阶段"原则违反）—— ai15 P4 启动前必须回写 02 文档
3. **P1**：ISSUE-031（相对路径错误）—— 简单修正，立即执行
4. **P2**：ISSUE-033（通知偏好 P4 落地范围）—— 与 ISSUE-013 合并处理，明确 parent-portal 通知功能阶段归属

---

## 2.8 ai14 补充的待仲裁问题（ISSUE-063 ~ ISSUE-066）

> 以下问题由 ai14（student-portal）在审核 coord-final-decisions.md + ai-work-orchestration.md + coord-cross-review.md + issues.md 后提请。
> 编号从 ISSUE-063 开始（避开 ai03 ISSUE-059 + ai16 ISSUE-044~~048 + ai06 ISSUE-047~~052 + ai02 ISSUE-053~058 等已用编号）。

### ISSUE-063: ai14 student-portal 02-architecture-design.md REST 假设与 F9/B1 GraphQL 裁决冲突（文档回写义务）

- **提请 AI**：ai14（student-portal）
- **类别**：裁决冲突（文档回写义务）
- **阶段**：P3
- **问题描述**：
  - `coord-final-decisions.md` F9 裁决："P2 起 BFF 用 GraphQL，前端用 urql/apollo"
  - `coord-final-decisions.md` B1 裁决："P2 起直接 GraphQL（GraphQL Yoga + DataLoader）"
  - ai14 的 `apps/student-portal/docs/02-architecture-design.md` §4 API 设计基于 REST 假设：
    - §4 API 请求层用 REST fetch 封装（`api.get`/`api.post`），未引入 GraphQL client（urql/apollo）
    - §6 路由表中后端端点标注为 REST 路径（如 `GET /student/dashboard`、`POST /student/exams/:id/submit`）
    - TanStack Query 集成基于 REST fetcher，未与 GraphQL operation 集成
    - 错误处理基于 HTTP 状态码 + ActionState REST 信封，未对齐 GraphQL errors 数组格式
  - 与 ai15 ISSUE-032（parent-portal REST vs GraphQL）同类问题，但 ai14 从 student-portal 视角提请
  - 与 ai04 ISSUE-028（student-bff 02 文档 B1/B2 冲突回写）关联：ai04 回写 BFF 侧后，ai14 须同步回写 portal 侧
- **影响**：
  - ai14 违反 coord-final-decisions §0.1 回写义务，coord 验收时不通过
  - 若不回写，ai14 P3 启动时按 REST 实现 API 请求层 → 后期必废弃重写（与用户"直接使用最好的方式"指示矛盾）
  - student-portal 须与 ai04 student-bff GraphQL schema 双向协调（见 ISSUE-030 ai04 已提请）
- **建议方案**：
  1. ai14 在 P3 启动前回写 02-architecture-design.md：
     - §4 引入 urql/apollo client（复用 ai13 teacher-portal MF Shell 暴露的 GraphQL Provider）
     - §6 路由表中 REST 端点路径改为 GraphQL operation name（Query/Mutation）
     - TanStack Query 与 GraphQL 集成（query key 命名不变，fetcher 改为 GraphQL query/mutation）
     - 错误处理对齐 GraphQL error 格式（ActionState 信封 + GraphQL errors 数组映射）
     - 与 ai04 协调 student-bff GraphQL schema 第一版（coord 仲裁，见 ISSUE-030）
  2. 回写期限：P3 启动前（与 ai04 回写同步进行，批次 1 等待期间完成）
  3. 回写完成后在 known-issues.md 工作经验日志追加记录
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-064: F7 权限点命名风格 ai14 文档与裁决不一致

- **提请 AI**：ai14（student-portal）
- **类别**：裁决冲突（命名规范）
- **阶段**：P3
- **问题描述**：
  - `coord-final-decisions.md` F7 裁决："统一 `<RESOURCE>_<ACTION>`（如 DASHBOARD_VIEW、EXAM_READ、GRADE_READ），数据范围用后缀 `_OWN/_CHILD`（如 GRADE_READ_CHILD）"
  - ai14 的 `02-architecture-design.md` §6 权限点命名使用 `STUDENT_` 前缀风格：
    - `STUDENT_DASHBOARD_READ` → 应为 `DASHBOARD_VIEW_OWN`
    - `STUDENT_EXAM_READ` → 应为 `EXAM_READ_OWN`
    - `STUDENT_EXAM_TAKE` → 应为 `EXAM_SUBMIT_OWN`（动作 SUBMIT 替代 TAKE）
    - `STUDENT_HOMEWORK_READ` → 应为 `HOMEWORK_READ_OWN`
    - `STUDENT_HOMEWORK_SUBMIT` → 应为 `HOMEWORK_SUBMIT_OWN`
    - `STUDENT_GRADE_READ` → 应为 `GRADE_READ_OWN`
    - `STUDENT_SCHEDULE_READ` → 应为 `SCHEDULE_READ_OWN`
  - F7 裁决移除角色前缀（`STUDENT_`），用 `_OWN` 后缀表示数据范围（学生只能看自己的数据）
  - ai14 known-issues.md §2.15 已记录此问题但未回写 02 文档
- **影响**：
  - ai14 02 文档权限点命名与 F7 裁决不一致，coord 验收时不通过
  - 若 iam PermissionGuard DB 中权限点按 ai14 文档命名注册，前端 `usePermission().hasPermission()` 调用时 key 不匹配
  - i18n key 命名（F4 裁决 `error.<service>.<code_snake>`）需同步调整
- **建议方案**：
  1. ai14 P3 启动前回写 02-architecture-design.md §6 权限点命名：
     - 移除 `STUDENT_` 前缀，改用 `<RESOURCE>_<ACTION>_OWN` 风格
     - 与 ai06 iam 协调权限点注册（DB 驱动 PermissionGuard，I3 裁决）
     - 与 ai13 MF Shell 协调 `usePermission()` hook 的权限点 key 对齐
  2. 回写期限：P3 启动前
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-065: student-portal P3 功能范围受限（下游 content/data-ana P4 才启用）

- **提请 AI**：ai14（student-portal）
- **类别**：跨度过大（功能范围受限）
- **阶段**：P3
- **问题描述**：
  - `coord-final-decisions.md` §5.3 gRPC 启用时机：content P4 启用 50054，data-ana P4 启用 50055
  - `ai-work-orchestration.md` §5.2：ai14 student-portal P3 依赖 ai04 student-bff，ai04 P3 只能 gRPC 调 iam + core-edu（跨阶段扩展例外，ISSUE-006 已裁决）
  - ai14 的 `02-architecture-design.md` 设计了以下页面，但部分依赖 content/data-ana gRPC（P4 才启用）：
    - **P3 可实现**（依赖 iam + core-edu）：
      - dashboard（学生仪表盘，调 core-edu GetClassesByTeacher + iam GetEffectivePermissions）
      - homework（作业列表 + 提交，调 core-edu HomeworkService）
      - exams（考试列表，调 core-edu ExamService）
      - take（考试作答，调 core-edu ExamService.GetExam + SubmitExam）
      - result（考试结果，调 core-edu ExamService.GetResult）
      - grades（成绩查询，调 core-edu GradeService）
      - my-schedule（课表，调 core-edu ScheduleService）
    - **P3 无法实现**（依赖 content/data-ana，P4 才启用）：
      - textbooks（教材浏览，调 content TextbookService.ListTextbooks）
      - questions（题库练习，调 content QuestionService）
      - diagnostic（学情诊断，调 data-ana GetStudentDashboard）
      - weakness（薄弱知识点，调 data-ana GetStudentWeakness）
    - **P3 无法实现**（依赖 ai/msg，P5 才启用）：
      - notifications（通知中心，调 msg NotificationService）
      - ai-chat（AI 辅助，调 ai StreamChat）
  - 与 ai04 ISSUE-029（P3 前置依赖确认）关联，但 ai14 从前端页面视角补充：哪些页面 P3 可交付、哪些须推迟
- **影响**：
  - student-portal P3 交付范围需明确缩减：仅 dashboard/homework/exams/take/result/grades/my-schedule 7 个页面
  - textbooks/questions/diagnostic/weakness 页面推迟到 P4
  - notifications/ai-chat 页面推迟到 P5
  - 路由表中 P4/P5 页面需标注"Coming Soon"占位，避免用户访问 404
- **建议方案**：
  1. 明确 student-portal P3 功能范围：
     - P3：dashboard / homework / exams / take / result / grades / my-schedule（7 页）
     - P4：textbooks / questions / diagnostic / weakness（4 页，依赖 content + data-ana gRPC）
     - P5：notifications / ai-chat（2 页，依赖 msg + ai gRPC）
  2. ai14 P3 路由表中 P4/P5 页面设 `<FeatureFlag>` 占位（显示"功能开发中"提示页）
  3. coord 验收 ai14 P3 时检查：P3 范围 7 页全部可用 + P4/P5 页面有占位
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-066: student-portal 通知功能推迟到 P5（关联 ISSUE-013/033）

- **提请 AI**：ai14（student-portal）
- **类别**：跨度过大（功能推迟）
- **阶段**：P3-P5
- **问题描述**：
  - `coord-final-decisions.md` B7 裁决："P2-P4 BFF 不订阅 Kafka，P5 push-gateway 落地后再订阅"
  - `coord-final-decisions.md` M1 裁决：msg 服务 P5 启用
  - ISSUE-013（coord 提请）：BFF P2-P4 不订阅 Kafka，家长通知实时性如何保证 — **状态：待 coord 仲裁（未解决）**
  - ISSUE-033（ai15 提请）：parent-portal 通知偏好 P4 落地与 B7 裁决冲突 — 同类问题
  - ai14 从 student-portal 视角补充：
    - student-portal 设计了通知中心页面（notifications route），显示作业发布/考试提醒/成绩公布/系统公告
    - P3-P4 阶段 student-bff 不订阅 Kafka，msg P5 才启用 → 学生通知无法实时推送
    - 学生端通知场景：作业截止提醒（core-edu HomeworkService 发布事件）、考试成绩公布（core-edu ExamService 发布事件）、系统公告（msg 通知）
    - P3-P4 阶段这些事件发到 Kafka 但 student-bff 不消费，学生端无通知入口
  - 与 ISSUE-013/033 的差异：
    - ISSUE-013 从 parent-bff 视角（家长通知）
    - ISSUE-033 从 parent-portal 视角（家长通知偏好设置）
    - 本 issue 从 student-portal 视角（学生通知中心页面）
- **影响**：
  - student-portal P3-P4 阶段通知中心页面无法实现（无数据源）
  - 学生无法收到作业/考试/成绩提醒，体验受损
  - P5 启用后需补开发通知中心 + WebSocket/SSE 推送
- **建议方案**：
  1. student-portal 通知功能推迟到 P5（msg + push-gateway 就绪后）：
     - P3-P4：notifications route 设 `<FeatureFlag>` 占位（显示"通知功能即将上线"）
     - P5：实现通知中心页面 + WebSocket/SSE 接入 push-gateway
  2. 与 ISSUE-013/033 合并处理：coord 统一裁决 BFF 通知功能阶段归属（P5 统一启用）
  3. P3-P4 阶段学生端可提供"手动刷新"降级方案（轮询 core-edu 查询最近作业/考试），但不作为正式通知功能
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

---

## 3.8 ai14 复审批次（2026-07-09）

**复审范围**：coord-cross-review.md + coord-final-decisions.md（前端专项 F1-F12 + BFF 专项 B1-B8 + 通用 G1-G17）+ ai-work-orchestration.md（批次 2 P3）+ issues.md v1.3 + ai14 自身 `apps/student-portal/docs/02-architecture-design.md`（§4/§6/§8/§9）+ ISSUE-006/008/013（已识别的 ai14 相关问题）

**复审结论**：

| 维度           | 评估                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| -------------- |   |
| **仲裁可行性** | 高。F1-F12 前端裁决 + B1-B8 BFF 裁决技术方案清晰，对齐黄金模板（teacher-portal ai13）。GraphQL Yoga + DataLoader + urql/apollo 均为成熟方案，ai13 teacher-portal P2 已先行，ai14 P3 可复用 ai13 的 GraphQL client 模式和 MF 共享组件。MF Module Federation（F10 暴露 AppShell 整体）方案成熟，ai14 P3 接入 MF remote 无技术风险。                                                                                                                                                                                                                                         |
| **仲裁影响**   | 中-高。直接影响 ai14 的裁决 12 项（F1-F12）：F1 端口 4001 已对齐；F2 MF 配置 teacher_app@localhost:4000 已对齐；F3 INP 指标已对齐；F4 i18n key 命名需回写（对齐 error.\<service>.\<code_snake>）；F5 错误码子前缀已对齐（CORE_EDU_*）；F6 iam 权限端点已对齐；**F7 权限点命名需回写**（STUDENT_DASHBOARD_READ → DASHBOARD_VIEW_OWN，见 ISSUE-064）；**F9 GraphQL vs REST 需回写**（见 ISSUE-063）；F10 MF 暴露粒度已对齐；F11 teacher-portal 归属不影响 ai14；F12 localStorage token 已对齐。间接影响：P3 功能范围缩减（见 ISSUE-065）、通知功能推迟 P5（见 ISSUE-066）。 |
| **文档同步**   | **差**。ai14 02-architecture-design.md 存在 2 项重大冲突未回写（F9 GraphQL / F7 权限点命名，见 ISSUE-063/064），违反 coord-final-decisions §0.1 回写义务。issues.md 文件结构严重混乱（ISSUE-035 ai15 已提请，ai14 确认此问题：3 个 `## 2.` 标题 + 2 个 `## 3.` 标题 + ISSUE-023~043 编号多处冲突）。coord-final-decisions.md + ai-work-orchestration.md 相对路径错误（ISSUE-031 ai15 已提请）。                                                                                                                                                                           |
| **契约明确性** | 中。ai04⟷ai14 student-bff GraphQL schema 第一版仲裁时机未明确（ISSUE-030 ai04 已提请）；ai13 MF 共享组件交付清单 + GraphQL Provider 暴露方式需与 ai13 协调；ai14 02 文档 §6 权限点命名需与 ai06 iam PermissionGuard DB 注册同步（F7 + I3 裁决）。                                                                                                                                                                                                                                                                                                                         |
| **批次规划**   | 高。批次 2 P3 规划合理：ai04⟷ai14 双向依赖 + ai08 core-edu 交接 + ai03 跨阶段扩展。跨阶段扩展例外原则（批次规划原则 5）已解决 ISSUE-006（student-bff P3 调 content/data-ana 断裂），ai14 接受此裁决。ai14 P3 功能范围明确缩减为 7 页（见 ISSUE-065），与 ai04 student-bff P3 gRPC 调用范围一致（仅 iam + core-edu）。                                                                                                                                                                                                                                                     |
| **遗留风险**   | 中。B7 裁决 P2-P4 BFF 不订阅 Kafka → student-bff P3-P4 学生通知无法实时推送（见 ISSUE-066，与 ISSUE-013/033 同类）；F9 GraphQL 回写工作量增加约 30%（引入 urql/apollo client + schema 协调 + TanStack Query 集成重构）；P3 功能范围缩减（7/13 页）需与用户预期管理。                                                                                                                                                                                                                                                                                                      |

**新增 4 个问题**（ISSUE-063 ~ ISSUE-066）已登记到 §2.8 区，待 coord 仲裁。

**ai14 对 coord 仲裁的整体评判**：

1. **F9 GraphQL 裁决可行性：中-高**
   - 优点：urql/apollo 是成熟 GraphQL client，ai13 teacher-portal P2 已先行，ai14 P3 可复用 ai13 的 client 模式和 MF Shell 暴露的 GraphQL Provider
   - 风险：ai04⟷ai14 双向依赖需 coord 仲裁 schema 第一版（ISSUE-030 ai04 已提请），若仲裁不及时将阻塞并行开发
   - 工作量影响：相比原 REST 设计，需引入 urql/apollo + GraphQL operation 定义 + TanStack Query fetcher 重构，工作量增加约 30%
   - 阻塞依赖：ai13 P2 MF Shell + GraphQL Provider + ai04 student-bff GraphQL schema（coord 仲裁）

2. **F7 权限点命名裁决可行性：高**
   - 优点：`<RESOURCE>_<ACTION>_OWN` 风格语义清晰，与 iam DB 驱动 PermissionGuard（I3）配合良好
   - 风险：ai14 02 文档 + known-issues.md §2.15 需同步回写权限点命名（7 个权限点重命名）
   - 工作量影响：命名替换为主，工作量小

3. **B7 Kafka 订阅推迟裁决可行性：中（体验受损但可接受）**
   - 优点：P2-P4 BFF 不订阅 Kafka 简化了 BFF 实现，避免了 Kafka consumer 复杂度
   - 风险：student-portal P3-P4 学生通知功能无法实现（见 ISSUE-066），用户体验受损
   - 缓解：P3-P4 通知页面占位 + P5 统一启用（msg + push-gateway 就绪后）
   - 工作量影响：P5 需补开发通知中心 + WebSocket/SSE 接入

4. **批次 2 P3 规划可行性：高**
   - 优点：ai04⟷ai14 双向依赖 + ai08 core-edu 交接 + ai03 跨阶段扩展，依赖关系清晰
   - 前置条件明确：批次 0.8（core_edu.proto 补全）+ 0.9（buf.gen.yaml gRPC 插件）+ 批次 1 完成（iam gRPC + ai03 DownstreamClient + ai13 MF Shell）
   - ai14 P3 功能范围明确缩减为 7 页（dashboard/homework/exams/take/result/grades/my-schedule），P4 扩展 4 页（textbooks/questions/diagnostic/weakness），P5 扩展 2 页（notifications/ai-chat）

5. **ISSUE-006 / ISSUE-008 / ISSUE-013 对 ai14 的影响**
   - ISSUE-006（student-bff P3 调 content/data-ana 断裂）：已被批次规划原则 5 解决（跨阶段扩展例外），ai14 接受此裁决，P3 仅实现 iam+core-edu 相关页面
   - ISSUE-008（teacher-portal P2 改造 urql/apollo）：ai13 P2 先行改造，ai14 P3 复用 ai13 产出的 GraphQL client 模式和 MF 共享组件，无额外阻塞
   - ISSUE-013（BFF P2-P4 不订阅 Kafka 通知实时性）：ai14 从 student-portal 视角补充 ISSUE-066，建议 P5 统一启用通知功能

**建议 coord 优先处理**：

1. **P0**：ISSUE-035（issues.md 结构混乱，ai15 已提请）—— ai14 确认此问题严重影响全部 AI 查询效率，建议 coord 立即整理
2. **P1**：ISSUE-063（student-portal REST vs GraphQL 回写）+ ISSUE-064（权限点命名回写）—— ai14 P3 启动前必须回写 02 文档
3. **P1**：ISSUE-030（ai04⟷ai14 GraphQL schema 仲裁时机，ai04 已提请）—— 阻塞 ai14 P3 并行开发
4. **P2**：ISSUE-065（P3 功能范围缩减）—— 明确 P3 交付范围，管理用户预期
5. **P2**：ISSUE-066（通知功能推迟 P5）—— 与 ISSUE-013/033 合并处理，统一裁决 BFF 通知功能阶段归属

**ai14 回写义务承诺**：

按 coord-final-decisions §7.1 要求，ai14 将在 P3 启动前（批次 0/1 等待期间）回写 02-architecture-design.md：

- 删除 F9 冲突（REST → GraphQL，见 ISSUE-063）
- 删除 F7 冲突（STUDENT_DASHBOARD_READ → DASHBOARD_VIEW_OWN，见 ISSUE-064）
- 更新 §8 风险与假设（移除已裁决项）
- 更新 §9 演进路线（删除 REST→GraphQL 演进描述）
- 回写后自行验证 + known-issues.md 工作经验日志追加记录

---

## 2.8 ai06 补充的待仲裁问题（ISSUE-047 ~ ISSUE-052）

> ai06（iam）在评判 coord 三件套仲裁结果对 iam 模块影响时识别的 6 项问题。
> 注：ai06 知悉 ISSUE-035（ai15 提请，issues.md 结构混乱）已识别编号冲突问题。由于 ai13/ai14 已使用 ISSUE-036~041，本组问题使用 ISSUE-047+ 编号避免进一步冲突（最高已用编号 ISSUE-046）。

### ISSUE-047: 批次 0 强阻塞 ai06 iam P2 启动（前置依赖未就绪）

- **提请 AI**：ai06（iam）
- **类别**：前置依赖未就绪
- **阶段**：P2
- **问题描述**：
  - `ai-work-orchestration.md` §3.1 批次 0 规划 7 项任务，其中 2 项直接阻塞 ai06 P2 启动：
    - 0.3 补全 `iam.proto` 8 个 RPC（GetViewports / GetEffectivePermissions / GetEffectiveAccess / Logout / GetPublicKey / BatchGetUsers / GetEffectiveDataScope / GetChildrenByParent）—— 状态 ⏳ 待办
    - 0.4 建立 `shared-ts` Outbox 工具包（I2 裁决要求 iam 首次实现即用）—— 状态 ⏳ 待办
  - `ai-work-orchestration.md` §4.1 前置条件明确："批次 0 中 0.1-0.7 全部就位"才能启动批次 1
  - 但批次 0 的 0.3 和 0.4 完成日期未明确，ai06 无法规划 P2 启动时间
  - 连锁影响：ai03 teacher-bff 依赖 ai06 gRPC（§4.2），ai13 teacher-portal 依赖 ai03 schema，全链路阻塞
- **影响**：
  - ai06 iam P2 启动被强阻塞，无法开始任何 gRPC / Outbox 相关工作
  - 连锁阻塞 ai03 teacher-bff（依赖 iam gRPC 50052）+ ai13 teacher-portal（依赖 teacher-bff schema）
  - 批次 1 整体（4 个 AI 并行）可能因 iam 未就绪而延迟
- **建议方案**：
  1. coord 明确批次 0 的 0.3 + 0.4 完成日期（建议在批次 0 启动时同步公布）
  2. 建立"批次 0 完成信号"机制（coord 在 ai-work-orchestration.md 标注 ✅ 已完成，或单独发启动信号）
  3. 备选方案：若 0.4 shared-ts Outbox 延迟，ai06 可临时用本地 Outbox 实现（仅在 iam 内部），但需在 shared-ts 就绪后迁移（违反"不分阶段"原则，需 coord 豁免）
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-048: I7 API 版本化 /iam/v1/* 破坏性变更跨服务协调

- **提请 AI**：ai06（iam）
- **类别**：契约不明确
- **阶段**：P2
- **问题描述**：
  - `coord-final-decisions.md` I7 裁决：iam 采用 `/iam/v1/*` 前缀，Gateway 同步调整
  - 但以下 4 个契约点未明确：
    1. **全服务统一 vs 仅 iam**：是全部服务都加 `/v1/*` 前缀，还是仅 iam？若仅 iam，其他服务何时加？
    2. **前缀位置**：`/v1` 加在 Controller 内（NestJS `@Controller('v1/iam')`）还是 Gateway 路由层（Gateway rewrite 后转发 `/iam/v1/*` → iam 服务 `/v1/*`）？
    3. **双 v1 问题**：若 Controller 加 `/v1` + Gateway 转发路径也含 `/v1`，会变成 `/iam/v1/v1/*`（路径重复）
    4. **现有端点兼容**：P1 已跑通的 `/iam/login` `/iam/refresh` 等端点是否保留旧路径（向后兼容）？还是直接迁移到 `/iam/v1/login`（破坏性变更）？
  - 跨服务协调成本高：ai01 gateway（路由配置）+ ai03 teacher-bff（gRPC 调用不受影响但 REST 调用需同步）+ ai04 student-bff + ai05 parent-bff + ai13~ai15 前端（API 请求路径）全部需同步
- **影响**：
  - 若 coord 未仲裁统一规则，各 AI 自行理解可能导致路径不一致
  - P1 已跑通的 gateway → iam 链路可能因路径迁移而断裂
  - 前端 4 个 portal 的 API 请求路径需全部更新
- **建议方案**：
  1. coord 仲裁统一规则：建议在 Controller 内加 `v1` 前缀（`@Controller('v1/iam/auth')`），Gateway 透传 `/iam/v1/*` → iam 服务 `/v1/iam/*`
  2. 全服务统一加 `/v1` 前缀（不只是 iam），但各服务按自身节奏推进（iam P2 / core-edu P3 / content P4）
  3. 现有端点立即迁移，不保留旧路径（遵循"不分阶段"原则，P1 链路由 ai01 + ai06 同步修复）
  4. gateway 路由配置同步更新（ai01 P2 工作项）
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-049: gRPC 与 REST 双入口实现策略未明确

- **提请 AI**：ai06（iam）
- **类别**：契约不明确
- **阶段**：P2
- **问题描述**：
  - `coord-final-decisions.md` I1 裁决：iam P2 即启用 gRPC server 50052，**"同时暴露 REST + gRPC"**
  - `coord-final-decisions.md` B2 裁决：teacher-bff 首次实现即 gRPC 调下游
  - 两者结合后存在 4 个实现策略问题：
    1. **REST 端点是否保留**：I1 说"同时暴露"，意味着 P2 后 iam 同时有 REST（`/iam/v1/*`）+ gRPC（50052）。但 teacher-bff 用 gRPC 调 iam，谁用 REST？gateway 是否还用 HTTP 透传到 iam REST？
    2. **P1 链路是否失效**：P1 已跑通 gateway → iam REST（`/iam/login`）链路。若 iam 改为 gRPC 优先，gateway 是否需改为 gRPC 客户端？还是保持 HTTP 透传到 iam REST？
    3. **前端如何调用**：teacher-portal / student-portal / parent-portal 不直连 iam（通过 BFF），但 admin-portal P6 可能直连 iam REST。REST 端点是否仅保留给 admin-portal + gateway？
    4. **gateway 角色定位**：gateway 是 HTTP 反向代理（透传到 iam REST），还是 gRPC 客户端（gRPC 调 iam 再转 HTTP 给前端）？
  - 现有 iam 02 文档 §1.2 设计为 REST 优先，gRPC 是 P3 补充，与 I1 裁决冲突需回写（见 ISSUE-051）
- **影响**：
  - iam 工作量翻倍（需同时实现 REST Controller + gRPC Controller，同一业务逻辑两个入口）
  - gateway 路由策略不明（HTTP 透传 vs gRPC 客户端），影响 ai01 P2 工作量
  - 若 REST 保留，iam 需维护两套 API 契约（REST DTO + gRPC proto message）
- **建议方案**：
  1. **双入口策略**：REST 供 gateway 透传 + 前端直连（admin-portal），gRPC 供 BFF 聚合调用
  2. **NestJS 复用**：同一 Application Service 同时被 REST Controller + gRPC Controller 调用，业务逻辑不重复
  3. **gateway 保持 HTTP 透传**：gateway 不改为 gRPC 客户端（降低 P2 工作量），gateway → iam REST 路径不变
  4. **BFF gRPC 调 iam**：teacher-bff / student-bff / parent-bff 用 gRPC 调 iam（B2 裁决）
  5. coord 在批次 0 结束前明确此策略，写入 coord-final-decisions.md I1 补充条款
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-050: shared-ts Outbox 工具包 API 契约未明确（iam 视角补充 ISSUE-018）

- **提请 AI**：ai06（iam）
- **类别**：契约不明确
- **阶段**：P2
- **问题描述**：
  - 关联 ISSUE-018（ai08 提请，shared-ts Outbox 工具包设计未明确）
  - ai06 补充 iam 视角的 6 项契约未明确：
    1. **包名与导入路径**：`@edu/shared-ts/outbox`？`@edu/shared-ts`？import 方式？
    2. **导出 API**：`OutboxService.publish(eventType, payload, options)` 签名？返回值？
    3. **集成方式**：NestJS Module 注入（`@Module({ imports: [OutboxModule.forRoot(...)] })`）还是工具函数？
    4. **是否含 Kafka producer**：shared-ts Outbox 是否内置 Kafka producer？还是各服务自建 producer，Outbox 仅负责表 + Relay Worker？
    5. **是否支持多 ORM**：iam 用 Drizzle ORM，core-edu 也用 Drizzle，但若其他服务用 TypeORM，shared-ts Outbox 是否兼容？
    6. **配置项**：Outbox 表名 / Kafka topic 命名 / Relay 轮询间隔 / 重试策略 / 最大重试次数，哪些是 shared-ts 默认、哪些是各服务可配？
- **影响**：
  - iam P2 启动时若 API 契约未明确，ai06 无法接入 shared-ts Outbox
  - 各服务接入方式可能不一致（NestJS Module vs 工具函数），后续维护成本高
  - 与 ISSUE-018 重复提请，但 iam 作为首个接入方（I2 裁决），需求更迫切
- **建议方案**：
  1. coord 在批次 0.4 完成时同步公布 shared-ts Outbox API 契约文档（README + 接口签名 + 使用示例）
  2. 建议 API 设计：
     - 包名：`@edu/shared-ts/outbox`
     - 导出：`OutboxModule.forRoot(config) → NestJS Module` + `OutboxService.publish(eventType, payload, options) → Promise<string>`（返回 outbox record id）
     - 内置 Kafka producer（iam 仅配置 topic）
     - 仅支持 Drizzle ORM（对齐黄金模板，TypeORM 服务自行实现 Outbox）
     - 配置项：表名 / topic / 轮询间隔 / 重试策略可配，默认值合理
  3. 若 ISSUE-018 已被 coord 仲裁，本 issue 可合并处理
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-051: 02-architecture-design.md 与 I1-I8 裁决对齐回写义务

- **提请 AI**：ai06（iam）
- **类别**：跨度过大（文档同步）
- **阶段**：P2
- **问题描述**：
  - `coord-final-decisions.md` §7.1 回写义务："各 AI 收到本文档后，必须在 3 个工作日内回写自己的 02-architecture-design.md"
  - ai06 的 `services/iam/docs/02-architecture-design.md` 需修订 4 处对齐裁决：
    1. **§1.2 AuthMiddleware 标注**：当前为"P2 仍不注册，Controller 直读 header"，I4 裁决为"首次实现即注册 AuthMiddleware"——需改写
    2. **§1.3 目录结构**：当前无 `grpc/` 子模块，I1 裁决为"P2 即启用 gRPC server 50052"——需新增 `grpc/iam.grpc.controller.ts` + `grpc/rbac.grpc.controller.ts`
    3. **§9.8 API 版本化**：当前为"P6+ 评估"，I7 裁决为"采用 /iam/v1/* 前缀"——需改写为"P2 落地"
    4. **§5 JWT 实现**：当前为"P2 待启用 RS256"，I5 裁决为"P2 本地文件"——需改写为"P2 首次实现即 RS256"
    5. **§9.13 HS256→RS256 迁移策略**：需标注"已前移到 P2"（I5 裁决）
  - 回写工作量约 0.5-1 工作日（小范围修订）
- **影响**：
  - 不阻塞 P2 启动（回写可在批次 0 等待期间完成）
  - 但若不回写，ai03 / ai01 等协作 AI 查阅 iam 02 文档会获得错误信息
- **建议方案**：
  1. ai06 立即执行回写（小范围修订 4 处 + §9 标注前移）
  2. 回写完成后在 `docs/troubleshooting/known-issues.md` 工作经验日志记录
  3. 不阻塞 P2 启动（回写可在批次 0 等待期间完成）
- **状态**：待 coord 仲裁（ai06 可自行执行，但报备 coord 知晓）
- **coord 裁决**：（待填写）

### ISSUE-052: iam P2 工作量评估与批次时间线不匹配

- **提请 AI**：ai06（iam）
- **类别**：跨度过大
- **阶段**：P2
- **问题描述**：
  - `ai-work-orchestration.md` §9 批次时间线：批次 1（P2）预计 5-7 工作日
  - ai06 评估 iam P2 实际工作量约 26-27 工作日（单人），明细如下：
    1. gRPC server 50052 + 8 RPC 实现（GetViewports / GetEffectivePermissions / GetEffectiveAccess / Logout / GetPublicKey / BatchGetUsers / GetEffectiveDataScope / GetChildrenByParent）：4-5 天
    2. DB 驱动 PermissionGuard + Redis 缓存（I3 裁决，废弃硬编码 ROLE_PERMISSIONS map）：2-3 天
    3. AuthMiddleware 注册 + Controller 改用 @Req() 注入（I4 裁决）：1 天
    4. JWT RS256 本地文件 + refresh token 轮换（I5 裁决）：2 天
    5. iam_student_guardians 表 + GetChildrenByParent RPC + GET /iam/children REST（I6 裁决）：2 天
    6. shared-ts Outbox 接入（I2 裁决）：1-2 天
    7. /iam/v1/* 前缀迁移（I7 裁决）+ 端点路径统一（I8 裁决）：1-2 天
    8. 三层角色模型（school_admin / teacher / student + 自定义角色）：2-3 天
    9. DataScope 6 级实现（ALL / SCHOOL / GRADE / CLASS / SUBJECT / SELF）：2-3 天
    10. 视口 4 层（admin / teacher / student / parent）+ getEffectivePermissions：2-3 天
    11. 审计日志（user_audit_log 表 + 记录关键操作）：1-2 天
    12. 密码策略（强度 / 过期 / 重用限制）：1-2 天
    13. 单元测试 + 集成测试：3-4 天
  - 与批次 1 预估 5-7 天差距 4-5 倍
- **影响**：
  - ai06 无法在 5-7 天内完成 iam P2 全部工作
  - 批次 2（P3）启动被阻塞（core-edu 依赖 iam gRPC 就绪，但 core-edu 不依赖 iam 全部功能完成）
  - 连锁影响 ai03 teacher-bff（依赖 iam gRPC）+ ai13 teacher-portal（依赖 teacher-bff schema）
  - 但 ai03 / ai13 仅需 iam gRPC 50052 可用即可启动，不依赖 iam 全部 8 RPC 完成
- **建议方案**（3 选 1，请 coord 仲裁）：
  - **方案 A（拆分 P2）**：将 iam P2 拆分为 P2.1（核心：gRPC + 8 RPC + AuthMiddleware + JWT RS256 + iam_student_guardians + shared-ts Outbox 接入，约 5-7 天）+ P2.2（扩展：三层角色 + DataScope + 视口 + 审计 + 密码策略 + 测试，约 20 天），P2.1 完成后批次 2 可启动
  - **方案 B（调整时间线）**：批次 1 时间线调整为 20-25 天（对齐 iam 实际工作量）
  - **方案 C（MVP 范围）**：coord 仲裁 iam P2 MVP 范围（如仅 gRPC + 8 RPC + AuthMiddleware + JWT RS256 + iam_student_guardians，其余 P3 补），违反"不分阶段"原则需豁免
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

---

## 3.5 ai06 复审批次（2026-07-09）

**复审范围**：coord-final-decisions.md（iam 部分 I1-I8）+ ai-work-orchestration.md（批次 1 P2）+ coord-cross-review.md + issues.md v1.3 + ai06 自身 `services/iam/docs/02-architecture-design.md`（§1.2/§1.3/§5/§9.8/§9.13）

**复审结论**：

| 维度           | 评估                                                                                                                                                                                                                                                                                                                                                                         |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **仲裁可行性** | 中-高。I1-I8 八项裁决技术方案清晰，对齐黄金模板（classes）。I2（shared-ts Outbox）/ I3（DB 驱动 PermissionGuard）/ I4（AuthMiddleware 注册）/ I5（JWT RS256 本地文件）/ I6（iam_student_guardians + GetChildrenByParent）/ I8（端点路径统一）六项可行性高，无阻塞。I1（gRPC + REST 双入口）+ I7（/iam/v1/* 版本化）两项可行性中，需 coord 补充明确策略（见 ISSUE-048/049）。 |
| **仲裁影响**   | 高。直接影响 ai06 的裁决 8 项（I1-I8），P2 工作量翻倍（gRPC + REST 双入口 + DB 驱动 + AuthMiddleware + RS256 + refresh 轮换 + 三层角色 + DataScope + 视口 4 层 + 审计 + 密码策略 + 测试，全部首次实现即最终）。间接影响：ai03 teacher-bff 依赖 iam gRPC 50052 就绪；ai05 parent-bff P4 依赖 iam.GetChildrenByParent（已通过 I6 裁决 P2 即补全解阻塞）。                      |
| **文档同步**   | 中。ai06 自身 02 文档需回写 4 处对齐裁决（ISSUE-051）；port-allocation.md §3 与 §5 关于 iam gRPC 启用阶段冲突（ISSUE-001/015，coord 已裁决待修正）；coord-final-decisions.md + ai-work-orchestration.md 相对路径错误（ISSUE-031，ai15 已提请）。                                                                                                                             |
| **契约明确性** | 中。shared-ts Outbox 工具包 API 契约未明确（ISSUE-050，关联 ISSUE-018）；/iam/v1/* 版本化跨服务协调规则未明确（ISSUE-048）；gRPC + REST 双入口策略未明确（ISSUE-049）。3 项契约不明确需 coord 在批次 0 结束前仲裁。                                                                                                                                                          |
| **批次规划**   | 中。批次 1 P2 规划合理（ai01/ai06/ai03⟷ai13 并行），但前置依赖（批次 0.3 iam.proto 8 RPC + 0.4 shared-ts Outbox 工具包）状态 ⏳ 待办，直接阻塞 ai06 启动（ISSUE-047）。批次时间线 5-7 天与 iam 实际工作量 26-27 天严重不匹配（ISSUE-052，4-5 倍差距）。                                                                                                                      |
| **遗留风险**   | 中。ISSUE-047（批次 0 阻塞）+ ISSUE-052（工作量超批）两项高优先级问题若未解决，批次 1 可能延迟 2-3 周。ISSUE-048/049/050 三项契约不明确需 coord 仲裁后 ai06 才能确定实现策略。ISSUE-051 回写义务可立即执行，不阻塞。                                                                                                                                                         |

**新增 6 个问题**（ISSUE-047 ~ ISSUE-052）已登记到 §2.8 区，待 coord 仲裁。

**建议 coord 优先处理**：

1. **P0**：ISSUE-047（批次 0 强阻塞）—— 明确批次 0.3 + 0.4 完成日期，建立启动信号机制
2. **P0**：ISSUE-052（工作量超批）—— 仲裁方案 A/B/C 之一，影响批次 1 时间线
3. **P1**：ISSUE-048（/iam/v1/* 版本化）+ ISSUE-049（gRPC + REST 双入口）—— 契约不明确，需批次 0 结束前仲裁
4. **P1**：ISSUE-050（shared-ts Outbox API 契约）—— 关联 ISSUE-018，iam 首次接入方需求迫切
5. **P2**：ISSUE-051（02 文档回写）—— ai06 可自行执行，不阻塞 P2 启动

---

### 3.6 ai10 复审批次（2026-07-09）

**复审范围**：coord-final-decisions.md（msg 专项 M1-M5 + 通用 G1-G17 + 契约 §5.1）+ ai-work-orchestration.md（批次 4 P5 + 批次 0.13 msg.proto 补全）+ issues.md（ISSUE-012/013 相关）+ 我的 `services/msg/docs/{01-understanding,02-architecture}.md` + `services/core-edu/src/shared/outbox/outbox.publisher.ts`（验证 M5 topic 命名）+ `004_architecture_impact_map.md` §7.2 / §16.3.2（验证 G16 topic 命名）

**复审结论**：

| 维度           | 评估                                                                                                                                                                                                                                                                                                                                                                                                                     |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **仲裁可行性** | 高。M1-M5 五项 msg 专项裁决技术方案清晰，对齐黄金模板（classes）+ 黄金先例（core-edu Outbox）。我的 02 文档已设计完整 6 层架构（Entry/Guard/App/Strategy/Domain/Data）+ 5 聚合 + 6 表 + 16 REST + 8 gRPC + 7 消费 topic + 3 发布事件 + 4 channel strategy，M1-M5 裁决全部可落地。M4 HTTP /internal/push 豁免 gRPC 符合 project_memory "Lessons Learned" 第 9 条经验。G9/G10/G11/G16/G17 通用裁决与 02 文档设计完全一致。 |
| **仲裁影响**   | 中。直接影响 ai10 的裁决 5 项（M1-M5）+ 通用 5 项（G9/G10/G11/G16/G17），全部已对齐无阻塞。间接影响：P5 工作量较大（gRPC server 50056 + Outbox + 三层幂等 + Redis bitmap + ES 双向回退 + DLQ + 4 channel strategy + 模板渲染 + 静默时段 + 优雅关闭）；M2 PushGateway 强依赖存在 P5 同批次时序风险（ISSUE-042）。                                                                                                         |
| **文档同步**   | **差**。004 §7.2 表格 `edu.notification.events` 与 §16.3.2 + G16 裁决不同步（ISSUE-043）；issues.md 文件结构严重混乱（ISSUE-035，ai15 已提请）；ISSUE-012 已被 coord 裁决但早期 14 个问题状态未全部回填（ISSUE-017，ai08 已提请）。                                                                                                                                                                                      |
| **契约明确性** | 中。HTTP /internal/push 接口契约待 coord 在批次 4 启动前仲裁（ISSUE-012 已裁决时序方案，但 path/body/schema/status code 详细契约未公布）；msg.proto 补全（批次 0.13）依赖 coord；M2 PushGateway 纳入 /readyz 的失败处理策略未明确（ISSUE-042）。                                                                                                                                                                         |
| **批次规划**   | 高。批次 4 P5 规划合理：ai10⟷ai02 双向依赖通过 coord 仲裁第一版契约 + ai02 优先 1-2 天启动解决；ai12 ai 服务独立无阻塞；ai03 teacher-bff P5 扩展依赖 ai10 + ai12。前置依赖清晰：批次 0.13 msg.proto 补全（coord 负责）+ 批次 3 完成（content.QuestionService 已就绪）。                                                                                                                                                  |
| **遗留风险**   | 低-中。ISSUE-042（PushGateway /readyz 强依赖）需 coord 仲裁失败处理策略；ISSUE-043（004 §7.2 表格同步）需 coord 修订文档；ISSUE-013（BFF P2-P4 不订阅 Kafka 通知实时性）影响 parent-bff P4 / student-bff P3-P4 通知功能，msg P5 启用后部分缓解但 BFF 仍不订阅 Kafka。                                                                                                                                                    |

**新增 2 个问题**（ISSUE-042 ~ ISSUE-043）已登记到 §1 待仲裁问题区末尾，待 coord 仲裁。

**ai10 对 coord 仲裁的整体评判**：

1. **M1 gRPC server 50056 裁决可行性：高**
   - 优点：NestJS gRPC 模式成熟，iam P2 / core-edu P3 / content P4 已先行，ai10 P5 可复用模式
   - 风险：批次 0.13 msg.proto 补全是强阻塞前置（5 RPC + NotificationPreferenceService + NotificationTemplateService + 3 message），若 coord 延期 ai10 必然延期
   - 工作量影响：gRPC server 实现 + 8 RPC 方法 + proto 生成代码，工作量约占 P5 总量 20%
   - 阻塞依赖：批次 0.13 msg.proto + 批次 0.9 buf.gen.yaml gRPC 插件 + shared-ts 目录建立

2. **M2 /readyz 检查 DB/ES/Redis/Kafka/PushGateway 裁决可行性：中**
   - 优点：符合 G2 "首次实现即检查全部下游依赖"精神，对齐黄金模板
   - 风险：PushGateway 与 msg 同属 P5 批次，Pod 启动时序冲突可能导致 msg /readyz 持续失败（ISSUE-042）
   - 工作量影响：5 项健康检查实现 + 软失败策略设计（若 ISSUE-042 仲裁采纳方案 A）
   - 阻塞依赖：PushGateway Pod Ready（运行时依赖，非接口契约依赖）

3. **M3 ZodError 处理裁决可行性：高**
   - 优点：GlobalErrorFilter 已在 classes 黄金模板实现，msg 直接复用
   - 风险：无
   - 工作量影响：极小（复用 classes 模式 + 适配 msg 错误码 MSG_*）
   - 阻塞依赖：无

4. **M4 HTTP POST /internal/push 豁免 gRPC 裁决可行性：高**
   - 优点：符合 project_memory "Lessons Learned" 第 9 条经验（gRPC 对 push-gateway 低 QPS 内部基础设施通信不必要）；HTTP + Kafka 双通道已足够
   - 风险：接口契约待 coord 仲裁第一版（ISSUE-012 已裁决时序，详细契约待公布）
   - 工作量影响：ChannelStrategy.PushStrategy 通过 HTTP client 调用，工作量小
   - 阻塞依赖：ai02 push-gateway 优先 1-2 天启动 + coord 公布接口契约

5. _*M5 edu.teaching.homework.* topic 命名裁决可行性：高（依赖 core-edu 代码修订）_*
   - 优点：与 004 §7.2 新约定 + G16 裁决一致，action-specific 命名清晰
   - 风险：core-edu 实际 TOPIC_MAP 仍用 `edu.homework.events`（旧表名分组命名），若 core-edu P3 实施时不修订，msg P5 消费方收不到事件（此问题已由 ai07 在历史版本中提请，ai08 复审已记录）
   - 工作量影响：msg 消费方按 `edu.teaching.homework.*` 实现，无额外工作量
   - 阻塞依赖：core-edu P3 实施时修订 TOPIC_MAP（coord 批次 2 验收时检查）

6. **G9/G10/G11/G16/G17 通用裁决可行性：高**
   - 全部与 02 文档设计一致，无冲突
   - G9 优雅关闭：02 文档 §6.4 已设计 7 步关闭流程
   - G10 getDb()：02 文档 §3 已设计复用 classes 模式
   - G11 cuid2：02 文档 §3 已设计
   - G16 topic 命名：02 文档 §5 已设计 `edu.notification.sent/read/recalled`（但 004 §7.2 表格未同步，见 ISSUE-043）
   - G17 proto 包名：02 文档 §4 已设计 `next_edu_cloud.msg.v1`

**建议 coord 优先处理**：

1. **P1**：ISSUE-042（M2 PushGateway /readyz 强依赖失败处理策略）—— 影响 msg P5 /readyz 实现策略，建议补充 M2 软失败条款
2. **P1**：ISSUE-043（004 §7.2 表格 `edu.notification.events` 同步修订）—— 影响 msg + push-gateway 双方 topic 契约一致性，建议立即修订
3. **P2**：ISSUE-012（HTTP /internal/push 接口契约详细公布）—— 时序已裁决，详细契约待 coord 在批次 4 启动前公布
4. **P2**：ISSUE-035（issues.md 结构混乱）—— ai15 已提请，影响全部 AI 查询效率

**ai10 回写义务承诺**：

按 coord-final-decisions §7.1 要求，ai10 将在 P5 启动前完成回写：

- 02-architecture.md §0-§14 已对齐 M1-M5 + G9/G10/G11/G16/G17 裁决（无需大改）
- 待 ISSUE-042 仲裁后，更新 §6.3 /readyz 实现策略（软失败方案 A）
- 待 ISSUE-043 修订后，验证 §5 发布事件 topic 与 004 §7.2 表格一致
- 待 ISSUE-012 详细契约公布后，更新 §8 ChannelStrategy.PushStrategy 实现
- 回写后自行验证 + known-issues.md 工作经验日志追加记录

**ai10 工作顺序规划**（基于仲裁结果）：

| 阶段     | 任务                                                                          | 依赖                      | 预估工作量   |
| -------- | ----------------------------------------------------------------------------- | ------------------------- | ------------ |
| 0 等待期 | 监控批次 0.13 msg.proto 补全 + coord 公布 HTTP /internal/push 契约            | coord 批次 0              | 被动等待     |
| 0 等待期 | 复审 02-architecture.md 与裁决对齐（已基本完成，待 ISSUE-036/037 仲裁后微调） | 无                        | 0.5 天       |
| 0 等待期 | 在 known-issues.md 工作经验日志追加 ai10 复审记录                             | 无                        | 0.1 天       |
| P5 启动  | proto 生成代码 + gRPC server 50056 框架搭建                                   | 批次 0.13 + 0.9 完成      | 1 天         |
| P5 启动  | DB schema 建立（6 表扩展/新增）+ ES mapping + Redis bitmap schema             | 无                        | 1 天         |
| P5 启动  | 6 层架构骨架（Entry/Guard/App/Strategy/Domain/Data）+ getDb() + cuid2         | G10/G11 裁决              | 1 天         |
| P5 中期  | 8 gRPC RPC 实现 + 16 REST 端点实现                                            | proto 生成代码            | 3-4 天       |
| P5 中期  | 7 Kafka 消费方实现 + 3 发布事件 Outbox                                        | G16 裁决 + ISSUE-037 修订 | 2 天         |
| P5 中期  | 4 ChannelStrategy 实现（InApp/Email/SMS/Push）+ 模板渲染                      | ISSUE-012 契约公布        | 2 天         |
| P5 中期  | 三层幂等（Redis SETNX + msg_idempotency + source_event_id）+ DLQ              | 无                        | 1 天         |
| P5 后期  | /readyz + /healthz + /metrics + 优雅关闭 + OTel                               | M2 裁决 + ISSUE-036 仲裁  | 1 天         |
| P5 后期  | 集成测试 + 端到端验证（含 push-gateway 联调）                                 | ai02 /internal/push 就绪  | 2 天         |
| **总计** |                                                                               |                           | **14-15 天** |

注：ai-work-orchestration.md §9 批次 4 预估 7-10 天，ai10 实际工作量评估 14-15 天，差距约 50%。建议 coord 仲裁是否拆分 P5 为 P5.1（核心：gRPC + REST + Outbox + 基础 channel）+ P5.2（扩展：模板 + 静默 + DLQ + 完整幂等），或调整批次时间线。此问题未单独提请 ISSUE（与 ai06 ISSUE-020 iam P2 工作量评估同类），建议 coord 统一仲裁各 AI 工作量与批次时间线匹配性。

---

## 2.7 ai13 补充的待仲裁问题（ISSUE-036 ~ ISSUE-041）

> 以下问题由 ai13（teacher-portal）在审核 coord-final-decisions.md（F1-F12 前端专项 + G14/G15 错误码）+ ai-work-orchestration.md（批次 1 P2）+ issues.md v1.3 后提请。
> 编号从 ISSUE-036 开始（避开 ai15 已用的 ISSUE-031~~035 + ai10 已用的 ISSUE-034/035 + ai04 已用的 ISSUE-028~~031 + ai11 已用的 ISSUE-026~030）。

### ISSUE-036: ai13 03-long-term-architecture.md §6 "REST→GraphQL 演进策略"与 F9 裁决冲突

- **提请 AI**：ai13（teacher-portal）
- **类别**：裁决冲突 + 文档同步遗漏
- **阶段**：P2
- **问题描述**：
  - `coord-final-decisions.md` F9 裁决："P2 起 BFF 用 GraphQL，前端用 urql/apollo"，禁止"P2-P6 REST，未来切 GraphQL"
  - ai13 `services/teacher-portal/docs/03-long-term-architecture.md` §6 仍保留"REST→GraphQL 演进策略"章节，描述 P2-P4 用 REST，P5+ 评估迁移 GraphQL
  - 这是明确的"中间过渡方案"描述，与 F9 裁决直接冲突
  - ai13 已在回写 02-architecture-design.md 时删除过渡方案，但 03-long-term-architecture.md §6 未同步更新
  - **修正**：提请时引用的章节号有误，实际 REST→GraphQL 内容在 §1.4（§6 是 i18n 实施），已按实际章节回写
- **影响**：ai13 P2 启动前必须回写 03 文档，删除 §6 演进策略，对齐 F9 裁决；否则文档与实现不一致，coord 验收会失败
- **建议方案**：
  1. 删除 03-long-term-architecture.md §6 "REST→GraphQL 演进策略"整节
  2. 替换为"GraphQL 客户端架构（P2 起最终方案）"章节，描述 urql/apollo client 集成、缓存策略、错误处理
  3. 同步更新 §8 风险与假设，移除"REST→GraphQL 迁移风险"
- **状态**：已回写闭合（2026-07-09，批次 0.15 后）
- **coord 裁决**：总裁裁决 §3.4 + §4.4 第 5 条（删除过渡方案本身，保留设计决策记录）
- **回写执行**：ai13 已于批次 0.15 后完成回写，详见 03-long-term-architecture.md §14.1 回写记录
  - 删除 §1.4 "REST → GraphQL 切换策略"整节（实际章节，非提请时误引用的 §6）
  - 替换为"GraphQL 客户端架构（P2 起最终方案）"（client 选型/单例/初始化/错误处理/缓存策略/ISSUE 关联/设计决策记录）
  - 修订 §1.1 P2 行 + §1.2 表格 + §12.3 #3 待裁决问题
  - 新增 §14 回写记录章节

### ISSUE-037: ai13 与 ai03 的 GraphQL schema 契约协调机制未明确（前端消费侧）

- **提请 AI**：ai13（teacher-portal）
- **类别**：契约不明确
- **阶段**：P2
- **问题描述**：
  - F9 裁决：P2 起 BFF 用 GraphQL（teacher-bff ai03 实现 GraphQL Yoga server），前端用 urql/apollo（teacher-portal ai13 实现 GraphQL client）
  - B1 裁决：GraphQL Yoga + DataLoader
  - ai13 与 ai03 的 GraphQL schema 契约如何协调未明确：
    - schema 定义权归属（ai03 定义 server schema，ai13 消费？还是 coord 仲裁第一版？）
    - schema 版本管理（GraphQL schema 演进如何同步前后端？）
    - 查询/变更/订阅的命名规范（camelCase vs snake_case？分页规范？）
    - 错误响应格式（GraphQL errors 数组 vs ActionState 信封？）
  - ISSUE-019（ai08 提请）已涉及"GraphQL schema 仲裁机制未明确"，但聚焦 core-edu 调用方；ISSUE-030（ai04 提请）聚焦 student-bff 前端消费侧；本问题聚焦 teacher-portal 前端消费侧，与 ISSUE-030 同类但不同 BFF
- **影响**：ai13 P2 启动时无法确定 GraphQL client 的查询文档（query/mutation/subscription）写法，阻塞前端开发
- **建议方案**：
  1. coord 在批次 1 启动前仲裁 teacher-bff GraphQL schema 第一版（含 Teacher/Class/Student/Subject 等核心类型 + 查询入口）
  2. 建立"schema-first"工作流：ai03 定义 schema → coord 仲裁 → ai13 消费 → 变更需 PR + 双方 review
  3. 明确 GraphQL 规范：camelCase 命名、Relay Cursor Connections 分页规范、errors 数组扩展 ActionState 字段（extensions.code = BFF_TEACHER_*）
  4. 建立 schema 注册表（packages/shared-ts/contracts/graphql/），前后端共享类型定义
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-038: MF 暴露 AppShell 整体（F10）是否包含 GraphQL client 单例未明确

- **提请 AI**：ai13（teacher-portal）
- **类别**：契约不明确
- **阶段**：P2
- **问题描述**：
  - F10 裁决："暴露 AppShell 整体，各 Remote 自行决定内部布局"
  - ai13 `services/teacher-portal/docs/02-architecture-design.md` §4 Module Federation 设计：Shell 暴露 AppShell（含 Layout + 路由骨架 + 全局 Provider）
  - 问题：AppShell 整体暴露是否包含 GraphQL client 单例（urql Client / apollo Client）？
    - 方案 A（包含）：Shell 初始化 GraphQL client，通过 React Context 注入给所有 Remote，Remote 共享同一 client 实例 + 缓存
    - 方案 B（不包含）：各 Remote 自行初始化 GraphQL client，但需统一 endpoint 配置，缓存隔离
  - 若方案 A：Shell 需暴露 GraphQLProvider，Remote 消费 Context；但 MF 跨 React 实例时 Context 共享有坑（shared singleton 要求）
  - 若方案 B：缓存隔离导致跨 Remote 数据不一致（如 Teacher 信息在 Shell 和 Remote 各存一份）
- **影响**：P2 MF Shell 实现时 Provider 设计不明确，影响所有 Remote 的数据获取方式
- **建议方案**：建议方案 A（Shell 暴露 GraphQL client 单例），理由：
  - 统一缓存避免数据不一致
  - 统一鉴权 header 注入（Authorization: Bearer token）
  - 统一错误处理（401 跳转登录、5xx 降级）
  - MF shared 配置需将 react/urql/apollo 设为 singleton，避免多实例
  - 实现方式：Shell 的 AppShell 包含 `<GraphQLProvider client={sharedClient}>`，Remote 通过 `useQuery` 等 hook 消费
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-039: F8 ai13 维护 packages 的建立时机与依赖未明确

- **提请 AI**：ai13（teacher-portal）
- **类别**：前置依赖未就绪 + 工作归属不明
- **阶段**：P2
- **问题描述**：
  - F8 裁决："ai13 维护 ui-tokens/ui-components/hooks，coord 仅维护 shared-ts/contracts"
  - ai13 `services/teacher-portal/docs/02-architecture-design.md` §3 设计 packages 结构：
    - `packages/ui-tokens`：设计令牌（primitive/semantic/tailwind theme）
    - `packages/ui-components`：shadcn/ui 组件 + 业务组件
    - `packages/hooks`：通用 hooks（useAuth/usePermission/useA11yId 等）
  - 问题：
    - 这 3 个 packages 何时建立？P2 启动前？P2 启动时？
    - ai13 P2 首次实现是否依赖这 3 个 packages 已就位？（teacher-portal 代码 import @edu/ui-components 等）
    - packages 的依赖关系：ui-components 依赖 ui-tokens，hooks 依赖 ui-components？还是平级？
    - 4 个 portal（teacher/student/parent/admin）是否都消费这 3 个 packages？版本管理策略？
  - ai-work-orchestration.md §3.1 批次 0（coord 前置）未列出这 3 个 packages 的建立任务
- **影响**：ai13 P2 启动时若 packages 未就位，teacher-portal 无法 import 共享组件/令牌/hooks，阻塞开发
- **建议方案**：
  1. ai13 在 P2 启动前（批次 0 末或批次 1 初）建立 3 个 packages 骨架（package.json + 基础导出）
  2. 依赖关系：ui-tokens（无依赖）→ ui-components（依赖 ui-tokens）→ hooks（依赖 ui-components）
  3. 4 个 portal 统一消费，版本通过 pnpm workspace 协议（"workspace:*"）
  4. ai13 完成 packages 建立后通知 ai14/ai15/ai16（其他 portal AI）消费
  5. coord 在批次 1 验收 ai13 时检查 packages 已建立
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-040: ai13 teacher-portal P2 功能范围与下游服务启用阶段的关系未明确

- **提请 AI**：ai13（teacher-portal）
- **类别**：跨度过大
- **阶段**：P2
- **问题描述**：
  - ai-work-orchestration.md §4.3 明确 ai13 P2 范围：client 改造 + MF shell + 共享组件抽取
  - 但 teacher-portal 作为教师端入口，P2 阶段需对接 teacher-bff（ai03 P2 启动）的哪些 GraphQL 查询未明确：
    - P2 仅实现登录 + Dashboard 框架？
    - 还是包含班级列表 + 学生列表等基础教学功能？
  - teacher-bff P2 只调 iam（gRPC），core-edu P3 / content P4 / data-ana P4 才启用
  - 若 teacher-portal P2 实现班级/学生/作业等页面，但 teacher-bff P2 无法 gRPC 调 core-edu（P3 才启用），数据来源断裂
  - ISSUE-004/005 已裁决"BFF 跨阶段扩展下游"是允许的例外，但前端是否也跟随"BFF 有什么就展示什么"？
- **影响**：ai13 P2 功能边界不明确，可能导致过度实现（写了 BFF 无法返回数据的页面）或不足（只做登录页，未利用 iam 已有能力）
- **建议方案**：
  1. 明确 ai13 P2 功能范围：登录 + 权限上下文 + Dashboard 框架 + 个人设置 + 班级列表（iam 数据）+ 学生列表（iam 数据）
  2. P3 起 teacher-portal 跟随 teacher-bff 扩展 core-edu 相关页面（课表/考勤/考试/作业）
  3. P4 起扩展 content/data-ana 相关页面（教材/题库/分析仪表盘）
  4. P5 起扩展 ai/msg 相关页面（AI 助教/消息通知）
  5. 前端路由骨架 P2 一次性建立，但页面内容随 BFF 能力分阶段填充
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-041: 仲裁评估总结 - 关键裁决对 ai13 的可行性与影响评估

- **提请 AI**：ai13（teacher-portal）
- **类别**：跨度过大（评估总结）
- **阶段**：P2-P6
- **问题描述**：
  - ai13 完整阅读 coord-final-decisions.md（80+ 项裁决）+ ai-work-orchestration.md（批次 0-5 规划）+ issues.md（35 个已识别问题）
  - 对 ai13 的关键裁决影响评估如下：

  | 裁决编号 | 裁决内容                                         | 对 ai13 影响                                       | 可行性                                 | 风险                                   |
  | -------- | ------------------------------------------------ | -------------------------------------------------- | -------------------------------------- | -------------------------------------- |
  | F9       | P2 起 GraphQL（urql/apollo）                     | 高：teacher-portal 需从 REST 改造为 GraphQL client | 中：schema 契约协调成本高（ISSUE-037） | schema 未及时仲裁阻塞 P2               |
  | F12      | P2 localStorage token                            | 低：与原设计一致                                   | 高                                     | 无                                     |
  | F8       | ai13 维护 3 个 packages                          | 中：新增 packages 建立任务                         | 高：ai13 已设计完毕                    | 时机不明确（ISSUE-039）                |
  | F10      | MF 暴露 AppShell 整体                            | 中：Shell 设计需包含 Provider                      | 高                                     | GraphQL client 单例不明确（ISSUE-038） |
  | F7       | 权限点命名 `<RESOURCE>_<ACTION>`                 | 低：命名规范调整                                   | 高                                     | 无                                     |
  | F4       | i18n key `error.<service>.<code_snake>`          | 低：命名规范调整                                   | 高                                     | 无                                     |
  | F11      | teacher-portal 归属 ai13                         | 无：已对齐                                         | 高                                     | 无                                     |
  | G14      | 错误码前缀 BFF_TEACHER_                          | 低：前端消费 BFF 错误码                            | 高                                     | 无                                     |
  | G15      | 错误码子前缀删除，统一 CORE_EDU_*                | 低：前端消费 core-edu 错误码                       | 高                                     | 无                                     |
  | F1/F2    | admin-portal 端口 4003，MF 配置 teacher_app@4000 | 低：teacher-portal 端口 4000 已对齐                | 高                                     | 无                                     |
  | F3       | 统一 INP（CWV 2024）                             | 低：性能指标调整                                   | 高                                     | 无                                     |
  - 总体评估：
    - **可行性**：高。11 项关键裁决中 9 项可行性高，2 项中等（F9 GraphQL 改造 + schema 协调）
    - **影响**：中。主要工作集中在 P2 阶段（GraphQL 改造 + MF Shell + packages 建立）
    - **阻塞风险**：ISSUE-037（schema 仲裁机制）+ ISSUE-039（packages 时机）是 P2 启动的关键阻塞点
    - **跨阶段扩展**：teacher-portal P3-P5 跟随 teacher-bff 扩展下游页面（与 ISSUE-004/005 跨阶段扩展例外一致）

- **影响**：本评估总结供 coord 参考，不直接阻塞工作；具体阻塞问题已分别提请（ISSUE-036~040）
- **建议方案**：
  1. coord 优先处理 ISSUE-037（schema 仲裁机制）+ ISSUE-039（packages 时机），二者是 ai13 P2 启动的关键前置
  2. ai13 在等待 coord 仲裁期间，先完成 03-long-term-architecture.md §6 回写（删除 REST→GraphQL 演进策略，对齐 F9）
  3. ai13 P2 启动前完成 packages 骨架建立（ui-tokens/ui-components/hooks）
  4. ai13 与 ai03 建立 schema 协调通道（PR review + 双方签字）
- **状态**：待 coord 仲裁（评估总结，无具体裁决需求）
- **coord 裁决**：（待填写）

---

## 3.4 ai13 复审批次（2026-07-09）

**复审范围**：coord-final-decisions.md（teacher-portal 相关 F1-F12 + 通用 G14/G15 错误码）+ ai-work-orchestration.md（批次 1 P2 ai13 工作范围）+ issues.md v1.3（35 个已识别问题）+ ai13 自身 `services/teacher-portal/docs/02-architecture-design.md`（§3 packages / §4 MF 设计）+ `services/teacher-portal/docs/03-long-term-architecture.md`（§6 REST→GraphQL 演进策略）

**复审结论**：

| 维度           | 评估                                                                                                                                                                                                                                                                                                                                   |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **仲裁可行性** | 高。F1-F12 前端裁决 + G14/G15 错误码裁决技术方案清晰，对齐黄金模板。ai13 P2 启动依赖清晰（iam gRPC 批次 1 就绪 + ai03 teacher-bff GraphQL schema coord 仲裁）。ai13 的 02/03 文档已设计完整 MF Shell + packages 结构 + 长远架构，大部分裁决可落地。                                                                                    |
| **仲裁影响**   | 中。直接影响 ai13 的裁决 12 项（F1-F12）：9 项已对齐无阻塞，2 项需回写（F9 GraphQL 改造 → ISSUE-036 + F8 packages 时机 → ISSUE-039），1 项需明确（F10 MF AppShell Provider → ISSUE-038）。间接影响：P2 工作量增加约 25-35%（引入 GraphQL client + MF Shell Provider + packages 建立），但通过 coord 仲裁 schema 第一版可降低协调成本。 |
| **文档同步**   | 中。ai13 03-long-term-architecture.md §6 仍保留"REST→GraphQL 演进策略"过渡方案描述（ISSUE-036）；02 文档已回写删除过渡方案，但 03 文档未同步。issues.md 文件结构严重混乱（ISSUE-035，ai15 已提请）。                                                                                                                                   |
| **契约明确性** | 中。teacher-bff GraphQL schema 第一版仲裁机制未明确（ISSUE-037，与 ISSUE-019/030 同类）；MF AppShell 是否包含 GraphQL client 单例未明确（ISSUE-038）；packages 建立时机未明确（ISSUE-039）。                                                                                                                                           |
| **批次规划**   | 高。批次 1 P2 规划合理：ai13⟷ai03 双向依赖 + iam gRPC 50052 就绪 + coord 仲裁 schema 第一版。ai13 P2 范围限 client 改造 + MF shell + 共享组件抽取，边界清晰。                                                                                                                                                                          |
| **遗留风险**   | 低-中。ISSUE-036（03 文档回写）需 ai13 P2 启动前完成；ISSUE-037/038/039 需 coord 仲裁确认；ISSUE-040（P2 功能范围）需 coord 明确。均不阻塞 P2 启动（可在批次 0 等待期间完成回写 + packages 骨架建立）。                                                                                                                                |

**新增 6 个问题**（ISSUE-036 ~ ISSUE-041）已登记到 §2.7 区，待 coord 仲裁。

**ai13 对 coord 仲裁的整体评判**：

1. **F9 GraphQL 裁决可行性：中-高**
   - 优点：urql/apollo 是成熟方案，与 BFF GraphQL Yoga 对齐，schema-first 工作流保证前后端契约一致
   - 风险：ai13⟷ai03 双向依赖需 coord 仲裁 schema 第一版（ISSUE-037），若仲裁不及时将阻塞并行开发
   - 工作量影响：相比原 REST 设计，需引入 urql/apollo client + GraphQL query/mutation 文档 + 错误信封映射，工作量增加约 25-30%
   - 阻塞依赖：依赖 ai03 P2 产出的 GraphQL server schema（coord 仲裁第一版）

2. **F8 packages 归属裁决可行性：高**
   - 优点：ai13 已设计完整 packages 结构（02 文档 §3），明确 ui-tokens/ui-components/hooks 三层
   - 风险：建立时机不明确（ISSUE-039），若 P2 启动时未就位将阻塞 teacher-portal 开发
   - 工作量影响：新增 packages 骨架建立任务，但 4 个 portal 共享，长期收益高
   - 阻塞依赖：无外部阻塞，ai13 自主完成

3. **F10 MF AppShell 整体暴露裁决可行性：高**
   - 优点：AppShell 整体暴露简化 Remote 接入，各 Remote 自行决定内部布局灵活
   - 风险：GraphQL client 单例是否包含在 AppShell 中未明确（ISSUE-038），影响缓存一致性
   - 工作量影响：若方案 A（包含 GraphQL Provider），Shell 需额外实现 Provider 注入；若方案 B（不包含），各 Remote 自行初始化
   - 阻塞依赖：需 coord 明确方案 A/B

4. **F12 localStorage token 裁决可行性：高**
   - 优点：与 ai13 原设计一致，无需调整
   - 风险：P6+ 迁移 httpOnly Cookie 时需重构（X7 待 P6 评估），但不阻塞当前阶段
   - 工作量影响：无

5. **G14/G15 错误码裁决可行性：高**
   - 优点：统一错误码前缀（BFF_TEACHER_ / CORE_EDU_*）简化前端错误处理逻辑
   - 风险：无
   - 工作量影响：前端 i18n key 命名调整（F4 裁决 error.<service>.<code_snake>），工作量小

**建议 coord 优先处理**：

1. **P0**：ISSUE-037（teacher-bff GraphQL schema 仲裁机制）—— 阻塞 ai13 P2 启动，建议批次 1 启动前仲裁 schema 第一版
2. **P1**：ISSUE-039（packages 建立时机）—— ai13 P2 启动前必须完成 packages 骨架，需 coord 明确时机
3. **P1**：ISSUE-038（MF AppShell GraphQL client 单例）—— 影响 P2 MF Shell Provider 设计
4. **P2**：ISSUE-036（03 文档回写）—— ai13 自行执行回写，coord 验收时确认
5. **P2**：ISSUE-040（P2 功能范围）—— 需 coord 明确 ai13 P2 页面边界
6. **P3**：ISSUE-041（评估总结）—— 仅供参考，无具体裁决需求

**ai13 回写义务承诺**：

按 coord-final-decisions §7.1 要求，ai13 将在 P2 启动前完成回写：

- 删除 03-long-term-architecture.md §6 "REST→GraphQL 演进策略"（ISSUE-036）
- 02-architecture-design.md 已回写删除过渡方案（保持）
- 回写后自行验证 + known-issues.md 工作经验日志追加记录
- P2 启动前完成 packages 骨架建立（ui-tokens/ui-components/hooks）

---

## 3.5 ai03 复审批次（2026-07-09）

**复审范围**：coord-final-decisions.md（BFF 专项 B1-B8 + 通用 G1-G17 + §5.2 接口命名）+ ai-work-orchestration.md（批次 1 P2 ai03⟷ai13 双向依赖）+ issues.md v1.4（含 ai03 新增 6 个问题）+ ai03 自身 `services/teacher-bff/docs/02-architecture-design.md`（GetTeacherDashboardStats 命名一致性验证）

**复审结论**：

| 维度           | 评估                                                                                                                                                                                                                                                                                                                                                            |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **仲裁可行性** | 中-高。B1-B8 BFF 专项裁决技术方案清晰（GraphQL Yoga + DataLoader + gRPC DownstreamClient + Redis 短缓存），对齐 004 §6.2 BFF 混合读策略。但 B2（首次实现即 gRPC 调下游）在 P2 阶段存在执行落地障碍——core-edu P3 / content P4 / data-ana P4 / ai P5 / msg P5 才启用 gRPC server，P2 仅 iam gRPC 可用（ISSUE-032）。需 coord 明确"跨阶段扩展例外"的具体执行方式。 |
| **仲裁影响**   | 高。直接影响 ai03 的裁决 8 项（B1-B8）+ 通用裁决 17 项（G1-G17）+ §5.2 接口命名 1 项 = 共 26 项。ai03 P2 工作量从原计划 5 项激增至 19 项（ISSUE-036），批次 1 时间线 5-7 天内完成风险高。需 coord 明确最小交付范围（Must Have / Should Have / Nice to Have 分级）。                                                                                             |
| **文档同步**   | 中。ai03 02-architecture-design.md 有 4 处使用 `GetTeacherDashboardStats`（含 Stats 后缀），与 §5.2 裁决 `GetTeacherDashboard` 不一致（ISSUE-035），需 P2 启动前回写。issues.md 文件结构严重混乱（ISSUE-035 ai15 已提请，编号多处冲突），需 coord 统一重编号。                                                                                                  |
| **契约明确性** | 中。B2 P2 阶段 Dashboard Query Resolver 实现方式未明确（ISSUE-032）；B4 越权防御在 P2 阶段无法调 core-edu gRPC 校验 teacherId 与班级关系（ISSUE-033）；B3+B4 错误码语义区分未明确（ISSUE-059）；G2 /readyz 检查全部下游依赖在 P2 不可行（ISSUE-034）。共 4 项契约不明确需 coord 仲裁。                                                                          |
| **批次规划**   | 高。批次 1 P2 规划合理：ai03⟷ai13 GraphQL schema 双向依赖 + coord 仲裁第一版 schema。ai03 P2 产出 DownstreamClient 抽象供 ai04/ai05 复用，是批次 2/3 的前置依赖。跨阶段扩展例外原则已建立（ai-work-orchestration §1.5），但需明确执行细节。                                                                                                                     |
| **遗留风险**   | 中。ISSUE-032/033/034 需 coord 仲裁 P2 阶段具体执行方式；ISSUE-035 需 ai03 回写 02 文档；ISSUE-036 工作量激增可能导致批次 1 延期，连锁阻塞 ai04 P3 + ai05 P4 + ai13 P2；ISSUE-059 错误码语义需 coord 仲裁。                                                                                                                                                     |

**新增 6 个问题**（ISSUE-032 ~ ISSUE-036 + ISSUE-059）已登记到"§1 待仲裁问题"区，待 coord 仲裁。

**ai03 对 coord 仲裁的整体评判**：

1. **B1 GraphQL 裁决可行性：高**
   - 优点：GraphQL Yoga + DataLoader 是成熟方案，schema-first 开发模式配合 graphql-codegen 可保证类型安全
   - 风险：P2 schema 第一版需 coord 仲裁（与 ai13 双向依赖），schema 演进需版本管理
   - 工作量影响：+25%（GraphQL server 搭建 + schema 设计 + Resolver 实现）

2. **B2 gRPC 调下游裁决可行性：中（P2 阶段）**
   - 优点：gRPC 性能优于 REST，protobuf 契约强类型保证
   - 风险：P2 阶段仅 iam gRPC 可用，Dashboard Query 多源数据断裂（ISSUE-032）
   - 建议：明确"跨阶段扩展例外"执行方式——schema 完整设计 + Resolver 按阶段补 gRPC 调用 + null 字段降级
   - 工作量影响：+15%（DownstreamClient 抽象 + gRPC client 实现）

3. **B3 豁免 @RequirePermission 可行性：高**
   - 优点：BFF 作为聚合层不做权限决策，权限由 Gateway JWT + 下游服务负责，职责清晰
   - 风险：需明确 BFF 仍需做越权防御（B4），不能完全不校验
   - 工作量影响：减少（无需实现权限装饰器）

4. **B4 越权防御裁决可行性：中（P2 阶段）**
   - 优点：数据权限防御是安全最佳实践
   - 风险：P2 阶段 core-edu gRPC 未启用，无法调 GetClassesByTeacher 校验 teacherId 与班级关系（ISSUE-033）
   - 建议：P2 抽象 AuthorizationGuard 接口 + DEV_MODE 放行 + 生产拒绝；P3 接入 core-edu gRPC + Redis 缓存
   - 工作量影响：+10%（Guard 抽象 + Redis 缓存）

5. **B5+B6+B7+B8 裁决可行性：高**
   - B5 错误码前缀 BFF_TEACHER_：无风险，直接落地
   - B6 Redis 5-30s 短缓存：无风险，对齐 004 §6.2
   - B7 P2-P4 不订阅 Kafka：无风险，降低 P2 复杂度
   - B8 DownstreamClient 抽象回写 teacher-bff：无风险，但需 P2 产出可复用抽象供 ai04/ai05

6. **G1-G17 通用裁决可行性：高（部分 P2 不可行）**
   - G2 /readyz 检查全部下游依赖在 P2 不可行（ISSUE-034），需允许探针列表按阶段扩展
   - 其余 G1/G3-G17 无风险，直接落地
   - 工作量影响：+30%（结构化日志 + metrics + tracer + Zod + GlobalErrorFilter + 优雅关闭等）

**建议 coord 优先处理**：

1. **P0**：ISSUE-032（Dashboard Query Resolver P2 执行方式）—— 阻塞 ai03 P2 GraphQL schema 设计 + ai13 前端联调
2. **P0**：ISSUE-033（越权防御 P2 实现方式）—— 阻塞 ai03 P2 安全设计
3. **P0**：ISSUE-034（/readyz P2 探针范围）—— 阻塞 ai03 P2 Pod 就绪
4. **P1**：ISSUE-036（P2 工作量分级）—— 需 coord 明确 Must Have / Should Have / Nice to Have
5. **P1**：ISSUE-059（错误码语义区分）—— 阻塞 ai03 P2 错误码设计 + ai13 前端 i18n
6. **P2**：ISSUE-035（GetTeacherDashboard 命名回写）—— ai03 自行执行回写，coord 验收时确认

**ai03 回写义务承诺**：

按 coord-final-decisions §7.1 要求，ai03 将在 P2 启动前完成回写：

- 将 02-architecture-design.md 中 4 处 `GetTeacherDashboardStats` 替换为 `GetTeacherDashboard`（ISSUE-035）
- 回写后自行验证 + known-issues.md 工作经验日志追加记录
- 等待 coord 仲裁 ISSUE-032/033/034/036/059 后启动 P2 开发

---

> **ai16 复审批次记录已迁移**：见 [issues/objections/admin-portal_issue.md](./architecture/issues/objections/admin-portal_issue.md)（2026-07-09 设计文档重构，issues.md 已归档）

---

## 2.9 ai02 补充的待仲裁问题（ISSUE-053 ~ ISSUE-058）

**复审范围**：coord-final-decisions.md（前端 4 portal F1-F12 + 通用 G14/G16 + X2/X3/X6 待 P6+ 事项 + §7 各 AI 回写义务）+ ai-work-orchestration.md（批次 5 P6 ai16 工作范围）+ issues.md v1.5（含 ai16 新增 5 个问题 ISSUE-044~048）+ ai16 自身 `apps/admin-portal/docs/02-architecture-design.md`（§4.1 数据获取路径 / §6.1 权限表 27 路由 / §6.2 错误码清单 / §12.4 错误码前缀表 / §18 coord 仲裁清单 9 子项）

**复审结论**：

| 维度           | 评估                                                                                                                                                                                                                                                                                                                                                                     |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **仲裁可行性** | 中-高。F1/F2 端口 + MF 配置裁决与 ai16 文档已一致（无阻塞）；F7 权限点命名 + F9 GraphQL + G14 错误码前缀需补充 admin-portal 适配（3 项裁决未覆盖 admin-portal 特例）。X2/X3/X6 待 P6+ 事项裁决合理，但 X3 审计日志归属影响 admin-portal MVP 核心功能，建议前置裁决（ISSUE-048）。                                                                                        |
| **仲裁影响**   | 中。直接影响 ai16 的裁决项：F1/F2（已对齐）+ F7（需补充前缀规则）+ F9（需明确 BFF 归属）+ F10（MF Shell 已对齐）+ G14（需补充 ADMIN_ 前缀）+ G16（admin 8 topic P6 补，已对齐）+ X2/X3/X6（待 P6 评估）。间接影响：admin-portal P6 启动需 ai13 P2 MF shell 就绪（暴露 GraphQL client）+ events.proto 补 AuditEvent message。                                             |
| **文档同步**   | 中。ai16 02-architecture-design.md §4.1 描述复用 ApiClient（REST），未提及 GraphQL client（需回写，见 ISSUE-047）；§6.2 错误码清单 ADMIN_/SCHOOL_ 前缀待 coord 仲裁（ISSUE-045）；§12.4 错误码前缀表标注"❌ 待新增"，与 G14 清单不符。issues.md 文件结构严重混乱（line 567 标题嵌入 / §2 出现 3 次 / §3.4 出现 3 次 / ISSUE-023~041 多处冲突），建议 coord P0 优先重构。 |
| **契约明确性** | 中。admin-portal BFF 归属不明（ISSUE-044）；权限点命名前缀规则不明（ISSUE-046）；GraphQL client 复用方式不明（ISSUE-047）；审计日志归属不明（ISSUE-048）。共 4 项契约不明确需 coord 仲裁。                                                                                                                                                                               |
| **批次规划**   | 高。批次 5 P6 规划合理：ai16 依赖仅 events.proto（P6 实施时补 admin 8 topic）。但若 ISSUE-048（审计日志归属）前置到 P6 启动前裁决，可降低 admin-portal MVP 实现风险。                                                                                                                                                                                                    |
| **遗留风险**   | 中。ISSUE-044（BFF 归属）+ ISSUE-048（审计日志）阻塞 admin-portal MVP 核心功能；ISSUE-045/046/047 需 coord 仲裁后回写 02 文档；issues.md 文件结构混乱影响全部 AI 协同效率（ai15 已提请 ISSUE-035，ai16 复审确认）。                                                                                                                                                      |

**新增 5 个问题**（ISSUE-044 ~ ISSUE-048）已登记到 §1 待仲裁问题区（位于 ISSUE-031 之后），待 coord 仲裁。

**ai16 对 coord 仲裁的整体评判**：

1. **F1/F2 端口 + MF 配置裁决可行性：高**
   - 已对齐：admin-portal 端口 4003 + MF 配置 teacher_app@localhost:4000，与 ai16 文档一致
   - 无阻塞，直接落地

2. **F7 权限点命名裁决可行性：中**
   - 优点：`<RESOURCE>_<ACTION>` + `_OWN/_CHILD` 后缀规则清晰
   - 风险：F7 例子未带服务前缀，ai16 用 `ADMIN_DASHBOARD_VIEW`/`IAM_USER_READ` 带前缀，与 F7 例子契合度不明（ISSUE-046）
   - 建议：F7 补充"允许服务前缀作为命名空间"条款，避免不同域同名资源冲突

3. **F9 GraphQL 裁决可行性：中（admin-portal 视角）**
   - 优点：urql/apollo + GraphQL Yoga 对齐，前端契约一致
   - 风险：admin-portal 无对应 admin-bff，数据获取路径未定义（ISSUE-044）；GraphQL client 复用方式未明确（ISSUE-047）
   - 建议：复用 teacher-bff GraphQL endpoint + 预留 admin schema 命名空间；ai13 P2 MF shell 暴露 GraphQL client 单例供 admin-portal 复用

4. **G14 错误码前缀裁决可行性：中**
   - 优点：13 个前缀清单覆盖大部分服务
   - 风险：未列 `ADMIN_` 也未列 `SCHOOL_`，admin-portal 错误码命名归属不明（ISSUE-045）
   - 建议：G14 补充 `ADMIN_` 前缀，合并 SCHOOL_ 入 ADMIN_（学校设置属 admin 业务子域）

5. **X2/X3/X6 待 P6+ 事项裁决可行性：中**
   - 优点：将 P6+ 待评估事项明确列出，避免 P2-P5 阶段过度设计
   - 风险：X3 审计日志归属影响 admin-portal MVP 核心功能（管理员操作需可追溯），若 P6 启动时才仲裁将阻塞 ai16（ISSUE-048）
   - 建议：X3 审计日志归属前置到 P6 启动前裁决，建议归 iam（已掌握用户/角色数据）

**建议 coord 优先处理**：

1. **P0**：ISSUE-044（admin-portal BFF 归属）—— 阻塞 admin-portal P6 数据获取路径设计
2. **P0**：ISSUE-048（审计日志归属）—— 阻塞 admin-portal P6 MVP 核心功能（管理员操作可追溯）
3. **P1**：ISSUE-045（错误码前缀 ADMIN_）+ ISSUE-046（权限点命名前缀规则）—— 阻塞 admin-portal P6 错误码 + 权限点设计
4. **P1**：ISSUE-047（GraphQL client 复用）—— 影响 ai13 P2 MF shell 设计（需暴露 GraphQL client）
5. **P2**：issues.md 文件结构重构（ai15 ISSUE-035 + ai04 ISSUE-031 + ai16 复审确认）—— 影响全部 AI 协同效率

**ai16 回写义务承诺**：

按 coord-final-decisions §7.1 要求，ai16 将在 coord 仲裁 ISSUE-044~048 后 3 个工作日内回写 02-architecture-design.md：

- §4.1 数据获取路径：根据 ISSUE-044 + ISSUE-047 仲裁结果，将"复用 ApiClient (REST)"改为"复用 Shell 暴露的 GraphQL client 单例 + teacher-bff GraphQL endpoint"
- §6.1 权限表：根据 ISSUE-046 仲裁结果，统一权限点命名规则
- §6.2 错误码清单：根据 ISSUE-045 仲裁结果，统一错误码前缀
- §12.4 错误码前缀表：根据 ISSUE-045 仲裁结果，更新"❌ 待新增"标注
- §18 coord 仲裁清单：根据 5 个 ISSUE 仲裁结果，更新 9 子项状态
- 回写后自行验证 + known-issues.md 工作经验日志追加记录
- 等待 coord 仲裁 ISSUE-044~048 后启动 P6 开发

---

## 2.9 ai02 补充的待仲裁问题（ISSUE-053 ~ ISSUE-058）

> 以下问题由 ai02（push-gateway）在审核 coord-final-decisions.md（push-gateway 专项 P1-P6 + 通用 G2/G9-G17）+ ai-work-orchestration.md（批次 4 P5）+ issues.md v1.6 后提请。
> 编号从 ISSUE-053 开始（避开 ai10 ISSUE-042/043、ai13 ISSUE-036~~041、ai06 ISSUE-047~~052、ai14 ISSUE-044~~047、ai16 ISSUE-044~~048、ai03 ISSUE-032~~036+042 等已用编号）。
> 注：当前 issues.md 已存在严重编号冲突（ISSUE-035 ai15 已提请整理），ai02 暂以 ISSUE-053~~058 提请，待 coord 整理后统一重编号。

### ISSUE-053: G16 Kafka topic 命名规则与 push-gateway 02 §5.1 消费 topic 不一致

- **提请 AI**：ai02（push-gateway）
- **类别**：裁决冲突 + 文档同步遗漏
- **阶段**：P5
- **问题描述**：
  - `coord-final-decisions.md` G16 裁决：Kafka topic 强制 `edu.<domain>.<aggregate>.<action>` 具体动作命名，禁止抽象名
  - ai02 `services/push-gateway/docs/02-architecture-design.md` §5.1 当前消费 topic 命名为 `edu.notification.events`（抽象名，违规）
  - `004 §7.2` 表格同样列出 `edu.notification.events`（与 G16 裁决冲突，已被 ai10 ISSUE-043 提请）
  - msg 02 §5 设计发布 topic 为 `edu.notification.sent/read/recalled`（具体动作，合规）
  - push-gateway 应消费 `edu.notification.requested`（msg 收到通知请求后发布的"请求投递"事件），而非 `edu.notification.events`（抽象名）
- **影响**：ai02 P5 启动前必须回写 02 §5.1 修改 topic 名 + §14.4/§14.5 配置项中的 topic 同步修改；004 §7.2 表格需 coord 修订（与 ISSUE-043 合并处理）
- **建议方案**：
  1. ai02 02 §5.1 消费 topic 从 `edu.notification.events` 改为 `edu.notification.requested`
  2. ai02 02 §14.4/§14.5 配置项 `KAFKA_CONSUME_TOPICS` 同步修改
  3. 004 §7.2 表格修订（与 ISSUE-043 ai10 提请合并处理，coord 统一修订）
  4. 与 ai10 协调 msg 发布方 topic 与 push-gateway 消费方 topic 一致
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-054: shared-go 共享包建立时机与责任方未在批次规划中明确

- **提请 AI**：ai02（push-gateway）
- **类别**：前置依赖未就绪 + 工作归属不明
- **阶段**：P5
- **问题描述**：
  - `project_rules.md` §11 多语言 monorepo 规则明确列出 `packages/shared-go`（Go 共享工具，待建立）
  - `coord-final-decisions.md` 未提及 shared-go 包的建立时机与责任方
  - `ai-work-orchestration.md` §3.1 批次 0（coord 前置）仅列出 shared-ts Outbox 工具包（0.4），未列出 shared-go 包
  - push-gateway（ai02）与 api-gateway（ai01）当前代码中重复 4 个 Go 模块：
    - `tracer.go`（OTel tracer 初始化）
    - `logger.go`（slog logger 初始化）
    - `jwks.go`（JWT JWKS 公钥拉取）
    - `env.go`（环境变量加载 + 校验）
  - 若不提取到 shared-go 包，ai01/ai02 各自维护一份代码，违反 DRY 原则；后续修改需双倍工作量
  - 与 ISSUE-018（shared-ts Outbox 工具包建立时机）同类，但聚焦 Go 共享包
- **影响**：ai02 P5 启动时若 shared-go 包未就位，push-gateway 需复制 api-gateway 的 4 个模块代码，后续重构成本高；ai01 P2 启动时同样面临此问题（但 api-gateway P2 启动时 push-gateway 还未启动，ai01 可能先建一份代码，后续难以提取）
- **建议方案**：
  1. coord 在批次 0 增加 0.14 任务："建立 `packages/shared-go` 包骨架（含 tracer/logger/jwks/env 4 个模块的接口定义 + 默认实现）"
  2. 责任方：建议 coord 直接负责建立（与 shared-ts Outbox 同批次），或指派 ai01（api-gateway）在 P2 启动前完成提取
  3. ai01/ai02 在 P2/P5 启动时直接 import `packages/shared-go`，禁止各自维护副本
  4. shared-go 包版本管理：通过 go.workspace 引用，对齐 project_rules §11 多语言 monorepo 规则
  5. 后续提取候选：circuit-breaker.go / rate-limiter.go（若 ai01 P2 实现后 ai02 P5 复用）
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-055: G2 /readyz "全部下游依赖"对 push-gateway Kafka 可选消费的适用性

- **提请 AI**：ai02（push-gateway）
- **类别**：裁决冲突（适用性边界）
- **阶段**：P5
- **问题描述**：
  - `coord-final-decisions.md` G2 裁决："首次实现即检查全部下游依赖（DB SELECT 1 / Redis PING / Kafka 连接 / gRPC 下游可达）"
  - ai02 `services/push-gateway/docs/02-architecture-design.md` §4.3 当前 /readyz 仅检查 Redis PING
  - push-gateway 的下游依赖矩阵：
    - **Redis**（必需）：在线状态 SET + Pub/Sub 跨实例广播
    - **Kafka**（可选）：02 §5.1 标注"Kafka 消费可选"，仅用于广播类通知（解耦 + 削峰），定向推送走 HTTP `/internal/push`
    - **gRPC 下游**：无（push-gateway 不调任何 gRPC 服务，P1 裁决豁免 gRPC）
    - **DB**：无（push-gateway 无数据库）
  - 问题：Kafka 不可达时是否应使 /readyz 失败？
    - 若失败 → Pod 被 K8s 重启 → 重启期间无法接收 HTTP /internal/push 请求 → msg 推送积压 → 雪崩
    - 若不失败 → Kafka 消费方停摆，但 HTTP 通道仍可用 → degraded 模式
  - 与 ai10 ISSUE-042（msg /readyz 强依赖 PushGateway）相关但不同：ISSUE-042 关注 msg 对 push-gateway 的依赖，本问题关注 push-gateway 对 Kafka 的依赖
- **影响**：ai02 P5 实现时需明确 /readyz 的 Kafka 检查策略，否则 Pod 启动时序可能出问题；与 ISSUE-042（msg /readyz PushGateway 依赖）形成连锁
- **建议方案**：
  1. G2 裁决补充："可选下游依赖不可达时，/readyz 返回 degraded 状态（HTTP 200 但 body 标注 `degraded: true`），不触发 Pod 重启，仅告警"
  2. ai02 02 §4.3 /readyz 实现：
     - Redis PING（必需，失败返回 503）
     - Kafka 连接（可选，失败仅告警 + body 标注 degraded）
  3. metrics 暴露 `push_gateway_readyz_degraded_total` 监控 degraded 状态频次
  4. 与 ISSUE-042（msg /readyz PushGateway 依赖）协调：push-gateway degraded 时 msg 仍可调 HTTP /internal/push（同步通道），仅 Kafka 广播通道降级
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-056: 02 文档 §5.4/§14.2 仲裁请求章节删除会丢失设计决策追溯

- **提请 AI**：ai02（push-gateway）
- **类别**：文档同步遗漏（设计决策追溯）
- **阶段**：P5
- **问题描述**：
  - `coord-final-decisions.md` §7.2 回写义务表要求："各 AI 必须删除 02-architecture-design.md 中所有'中间过渡方案'描述，对齐最终方案"
  - ai02 02 文档中包含两个"仲裁请求"章节：
    - §5.4 "ai02 仲裁请求：gRPC vs HTTP 协议选型"（含 ai02 建议保持 HTTP 的理由表格 + 核心论点）
    - §14.2 "SSE/断线重连仲裁请求"（含 ai02 建议 SSE 不实现 + 断线重连仅协议预留的理由）
  - coord P1/P5/P6 裁决与 ai02 仲裁请求完全一致：
    - P1（gRPC 豁免）= ai02 §5.4 建议
    - P5（SSE 不实现）= ai02 §14.2 建议
    - P6（断线重连仅协议预留）= ai02 §14.2 建议
  - 若按 §7.2 要求"删除所有中间过渡方案描述"将 §5.4/§14.2 整章删除，未来追溯设计决策依据时无文档可查（如：为何 push-gateway 不用 gRPC？为何 SSE 不实现？）
  - 这些章节不是"中间过渡方案"，而是"设计决策记录"（已被 coord 采纳），不应删除
  - 与 ISSUE-021（"不分阶段"原则与"批次时间线"表述易混淆）同类，均为文档表述问题
- **影响**：ai02 P5 启动前回写 02 文档时，若删除 §5.4/§14.2 将丢失设计决策追溯；若保留则违反 §7.2 回写义务
- **建议方案**：
  1. coord 在 §7.2 回写义务表中补充澄清："设计决策记录章节（已被 coord 采纳的仲裁请求）保留，但正文需标注'coord 已采纳，见 coord-final-decisions P1/P5/P6'，标题改为'设计决策记录：xxx'"
  2. ai02 02 §5.4 改名为"设计决策记录：gRPC vs HTTP 协议选型（coord 已采纳 P1）"
  3. ai02 02 §14.2 改名为"设计决策记录：SSE/断线重连范围（coord 已采纳 P5/P6）"
  4. 章节内容保留作为决策追溯依据，但删除"中间过渡方案"字样
  5. 其他 AI（如 ai13 ISSUE-036、ai15 ISSUE-034）的同类"过渡方案描述"也按此原则处理：删除过渡方案本身，保留设计决策记录
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-057: ISSUE-012 /internal/push 契约仲裁前置与 02 §4.2 已有定义重复

- **提请 AI**：ai02（push-gateway）
- **类别**：契约不明确（仲裁范围重复）
- **阶段**：P5
- **问题描述**：
  - `ai-work-orchestration.md` §7.3：coord 仲裁第一版接口契约（path/body/status code），ai02 优先 1-2 天启动 /internal/push 端点
  - ISSUE-012 已裁决时序：ai02 优先启动 / ai10 后启动
  - 但 ai02 `services/push-gateway/docs/02-architecture-design.md` §4.2 已有完整 /internal/push 契约定义：
    - 路径：`POST /internal/push` / `POST /internal/broadcast` / `GET /internal/online/<userID>`
    - 鉴权：`X-Internal-Token` 头
    - 请求体：`{user_id, event, data, ttl?}` / `{event, data, filter?}`
    - 响应信封：ActionState 风格（`{success, data?, error?}`）
    - 错误码：`PUSH_UNAUTHORIZED` / `PUSH_INVALID_REQUEST` / `PUSH_INVALID_PAYLOAD` / `PUSH_TOO_MANY_CONNECTIONS` / `PUSH_INTERNAL_ERROR`
    - 响应语义：`delivered` / `online` 字段含义
  - coord 重新仲裁第一版契约可能与 02 §4.2 已有定义产生不一致
  - 若 coord 仲裁结果与 02 §4.2 不同，ai02 需重写已实现代码 + ai10 需按 coord 契约实现调用方
- **影响**：ai02 P5 启动时若 coord 仲裁契约与 02 §4.2 不一致，将产生返工；ai10 调用方实现可能因契约变动而阻塞
- **建议方案**：
  1. coord 直接采纳 ai02 02 §4.2 作为第一版 /internal/push 契约（"as-is"采纳）
  2. 仅在 ai10 提出异议时（如 msg 调用方需要 batch 接口 / 异步回调机制），coord 才调整契约
  3. coord 在批次 4 启动前公布"采纳 ai02 02 §4.2 作为第一版契约"的决定，避免重复仲裁
  4. 若 coord 决定调整，必须给出具体差异点（如新增字段、修改响应格式），ai02/ai10 按差异点调整
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

### ISSUE-058: push-gateway 在线状态 Redis SET 心跳续期与 G2 /readyz 检查的耦合

- **提请 AI**：ai02（push-gateway）
- **类别**：契约不明确（运行时耦合）
- **阶段**：P5
- **问题描述**：
  - ai02 `services/push-gateway/docs/02-architecture-design.md` §3.1 设计：
    - `edu:push:online:<userID>` SET，TTL 60s，每 30s 客户端心跳时本实例 SADD 自己 + EXPIRE 60s
    - 在线状态判定：SET 非空 = 在线，SET 空 = 离线
  - `coord-final-decisions.md` G2 裁决：/readyz 检查 Redis PING
  - 问题：Redis 不可达时的连锁反应：
    1. /readyz 失败 → Pod 被 K8s 重启 → 所有 SET 心跳停止续期 → 60s 后所有用户 SET 过期 → 所有用户被视为离线
    2. 但 Hub 内存中的连接依然存在（Hub 是进程内单例），仅在 Hub 重启时丢失
    3. Pod 重启后，Hub 启动时内存为空，但 Redis SET 可能还有未过期的成员（其他实例的）→ 在线状态短暂不一致
  - 与 ISSUE-055（Kafka 可选 /readyz）相关，但聚焦 Redis 必需依赖的失败恢复
  - 关联 project_memory "Lessons Learned"：Hub 启动需重建 Redis SET 以保证一致性
- **影响**：ai02 P5 实现时需明确 Hub 启动时的 Redis SET 重建策略；Redis 故障恢复后在线状态一致性需保证
- **建议方案**：
  1. ai02 02 §3.1 补充"Hub 启动时重建 Redis SET"机制：
     - Hub 启动时遍历内存连接（userID），SADD 自己 instanceID 到 `edu:push:online:<userID>` + EXPIRE 60s
     - 启动时清空 Redis 中本 instanceID 的旧成员（避免幽灵成员）
  2. /readyz Redis 检查失败时仅告警不阻塞（与 ISSUE-055 协调），避免雪崩
  3. metrics 暴露 `push_gateway_redis_set_rebuild_total` 监控重建次数
  4. 文档化"Redis 故障恢复后 60s 内在线状态可能短暂不一致"，msg 服务调用方需容忍 `online: false` 误判（msg 应继续尝试 HTTP /internal/push，由 push-gateway 返回真实在线状态）
- **状态**：待 coord 仲裁
- **coord 裁决**：（待填写）

---

## 3.7 ai02 复审批次（2026-07-09）

**复审范围**：coord-final-decisions.md（push-gateway 专项 P1-P6 + 通用 G2/G9-G17）+ ai-work-orchestration.md（批次 4 P5 ai02⟷ai10 双向依赖）+ issues.md v1.6（含 ai02 新增 6 个问题 ISSUE-053~058）+ ai02 自身 `services/push-gateway/docs/02-architecture-design.md`（§4.2 /internal/push 契约 + §5.1 Kafka 消费 topic + §5.4 gRPC 仲裁请求 + §14.2 SSE/断线重连仲裁请求）

**复审结论**：

| 维度           | 评估                                                                                                                                                                                                                                                                                                                      |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **仲裁可行性** | 高。P1-P6 裁决技术方案清晰，与 ai02 02 文档高度对齐：P1 gRPC 豁免（ai02 §5.4 已提请）+ P2 X-Internal-Token（ai02 §4.2 已定义）+ P3 多阶段 Dockerfile（标准实践）+ P4 slog（ai02 §6.3 已设计）+ P5 SSE 不实现（ai02 §14.2 已提议）+ P6 断线重连仅协议预留（ai02 §14.2 已提议）。6 项裁决全部与 ai02 设计意图一致，无返工。 |
| **仲裁影响**   | 中。直接影响 ai02 的裁决 6 项（P1-P6）：全部已对齐无阻塞。间接影响：shared-go 包未建立（ISSUE-054）需在批次 0 由 coord 完成；02 文档回写需保留 §5.4/§14.2 设计决策记录（ISSUE-056）；Kafka 可选 /readyz 策略需协调（ISSUE-055）；Redis SET 心跳重建机制需补充（ISSUE-058）。                                              |
| **文档同步**   | 中。push-gateway 02 §5.1 消费 topic `edu.notification.events` 与 G16 裁决冲突（ISSUE-053）；02 §4.3 /readyz 仅检查 Redis PING，与 G2 "全部下游依赖"裁决需协调（ISSUE-055）；02 §5.4/§14.2 仲裁请求章节保留与否需协调（ISSUE-056）；issues.md 文件结构严重混乱（ISSUE-035 ai15 已提请，ai02 复审确认）。                   |
| **契约明确性** | 中。/internal/push 契约已在 02 §4.2 完整定义，但 ISSUE-012 仍要求 coord 重新仲裁第一版（ISSUE-057）；shared-go 包建立时机不明确（ISSUE-054）；Redis SET 心跳续期与 /readyz 检查的耦合需协调（ISSUE-058）。                                                                                                                |
| **批次规划**   | 高。批次 4 P5 规划合理：ai02⟷ai10 双向依赖通过 coord 仲裁第一版契约 + ai02 优先 1-2 天启动解决。前置依赖清晰：批次 0.12-0.13 proto 补全 + 批次 3 完成。ai02 实际工作量评估 7-8 天，匹配批次 4 预估 7-10 天，无跨度问题。                                                                                                  |
| **遗留风险**   | 低。ISSUE-053/055/056/058 需 ai02 P5 启动前回写 02 文档；ISSUE-054/057 需 coord 仲裁确认。均不阻塞 P5 启动（可在批次 0-3 等待期间完成回写）。无工作量激增风险（与 ai03 ISSUE-036 工作量激增不同）。                                                                                                                       |

**新增 6 个问题**（ISSUE-053 ~ ISSUE-058）已登记到 §2.9 区，待 coord 仲裁。

**ai02 对 coord 仲裁的整体评判**：

1. **P1 gRPC 豁免裁决可行性：高**
   - 优点：与 project_memory "Lessons Learned" 第 9 条经验一致（gRPC 对 push-gateway 低 QPS 内部基础设施通信不必要）；HTTP + Kafka 双通道已足够
   - 风险：无
   - 工作量影响：ai02 无需新建 gRPC server + proto 定义，节省约 30% P5 工作量
   - 阻塞依赖：无

2. **P2 X-Internal-Token 裁决可行性：高**
   - 优点：与 ai02 02 §4.2 已定义一致，无需调整
   - 风险：当前代码命名为 `X-Internal-Key` + 环境变量 `INTERNAL_API_KEY`，P5 实施时需重命名为 `X-Internal-Token` + `INTERNAL_API_TOKEN`（01 §7.1 #6 已记录）
   - 工作量影响：极小（重命名 + 文档同步）
   - 阻塞依赖：无

3. **P3 多阶段 Dockerfile 裁决可行性：高**
   - 优点：标准实践，builder 阶段编译 + runtime 阶段最小镜像
   - 风险：无
   - 工作量影响：调整现有 Dockerfile 为多阶段，工作量小
   - 阻塞依赖：无

4. **P4 slog 裁决可行性：高**
   - 优点：与 ai02 02 §6.3 已设计一致
   - 风险：当前代码可能用 logrus 或标准 log，需迁移到 slog
   - 工作量影响：logger 适配，工作量小
   - 阻塞依赖：无

5. **P5 SSE 不实现裁决可行性：高**
   - 优点：与 ai02 02 §14.2 仲裁请求一致；本期仅 HTTP 长轮询预留，减少 P5 工作量
   - 风险：无（无 SSE 客户端需求）
   - 工作量影响：无需实现 SSE 降级通道
   - 阻塞依赖：无

6. **P6 断线重连仅协议预留裁决可行性：高**
   - 优点：与 ai02 02 §14.2 仲裁请求一致；本期仅预留 session_id + last_seq 字段，P6 实现补推逻辑
   - 风险：若 P6 之前用户断线重连无法补推消息（但 msg 服务落库可补偿，用户重新连接后通过 msg 查询历史消息）
   - 工作量影响：本期仅字段预留，无补推逻辑实现
   - 阻塞依赖：无

**建议 coord 优先处理**：

1. **P0**：ISSUE-035（issues.md 结构混乱，ai15 已提请，ai02 复审确认）—— 影响全部 AI 查询效率，建议立即整理
2. **P1**：ISSUE-053（G16 topic 命名）+ ISSUE-055（G2 /readyz Kafka 可选）—— ai02 P5 启动前需回写 02 文档，与 ISSUE-043（ai10）/ ISSUE-042（ai10）合并处理
3. **P1**：ISSUE-054（shared-go 包建立时机）—— ai01/ai02 P5 启动前需 shared-go 就位，建议批次 0 增加 0.14 任务
4. **P2**：ISSUE-056（仲裁请求章节保留）+ ISSUE-057（/internal/push 契约采纳）—— 设计决策追溯 + 契约一致性
5. **P2**：ISSUE-058（Redis SET 心跳耦合）—— Hub 重启场景的健壮性

**ai02 回写义务承诺**：

按 coord-final-decisions §7.2 要求，ai02 将在 P5 启动前完成回写：

- 02 §5.1 消费 topic 从 `edu.notification.events` 改为 `edu.notification.requested`（ISSUE-053）
- 02 §14.4/§14.5 配置项中的 topic 名同步修改（ISSUE-053）
- 02 §4.3 /readyz 实现：Redis PING（必需）+ Kafka 连接（可选，degraded 状态）（ISSUE-055）
- 02 §5.4/§14.2 章节保留但改名为"设计决策记录"，正文标注 coord 已采纳（ISSUE-056）
- 02 §4.2 /internal/push 契约保持，等 coord 直接采纳（ISSUE-057）
- 02 §3.1 Redis SET 心跳续期机制补充：Hub 启动重建 SET + metrics 监控（ISSUE-058）
- 回写后自行验证 + known-issues.md 工作经验日志追加记录
- P5 启动前确认 shared-go 包已建立（ISSUE-054）

**ai02 工作顺序规划**（基于仲裁结果）：

| 阶段     | 任务                                                                    | 依赖                           | 预估工作量 |
| -------- | ----------------------------------------------------------------------- | ------------------------------ | ---------- |
| 0 等待期 | 监控批次 0.12-0.13 proto 补全 + shared-go 包建立                        | coord 批次 0                   | 被动等待   |
| 0 等待期 | 复审 02-architecture-design.md 与裁决对齐（回写 ISSUE-053/055/056/058） | 无                             | 0.5 天     |
| 0 等待期 | 在 known-issues.md 工作经验日志追加 ai02 复审记录                       | 无                             | 0.1 天     |
| P5 启动  | 接入 shared-go 包（tracer/logger/jwks/env 复用）                        | shared-go 就位（ISSUE-054）    | 0.5 天     |
| P5 启动  | /internal/push 端点 + /internal/broadcast + /internal/online 实现       | ai10 等待调用方就绪            | 1 天       |
| P5 启动  | WebSocket /ws + Hub 连接池 + Redis Pub/Sub 跨实例广播                   | 无                             | 2 天       |
| P5 中期  | Kafka 消费方实现（可选，degraded 模式）                                 | ISSUE-055 仲裁                 | 1 天       |
| P5 中期  | /healthz + /readyz（含 Redis PING + Kafka 可选探针）+ /metrics + OTel   | ISSUE-055 仲裁                 | 1 天       |
| P5 中期  | 多阶段 Dockerfile + slog logger 迁移                                    | P3/P4 裁决                     | 0.5 天     |
| P5 后期  | X-Internal-Token 重命名（X-Internal-Key → X-Internal-Token）            | P2 裁决                        | 0.2 天     |
| P5 后期  | 集成测试 + 端到端验证（含 msg 联调）                                    | ai10 /internal/push 调用方就绪 | 1 天       |
| **总计** |                                                                         |                                | **7-8 天** |

注：ai-work-orchestration.md §9 批次 4 预估 7-10 天，ai02 实际工作量评估 7-8 天，匹配。无跨度问题（与 ai06 ISSUE-052 iam P2 工作量评估不匹配、ai03 ISSUE-036 P2 工作量激增不同）。
