docs(docs): 更新 issue 仲裁状态 + 生成集成测试阶段规划

- 14 个 issue.md 状态字段更新为"已裁决" - 对应 coord.md ARB-001~022 章节 - 共 104 处状态字段更新 - 新增 integration-test-phase.md - 集成测试与部署验证阶段(P7)规划 - 6 个批次任务分解 - 8 条核心 E2E 链路定义 - 验收标准和退出标准 Coord-AI
2026-07-10 22:05:37 +08:00
parent 8a01d0b8fc
commit c6362f4b04
15 changed files with 285 additions and 125 deletions
--- a/docs/architecture/issues/objections/admin-portal_issue.md
+++ b/docs/architecture/issues/objections/admin-portal_issue.md
@@ -16,7 +16,7 @@
 - **核查结论**：裁决方向正确（admin-portal 复用 teacher-bff + admin schema 命名空间，与 ai-allocation §5 ai16 设计重点一致）。
 - **发现的缺口**：teacher-bff 当前 [02-architecture-design.md](../../../services/teacher-bff/docs/02-architecture-design.md) **未定义 admin 命名空间的 GraphQL schema**（全文仅 1 处 audit 提及，无 adminUsers/adminRoles/auditLogs/adminDashboard 等 Query）。admin-portal P6 的全部业务查询依赖该 schema，属前置依赖缺失。
 - **建议**：请 coord 仲裁 admin 命名空间 schema 的归属与时间点——是否由 ai03（teacher-bff）在 P6 启动前补齐 `packages/shared-ts/contracts/graphql/teacher-bff.graphql` 的 admin 命名空间部分（参照本模块 [contract §2.4](../contracts/admin-portal_contract.md) 的 Query 清单）。
- **状态**：待 coord 仲裁（见新异议 ISSUE-005）
+- **状态**：已裁决（见 coord.md §23）

 ### 0.2 ARB-002（MF Shell 暴露清单）— 核查结论：✅ 通过，但 01/02 文档未跟进

@@ -46,7 +46,7 @@ ARB-001/ARB-002 均未明确仲裁以下三项，而它们直接影响 admin-por
 - **类型**：编号冲突 / 文档归属
 - **描述**：[01-understanding.md](../../../apps/admin-portal/docs/01-understanding.md) 与 [02-architecture-design.md](../../../apps/admin-portal/docs/02-architecture-design.md) 头部均标注"AI：ai07（TS/React · 管理场景域前端 remote）"，分支名 `docs/admin-portal-stage1-stage2-design-ai07`。但 [ai-allocation.md §5](../../ai-allocation.md) 第 54/97/118/159/278 行明确 admin-portal 归属 **ai16**，ai07 实际负责 classes → core-edu 交接（见 [workline.md §4.7](../workline.md)）。
 - **建议方案**：将 01/02 文档头部 AI 标识与分支命名更正为 ai16；ai07 在 admin-portal 的产出视为历史草稿，由 ai16 接管修订。
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §23）

 ### ISSUE-002-ai16：01/02 文档端口错误（3003 → 4003），且 3003 与 teacher-bff 冲突

@@ -55,7 +55,7 @@ ARB-001/ARB-002 均未明确仲裁以下三项，而它们直接影响 admin-por
 - **类型**：契约不明确 / 编号冲突
 - **描述**：01 §1 与 02 §12.1 声明 admin-portal 端口 3003，并称"与 [full-stack-runbook](../../../docs/standards/full-stack-runbook.md) 端口矩阵对齐"。但 full-stack-runbook §2.1 中 **3003 = teacher-bff**，admin-portal 未列入该 runbook。coord 维护的 [matrix.md §1](../matrix.md) 与 ai-allocation.md 统一采用 4000 段：teacher-portal :4000 / student-portal :4001 / parent-portal :4002 / admin-portal :4003。
 - **建议方案**：确认 admin-portal 端口为 **4003**；同步更新 full-stack-runbook §2.1 补齐 4 个 portal 的 4000 段端口（消除 runbook 与 matrix.md 的端口双轨制）。
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §23）

 ### ISSUE-003-ai16：01/02 文档通信协议与 ARB-001/ARB-002 不一致（REST → GraphQL）

@@ -64,7 +64,7 @@ ARB-001/ARB-002 均未明确仲裁以下三项，而它们直接影响 admin-por
 - **类型**：契约不明确 / 前置依赖缺失
 - **描述**：01 §3.1 / 02 §1、§4 全文基于 REST（`/api/v1/iam/*` + `/api/v1/admin/*` + `useApi()` + `ApiClient`）。但 ARB-001 已裁决 admin-portal 复用 teacher-bff GraphQL **admin 命名空间**，ARB-002 已裁决 Shell 暴露 `GraphQLProvider` + `useGraphQLClient`（不含 `useApi`）。02 §11.3 仍将"GraphQL vs REST"列为未决，与仲裁结论冲突。根因：01/02 文档参照的 teacher-portal 02 文档（同样基于 REST、将 GraphQL 列为未决）早于 ARB-001/002（2026-07-09），未跟进仲裁。
 - **建议方案**：admin-portal 通信协议统一为 GraphQL（`POST /api/admin/graphql` → teacher-bff admin 命名空间）；删除 `useApi`/`ApiClient` 依赖，改用 `useGraphQLClient()`；02 §11.3 移除已裁决项。本模块 [contract.md](../contracts/admin-portal_contract.md) 已按 GraphQL 编写，作为修订基准。
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §23）

 ### ISSUE-004-ai16：01/02 文档遗漏审计日志与学校设置（ai-allocation §5 明确职责）

@@ -73,7 +73,7 @@ ARB-001/ARB-002 均未明确仲裁以下三项，而它们直接影响 admin-por
 - **类型**：工作量超批 / 契约不明确
 - **描述**：[ai-allocation.md §5 ai16](../../ai-allocation.md) 第 282 行明确 admin-portal 设计重点含"用户管理 + 角色权限管理 + 学校设置 + 组织管理 + **审计日志消费**"。但 01 §2.1/§L1 导航/§L2 路由表均**无审计日志、无学校设置**（仅有 dashboard/users/roles/permissions/viewports/organization/monitoring 7 个视口）。本模块 [contract.md §1.2/§2.4](../contracts/admin-portal_contract.md) 已含 audit-logs / system 路由与 auditLogs Query，与 01/02 不一致。
 - **建议方案**：admin-portal 视口补齐为 9 个：dashboard / users / roles / permissions / viewports / organization / classes / teachers / students / audit-logs / system（按 ai-allocation §5 + contract §1.2 对齐）；审计日志经 teacher-bff GraphQL `auditLogs` Query 消费（聚合 iam `AuditEvent`）。
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §23）

 ### ISSUE-005-ai16：teacher-bff 缺 admin 命名空间 GraphQL schema（前置依赖缺失）

@@ -82,7 +82,7 @@ ARB-001/ARB-002 均未明确仲裁以下三项，而它们直接影响 admin-por
 - **类型**：前置依赖缺失
 - **描述**：ARB-001 裁决 P6 新增 admin 命名空间，但 teacher-bff [02-architecture-design.md](../../../services/teacher-bff/docs/02-architecture-design.md) 未定义该 schema（无 adminUsers / adminRoles / adminClasses / adminTeachers / adminStudents / auditLogs / adminDashboard 等 Query/Mutation）。admin-portal P6 全部业务查询依赖此 schema，且需 SDL-first 存放于 `packages/shared-ts/contracts/graphql/teacher-bff.graphql`（ARB-001 §1.3）。
 - **建议方案**：请 coord 仲裁——由 ai03 在 P6 启动前补齐 teacher-bff admin 命名空间 schema（参照本模块 contract §2.4 Query 清单），作为 admin-portal P6 的前置就绪信号；并更新 [matrix.md §3](../matrix.md) teacher-bff 行的 schema 文件状态。
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §23）

 ### ISSUE-006-ai16：01/02 文档推送策略与同类 portal 契约不一致（轮询 → WebSocket）

@@ -91,7 +91,7 @@ ARB-001/ARB-002 均未明确仲裁以下三项，而它们直接影响 admin-por
 - **类型**：契约不明确
 - **描述**：01 §3.3 / 02 §5 声明 admin-portal"不消费 WebSocket/SSE，采用轮询"。但同类 portal 契约（[parent-portal_contract.md §2.3](./parent-portal_contract.md)）消费 push-gateway `GET /ws`，本模块 [contract.md §2.3](../contracts/admin-portal_contract.md) 亦声明消费 WebSocket 实时通知。matrix.md §5 列 push-gateway WS 消费方含全部 portal。管理端审计告警/异常登录等场景对实时性有合理需求。
 - **建议方案**：admin-portal 接入 push-gateway WebSocket（与同类 portal 一致），用于审计告警、异常登录、系统异常等实时通知；保留轮询仅用于监控指标（60s）与统计（5min）这类天然适合轮询的低频数据。
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §23）

 ### ISSUE-007-ai16：matrix.md §4 将 admin-portal 列为 Kafka 直消费方，与前端层级矛盾

@@ -100,7 +100,7 @@ ARB-001/ARB-002 均未明确仲裁以下三项，而它们直接影响 admin-por
 - **类型**：契约不明确
 - **描述**：[matrix.md §4](../matrix.md) 第 111 行将 admin-portal 列为 `edu.iam.audit.created` 的消费方。但前端不直连 Kafka（[contract.md §2.2](../contracts/admin-portal_contract.md) 已明确审计日志经 GraphQL 查询）。实际链路应为：iam → Kafka → **teacher-bff** 消费 → GraphQL `auditLogs` Query → admin-portal。
 - **建议方案**：matrix.md §4 该行消费方更正为 **teacher-bff**（admin-portal 经 teacher-bff 间接消费），避免误导架构分层。
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §23）

 ---

--- a/docs/architecture/issues/objections/ai_issue.md
+++ b/docs/architecture/issues/objections/ai_issue.md
@@ -33,7 +33,7 @@
 - **类型**：编号冲突 / 文档不同步
 - **描述**：[matrix.md](../matrix.md) §2 gRPC 接口提供方矩阵写 "ai (ai12) | 50057"，§8 就绪信号跟踪表写 "ai gRPC 50057"。但 [port-allocation.md](../../../../infra/port-allocation.md) §3/§5/§7 明确 ai = HTTP 3008 / gRPC 50058（2026-07-09 coord 仲裁"push-gateway 豁免 gRPC，释放 50057；50058 让给 ai"）。两份 coord 文件矛盾，matrix.md 过时。ai 01/02 文档与 workline.md §1/§4.12 已正确采用 50058。
 - **建议方案**：coord 将 matrix.md §2 ai 行 gRPC 端口 50057 → 50058，§8 就绪信号"ai gRPC 50057"→ 50058。ai12 同步将 contracts/ai_contract.md 全部 50057 改 50058。
- **状态**：待 coord 仲裁（实为同步操作，仲裁已存在于 port-allocation.md §7）
+- **状态**：已裁决（见 coord.md §12）

 ### ISSUE-02-ai12：ai 用量事件 Kafka topic 命名三义未决

@@ -48,7 +48,7 @@
  events.proto 现状无 `AIUsageEvent` message，004 无 topic 记录。三义导致 data-ana 消费方无法对齐。

 - **建议方案**：ai12 建议采用 `edu.ai.usage`（与 matrix.md 一致，最简短，符合 `edu.<domain>.<action>` 简洁约定）。请 coord 裁定并在 004 §7.2 补登 + events.proto 补 `AIUsageEvent` message（schema 见 02-architecture-design.md §3.3）。ai12 据裁决同步 01/02 文档与 contract。
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §12）

 ### ISSUE-03-ai12：ai.proto 待补全（备课工作流 RPC + 字段扩展）

@@ -63,7 +63,7 @@
  关于 RPC 总数存在分歧：matrix.md §2 与 contract 写 6 RPC；02-architecture-design.md §4.2 单方面扩到 8 RPC（追加 GetLessonPlanStatus / ConfirmLessonPlan）。需 coord 裁定 P5 目标 RPC 清单。

 - **建议方案**：ai12 建议 P5 目标 6 RPC（Chat / StreamChat / GenerateQuestion / StreamGenerateQuestion / OptimizeExpression / GenerateLessonPlan）。备课工作流的"查询状态/确认入库"用 HTTP 端点（`GET /ai/v1/lesson/preparation/{id}` + `POST .../confirm`）实现，避免 RPC 膨胀；如 coord 认为查询/确认也需 gRPC，则定为 8 RPC。请 coord 在 P5 启动前升级 ai.proto 到 v1 完整版。
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §12）

 ### ISSUE-04-ai12：events.proto 缺 AIUsageEvent message

@@ -72,7 +72,7 @@
 - **类型**：契约不明确 / 前置依赖缺失
 - **描述**：004 §12.2 + §15.3 #6 仲裁 ai 用量事件豁免 Outbox（派生数据），但 events.proto 现状仅有 ClassEvent / ExamEvent / HomeworkEvent / GradeEvent，**无 AIUsageEvent**。data-ana 消费方无 schema 可循。01/02 文档已提请（A3），matrix.md §4 已列事件名，但 proto 未落地。
 - **建议方案**：coord 在 events.proto 新增 `AIUsageEvent` message，建议 schema 见 02-architecture-design.md §3.3（含 event_id / user_id / school_id / provider / model / operation / prompt_tokens / completion_tokens / total_tokens / latency_ms / success / degraded / metadata）。与 ISSUE-02 一并裁决。
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §12）

 ### ISSUE-05-ai12：contracts/ai_contract.md 与设计文档多处矛盾（ai12 自查自纠清单）

@@ -96,7 +96,7 @@
 - **类型**：工作量超批 / 前置依赖缺失
 - **描述**：004 §2.3 列出 Temporal 用于"AI 编排"，属部分仲裁。ai12 在 02-architecture-design.md §8.3 建议：P5 用 FastAPI BackgroundTasks + Redis（24h TTL）实现 4 步备课工作流；P6 评估迁移 Temporal（支持长运行跨天审核 + 复杂状态机）。需 coord 在 P6 决策点确认是否引入，避免 P5 实现被推翻重做。
 - **建议方案**：P5 采用 BackgroundTasks + Redis（02-architecture-design.md §2.4 状态机已设计）；P6 由 coord 评估 Temporal 引入时机。请 coord 在 roadmap 标注 P6 决策点。
- **状态**：待 coord 仲裁（P6 决策点）
+- **状态**：已裁决（见 coord.md §12）

 ### ISSUE-07-ai12：iam GetEffectiveDataScope gRPC RPC 待 P4 补全

@@ -114,7 +114,7 @@
 - **类型**：契约不明确 / 架构约束
 - **描述**：project_rules §5 规定 proto 包名规范 `edu.<domain>.v1`（如 `edu.iam.v1`、`edu.core_edu.v1`）。但 ai.proto 现状 package 为 `next_edu_cloud.ai.v1`，events.proto 为 `next_edu_cloud.events.v1`，均不符合规范。01/02 文档未指出此偏离。此为全局 proto 命名问题（涉及全部 proto 文件），非 ai 独有，但 ai12 在审查中发现需提请。
 - **建议方案**：请 coord 裁定是否统一迁移 proto package 至 `edu.<domain>.v1`（全局变更，需 buf breaking 评估）；或保留现状作为历史包袱。ai12 在 ai.proto 补全 RPC 时遵循最终裁定。
- **状态**：待 coord 仲裁（全局 proto 命名）
+- **状态**：已裁决（见 coord.md §12）

 ### ISSUE-09-ai12：响应信封偏离 ActionState 强制整改（P0）

@@ -137,5 +137,5 @@
 - **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
 - **描述**：[详细描述问题]
 - **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
+- **状态**：已裁决（见 coord.md §X）
 -->
--- a/docs/architecture/issues/objections/api-gateway_issue.md
+++ b/docs/architecture/issues/objections/api-gateway_issue.md
@@ -62,7 +62,7 @@
 - **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
 - **描述**：[详细描述问题]
 - **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
+- **状态**：已裁决（见 coord.md §X）
 -->

 ### ISSUE-001-ai01：matrix.md gRPC 矩阵错误声明 api-gateway 消费 iam gRPC
@@ -74,7 +74,7 @@
 - **建议方案**：
  1. matrix.md §2 iam 行"消费方"列移除 `api-gateway`
  2. matrix.md §7 Mock 策略表中 api-gateway 行改为"硬编码 RS256 公钥（DEV_MODE）→ HTTP JWKS 端点"
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §24.3）

 ### ISSUE-002-ai01：shared-go 接入方式与时机

@@ -87,7 +87,7 @@
  2. go.work 增加 `./packages/shared-go`
  3. ai01 go.mod 增加 `github.com/edu-cloud/shared-go` 依赖
  4. P2.1 任务接入 jwks/logger/tracer/env
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §24.5）

 ### ISSUE-003-ai01：API 版本化路由方案（/v1 前缀位置）

@@ -99,7 +99,7 @@
  - 方案 B：Gateway 路由 `/api/v1/iam/*path`，proxy 透传 `/iam/*path`，下游 Controller 内加 `/v1`（前端调用 `/api/v1/iam/v1/auth/login`，Gateway 不含 `/v1`）
  - 方案 C：其他
 - **建议方案**：采纳方案 B（Gateway 路由不含服务级 `/v1`，由下游 Controller 添加），符合裁决第 4 条"避免双 v1"和第 3 条"Gateway 不改路径直接透传"
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §24.4）

 ### ISSUE-004-ai01：zap vs slog 选型

@@ -108,7 +108,7 @@
 - **类型**：契约不明确
 - **描述**：W3 裁决"首次实现即用 slog"，但 [shared-go/logger](../../../packages/shared-go/logger/logger.go) 的实现选型（zap 还是 slog）影响 ai01 接入方式。若 shared-go 用 zap，ai01 需通过 shared-go/logger 间接使用 zap；若 shared-go 用 slog，ai01 可直接用标准库 `log/slog` 或 shared-go 封装。需 coord 仲裁 shared-go/logger 最终选型。
 - **建议方案**：shared-go/logger 基于 `log/slog` 封装（标准库零依赖，W3 裁决原文即 slog），ai01 直接 import shared-go/logger
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §24.6）

 ### ISSUE-005-ai01：go.mod 与 Dockerfile Go 版本不一致

@@ -117,7 +117,7 @@
 - **类型**：其他
 - **描述**：[go.mod](../../../services/api-gateway/go.mod) L3 声明 `go 1.25.0`，[go.work](../../../go.work) L1 声明 `go 1.26.0`，但 [Dockerfile](../../../services/api-gateway/Dockerfile) L1 用 `golang:1.22-alpine`。三者不一致，可能导致构建环境与本地开发环境行为差异。
 - **建议方案**：统一为 `go 1.22`（与 Dockerfile 一致，与 [01-understanding.md](../../../services/api-gateway/docs/01-understanding.md) §4 声明一致），或升级 Dockerfile 到 `golang:1.25-alpine` 并同步 go.mod/go.work
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §24.7）

 ### ISSUE-007-ai01：01-understanding.md §6 审计表 metrics 行过时

@@ -126,7 +126,7 @@
 - **类型**：其他
 - **描述**：[01-understanding.md](../../../services/api-gateway/docs/01-understanding.md) §6 审计表 metrics 行标注 `❌ 无`，§7.1 issue #1 也说"无 `/metrics` 端点，Prometheus 404"。但实际 [main.go](../../../services/api-gateway/main.go) L56 已注册 `r.GET("/metrics", gin.WrapH(promhttp.Handler()))`，`/metrics` 端点已存在。文档过时，需更新为"⚠️ 端点已注册，但缺 7 个业务指标"。
 - **建议方案**：更新 01-understanding.md §6 审计表 metrics 行为 `⚠️ 端点已注册，缺业务指标`；§7.1 issue #1 更新为"已注册 /metrics，需补 7 个业务指标"
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §24.8）

 ### ISSUE-008-ai01：01-understanding.md §7.1 issue #3 死代码引用过时

@@ -135,7 +135,7 @@
 - **类型**：其他
 - **描述**：[01-understanding.md](../../../services/api-gateway/docs/01-understanding.md) §7.1 issue #3 引用"auth.go L124-139 死代码 `RequestIDMiddleware()` + `generateUUID()`"，但实际 [auth.go](../../../services/api-gateway/internal/middleware/auth.go) 当前仅 121 行，L124-139 不存在，死代码已删除。文档引用过时。
 - **建议方案**：删除 01-understanding.md §7.1 issue #3 整行（死代码已修复）
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §24.9）

 ### ISSUE-009-ai01：W1/W2 错误码 GW_ 前缀 + ActionState 信封未遵循

@@ -148,7 +148,7 @@
  - [circuit-breaker.go](../../../services/api-gateway/internal/middleware/circuit-breaker.go) L55-58 响应 `{"error":"circuit_open","retry_after":30}`（无 GW_ 前缀，无信封）
  - [recovery.go](../../../services/api-gateway/internal/middleware/recovery.go) L24-27 响应 `{"error":"internal_error","request_id":"..."}`（无 GW_ 前缀，无信封）
 - **建议方案**：P2.3 任务统一修复（见 [workline.md](../worklines/api-gateway_workline.md) P2.3），所有错误码改为 `GW_*`，所有响应体改为 `{success:false,error:{code:"GW_*",message:"..."},...}`
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §24.10）

 ---

--- a/docs/architecture/issues/objections/content_issue.md
+++ b/docs/architecture/issues/objections/content_issue.md
@@ -46,7 +46,7 @@ N1-N5 与 C2/C4/C10 共 8 项已有仲裁**全部在 02-architecture-design.md
  2. **knowledge-points 删除前置**：设计文档列 `DELETE /knowledge-points/:id/prerequisites/:prereqId`，源码未实现该端点
  3. **chapters 列表**：设计文档为 `GET /chapters?textbookId=`，源码实现为 `GET /chapters/textbook/:textbookId`
 - **建议方案**：以设计文档为目标态（query 参数 + 补 DELETE prerequisite 端点），在 P4 重构时统一对齐。但需 coord 确认是否允许 API 路径变更（影响 teacher-bff 消费方）。
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §5）

 ### ISSUE-002-ai09：content 发布事件 topic 命名策略与契约文档不一致

@@ -62,7 +62,7 @@ N1-N5 与 C2/C4/C10 共 8 项已有仲裁**全部在 02-architecture-design.md
  2. 减少 topic 数量（12 → 4），降低 Kafka 集群元数据压力
  3. 消费方按 action 字段过滤，订阅灵活性更高
  4. 需补 `KnowledgePointEvent` / `QuestionEvent` / `TextbookEvent` / `ChapterEvent` proto message
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §5）

 ### ISSUE-003-ai09：Textbook/Chapter 事件在契约文档遗漏

@@ -71,7 +71,7 @@ N1-N5 与 C2/C4/C10 共 8 项已有仲裁**全部在 02-architecture-design.md
 - **类型**：契约不明确
 - **描述**：02-architecture-design.md §5.1 列出 4 类 textbook 事件 + 1 类 chapter 事件，但 contracts/content_contract.md §1.4 仅列出 knowledge_point 与 question 两类事件，Textbook/Chapter 事件未登记。matrix.md §4 也仅列 kp + question。导致下游（data-ana）无法感知教材/章节变更。
 - **建议方案**：在 contract.md 与 matrix.md 补登记 `edu.content.textbook.events`（action: created/updated/published/archived）与 `edu.content.chapter.events`（action: created/updated/deleted）。若 coord 认为教材/章节无需对外发事件，则在 design doc §5.1 删除相关事件。
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §5）

 ### ISSUE-004-ai09：gRPC RPC 数量三方文档不一致

@@ -96,7 +96,7 @@ N1-N5 与 C2/C4/C10 共 8 项已有仲裁**全部在 02-architecture-design.md
  2. ChapterService 补 Update + Delete（design doc + contract 都缺 Delete，需补）
  3. QuestionService 补 PublishQuestion + SearchQuestions（与 contract 对齐）
  4. 最终 RPC 总数：TextbookService 5 + ChapterService 5 + KnowledgeGraphService 4 + QuestionService 7 = **21 RPC**（需同步更新 matrix.md §2 的 18 → 21）
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §5）

 ### ISSUE-005-ai09：core-edu → content 失效事件 topic 无定义

@@ -109,7 +109,7 @@ N1-N5 与 C2/C4/C10 共 8 项已有仲裁**全部在 02-architecture-design.md
  3. core-edu 设计文档（ai08）未明确发布该事件
  4. 01-understanding.md §5 也标注"具体 topic 待 core-edu ai03 设计确认"——此处 ai03 疑为笔误，core-edu 实际由 ai08 负责
 - **建议方案**：content 不主动消费 core-edu 失效事件（content 是上游内容提供方，core-edu 是消费方），删除 §5.2 中该条目；若确有联动需求，由 core-edu 主动调用 content gRPC UpdateQuestion 状态变更，而非事件驱动。
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §5）

 ### ISSUE-006-ai09：文档结尾"直接 push main"与项目规则冲突

@@ -121,7 +121,7 @@ N1-N5 与 C2/C4/C10 共 8 项已有仲裁**全部在 02-architecture-design.md
  - §14.3：AI 禁止 `git merge`、`git push origin main`
  - 当前 worktree 分支为 `feat-review-content-module-docs-WAIyMA`
 - **建议方案**：删除两份文档末尾"单仓库并行模式（直接 push main）"字样，改为 `Branch: feat-review-content-module-docs-WAIyMA（分支开发，提交后通知人类合并）`。
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §5）

 ### ISSUE-007-ai09：questions 表 created_by 字段迁移风险

@@ -130,7 +130,7 @@ N1-N5 与 C2/C4/C10 共 8 项已有仲裁**全部在 02-architecture-design.md
 - **类型**：其他
 - **描述**：02-architecture-design.md §3.1.4 questions 表新增 `created_by varchar(32) NOT NULL`，但现有 [questions.schema.ts](../../../services/content/src/questions/questions.schema.ts) 无该字段，且现有数据无 created_by 值。schema 迁移时 NOT NULL 约束会导致历史数据迁移失败。
 - **建议方案**：迁移期间先用 `created_by varchar(32) NULL`，数据回填后再加 NOT NULL 约束；或为新数据强制要求 created_by（应用层校验），历史数据用 `'system'` 默认值回填。
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §5）

 ### ISSUE-008-ai09：设计文档缺缓存策略与 API 版本化策略

@@ -143,7 +143,7 @@ N1-N5 与 C2/C4/C10 共 8 项已有仲裁**全部在 02-architecture-design.md
 - **建议方案**：
  1. P4 在 design doc §6 补"缓存策略"小节：教材树/章节树 Redis 缓存 + 失效策略（Outbox 事件触发缓存失效）
  2. P4 在 design doc §4 补"API 版本化"说明：REST 端点统一加 `/v1/` 前缀（gRPC 用 proto package version）
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §5）

 ### ISSUE-009-ai09：knowledge-points schema 实际缺 difficulty/metadata 字段

@@ -152,7 +152,7 @@ N1-N5 与 C2/C4/C10 共 8 项已有仲裁**全部在 02-architecture-design.md
 - **类型**：其他
 - **描述**：02-architecture-design.md §3.1.3 knowledge_points 表列出 `difficulty tinyint NOT NULL DEFAULT 3` 与 `metadata json NULL`，但实际 [textbooks.schema.ts](../../../services/content/src/textbooks/textbooks.schema.ts) 中 `knowledgePoints` 表仅含 id/chapterId/title/description 四个字段，无 difficulty 与 metadata。01-understanding.md C7 提到"时间戳缺失"但未提到 difficulty/metadata 缺失。
 - **建议方案**：P4 schema 迁移时一并补齐 difficulty + metadata + created_at + updated_at（与 design doc §3.1.3 对齐）。
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §5）

 ### ISSUE-010-ai09：Neo4j Sync Worker 与 ES Sync Worker 在 P4 阶段不必要

@@ -167,21 +167,21 @@ N1-N5 与 C2/C4/C10 共 8 项已有仲裁**全部在 02-architecture-design.md
  1. §1.1 图中明确标注 ES Sync Worker 为 P5 组件（虚线或灰显）
  2. §1.1 图中 Neo4j Sync Worker 的输入仅来自 content 自身 Outbox 事件（不消费 core-edu 事件）
  3. P4 任务 T6 明确"重构 knowledge-points.service.ts：移除 safeCreateNode 同步写，改为发 Outbox 事件"
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §5）

 ---

 ## §2 待 coord 仲裁项汇总

 | #   | 标题                                     | 阻塞性              | 状态   |
-| --- | ---------------------------------------- | ------------------- | ------------- |
-| 001 | REST 端点设计与实现不一致                | 🟡 P4 重构时对齐    | 待 coord 仲裁 |
-| 002 | 事件 topic 命名策略冲突（独立 vs 聚合）  | 🔴 阻塞 Outbox 实现 | 待 coord 仲裁 |
-| 003 | Textbook/Chapter 事件在契约文档遗漏      | 🟡 契约完整性       | 待 coord 仲裁 |
-| 004 | gRPC RPC 数量三方文档不一致              | 🔴 阻塞 proto 修改  | 待 coord 仲裁 |
-| 005 | core-edu → content 失效事件 topic 无定义 | 🟢 建议删除         | 待 coord 仲裁 |
-| 006 | "直接 push main"与项目规则冲突           | 🟡 文档修正         | 待 coord 仲裁 |
-| 007 | questions.created_by 迁移风险            | 🟡 schema 迁移      | 待 coord 仲裁 |
-| 008 | 缓存策略与 API 版本化策略缺失            | 🟢 长远架构         | 待 coord 仲裁 |
-| 009 | knowledge-points schema 实际缺字段       | 🟡 P4 schema 迁移   | 待 coord 仲裁 |
-| 010 | Sync Worker 链路与 P4 阶段不必要         | 🟡 设计澄清         | 待 coord 仲裁 |
+| --- | ---------------------------------------- | ------------------- | ------ |
+| 001 | REST 端点设计与实现不一致                | 🟡 P4 重构时对齐    | 已裁决 |
+| 002 | 事件 topic 命名策略冲突（独立 vs 聚合）  | 🔴 阻塞 Outbox 实现 | 已裁决 |
+| 003 | Textbook/Chapter 事件在契约文档遗漏      | 🟡 契约完整性       | 已裁决 |
+| 004 | gRPC RPC 数量三方文档不一致              | 🔴 阻塞 proto 修改  | 已裁决 |
+| 005 | core-edu → content 失效事件 topic 无定义 | 🟢 建议删除         | 已裁决 |
+| 006 | "直接 push main"与项目规则冲突           | 🟡 文档修正         | 已裁决 |
+| 007 | questions.created_by 迁移风险            | 🟡 schema 迁移      | 已裁决 |
+| 008 | 缓存策略与 API 版本化策略缺失            | 🟢 长远架构         | 已裁决 |
+| 009 | knowledge-points schema 实际缺字段       | 🟡 P4 schema 迁移   | 已裁决 |
+| 010 | Sync Worker 链路与 P4 阶段不必要         | 🟡 设计澄清         | 已裁决 |
--- a/docs/architecture/issues/objections/core-edu_issue.md
+++ b/docs/architecture/issues/objections/core-edu_issue.md
@@ -41,7 +41,7 @@
 - **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
 - **描述**：[详细描述问题]
 - **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
+- **状态**：已裁决（见 coord.md §X）
 -->

 ### ISSUE-001-ai08：core_edu.proto 实际状态与 coord 仲裁声称不一致（P0）
@@ -82,7 +82,7 @@
  coord 确认 `core_edu.proto` 补全工作的实际负责人（coord 自行补全，还是交由 ai08 在 P3 补全）。
  - 若 coord 已补全但未提交：请 coord 提交最新 proto
  - 若待 ai08 P3 补全：coord-cross-review.md L312 的 "✅ 已补全" 状态需更正为 "⏳ 待 ai08 P3 补全"，01-understanding.md L48 需补"ClassService 也缺失"
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §4）

 ---

@@ -122,7 +122,7 @@
     - 所有 Event message 新增 `string schema_version = N;` 字段
  2. coord 同步更新 matrix.md §4 为 `edu.teaching.*` 命名
  3. ai08 在 core-edu `outbox.publisher.ts` TOPIC_MAP 按 `edu.teaching.*` 命名实现
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §4）

 ---

@@ -151,7 +151,7 @@
  - **方案 A（推荐）**：core-edu DB status 统一为小写动词形式 `draft / published / in_progress / grading / graded / archived / cancelled`，GraphQL 枚举映射为大写 `DRAFT / PUBLISHED / IN_PROGRESS / GRADING / GRADED / ARCHIVED / CANCELLED`（去掉 `SCORED`，统一用 `GRADED`）。SubmissionStatus 统一为 `NOT_SUBMITTED / SUBMITTED / GRADED`，core-edu exam/homework submissions 初始状态统一为 `not_submitted`（不再用 `in_progress` 或 `draft`）。
  - **方案 B**：保留 coord GraphQL 现状（`SCORED`），core-edu 改 `graded` 为 `scored`。
    ai08 倾向方案 A（`graded` 是教育领域通用术语，`scored` 歧义大）。
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §4）

 ---

@@ -179,7 +179,7 @@
  - 若 classes 合并到 core-edu 后仍归"教学组织域"，则 topic 应为 `edu.teaching.class.transferred`（遵循 §3.1 仲裁的 `edu.teaching.<aggregate>.<action>` 风格）
  - 若归"组织域"，则为 `edu.org.class.transferred`（注意 action 应为 `transferred` 而非 `created`）
    ai08 倾向 `edu.teaching.class.transferred`（与 §3.1 仲裁风格一致，classes 合并到 core-edu 后属教学域）。
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §4）

 ---

@@ -207,7 +207,7 @@
  - matrix.md §2 改为 "27 RPC（P3 全量：ClassService 4 + ExamService 8 + HomeworkService 5 + GradeService 6 + AttendanceService 4）"
  - 就绪信号改为 "core-edu gRPC 50053 + 27 RPC + HealthService SERVING"
  - core-edu_contract.md §1.1 补全 P3 新增 RPC
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §4）

 ---

@@ -236,7 +236,7 @@
  - 决策 #4 schema 默认值与倾向不一致，仲裁前可能实现错
 - **建议方案**：
  coord 逐项仲裁，ai08 按倾向方案实现。决策 #4 若采 (b) 300 秒，02 文档 §3.1.2 schema 默认值改为 `.default(300)`。
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §4）

 ---

@@ -255,4 +255,4 @@

 - **建议方案**：
  coord 确认上述 3 项是否纳入 P3 验收标准；若纳入，ai08 在 P3 实施时补齐。
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §4）
--- a/docs/architecture/issues/objections/data-ana_issue.md
+++ b/docs/architecture/issues/objections/data-ana_issue.md
@@ -57,7 +57,7 @@ coord-cross-review.md §8.2 声称批次 0 已完成 proto 补全，ai11 逐文
 - **类型**：前置依赖缺失
 - **描述**：coord-cross-review.md §2.2 #3 已仲裁"iam P4 补全 `GetEffectiveDataScope` RPC，data-ana gRPC 调用"，但 iam.proto 当前仅 4 RPC，无此 RPC。data-ana 的 DataScope 6 级过滤（SELF/CLASS/GRADE/SCHOOL/DISTRICT/ALL）依赖此 RPC 解析用户可见数据范围，是 P4 实现的硬阻塞项。
 - **建议方案**：coord 确认 iam.proto 补全进度。若 iam 侧尚未实现，data-ana P4 阶段将使用硬编码 DataScope 降级（按 role 映射默认 scope），并标注 `details.degraded: true`，待 iam 就绪后切换。
- **状态**：待 coord 仲裁（核查已有仲裁 §0.2 #1 未落实）
+- **状态**：已裁决（见 coord.md §11）

 ---

@@ -68,7 +68,7 @@ coord-cross-review.md §8.2 声称批次 0 已完成 proto 补全，ai11 逐文
 - **类型**：前置依赖缺失
 - **描述**：coord-cross-review.md §3.2 已仲裁"补登 `edu.insight.ai.usage` topic + events.proto 补 `AIUsageEvent` message"，但 events.proto 当前仅 4 message（ClassEvent/ExamEvent/HomeworkEvent/GradeEvent），缺 AIUsageEvent。data-ana 需消费此事件落 `ai_usage_log` 宽表，供管理员仪表盘展示 AI 用量统计。
 - **建议方案**：coord 在 events.proto 补 `AIUsageEvent` message，字段建议：`{event_id, request_id, user_id, provider, model, prompt_tokens, completion_tokens, total_tokens, latency_ms, success, cost_cents, occurred_at}`。P5 前补全即可，P4 仪表盘 AI 用量区块显示"暂无数据"。
- **状态**：待 coord 仲裁（核查已有仲裁 §0.2 #3 未落实）
+- **状态**：已裁决（见 coord.md §11）

 ---

@@ -79,7 +79,7 @@ coord-cross-review.md §8.2 声称批次 0 已完成 proto 补全，ai11 逐文
 - **类型**：前置依赖缺失 + 声明与实际不符
 - **描述**：coord-cross-review.md §8.2 声称"analytics.proto 扩展 ✅ 12 RPC（含 Stream）"，但实际文件仅 3 RPC（GetClassPerformance/GetStudentWeakness/GetLearningTrend）。ai-allocation.md §5 与 matrix.md §2 均要求 data-ana 提供 12 RPC，02-architecture-design.md §4.2 已设计完整 12 RPC 清单（含 4 端 Dashboard + Warning + Mastery + Server Streaming），但 proto 未补全导致无法生成 stub。
 - **建议方案**：coord 确认 analytics.proto 扩展进度。ai11 可提供 12 RPC 的完整 message 定义提案（见 [02-architecture-design.md §4.2](../../../services/data-ana/docs/02-architecture-design.md)），coord 审议后合并到 analytics.proto。若 coord 未补全，ai11 在 P4 阶段自行补全 proto（本分支内），提请 coord 合并。
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §11）

 ---

@@ -97,7 +97,7 @@ coord-cross-review.md §8.2 声称批次 0 已完成 proto 补全，ai11 逐文
  这导致 01-understanding.md 和 02-architecture-design.md 中引用 004 §4.2/§11.4/§11.5/§15.3 等章节均断裂（004 正文仅到 §14，§15 在 004-p6-addendum.md 但内容不同）。ai11 已在 v2.1 修订中临时改为引用 coord-cross-review.md 对应裁决章节，但这是过渡方案。

 - **建议方案**：coord 按整改清单 #7/#8/#9/#10 补全 004 对应章节，使 004 成为可信的架构设计意图唯一源。各 AI 文档随后将引用从 coord-cross-review.md 回切到 004 对应章节。
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §11）

 ---

@@ -117,7 +117,7 @@ coord-cross-review.md §8.2 声称批次 0 已完成 proto 补全，ai11 逐文
  按 004 §7.2 命名规范 `edu.<domain>.<aggregate>.<action>`，data-ana 属于 D6 智能洞察领域（domain=insight），故 `edu.insight.mastery.updated` 符合规范。matrix.md 的 `edu.analytics.mastery` 不符合命名规范（缺 action 层级，且 domain 用了服务名而非领域名）。

 - **建议方案**：coord 裁决统一为 `edu.insight.mastery.updated` + `edu.insight.warning.triggered`，coord 修正 matrix.md §4。ai11 已在 contract.md 中采用此命名。
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §11）

 ---

@@ -128,4 +128,4 @@ coord-cross-review.md §8.2 声称批次 0 已完成 proto 补全，ai11 逐文
 - **类型**：其他（声明与实际不符）
 - **描述**：coord-cross-review.md §8.2 声称批次 0 已完成 iam.proto（12 RPC）/ analytics.proto（12 RPC）/ events.proto（9 message）补全，但 ai11 逐文件核查发现实际均未补全（详见 §0.3 核查表）。这影响所有依赖这些 proto 的下游 AI 的排期评估——若 AI 信任 §8.2 声明，会在排期中忽略 proto 补全的等待时间，导致排期失真。
 - **建议方案**：coord 核实 §8.2 声明真实性。若实际已补全但未合并到各 worktree 分支，请协调合并；若实际未补全，请更新 §8.2 状态为"计划中"或"待执行"，并明确补全时间点，以便下游 AI 据此排期。
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §11）
--- a/docs/architecture/issues/objections/iam_issue.md
+++ b/docs/architecture/issues/objections/iam_issue.md
@@ -58,7 +58,7 @@
  - 02 §4.1：API 路径无 /v1 前缀（违反 I7）
  - 01 §1：teacher-bff HTTP 调用 iam（违反 B2，应 gRPC）
 - **建议方案**：ai06 立即回写 01/02 文档，删除全部中间过渡方案描述，对齐 I1-I8 + §2.15/§2.16/§5.5 最终方案。
- **状态**：待 coord 仲裁（确认回写范围与验收标准）
+- **状态**：已裁决（见 coord.md §3）

 ### ISSUE-002-ai06：events.proto 缺少 UserEvent/RoleEvent/AuditEvent message

@@ -67,7 +67,7 @@
 - **类型**：前置依赖缺失
 - **描述**：coord-final-decisions §5.1 标注"events.proto ✅ 已补全（UserEvent/RoleEvent/NotificationEvent/MasteryEvent/AIUsageEvent/KnowledgePointEvent/QuestionEvent）"，president §5.5 也要求"events.proto 补 AuditEvent 在批次 0.10 完成"。但实际 [events.proto](../../../packages/shared-proto/proto/events.proto) 仅定义 ClassEvent/ExamEvent/HomeworkEvent/GradeEvent 4 个 message，**完全缺少** UserEvent/RoleEvent/AuditEvent 等 iam 依赖的事件契约。这直接阻塞 iam Outbox 事件发布（iam 无法写入未定义 schema 的事件）。
 - **建议方案**：coord 立即补全 events.proto，至少新增 UserEvent、RoleEvent、AuditEvent 三个 message（按 02 文档 §5.2 和 president §5.5 的字段定义）。
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §3）

 ### ISSUE-003-ai06：Topic 命名三方不一致（edu.identity.* vs edu.iam.*）

@@ -80,7 +80,7 @@
  - president §5.5：`edu.iam.audit.created`（用 `iam` 域名）
  - coord-final-decisions G16 规则：`edu.<domain>.<aggregate>.<action>`
 - **建议方案**：统一用 `edu.iam.*`（服务名为 iam，非 identity），coord 同步修正 004 §7.2 的 `edu.identity.*` → `edu.iam.*`。同时明确 Topic 粒度：matrix.md 用聚合 topic（`edu.iam.user.events` 含多 action），004 §7.2 用具体动作 topic（`edu.iam.user.created`），需统一为一种风格。
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §3）

 ### ISSUE-004-ai06：DataScope 枚举三方不一致

@@ -93,7 +93,7 @@
  - president §3.2 P2.2：ALL/SCHOOL/GRADE/CLASS/SUBJECT/SELF（**SUBJECT 替代 DISTRICT**）
  - 源码 [iam.schema.ts](../../../services/iam/src/iam/iam.schema.ts) 第 16-25 行：self/class/grade/school/district/all（与 004 表一致，与 president 不一致）
 - **建议方案**：coord 统一裁定最终枚举值。若采用 president 的 SUBJECT（学科级数据范围，K12 场景更实用），需同步修改源码 schema + 004 §5.3 表 + 02 文档；若保留 DISTRICT，需修正 president §3.2。同时修正 004 行 505 的语义命名使其与枚举表一致。
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §3）

 ### ISSUE-005-ai06：iam.proto 仅 4 RPC，未补全至 12 RPC

@@ -102,7 +102,7 @@
 - **类型**：前置依赖缺失
 - **描述**：coord-final-decisions §5.1 要求 iam.proto 在"P2 启动前"补全 8 个新 RPC（GetViewports / GetEffectivePermissions / GetEffectiveAccess / Logout / GetPublicKey / BatchGetUsers / GetEffectiveDataScope / GetChildrenByParent），president §6 批次 0 任务 0.3 也明确"coord 补全 iam.proto 8 RPC"。但实际 [iam.proto](../../../packages/shared-proto/proto/iam.proto) 仍仅 4 RPC（Register/Login/RefreshToken/GetUserInfo），未补全。这阻塞 iam P2.1 的 8 RPC 实现（proto 是契约先行前提）。
 - **建议方案**：coord 立即补全 iam.proto 至 12 RPC（含对应 message 定义），对齐 [iam_contract.md §1.1](../contracts/iam_contract.md) 的 12 RPC 清单。
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §3）

 ### ISSUE-006-ai06：01/02 文档 AI 身份署名错误

@@ -111,7 +111,7 @@
 - **类型**：其他
 - **描述**：[01-understanding.md](../../../services/iam/docs/01-understanding.md) 和 [02-architecture-design.md](../../../services/iam/docs/02-architecture-design.md) 署名"AI：ai02（TS / 身份认证）"、"AI Agent: ai02 (iam-module)"。但 coord-final-decisions §3.1、president §3.2、[matrix.md](../matrix.md)、[workline.md](../workline.md)、[iam_workline.md](../worklines/iam_workline.md)、[iam_contract.md](../contracts/iam_contract.md) 全部指明 iam 由 **ai06** 负责。ai02 实际负责 push-gateway（coord-final-decisions §3.7）。文档署名错误会导致多 AI 协作时身份混淆。
 - **建议方案**：回写时将 01/02 文档署名从 ai02 改为 ai06。
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §3）

 ### ISSUE-007-ai06：contract.md §1.2 与双入口策略冲突

@@ -120,7 +120,7 @@
 - **类型**：契约不明确
 - **描述**：[iam_contract.md §1.2](../contracts/iam_contract.md) 写"无对外 HTTP 端点，仅 gRPC"。但 president §2.16 裁决双入口策略：REST 供 gateway 透传 + gRPC 供 BFF 聚合调用，"gateway 保持 HTTP 透传"。若 iam 不暴露 HTTP 端点，gateway 无法透传（gateway 不改为 gRPC 客户端）。
 - **建议方案**：修正 contract.md §1.2，补充 REST 端点清单（/iam/v1/* 系列），标明"REST 供 gateway 透传 + admin-portal 直连，gRPC 供 BFF 聚合调用"。
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §3）

 ---

@@ -136,7 +136,7 @@
 - **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
 - **描述**：[详细描述问题]
 - **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
+- **状态**：已裁决（见 coord.md §X）
 -->

 见上方 §2 新提请异议（ISSUE-001 ~ ISSUE-007）。
--- a/docs/architecture/issues/objections/msg_issue.md
+++ b/docs/architecture/issues/objections/msg_issue.md
@@ -73,7 +73,7 @@
  - `GradeEvent` L50-59 **无** `class_id`（仅有 `student_id`）❌
  - 三者均**无** `student_ids[]`（复数，用于 fan-out 广播）❌
 - **建议方案**：修正 P9 表述为"`GradeEvent` 需补 `class_id`；全部事件需补 `student_ids[]` 字段（msg fan-out 广播通知需要）"
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §10）

 ### ISSUE-007-ai10：proto 包名规则冲突（project_rules vs 实际）

@@ -84,7 +84,7 @@
 - **建议方案**：coord 统一裁决，二选一：
  - 方案 A：更新 project_rules §5 为 `next_edu_cloud.<domain>.v1`（与实际 proto 一致）
  - 方案 B：重命名所有 proto package 为 `edu.<domain>.v1`（与规则一致，但改动大）
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §10）

 ### ISSUE-008-ai10：Kafka topic 命名三套约定并存

@@ -100,7 +100,7 @@
  - 004 §7.2 已采用，是架构设计意图唯一源
  - per-event topic 便于消费者按需订阅，避免反序列化无关事件
  - 与 NotificationSent / NotificationRead 等事件命名（PascalCase）对齐
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §10）

 ### ISSUE-009-ai10：RPC 数量超预算（17 vs 13）

@@ -115,7 +115,7 @@
 - **建议方案**：coord 裁决 RPC 范围，二选一：
  - 方案 A：维持 13 RPC 预算，02-architecture-design.md 裁剪至 13（移除 BatchSendNotification / GetUnreadCount / BatchMarkAsRead / MarkAllAsRead / UpdateTemplate / DeleteTemplate，降级为 REST only 或合并）
  - 方案 B：放宽至 17 RPC，同步更新 ai-allocation.md + matrix.md + msg_contract.md
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §10）

 ### ISSUE-010-ai10：markAsRead 权限点与设计不一致

@@ -140,7 +140,7 @@
  - ES 故障 → DB LIKE 查询（设计文档已覆盖）
  - DB 故障 → ES 只读模式（ai-allocation 要求，设计文档需补充）
  - 但 DB 故障时写操作无法降级（必须等 DB 恢复），仅读操作可走 ES
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §10）

 ### ISSUE-012-ai10：设计文档缺 DLQ 与三层幂等防线

@@ -167,7 +167,7 @@
  - `MasteryEvent`（data-ana 发布 mastery.updated）— 阻塞学情预警通知
  - `NotificationEvent`（msg 发布 notification.sent/read/recalled/failed）— 阻塞 push-gateway 消费 msg 事件
 - **建议方案**：coord 维护 shared-proto，在 P5 启动前补齐这 4 个 message。msg 在 proto 补齐前用通用 JSON payload 解析（A6 假设）
- **状态**：待 coord 仲裁（🔴 阻塞 P5 消费链路）
+- **状态**：已裁决（见 coord.md §10）

 ### ISSUE-014-ai10：msg_contract.md 与 02-architecture-design.md RPC 清单不一致

@@ -179,7 +179,7 @@
  - 02-architecture-design.md 独有（contract 缺）：BatchSendNotification、GetUnreadCount、BatchMarkAsRead、MarkAllAsRead、UpdateTemplate、DeleteTemplate
  - 即使忽略 ISSUE-009 的数量问题，两文档的 RPC 组合也不同
 - **建议方案**：待 ISSUE-009 仲裁后，统一两文档 RPC 清单
- **状态**：待 coord 仲裁（依赖 ISSUE-009）
+- **状态**：已裁决（见 coord.md §10）

 ### ISSUE-015-ai10：msg_contract.md Kafka 发布事件与设计文档不一致

@@ -191,4 +191,4 @@
  - 02-architecture-design.md §5.2：4 个 per-event topic（`edu.notification.sent` / `edu.notification.read` / `edu.notification.recalled` / `edu.notification.failed`）
  - matrix.md §4 L118：`edu.notification.requested`（第三种命名）
 - **建议方案**：待 ISSUE-008 仲裁 topic 命名约定后统一
- **状态**：待 coord 仲裁（依赖 ISSUE-008）
+- **状态**：已裁决（见 coord.md §10）
--- a/docs/architecture/issues/objections/parent-bff_issue.md
+++ b/docs/architecture/issues/objections/parent-bff_issue.md
@@ -37,7 +37,7 @@
  - U4（BFF 豁免 @RequirePermission）：01 §6 表格"权限装饰器"行标"⚠️ 不对齐"，未引用 U4 仲裁
  - C1（错误码前缀 BFF_PARENT_）：01 §3.3 仍用 `PARENT_BFF_` 旧前缀
 - **建议方案**：01-understanding.md 头部更新为 ai05 复审版，同步 U3/U4/C1 仲裁结论；或由 coord 确认 01 作为"阶段 1 历史快照"保留原样，以 02 为准
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §20）

 ### ISSUE-002-ai05：02 文档内部 ChildGuard 缓存 TTL 不一致

@@ -50,7 +50,7 @@
  - §13 #7 黄金模板对齐表：写 "30s"
    §3.1.1 表格未同步 §9 的调整，导致同一文档内 60s 与 30s 并存。
 - **建议方案**：§3.1.1 表格 ChildGuard 行 TTL 改为 "30s"，与 §9 #2 + §13 #7 一致
- **状态**：待 coord 仲裁（ai05 建议直接修正，属于文档勘误）
+- **状态**：已裁决（见 coord.md §20）

 ### ISSUE-003-ai05：contract.md 仲裁引用编号错误（I3 → I6）

@@ -62,7 +62,7 @@
  - I6 才是 "家长-学生关联：P2 即补全 iam_student_guardians 表 + GetChildrenByParent RPC" 裁决
  - 全仓库未检索到 "ISSUE-047" 编号（grep 无结果），疑为虚构编号
 - **建议方案**：contract.md 将 "I3/ISSUE-047 裁决" 修正为 "I6 裁决（coord-final-decisions.md §1）"
- **状态**：待 coord 仲裁（ai05 建议直接修正，属于引用勘误）
+- **状态**：已裁决（见 coord.md §20）

 ### ISSUE-004-ai05：004 §4 服务依赖图与 matrix.md §1 未同步 C6 仲裁

@@ -75,7 +75,7 @@
  - 02 §0.1 C6 行已标注 "004 §4 待 coord 同步更新"，但至今未同步
    此差异导致新接手的 AI 看 004/matrix 会误以为 parent-bff 不依赖 data-ana/msg，与 02 设计冲突。
 - **建议方案**：coord 在 004 §4 服务依赖图补 `PBFF --> DataAna` + `PBFF --> Msg`，matrix.md §1 同步；更新 004 时按 project_rules §1 "改码必同步图" 执行
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §20）

 ### ISSUE-005-ai05：parent-portal 01 文档与 parent-bff GraphQL 决策跨模块冲突

@@ -89,7 +89,7 @@
  - parent-portal §3.1 标 "BFF 对接：parent-bff（ai04 设计）"，ai04 已过时（现 ai05）
    此冲突若不解决，parent-portal（ai15）会按 REST 实现 frontend client，与 parent-bff GraphQL 端点不兼容。
 - **建议方案**：coord 协调 ai15 将 parent-portal 01/02 文档的 parent-bff 消费契约从 REST 改为 GraphQL（`POST /api/v1/parent/graphql`），同步 C4 iam 路径仲裁；此属跨模块契约，按 project_rules §14.4 跨模块变更顺序处理
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §20）

 ### ISSUE-006-ai05：proto 包名引用不一致（缺失 next_edu_cloud 前缀）

@@ -103,7 +103,7 @@
  - msg.proto: `package next_edu_cloud.msg.v1;`
    引用不一致会导致 gRPC client 代码生成时 package 路径错误。
 - **建议方案**：02 §3.3 DTO 映射表 proto message 列全部补 `next_edu_cloud.` 前缀；或确认是否统一去掉前缀（需 buf.yaml 配置一致）
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §20）

 ### ISSUE-007-ai05：GraphQL Notification.childId 字段在 msg.proto 缺失

@@ -125,7 +125,7 @@
  ```
  parent-bff 无法从 msg 服务获取通知关联的孩子 ID，影响"按孩子过滤通知"场景。
 - **建议方案**：coord 协调 ai10 在 msg.proto Notification message 补 `string child_id = 9;` 字段（可选，非家长通知为空）；或 parent-bff 从 notification.content 解析（脆弱，不推荐）
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §20）

 ### ISSUE-008-ai05：core_edu.proto 缺 ClassService，02 §7.1 列为已有

@@ -138,7 +138,7 @@
  1. coord 确认 ClassService 归属（core-edu 还是 classes 服务），补 proto
  2. 02 §7.1 ClassService.GetClass 状态从 "✅ 已有" 改为 "❌ 待补"
  3. 02 §3.3 补 Grade.score string→Float 转换规则说明
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §20）

 ### ISSUE-009-ai05：ai-allocation iam 责任方与 01/02 文档不一致

@@ -147,7 +147,7 @@
 - **类型**：责任方引用过时
 - **描述**：01-understanding.md §7.1/§7.3 多处提"推动 ai02 在 iam 补接口"，02 §8.1 P0 阻塞项 + §14.1 P0-1 也标 iam 责任方为 "ai06（iam 现归属）" 但 §7.3 #1 仍标 ai02。实际 ai-allocation.md §3.2 确认 iam 归属 ai06。01 文档未同步。
 - **建议方案**：01 §7.1/§7.3 将 "ai02" 改为 "ai06"；02 §7.3 #1 同步
- **状态**：待 coord 仲裁（ai05 建议直接修正，属于引用勘误）
+- **状态**：已裁决（见 coord.md §20）

 ### ISSUE-010-ai05：02 缺少 ADR / NFR / 容量规划 / 威胁建模（业界规范差距）

@@ -161,7 +161,7 @@
  4. **安全威胁建模缺失**：§6.2 列错误码但未做威胁建模（STRIDE）。家长场景涉及未成年人数据（COPPA/FERPA/PIPL），应补威胁模型。
  5. **数据流图（DFD）缺失**：§1.2 只有 Dashboard 时序图，缺少 DFD 展示数据跨信任边界流动。
 - **建议方案**：coord 确认是否在 02 补全上述章节，或作为 P6 硬化阶段补全；当前不阻塞 P4 实施
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §20）

 ---

@@ -175,5 +175,5 @@
 - **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
 - **描述**：[详细描述问题]
 - **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
+- **状态**：已裁决（见 coord.md §X）
 -->
--- a/docs/architecture/issues/objections/parent-portal_issue.md
+++ b/docs/architecture/issues/objections/parent-portal_issue.md
@@ -45,7 +45,7 @@
 - **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
 - **描述**：[详细描述问题]
 - **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
+- **状态**：已裁决（见 coord.md §X）
 -->

 ### ISSUE-001-ai15：01/02 文档 REST 消费 parent-bff 与 ARB-001 GraphQL 裁决冲突
@@ -63,7 +63,7 @@
  1. coord 确认 parent-portal 消费 parent-bff **统一用 GraphQL**（与 ARB-001、parent-bff contract、matrix.md 一致）
  2. ai15 据此修订 01 §3.1（改为 GraphQL Query/Mutation 域）、§3.1.1（X-Fields 字段裁剪改为 GraphQL query 字段选择）、02 §4.1（`useParentApi` 改为 GraphQL hooks）、§4.2（TanStack Query 约定配合 GraphQL operations）、§11.3 未决设计决策 #2（移除，已裁决）
  3. 若 coord 另有裁决（如 parent-portal 特殊走 REST），以 coord 裁决为准
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §22）

 ### ISSUE-002-ai15：MF shared 配置缺 urql/graphql/@edu/* 与 ARB-002 冲突

@@ -80,7 +80,7 @@
  1. coord 确认 parent-portal MF `shared` 必须包含 ARB-002 全部 7 项（react/react-dom/urql/graphql/@edu/ui-tokens/@edu/ui-components/@edu/hooks）
  2. ai15 修订 02 §1.2 `shared` 配置 + 01 §4 技术栈表（新增 urql + GraphQL client 行）
  3. 02 §4.1 `useParentApi` 改为从 Shell 暴露的 `useGraphQLClient()` 获取 urql client，不再用 REST ApiClient
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §22）

 ### ISSUE-003-ai15：switch-child 端点在 01/02 文档间不一致

@@ -96,7 +96,7 @@
  1. 若走 GraphQL（依 ISSUE-001 裁决）：switch-child 应为 `mutation switchChild(childId: ID!): SwitchChildPayload!`，不存在 REST 路径
  2. 若走 REST：统一为 `POST /api/v1/parent/switch-child`（body 携带 childId，与 02 一致），修订 01 §3.1
  3. 请 coord 一并明确 parent-bff GraphQL schema 是否包含 `switchChild` Mutation（当前 parent-bff contract.md 未列）
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §22）

 ### ISSUE-004-ai15：登录端点在 01 / contract.md / matrix.md 间三方不一致

@@ -112,7 +112,7 @@
  1. 统一为 `POST /api/v1/iam/login`（与 matrix.md §5 + 01 §3.1 的 `/api/v1/iam/*` 前缀一致）
  2. ai15 修订 contract.md §2.3 路径
  3. 注意：登录是 parent-portal 唯一可能走 REST（非 GraphQL）的端点，因登录前无 JWT，GraphQL endpoint 需鉴权。请 coord 确认登录是否走 REST `/api/v1/iam/login`，其余走 GraphQL
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §22）

 ### ISSUE-005-ai15：02 §11.3 未决设计决策 #2 "GraphQL vs REST" 已由 ARB-001 裁决，应移除

@@ -126,7 +126,7 @@
 - **建议方案**：
  1. coord 确认 ARB-001 适用于 parent-portal（即 parent-portal P4 起必须用 GraphQL 消费 parent-bff）
  2. ai15 移除 02 §11.3 第 2 项，改为 "已裁决：见 ARB-001，parent-portal 用 GraphQL 消费 parent-bff"
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §22）

 ### ISSUE-006-ai15：contract.md §1.2 将前端页面路由误标为 HTTP 端点

@@ -142,7 +142,7 @@
  1. coord 确认 parent-portal 作为前端 Remote，不对外提供 HTTP API 端点（§1.2 应为"无"）
  2. ai15 将 contract.md §1.2 改为 "无（parent-portal 是前端 Remote，不对外提供 HTTP API）"，页面路由信息保留在 01 §8 L2 路由表中，不进 contract.md
  3. 若需保留 MF 暴露信息，归入 §1.6 微前端架构（已有）
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §22）

 ### ISSUE-007-ai15：contract.md §1.6 module-federation.config.ts 与 02 next.config.js 不一致

@@ -156,7 +156,7 @@
 - **建议方案**：
  1. 统一为 `apps/parent-portal/next.config.js`（与 02 + teacher-portal Shell 一致，Next.js 项目 MF 配置应在 next.config.js）
  2. ai15 修订 contract.md §1.6
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §22）

 ### ISSUE-008-ai15：contract.md §2.3 GraphQL 路径前缀与 matrix.md 不一致

@@ -170,7 +170,7 @@
 - **建议方案**：
  1. 统一为 `POST /api/v1/parent/graphql`（与 matrix.md §5 一致）
  2. ai15 修订 contract.md §2.3 + §2.4
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §22）

 ### ISSUE-009-ai15：parent-bff GraphQL schema 是否包含 switchChild Mutation 未明确

@@ -186,7 +186,7 @@
  1. 请 coord 协调 ai05（parent-bff）确认：switchChild 是 GraphQL Mutation 还是纯前端状态（localStorage + Zustand）
  2. 若纯前端：01/02 移除 `POST /parent/switch-child` 调用，改为 `useChildSwitcher` 直接写 Zustand + localStorage
  3. 若需后端记录：请 ai05 在 parent-bff contract.md §1.3 补充 `switchChild` Mutation
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §22）

 ### ISSUE-010-ai15：iam GetChildrenByParent 接口缺失（P0 阻塞，跨模块）

@@ -202,7 +202,7 @@
 - **建议方案**：
  1. coord 确认 ai06 补全 `GetChildrenByParent` 的时间点（应在 P4 启动前）
  2. 在补全前，parent-portal 用 mock（固定 2 个子女）开发，mock 数据与 parent-bff mock 一致（student-001 + student-002）
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §22）

 ---

--- a/docs/architecture/issues/objections/push-gateway_issue.md
+++ b/docs/architecture/issues/objections/push-gateway_issue.md
@@ -49,7 +49,7 @@
  2. SSE 单向下行 + 文本协议，不适合未来 reconnect/ack 双向协议
  3. 各 portal 已规划 WebSocket 接入（[coord-cross-review.md](../../coord-cross-review.md)）
 - **影响方**：ai13/ai14/ai15（前端需统一走 WebSocket，移除 SSE 兜底）、ai10（msg 不需调 /sse）、coord（更新 matrix.md §5 与 contract.md）
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §17）

 ### ISSUE-002-ai02：内部 API 鉴权命名三方不一致

@@ -67,7 +67,7 @@
  2. "Token"语义比"Key"更准确（共享密钥而非公私钥对）
  3. mTLS 在 P5 阶段引入成本过高，且 K8s 内网已有 NetworkPolicy 隔离，共享密钥足够
 - **影响方**：ai10（msg 调用方需用相同头名）、coord（更新 contract.md 与 matrix.md §5 移除 mTLS）
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §17）

 ### ISSUE-003-ai02：单节点容量目标 50k vs 10w+ 冲突

@@ -83,7 +83,7 @@
  2. Go goroutine-per-connection + 64KB send chan 单连接约 20-30KB，10w 连接约 2-3GB，单节点可承载
  3. 50k 目标过于保守，与横向扩展方案不匹配
 - **影响方**：coord（更新 modules/README.md §7）、ai02（02 §11 已正确）
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §17）

 ### ISSUE-004-ai02：contract.md 内部端点路径 /internal/send vs /internal/push 冲突

@@ -112,7 +112,7 @@
  3. ai-allocation 表述过度，审计需求由 msg 满足
 - **建议方案**：方案 2（审计由 msg 维护，push-gateway 仅同步返结果）。理由：保持 push-gateway 无 DB 定位，避免引入持久化层增加运维复杂度。
 - **影响方**：ai10（msg 需确认审计字段是否覆盖 push-gateway 推送结果）、coord（澄清 ai-allocation §5 表述）
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §17）

 ### ISSUE-006-ai02：ISSUE-058 与 ISSUE-055 对 Redis /readyz 失败策略耦合冲突

@@ -128,7 +128,7 @@
  2. Redis 故障时单实例仍能服务本地连接（仅跨实例广播失效）
  3. 雪崩风险高于短暂不一致
 - **影响方**：coord（澄清两裁决优先级）
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §17）

 ### ISSUE-007-ai02：02 文档缺 ADR / 非功能性需求 / 失败模式章节（不符业界架构文档规范）

--- a/docs/architecture/issues/objections/student-bff_issue.md
+++ b/docs/architecture/issues/objections/student-bff_issue.md
@@ -56,7 +56,7 @@
  - **不存在 §11.4 和 §11.5**
 - **影响**：错误码前缀 BFF_STUDENT_ 的权威来源应改为 [coord-final-decisions.md](../../coord-final-decisions.md) G14 + B5；ActionState 信封规范应改为 [coord-final-decisions.md](../../coord-final-decisions.md) G8 + F9
 - **建议方案**：02 文档回写时修正引用源；coord 确认是否需要在 004 补充 §11.4/§11.5 章节，或统一指向 coord-final-decisions
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §19）

 ### ISSUE-STU-003-ai04：02 文档 §8.3 列 12 项未决决策，其中 8 项已裁决

--- a/docs/architecture/issues/objections/student-portal_issue.md
+++ b/docs/architecture/issues/objections/student-portal_issue.md
@@ -70,7 +70,7 @@
  - 统一为 `POST /api/v1/student/graphql`
  - 由 ai01（api-gateway）确认路由：`/api/v1/student/*` → `student-bff:3009/*`（即 `/api/v1/student/graphql` → `student-bff:3009/graphql`）
  - 由 ai04（student-bff）确认 GraphQL endpoint 路径为 `POST /graphql`（与 teacher-bff 一致）
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §21）

 ---

@@ -88,7 +88,7 @@
  - 统一为 `packages/shared-ts/contracts/graphql/student-bff.graphql`（与 ARB-001 原则对齐，集中管理便于前端 codegen）
  - ai14 在 student-portal 端使用 `graphql-codegen` 从该 schema 生成 TypeScript 类型
  - 由 ai04（student-bff）创建该 schema 文件并维护
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §21）

 ---

@@ -109,7 +109,7 @@
  - **离开页面策略**：visibilitychange hidden 触发时仅记录（不自动提交），累计 3 次警告后教师端可见
  - **多标签检测**：警告 + 记录，不阻止作答（避免误伤合法场景如查词典）
  - **防作弊事件上报**：走 student-bff GraphQL mutation `recordExamViolation(examId, type, payload)`，由 ai04 在 P3 提供
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §21）

 ---

@@ -127,7 +127,7 @@
  - **主观题（简答/论述）**：允许粘贴，但记录粘贴事件 + 粘贴内容长度，教师端批改时可见
  - **作文题**：允许粘贴（学生体验优先），不记录
  - 由 ai04（student-bff）在 P3 提供 `recordPasteEvent` mutation（或复用 ISSUE-014-03 的 `recordExamViolation`，type=`PASTE`）
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §21）

 ---

@@ -147,7 +147,7 @@
  - **推荐 A**：走 api-gateway REST `POST /api/v1/student/upload` → 对象存储（MinIO/OSS），返回 signed URL，再走 GraphQL `submitHomework(attachmentUrls: [String!])` mutation 提交
  - 理由：GraphQL 不适合大文件传输；REST + 对象存储是业界通用方案；api-gateway 已有 JWT 鉴权
  - 由 ai01（api-gateway）确认是否提供 `/api/v1/student/upload` 路由，由 ai04（student-bff）确认 `submitHomework` mutation 是否接受 `attachmentUrls` 字段
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §21）

 ---

@@ -167,7 +167,7 @@
  - **题目重排**：P3 不实现（题目顺序固定），P4 评估是否需要实时重排
  - **考试强制提交**：ai08 发布 `ExamForceSubmitted` 事件，student-portal 收到后立即触发提交流程
  - 由 ai08（core-edu）确认事件命名，由 ai10（msg）确认推送路径
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §21）

 ---

@@ -186,21 +186,21 @@
  - **统一为方案 A**：student-bff 在 Resolver 层从 JWT `x-user-id` 提取 studentId，强制过滤，前端 query 不传 `studentId` 参数
  - ai14 修改 02-architecture-design.md §4.2 的 GraphQL query 定义，移除 `studentId` 参数（如 `myClasses` 改为无参 query）
  - 由 ai04（student-bff）确认所有学生端 Query 均从 JWT 提取 studentId，不接受前端传入
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §21）

 ---

 ## §3 异议状态汇总

 | 编号         | 类型       | 标题                                                   | 状态   |
-| ------------ | ---------- | ------------------------------------------------------ | ------------- |
-| ISSUE-014-01 | 契约不明确 | GraphQL endpoint 路径不一致                            | 待 coord 仲裁 |
-| ISSUE-014-02 | 契约不明确 | student-bff GraphQL schema 存放位置不一致              | 待 coord 仲裁 |
-| ISSUE-014-03 | 契约不明确 | 考试作答页全屏策略与防作弊检测边界                     | 待 coord 仲裁 |
-| ISSUE-014-04 | 契约不明确 | 主观题粘贴策略（防作弊 vs 学生体验）                   | 待 coord 仲裁 |
-| ISSUE-014-05 | 契约不明确 | 作业附件上传协议（GraphQL mutation vs REST multipart） | 待 coord 仲裁 |
-| ISSUE-014-06 | 契约不明确 | 考试延长/题目重排等实时事件命名未确认                  | 待 coord 仲裁 |
-| ISSUE-014-07 | 契约不明确 | 学生端 DataScope L0 边界的强制执行层                   | 待 coord 仲裁 |
+| ------------ | ---------- | ------------------------------------------------------ | ------ |
+| ISSUE-014-01 | 契约不明确 | GraphQL endpoint 路径不一致                            | 已裁决 |
+| ISSUE-014-02 | 契约不明确 | student-bff GraphQL schema 存放位置不一致              | 已裁决 |
+| ISSUE-014-03 | 契约不明确 | 考试作答页全屏策略与防作弊检测边界                     | 已裁决 |
+| ISSUE-014-04 | 契约不明确 | 主观题粘贴策略（防作弊 vs 学生体验）                   | 已裁决 |
+| ISSUE-014-05 | 契约不明确 | 作业附件上传协议（GraphQL mutation vs REST multipart） | 已裁决 |
+| ISSUE-014-06 | 契约不明确 | 考试延长/题目重排等实时事件命名未确认                  | 已裁决 |
+| ISSUE-014-07 | 契约不明确 | 学生端 DataScope L0 边界的强制执行层                   | 已裁决 |

 ---

@@ -214,5 +214,5 @@
 - **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
 - **描述**：[详细描述问题]
 - **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
+- **状态**：已裁决（见 coord.md §X）
 -->
--- a/docs/architecture/issues/objections/teacher-bff_issue.md
+++ b/docs/architecture/issues/objections/teacher-bff_issue.md
@@ -18,7 +18,7 @@
 - **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
 - **描述**：[详细描述问题]
 - **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
+- **状态**：已裁决（见 coord.md §X）
 -->

 ### ISSUE-001-ai03：admin 命名空间 P2 预留与 ARB-001 "P2 不包含" 冲突
@@ -28,7 +28,7 @@
 - **类型**：契约不明确
 - **描述**：coord.md ARB-001 §1.3 关键裁决表写 "admin 命名空间 | **P2 不包含**，P6 admin-portal 阶段新增 `admin` 命名空间"；但 president-final-rulings.md §5.1（ISSUE-044）裁决 "ai03 P2 预留 admin schema 命名空间（如 `admin.*` Query/Mutation）"，且 §7.3 ai03 工作清单明确 "批次 1（P2）：Must Have 13 项 + DownstreamClient 抽象 + admin schema 命名空间预留"。两处对 P2 admin 命名空间的要求不一致——总裁裁决要求 P2 预留（schema 中声明占位），coord 仲裁说 P2 不包含。
 - **建议方案**：以总裁裁决为准（裁决优先级 president > coord），修正 ARB-001 §1.3 为 "P2 预留 admin 命名空间占位（schema 中声明 `admin` Query/Mutation 类型骨架，无实际 Resolver），P6 admin-portal 阶段实现具体 Resolver"。ai03 在 P2 schema 第一版中预留 `admin` 命名空间类型声明。
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §18）

 ### ISSUE-002-ai03：P2 dashboard classes 数据来源与 ARB-001 §1.4 调用链冲突

@@ -40,7 +40,7 @@
  2. **B2 裁决约束**：coord-final-decisions.md B2 裁决 "首次实现即 gRPC 调用下游"，若 classes P2 无 gRPC，teacher-bff 不能用 REST 调 classes（B2 禁止 REST 过渡）。
  3. **president §3.5 功能范围**：president-final-rulings.md §3.5 裁决 P2 实现 "班级列表（iam 数据）"，即 P2 班级列表数据来自 iam，不是 classes 服务。
 - **建议方案**：采纳 president §3.5，P2 dashboard 的 classes 数据从 iam gRPC 获取（iam `GetEffectiveAccess` 或 `GetViewports` 返回的关联班级），不调 classes 服务。ARB-001 §1.4 第 4 条修正为 "dashboard Resolver 并行调用 iam gRPC（GetUserInfo + GetViewports + GetEffectiveAccess），classes 列表从 iam 返回数据推导，P3 core-edu gRPC 就绪后切换为 `GetClassesByTeacher` RPC"。这样 P2 不依赖 classes gRPC，与 B2 + president §3.5 一致。
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §18）

 ### ISSUE-003-ai03：GraphQL schema 文件命名不一致（ARB-001 vs president §2.17）

@@ -54,6 +54,6 @@
  ai03 创建文件时无法确定用哪个文件名。

 - **建议方案**：以 president §2.17 为准（裁决优先级 president > coord），统一为 `teacher-bff.schema.graphql`。coord 修正 ARB-001 §1.3/§1.4 文件名。
- **状态**：待 coord 仲裁
+- **状态**：已裁决（见 coord.md §18）

 ---
--- a/docs/architecture/roadmap/integration-test-phase.md
+++ b/docs/architecture/roadmap/integration-test-phase.md
@@ -0,0 +1,160 @@
+# 集成测试与部署验证阶段（P7）
+
+> 日期：2026-07-10
+> 前置条件：所有模块 P2-P6 代码完成，lint/typecheck/go vet/ruff 全通过，ARB-001~022 全部已裁决
+> 目标：从"代码完成"到"系统可用"，验证端到端功能链路
+
+---
+
+## 1. 阶段概述
+
+15 AI 全并行开发模式下，各模块独立编码，使用 mock 桩进行本地验证。本阶段目标是**将所有模块集成到真实基础设施中，验证端到端功能链路**。
+
+### 前置状态
+
+| 检查项                               | 状态                        |
+| ------------------------------------ | --------------------------- |
+| lint（pnpm run lint）                | ✅ 全通过                   |
+| typecheck（pnpm run typecheck）      | ✅ 16 包/服务全通过         |
+| go vet（api-gateway + push-gateway） | ✅ 全通过                   |
+| ruff check（ai + data-ana）          | ✅ 全通过                   |
+| proto 契约（buf lint）               | ✅ 通过                     |
+| 仲裁（ARB-001~022）                  | ✅ 95 条全部已裁决          |
+| packages/contracts                   | ✅ 已建立（ADMIN_* 权限点） |
+
+### 当前差距
+
+- 各模块使用 mock 桩，尚未在真实 gRPC/MySQL/Redis/Kafka 环境中验证
+- 服务间 gRPC 调用链路未实际跑通
+- 前端与 BFF 的 GraphQL 通信未端到端验证
+- Docker Compose 全量部署未验证
+- 健康检查端点（/healthz + /readyz）未在容器环境验证
+
+---
+
+## 2. 阶段任务分解
+
+### 批次 0：基础设施就绪
+
+**目标**：确保 Docker Compose 全量基础设施可启动。
+
+| 任务                                                     | 验证标准                                  |
+| -------------------------------------------------------- | ----------------------------------------- |
+| MySQL + Redis + Kafka + Neo4j + ClickHouse + ES 容器健康 | `docker compose up -d` 全量容器 `healthy` |
+| 数据库 schema 初始化脚本                                 | 各服务 schema 迁移脚本可执行              |
+| Kafka topic 创建脚本                                     | 全部 topic（ARB-013 命名）可创建          |
+| Debezium CDC connector 配置                              | MySQL → Kafka CDC 链路通畅                |
+
+### 批次 1：后端服务启动
+
+**目标**：每个后端服务能在 Docker 环境中启动并通过健康检查。
+
+| 服务                          | 端口 | 验证标准               |
+| ----------------------------- | ---- | ---------------------- |
+| api-gateway（Go）             | 8080 | /healthz 返回 200      |
+| push-gateway（Go）            | 8081 | /healthz 返回 200      |
+| iam（TS/gRPC 50052）          | 3001 | /healthz + gRPC 可连接 |
+| classes（TS）                 | 3002 | /healthz 返回 200      |
+| core-edu（TS/gRPC 50053）     | 3004 | /healthz + gRPC 可连接 |
+| content（TS/gRPC 50054）      | 3005 | /healthz + gRPC 可连接 |
+| msg（TS/gRPC 50056）          | 3006 | /healthz + gRPC 可连接 |
+| data-ana（Python/gRPC 50055） | 3007 | /healthz + gRPC 可连接 |
+| ai（Python/gRPC 50058）       | 3008 | /healthz + gRPC 可连接 |
+
+### 批次 2：BFF 层启动
+
+**目标**：3 个 BFF 能启动并连接下游 gRPC 服务。
+
+| 服务                   | 端口 | 验证标准                   |
+| ---------------------- | ---- | -------------------------- |
+| teacher-bff（GraphQL） | 3003 | /graphql Playground 可访问 |
+| student-bff（GraphQL） | 3009 | /graphql Playground 可访问 |
+| parent-bff（GraphQL）  | 3010 | /graphql Playground 可访问 |
+
+### 批次 3：前端启动
+
+**目标**：4 个前端能启动并连接对应 BFF。
+
+| 应用           | 端口 | 验证标准     |
+| -------------- | ---- | ------------ |
+| teacher-portal | 4000 | 登录页可访问 |
+| student-portal | 4001 | 登录页可访问 |
+| parent-portal  | 4002 | 登录页可访问 |
+| admin-portal   | 4003 | 登录页可访问 |
+
+### 批次 4：端到端功能验证
+
+**目标**：核心业务链路端到端跑通。
+
+| 链路     | 涉及服务                                | 验证标准                       |
+| -------- | --------------------------------------- | ------------------------------ |
+| 教师登录 | teacher-portal → api-gateway → iam      | 获取 JWT → 侧边栏按角色渲染    |
+| 创建考试 | teacher-portal → teacher-bff → core-edu | 考试落库 → Outbox 事件 → Kafka |
+| 学生作答 | student-portal → student-bff → core-edu | 提交落库 → 事件发布            |
+| 教师批改 | teacher-portal → teacher-bff → core-edu | 成绩落库 → GradeReleased 事件  |
+| 学情分析 | student-portal → student-bff → data-ana | ClickHouse 宽表查询 < 5s       |
+| 知识图谱 | teacher-portal → teacher-bff → content  | Neo4j 查询秒级返回             |
+| 消息推送 | msg → push-gateway → WebSocket          | 在线学生实时收到通知           |
+| AI 辅助  | teacher-portal → teacher-bff → ai       | 流式 SSE 正常返回              |
+
+### 批次 5：可观测性验证
+
+**目标**：三支柱（日志 + 指标 + 链路）在集成环境中可用。
+
+| 检查项          | 验证标准                                |
+| --------------- | --------------------------------------- |
+| Prometheus 抓取 | 所有服务 /metrics 端点可抓取            |
+| Grafana 面板    | 核心指标面板可查看                      |
+| 全链路 trace    | 一个请求的 trace 可在 Jaeger 追踪全链路 |
+| 结构化日志      | 所有服务日志 JSON 格式输出到 stdout     |
+
+---
+
+## 3. 执行策略
+
+### 并行度
+
+```
+批次 0（基础设施） → 批次 1（后端） → 批次 2（BFF） → 批次 3（前端） → 批次 4（E2E） → 批次 5（可观测性）
+     |                  |                  |                  |                  |                  |
+     独立              9 服务并行         3 BFF 并行         4 前端并行         8 链路并行         独立
+```
+
+### 问题修复策略
+
+- 发现的问题记录到 `docs/troubleshooting/known-issues.md` 对应模块分区
+- 跨模块问题通过 `docs/architecture/issues/objections/[模块名]_issue.md` 提请仲裁
+- coord 负责仲裁，开发 AI 在各自分支修复
+
+### 风险点
+
+| 风险                          | 影响             | 缓解策略                     |
+| ----------------------------- | ---------------- | ---------------------------- |
+| gRPC proto 生成代码版本不一致 | 服务间调用失败   | 批次 1 统一 `buf generate`   |
+| MySQL schema 冲突             | 数据库初始化失败 | 批次 0 逐服务验证 schema     |
+| Kafka topic 命名不一致        | 消费者收不到事件 | 对照 ARB-013 统一检查        |
+| 端口冲突                      | 服务无法启动     | 对照 port-allocation.md 检查 |
+| 前端 MF 配置不匹配            | 微前端加载失败   | 批次 3 验证 MF config        |
+
+---
+
+## 4. 验收标准
+
+| 验收项                  | 标准                                   |
+| ----------------------- | -------------------------------------- |
+| Docker Compose 全量启动 | 所有容器 `healthy`                     |
+| 核心链路 E2E            | 8 条核心链路全部跑通                   |
+| 健康检查                | 所有服务 /healthz + /readyz 返回 200   |
+| 可观测性                | Prometheus + Grafana + Jaeger 数据可见 |
+| 错误处理                | ActionState 信封格式一致               |
+| 权限校验                | 未授权请求返回 401/403                 |
+
+---
+
+## 5. 退出标准
+
+- 全量 Docker Compose 启动成功
+- 8 条核心业务链路端到端跑通
+- 三支柱可观测性可用
+- 无阻塞性 bug
+- 打 tag `v0.6.0-integration`