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

Merge worktree branch merge-15-modules-to-main-5ug5xJ

Browse Source
This commit is contained in:
SpecialX
2026-07-10 15:28:20 +08:00
parent 60d7173545
commit df62ffc176
51 changed files with 11559 additions and 1908 deletions
Download Patch File Download Diff File Expand all files Collapse all files

109
docs/architecture/issues/objections/admin-portal_issue.md
View File

@@ -1,24 +1,109 @@
# admin-portal 问题记录
> 负责人：ai16
> 关联：[coord.md](../coord.md)、[contracts/admin-portal_contract.md](../contracts/admin-portal_contract.md)
> 关联：[coord.md](../coord.md)、[contracts/admin-portal_contract.md](../contracts/admin-portal_contract.md)、[matrix.md](../matrix.md)、[ai-allocation.md §5 ai16](../../ai-allocation.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态
---
## §0 已有仲裁核查（ai16 复核）
> 任务要求：对 coord 已有仲裁进行核查。以下为 ai16 对照 admin-portal 实际职责逐条复核结论。
### 0.1 ARB-001（teacher-bff GraphQL schema 第一版）— 核查结论：✅ 通过，但存在依赖缺口
- **核查点**：ARB-001 §1.3 裁决"admin 命名空间 P2 不包含，P6 admin-portal 阶段新增 admin 命名空间"。
- **核查结论**：裁决方向正确（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）
### 0.2 ARB-002（MF Shell 暴露清单）— 核查结论：✅ 通过，但 01/02 文档未跟进
- **核查点**：ARB-002 §2.2 Shell 暴露清单含 `GraphQLProvider` / `useGraphQLClient` / `useAuth` / `usePermission` / `AppShell` / `ErrorBoundary` / `Loading` / `Empty` / `RequirePermission`，**不含** `useApi` / `ApiClient`。
- **核查结论**：裁决正确。admin-portal 应通过 `useGraphQLClient()` 消费 teacher-bff GraphQL，而非 REST ApiClient。
- **发现的问题**：本模块 [01-understanding.md](../../../apps/admin-portal/docs/01-understanding.md) 与 [02-architecture-design.md](../../../apps/admin-portal/docs/02-architecture-design.md) 仍基于 REST `useApi()` / `ApiClient` 编写，未跟进 ARB-002。属本模块文档与仲裁不同步（见新异议 ISSUE-003）。
- **状态**：本模块文档待修订（见 ISSUE-003）
### 0.3 未仲裁但影响 admin-portal 的关键项
ARB-001/ARB-002 均未明确仲裁以下三项，而它们直接影响 admin-portal 实现，建议 coord 补充裁决：
| 待裁决项 | 当前依据 | 影响 |
| -------- | -------- | ---- |
| admin-portal 端口 | matrix.md / ai-allocation.md = 4003 | 01/02 文档误用 3003（与 teacher-bff 冲突） |
| admin-portal 是否消费 push-gateway WebSocket | 同类 portal（parent-portal）契约 = 消费 | 01/02 文档误声明"不消费推送" |
| 审计日志消费机制（iam Kafka → teacher-bff → GraphQL auditLogs） | matrix.md §4 列 admin-portal 为 edu.iam.audit.created 消费方 | 前端不直连 Kafka，需经 teacher-bff 聚合，matrix.md 表述不精确 |
---
## 问题列表
<!--
追加条目格式：
### ISSUE-001-ai16：01/02 模块文档归属错误（ai07 → ai16）
### ISSUE-[编号]-[AI标识]：[标题]
- **提请方**：ai16
- **日期**：2026-07-10
- **类型**：编号冲突 / 文档归属
- **描述**：[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 仲裁
- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
### ISSUE-002-ai16：01/02 文档端口错误（3003 → 4003），且 3003 与 teacher-bff 冲突
（暂无问题）
- **提请方**：ai16
- **日期**：2026-07-10
- **类型**：契约不明确 / 编号冲突
- **描述**：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 仲裁
### ISSUE-003-ai16：01/02 文档通信协议与 ARB-001/ARB-002 不一致（REST → GraphQL）
- **提请方**：ai16
- **日期**：2026-07-10
- **类型**：契约不明确 / 前置依赖缺失
- **描述**：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 仲裁
### ISSUE-004-ai16：01/02 文档遗漏审计日志与学校设置（ai-allocation §5 明确职责）
- **提请方**：ai16
- **日期**：2026-07-10
- **类型**：工作量超批 / 契约不明确
- **描述**：[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 仲裁
### ISSUE-005-ai16：teacher-bff 缺 admin 命名空间 GraphQL schema（前置依赖缺失）
- **提请方**：ai16
- **日期**：2026-07-10
- **类型**：前置依赖缺失
- **描述**：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 仲裁
### ISSUE-006-ai16：01/02 文档推送策略与同类 portal 契约不一致（轮询 → WebSocket）
- **提请方**：ai16
- **日期**：2026-07-10
- **类型**：契约不明确
- **描述**：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 仲裁
### ISSUE-007-ai16：matrix.md §4 将 admin-portal 列为 Kafka 直消费方，与前端层级矛盾
- **提请方**：ai16
- **日期**：2026-07-10
- **类型**：契约不明确
- **描述**：[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 仲裁
---
## §1 历史问题
（暂无已裁决问题）

121
docs/architecture/issues/objections/ai_issue.md
View File

@@ -1,13 +1,130 @@
# ai 问题记录
> 负责人：ai12
> 关联：[coord.md](../coord.md)、[contracts/ai_contract.md](../contracts/ai_contract.md)
> 关联：[coord.md](../coord.md)、[contracts/ai_contract.md](../contracts/ai_contract.md)、[matrix.md](../matrix.md)、[port-allocation.md](../../../../infra/port-allocation.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态
---
## §0 已有仲裁核查（ai12 复核，2026-07-10）
> 任务要求：对已有的仲裁进行核查。coord.md 当前仅含 ARB-001 / ARB-002；另在 [port-allocation.md](../../../../infra/port-allocation.md) §7、coord-final-decisions.md、president-final-rulings.md 中存在涉及 ai 的历史仲裁。逐项核查如下。
| 仲裁编号 / 来源 | 主题 | 涉及 ai？ | 核查结论 | 状态 |
| -------------------------- | ----------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| ARB-001（coord.md §1） | teacher-bff GraphQL schema 第一版 | ❌ 否 | 与 ai 无关，不适用。 | — |
| ARB-002（coord.md §2） | MF Shell 暴露清单 | ❌ 否 | 与 ai 无关，不适用。 | — |
| port-allocation.md §7 | 50058 让给 ai（push-gateway 豁免 gRPC） | ✅ 是 | **仲裁有效**：port-allocation.md §3/§5 已登记 ai = HTTP 3008 / gRPC 50058。ai 的 01/02 文档已按 50058 设计，一致。**但 [matrix.md](../matrix.md) §2 gRPC 接口提供方矩阵、§8 就绪信号跟踪表仍写 50057，未同步** → 提请 coord 同步（见 ISSUE-01） | ⚠️ 仲裁有效但未同步 |
| coord-final-decisions §1-§4 | iam P2 契约 / BFF 设计 / Gateway / content | ❌ 否 | 历史仲裁，与 ai 无直接约束。ai 仅消费 content/data-ana gRPC，需待其就绪。 | — |
| president-final-rulings §2.3 | Temporal 用于 AI 编排 | ✅ 是 | **部分仲裁**：004 §2.3 列出 Temporal。ai12 已在 02-architecture-design.md §8.3 建议简单 4 步工作流用 BackgroundTasks + Redis，长运行评估 Temporal。需 coord 在 P6 决策点确认（见 ISSUE-06）。 | ⚠️ 部分仲裁 |
| 01/02 文档引用"004 §7.2 已确认 topic edu.insight.ai.usage" | ai 用量事件 topic | ✅ 是 | **核查不通过**：grep 004 全文未发现 `ai.usage` / `insight.ai` / `AIUsage` 任何字样，004 §7.2 并未确认 ai 的 topic。该引用无法证实，topic 命名实际处于三义未决状态（见 ISSUE-02）。 | ❌ 引用失实 |
| 01/02 文档引用"004 §1.2 端口矩阵 HTTP+10050 规则" | ai gRPC 端口推导规则 | ✅ 是 | **核查不通过**：004 全文无端口矩阵；`HTTP+10050` 公式不成立（3008+10050=13058≠50058）。端口唯一源是 port-allocation.md（顺序分配），ai=50058。ai 文档应改引 port-allocation.md。 | ❌ 引用失实 |
**核查总结**：coord.md 现有 2 项仲裁（ARB-001/002）均与 ai 无关；涉及 ai 的真实仲裁在 port-allocation.md（50058 已定）与 004 §2.3（Temporal 部分仲裁）。ai 文档对"004 §7.2/§1.2"的两处引用失实，需修正引用源。
---
## 问题列表
### ISSUE-01-ai12：matrix.md 端口 50057 与 port-allocation.md 50058 不同步
- **提请方**：ai12
- **日期**：2026-07-10
- **类型**：编号冲突 / 文档不同步
- **描述**：[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）
### ISSUE-02-ai12：ai 用量事件 Kafka topic 命名三义未决
- **提请方**：ai12
- **日期**：2026-07-10
- **类型**：契约不明确
- **描述**：ai 用量计费事件 topic 在三份文档中命名不一致，且无权威源：
- 01-understanding.md §3.2 / 02-architecture-design.md §5.2：`edu.insight.ai.usage`（自称"004 §7.2 已确认"，但 004 中不存在）
- matrix.md §4 Kafka 事件发布方矩阵：`edu.ai.usage`，事件 `AIUsageEvent`
- contracts/ai_contract.md §1.4：`edu.ai.usage.events`
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 仲裁
### ISSUE-03-ai12：ai.proto 待补全（备课工作流 RPC + 字段扩展）
- **提请方**：ai12
- **日期**：2026-07-10
- **类型**：契约不明确 / 前置依赖缺失
- **描述**：ai.proto 现状仅 4 RPC（Chat / StreamChat / GenerateQuestion / OptimizeExpression），且 `GenerateQuestionRequest` 仅 prompt/subject/difficulty 三字段。P5 交付需要：
- 新增 RPC：`GenerateLessonPlan`、`StreamGenerateQuestion`（ai-allocation §5 "题目逐字生成"）
- `GenerateQuestionRequest` 扩展字段：grade / knowledge_point_ids / question_type / count
- `ChatRequest` 扩展可选字段：user_id / session_id / data_scope
关于 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 仲裁
### ISSUE-04-ai12：events.proto 缺 AIUsageEvent message
- **提请方**：ai12
- **日期**：2026-07-10
- **类型**：契约不明确 / 前置依赖缺失
- **描述**：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 仲裁
### ISSUE-05-ai12：contracts/ai_contract.md 与设计文档多处矛盾（ai12 自查自纠清单）
- **提请方**：ai12
- **日期**：2026-07-10
- **类型**：契约不明确 / 文档不同步
- **描述**：现有 contracts/ai_contract.md（coord 模板，ai12 接管前未细化）与 01/02 设计文档存在 5 处矛盾：
1. §1.1 gRPC 端口 50057（应为 50058，见 ISSUE-01）
2. §1.2 "无对外 HTTP 端点，仅 gRPC"——错误。api-gateway 代理 `/api/v1/ai/*` → ai HTTP（main.py 已实现 /ai/* 端点 + SSE 流式），HTTP 保留作 Gateway 直连降级
3. §1.4 topic `edu.ai.usage.events`（三义，见 ISSUE-02）
4. §1.5 错误码示例 `AI_PROVIDER_UNAVAILABLE` / `AI_TOKEN_LIMIT_EXCEEDED` / `AI_CONTENT_FILTERED` 与 02-architecture-design.md §6.2 清单（`AI_LLM_UNAVAILABLE` / `AI_QUOTA_EXCEEDED` / `AI_CONTENT_MODERATION_REJECTED`）命名不一致
5. §2.2 列出 ai 消费 2 个 content Kafka 事件，与 01/02 §5.1 "ai 不消费任何事件（无状态）"矛盾
- **建议方案**：ai12 在本次工作中直接重写 contracts/ai_contract.md 对齐设计文档（端口 50058 / 补 HTTP 端点 / topic 待 ISSUE-02 裁决后填 / 错误码对齐 02 §6.2 / 删除消费事件或标注 P6+ 评估）。仅 RPC 数与 topic 命名待 coord 裁决后最终定稿。
- **状态**：ai12 自纠中（依赖 ISSUE-01/02/03 裁决的字段待补）
### ISSUE-06-ai12：备课工作流是否引入 Temporal（P6 决策点）
- **提请方**：ai12
- **日期**：2026-07-10
- **类型**：工作量超批 / 前置依赖缺失
- **描述**：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 决策点）
### ISSUE-07-ai12：iam GetEffectiveDataScope gRPC RPC 待 P4 补全
- **提请方**：ai12
- **日期**：2026-07-10
- **类型**：前置依赖缺失
- **描述**：ai 多租户用量配额校验需调用 `IamService.GetEffectiveDataScope` 查询用户 DataScope。01/02 文档已提请（A4），coord 已仲裁 P4 补全（§15.3 #5），但 iam.proto 现状未见此 RPC。ai P5 实施时依赖，若 P4 未补全将阻塞配额校验功能。
- **建议方案**：请 coord 确认 iam (ai06) 在 P4 已补全 `GetEffectiveDataScope` RPC；ai12 在 P5 实施时调用，Redis 缓存 5min。若 P4 未补全，ai 降级为"仅按 user_id 配额，不按 school_id"。
- **状态**：待 coord 确认 P4 补全情况
### ISSUE-08-ai12：proto package 命名不符合 project_rules §5
- **提请方**：ai12
- **日期**：2026-07-10
- **类型**：契约不明确 / 架构约束
- **描述**：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 命名）
### ISSUE-09-ai12：响应信封偏离 ActionState 强制整改（P0）
- **提请方**：ai12
- **日期**：2026-07-10
- **类型**：架构约束
- **描述**：004 §11.5 强制响应信封为 ActionState（`{success, data, error:{code,message,details,traceId}}`）。ai 当前 main.py 违反：返回 `{success:true, data:..., degraded:false}` 顶层 degraded 字段（见 main.py:89/201-210/233-244）。01/02 文档已提请（A5），contracts 未记录。P5 实施必须整改。
- **建议方案**：P5 实施时所有 HTTP 端点 + gRPC RPC 返回值改为 ActionState；degraded 作为 `error.details.degraded` 子字段。请 coord 在 known-issues §2.9 ai 分区记录此约束（01 文档已提请，需 coord 落地 known-issues）。
- **状态**：待 coord 在 known-issues 记录约束（整改由 ai12 P5 执行）
---
<!--
追加条目格式：
@@ -20,5 +137,3 @@
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
（暂无问题）

23
docs/architecture/issues/objections/api-gateway_issue.md
View File

@@ -1,24 +1,3 @@
# api-gateway 问题记录
> 负责人：ai01
> 关联：[coord.md](../coord.md)、[contracts/api-gateway_contract.md](../contracts/api-gateway_contract.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态
---
## 问题列表
<!--
追加条目格式：
### ISSUE-[编号]-[AI标识]：[标题]
- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
（暂无问题）
> 负

189
docs/architecture/issues/objections/content_issue.md
View File

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

231
docs/architecture/issues/objections/core-edu_issue.md
View File

@@ -1,11 +1,34 @@
# core-edu 问题记录
> 负责人：ai08
> 关联：[coord.md](../coord.md)、[contracts/core-edu_contract.md](../contracts/core-edu_contract.md)
> 关联：[coord.md](../coord.md)、[contracts/core-edu_contract.md](../contracts/core-edu_contract.md)、[coord-cross-review.md](../../coord-cross-review.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态
---
## §0 已有仲裁核查记录（ai08 接管后核查）
> 核查日期：2026-07-10
> 核查范围：01-understanding.md / 02-architecture-design.md 引用的 coord 仲裁结论
> 核查方法：对照 [coord-cross-review.md](../../coord-cross-review.md) 原文 + 实际 proto 文件 + 实际源码
### 0.1 已核查通过的仲裁
| 仲裁编号 | 位置 | 核查结论 |
| -------- | ---- | -------- |
| coord-cross-review §3.1 | topic 命名统一为 `edu.teaching.<aggregate>.<action>` | ✅ 仲裁真实存在，结论准确，core-edu 01/02 文档引用正确 |
| coord-cross-review §5.5 | 错误码前缀 `CORE_EDU_*` 统一（不再细分 `EXAMS_`/`HOMEWORK_`/`GRADES_`） | ✅ 仲裁真实存在，结论准确 |
| coord-cross-review §5.7 | ActionState 信封结构统一 | ✅ 仲裁真实存在，core-edu GlobalErrorFilter 已对齐 |
| coord-cross-review §2.1 | proto 包名 `next_edu_cloud.core_edu.v1` | ✅ 仲裁真实存在，core_edu.proto L3 符合 |
| coord-cross-review §6 整改 #14 | core_edu.proto 补 AttendanceService | ⚠️ 仲裁真实存在，但状态与实际不符（见 ISSUE-001） |
| coord-cross-review §6 整改 #16 | buf.gen.yaml 补 gRPC 插件 | ⚠️ 待 ai08 核实 buf.gen.yaml 实际状态 |
### 0.2 核查发现的仲裁状态不一致（升级为 ISSUE）
详见下方 ISSUE-001 ~ ISSUE-003。
---
## 问题列表
<!--
@@ -21,4 +44,208 @@
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
（暂无问题）
### ISSUE-001-ai08：core_edu.proto 实际状态与 coord 仲裁声称不一致（P0）
- **提请方**：ai08
- **日期**：2026-07-10
- **类型**：契约不明确（仲裁状态与代码实际不符）
- **描述**：
[coord-cross-review.md](../../coord-cross-review.md) L312 声称：
> `core_edu.proto 补全 | packages/shared-proto/proto/core_edu.proto | ✅ 5 service（+ClassService +AttendanceService）`
但 ai08 核查实际文件 `packages/shared-proto/proto/core_edu.proto`，**实际只有 3 个 service**：
```
service ExamService { ... } // 5 RPC
service HomeworkService { ... } // 4 RPC
service GradeService { ... } // 5 RPC
```
**缺失**：
- `ClassService`（4 RPC：GetClass / GetClassesByTeacher / BatchGetClasses / ListStudentsByClass）
- `AttendanceService`（4 RPC：RecordAttendance / GetAttendance / ListAttendanceByStudent / ListAttendanceByClass）
同时 Exam/Homework/Grade message **缺 P3 新增字段**：
- Exam 缺 `subject_id`、`school_id`、`status_changed_at`、`status_changed_by`、`archived_at`
- Homework 缺 `subject_id`、`grace_period`、`school_id`
- Grade 缺 `total_score`、`school_id`、`idempotency_key`
- SubmitHomeworkRequest 缺 `answers` 字段（02 文档 §4.2 要求含完整 answers）
缺失 P3 新增 RPC：`PublishExam` / `SubmitExam` / `GradeExam` / `GradeHomework` / `UpdateGrade`。
- **影响**：
1. 01-understanding.md L48 仅声称缺 AttendanceService，遗漏了 ClassService 也缺失
2. matrix.md §2 声称 core-edu 22 RPC，但实际 proto 仅 14 RPC（5+4+5）
3. 下游 teacher-bff / student-bff / parent-bff 按 22 RPC 设计 mock，实际无 proto 定义可生成代码
- **建议方案**：
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 仲裁
---
### ISSUE-002-ai08：events.proto 未同步 coord topic 命名仲裁（P0）
- **提请方**：ai08
- **日期**：2026-07-10
- **类型**：契约不明确（仲裁未落实到 proto）
- **描述**：
[coord-cross-review.md](../../coord-cross-review.md) §3.1 仲裁"统一为 `edu.teaching.<aggregate>.<action>` 风格"，但 `packages/shared-proto/proto/events.proto` 实际状态：
1. **文件头注释（L9-13）仍是旧 topic 命名**：
```
// edu.exam.events <- exam.created / exam.updated / exam.deleted
// edu.homework.events <- homework.assigned / homework.submitted / homework.graded
// edu.grade.events <- grade.recorded / grade.updated
// edu.class.events <- class.transferred
```
未同步 `edu.teaching.exam.created` 等仲裁后命名。
2. **缺 `AttendanceEvent` message**：events.proto 仅定义 ClassEvent / ExamEvent / HomeworkEvent / GradeEvent，无 AttendanceEvent。02 文档 §5.1 要求发布 `edu.teaching.attendance.recorded` 事件，但 proto 无对应 message。
3. **缺 `schema_version` 字段**：所有 Event message（ClassEvent/ExamEvent/HomeworkEvent/GradeEvent）均无 `schema_version` 字段。coord §3.1 仲裁 + known-issues §1.3 + 01-understanding.md L67 + 02-architecture-design.md §5.1 均要求事件 payload 含 `schema_version`，但 proto 未定义。
4. **matrix.md §4 与 coord §3.1 仲裁不一致**：matrix.md §4 Kafka 事件发布方矩阵仍列 `edu.exam.events` / `edu.homework.events` / `edu.grade.events` / `edu.class.events`，未同步 coord §3.1 仲裁后的 `edu.teaching.*` 命名。
- **影响**：
- core-edu 修改 TOPIC_MAP 后，发布到 `edu.teaching.*` topic，但 events.proto 注释和 matrix.md 仍记录旧 topic，下游 AI 文档被误导
- 缺 AttendanceEvent message 导致 AttendanceService 无事件契约可发布
- 缺 schema_version 字段导致消费端无法按版本处理
- **建议方案**：
1. coord 同步更新 events.proto：
- 文件头注释改为 `edu.teaching.*` 命名
- 新增 `AttendanceEvent` message
- 所有 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 仲裁
---
### ISSUE-003-ai08：考试/作业状态命名跨模块不一致（P1）
- **提请方**：ai08
- **日期**：2026-07-10
- **类型**：契约不明确（跨模块命名冲突）
- **描述**：
02-architecture-design.md 定义的状态命名与 [coord.md](../coord.md) §1.2 GraphQL schema 枚举不一致：
| 维度 | 02-architecture-design.md（core-edu） | coord.md §1.2 GraphQL schema（teacher-bff） | 不一致点 |
| ---- | ------------------------------------- | ------------------------------------------- | -------- |
| ExamStatus | `draft / published / in_progress / grading / graded / archived / cancelled` | `DRAFT / PUBLISHED / IN_PROGRESS / GRADING / SCORED / ARCHIVED` | core-edu 用 `graded`，coord GraphQL 用 `SCORED`；core-edu 多 `cancelled` |
| SubmissionStatus（exam） | `in_progress / submitted / graded` | `NOT_SUBMITTED / SUBMITTED / GRADED` | core-edu 用 `in_progress`，coord 用 `NOT_SUBMITTED` |
| SubmissionStatus（homework） | `draft / submitted / graded` | `NOT_SUBMITTED / SUBMITTED / GRADED` | core-edu exam 用 `in_progress`，homework 用 `draft`，自身也不一致 |
02 文档 §3.1.1 exam_submissions.status 注释 `in_progress / submitted / graded`，§3.1.2 homework_submissions.status 注释 `draft / submitted / graded`，**core-edu 内部 exam 与 homework 的初始状态命名也不一致**（`in_progress` vs `draft`）。
- **影响**：
- teacher-bff GraphQL schema 枚举值与 core-edu DB status 字段值无法直接映射，BFF 需要转换层
- 前端展示需处理两套命名
- coord 仲裁 teacher-bff schema 时未与 core-edu 状态机命名对齐
- **建议方案**：
coord 仲裁统一状态命名（建议二选一）：
- **方案 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 仲裁
---
### ISSUE-004-ai08：class.transferred 事件 topic 三处不一致（P1）
- **提请方**：ai08
- **日期**：2026-07-10
- **类型**：契约不明确（topic 命名跨文档不一致）
- **描述**：
`class.transferred` 事件的 topic 命名在三处文档不一致：
| 文档 | topic 命名 |
| ---- | ---------- |
| 01-understanding.md L64 / 02-architecture-design.md §5.1 / §7 | `edu.org.class.created`（合并后归 org 域） |
| matrix.md §4 | `edu.class.events`（ClassEvent，action: transferred） |
| events.proto L13 注释 | `edu.class.events` |
core-edu 文档声称"classes 合并后归 org 域"用 `edu.org.class.created`，但 coord 维护的 matrix.md 和 events.proto 仍用 `edu.class.events`。
- **影响**：
- core-edu 按 `edu.org.class.created` 实现 TOPIC_MAP 后，matrix.md 记录的 `edu.class.events` topic 下游消费者订阅不上
- 命名归类不一致（org 域 vs class 域）
- **建议方案**：
coord 仲裁统一：
- 若 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 仲裁
---
### ISSUE-005-ai08：core-edu gRPC RPC 数量统计口径不一致（P1）
- **提请方**：ai08
- **日期**：2026-07-10
- **类型**：契约不明确（统计口径冲突）
- **描述**：
core-edu gRPC RPC 数量在三处文档统计不一致：
| 文档 | RPC 数 | 包含 ClassService | 包含 P3 新增 RPC |
| ---- | ------ | ----------------- | ---------------- |
| matrix.md §2 | 22 | ✅ 是（4 RPC） | ❌ 否（P2 基线） |
| 02-architecture-design.md §4.2 | 22 | ❌ 否 | ✅ 是（PublishExam/SubmitExam/GradeExam/GradeHomework/UpdateGrade） |
| core-edu_contract.md §1.1 | 22 | ✅ 是（4 RPC） | ❌ 否（P2 基线） |
P3 全量应为：ClassService 4 + ExamService 8（5+3 新增）+ HomeworkService 5（4+1 新增）+ GradeService 6（5+1 新增）+ AttendanceService 4 = **27 RPC**。
- **影响**：
- matrix.md §2 声明 22 RPC 但含 ClassService，02 文档声明 22 RPC 但不含 ClassService，下游 AI 无法判断应实现多少 RPC
- 就绪信号"core-edu gRPC 50053 + 22 RPC"含义模糊
- **建议方案**：
coord 统一 RPC 统计口径：
- 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 仲裁
---
### ISSUE-006-ai08：core-edu 02 文档 §13.3 七项未决决策待仲裁（P2）
- **提请方**：ai08
- **日期**：2026-07-10
- **类型**：契约不明确（设计决策未仲裁）
- **描述**：
02-architecture-design.md §13.3 列出 7 项未决设计决策，ai08 尚未正式提请 coord 仲裁，现集中提请：
| # | 决策点 | ai08 倾向 |
| - | ------ | --------- |
| 1 | classes 服务合并到 core-edu 的时机 | (a) P3 初期合并 |
| 2 | 排课 room_id 是否 P3 实现 | (b) 仅预留字段 |
| 3 | 成绩计算公式 scope 优先级 | (a) class > subject > school |
| 4 | 作业 grace_period 默认值 | (b) 300 秒（5 分钟宽限） |
| 5 | P3 是否启用 events.proto schema 强制校验 | (b) 仅文档约束 |
| 6 | exam.submitted 事件是否包含完整 answers | (b) 仅含 submission_id |
| 7 | archived 考试数据是否物理迁移 | (b) P3 仅软删除 |
注：决策 #4 与 02 文档 §3.1.2 homework 表 `gracePeriod: int("grace_period").notNull().default(0)` 默认 0 不一致，仲裁后需统一 schema 默认值。
- **影响**：
- 决策未定，core-edu P3 实现无法启动
- 决策 #4 schema 默认值与倾向不一致，仲裁前可能实现错
- **建议方案**：
coord 逐项仲裁，ai08 按倾向方案实现。决策 #4 若采 (b) 300 秒，02 文档 §3.1.2 schema 默认值改为 `.default(300)`。
- **状态**：待 coord 仲裁
---
### ISSUE-007-ai08：core-edu 01 文档审计表"待核对"项待 coord 确认（P2）
- **提请方**：ai08
- **日期**：2026-07-10
- **类型**：其他（审计未完成项）
- **描述**：
01-understanding.md 审计表与"黄金模板对齐清单"中 3 项标记"待核对"：
1. Dockerfile 多阶段构建（L111 / L128 审计表"待核对"）
2. ActionState 信封 traceId 验证（L116）
3. homework/grades controller 权限装饰器覆盖核对（L104）
ai08 在 P3 实施前需 coord 确认这些项是否作为 P3 验收硬性标准。
- **建议方案**：
coord 确认上述 3 项是否纳入 P3 验收标准；若纳入，ai08 在 P3 实施时补齐。
- **状态**：待 coord 仲裁

131
docs/architecture/issues/objections/data-ana_issue.md
View File

@@ -1,24 +1,129 @@
# data-ana 问题记录
> 负责人：ai11
> 关联：[coord.md](../coord.md)、[contracts/data-ana_contract.md](../contracts/data-ana_contract.md)
> 关联：[coord.md](../coord.md)、[coord-cross-review.md](../../coord-cross-review.md)、[contracts/data-ana_contract.md](../contracts/data-ana_contract.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态
---
## 问题列表
## §0 已有仲裁核查记录（2026-07-10）
<!--
追加条目格式：
> ai11 在编写 objections 前对 coord.md 与 coord-cross-review.md 中涉及 data-ana 的仲裁逐项核查落实状态。
### ISSUE-[编号]-[AI标识]：[标题]
### 0.1 coord.md 仲裁核查
- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
| 编号 | 主题 | 涉及 data-ana | 核查结论 |
| ------- | ---------------------------- | ------------- | ------------------------------ |
| ARB-001 | teacher-bff GraphQL schema | ❌ 否 | 不涉及，无需 action |
| ARB-002 | MF Shell 暴露清单 | ❌ 否 | 不涉及，无需 action |
（暂无问题）
**结论**：coord.md 无 data-ana 直接仲裁。
### 0.2 coord-cross-review.md 仲裁核查（8 项涉及 data-ana）
| # | 审查章节 | 裁决内容 | 责任方 | 核查结论 |
| -- | ---------------- | ------------------------------------------------------------------ | ------ | ---------------------------------------------------------------------------------------------------- |
| 1 | §2.2 #3 | iam 新增 `GetEffectiveDataScope` RPC，P4 补全，data-ana gRPC 调用 | iam | ⚠️ **未落实**：iam.proto 当前仅 4 RPC（Register/Login/RefreshToken/GetUserInfo），无 GetEffectiveDataScope |
| 2 | §2.3 P4 行 | content + data-ana P4 启用 gRPC server | ai11 | ⏳ 未到 P4 阶段，待执行 |
| 3 | §3.2 | 补登 `edu.insight.ai.usage` topic + events.proto 补 AIUsageEvent | coord | ⚠️ **未落实**：events.proto 当前仅 4 message（Class/Exam/Homework/GradeEvent），缺 AIUsageEvent |
| 4 | §3.3 | Python 服务 Outbox 豁免（MasteryUpdated / WarningTriggered） | coord | ✅ **已对齐**：01/02 文档已声明豁免，引用 coord-cross-review.md §3.3 |
| 5 | §4.3 | data-ana HTTP=3006 / gRPC=50055 | coord | ✅ **已对齐**：01/02 文档端口声明一致 |
| 6 | §5.3 | Python 服务信封改为 ActionState（degraded 放 details 子字段） | ai11 | ✅ **已对齐**：02 §4.3 ActionState 实现已修正，degraded 移至顶层 details |
| 7 | §6 #4 | 同 #6，ai06 修正 data-ana/ai 02 文档 + 代码 | ai11 | ✅ **已对齐（文档）**：02 已修正；代码待 P4 实现阶段重构 |
| 8 | §6 #7/#8/#9/#10 | coord 在 004 §7.2 补登 topic + §1.2 端口列 + §4.1 gRPC 矩阵 + §12.2 豁免 | coord | ⚠️ **未落实**：004 正文无 §4.2/§7.2 补登段/§11.4/§11.5，01/02 引用断裂已临时改为引 coord-cross-review.md |
### 0.3 coord-cross-review §8.2 批次 0 产出声明核查
coord-cross-review.md §8.2 声称批次 0 已完成 proto 补全，ai11 逐文件核查实际状态：
| 声明产出项 | 声明状态 | 实际文件状态（ai11 核查） | 核查结论 |
| -------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------- | ------------ |
| iam.proto 12 RPC | ✅ 12 RPC | **4 RPC**（Register/Login/RefreshToken/GetUserInfo） | ⚠️ 严重不符 |
| analytics.proto 扩展 | ✅ 12 RPC（含 Stream） | **3 RPC**（GetClassPerformance/GetStudentWeakness/GetLearningTrend） | ⚠️ 严重不符 |
| events.proto 补全 | ✅ 9 message（+AuditEvent） | **4 message**（ClassEvent/ExamEvent/HomeworkEvent/GradeEvent） | ⚠️ 严重不符 |
| core_edu.proto 补全 | ✅ 5 service | 未由 ai11 核查（非本模块边界） | — |
| buf.gen.yaml 插件 | ✅ go + python | 未由 ai11 核查（coord 维护） | — |
> **核查说明**：ai11 仅核查与 data-ana 直接相关的 proto（iam/analytics/events）。§8.2 声明与实际文件严重不符，可能原因：(a) 声明为计划态但未执行；(b) 执行后未提交到本 worktree 分支；(c) 在其他分支已执行但未合并。无论哪种原因，data-ana 的 P4 实现依赖这些 proto 补全，当前实际状态构成 P4 阻塞。
---
## §1 问题列表
### ISSUE-001-ai11：iam.proto 缺 GetEffectiveDataScope RPC（P4 阻塞）
- **提请方**：ai11
- **日期**：2026-07-10
- **类型**：前置依赖缺失
- **描述**：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 未落实）
---
### ISSUE-002-ai11：events.proto 缺 AIUsageEvent message（P5 阻塞，P4 预备）
- **提请方**：ai11
- **日期**：2026-07-10
- **类型**：前置依赖缺失
- **描述**：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 未落实）
---
### ISSUE-003-ai11：analytics.proto 仅 3 RPC，coord-cross-review §8.2 声称已扩展至 12 RPC 但实际未落实（P4 阻塞）
- **提请方**：ai11
- **日期**：2026-07-10
- **类型**：前置依赖缺失 + 声明与实际不符
- **描述**：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 仲裁
---
### ISSUE-004-ai11：coord-cross-review §6 整改清单 coord 责任项未落实，导致 004 章节引用断裂
- **提请方**：ai11
- **日期**：2026-07-10
- **类型**：契约不明确
- **描述**：coord-cross-review.md §6 整改清单中标注"coord"责任的 4 项整改未在 004 正文中落实：
- #7：004 §7.2 补登 6 个 topic + CDC 命名规范 → 004 正文无对应段落
- #8：004 §1.2 新增 HTTP/gRPC 端口两列 → 004 §1.2 服务清单无端口列
- #9：004 §4.1 补充 gRPC 启用阶段矩阵 → 004 正文无 §4.2 子节
- #10：004 §12.2 补充派生数据事件 Outbox 豁免条款 → 004 §12.2 未补充
这导致 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 仲裁
---
### ISSUE-005-ai11：data-ana 发布的 MasteryEvent topic 命名三处不一致
- **提请方**：ai11
- **日期**：2026-07-10
- **类型**：契约不明确
- **描述**：data-ana 发布的掌握度/预警事件 topic 命名在三个文档中不一致：
| 文档 | topic 命名 |
| -------------------------------------- | ------------------------------------- |
| 01-understanding.md / 02-architecture-design.md | `edu.insight.mastery.updated` + `edu.insight.warning.triggered` |
| matrix.md §4 | `edu.analytics.mastery` |
| contracts/data-ana_contract.md（修正前） | `edu.data_ana.mastery.events` |
按 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 仲裁
---
### ISSUE-006-ai11：coord-cross-review §8.2 批次 0 产出声明与 proto 实际文件状态严重不符
- **提请方**：ai11
- **日期**：2026-07-10
- **类型**：其他（声明与实际不符）
- **描述**：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 仲裁

120
docs/architecture/issues/objections/iam_issue.md
View File

@@ -6,6 +6,124 @@
---
## §1 已有仲裁核查
> 对已生效的仲裁（coord-final-decisions I1-I8、president-final-rulings 相关条款、coord.md ARB-001/ARB-002）逐条核查落地情况。
### 1.1 coord-final-decisions I1-I8（iam 专项）核查
| 裁决 | 内容摘要 | 核查结论 | 证据 |
| ---- | -------- | -------- | ---- |
| I1 | P2 即启用 gRPC server 50052，REST + gRPC 并存 | ⚠️ **02 文档未回写**：[02-architecture-design.md](../../../services/iam/docs/02-architecture-design.md) §1/§7.1/§8.1 决策点 5 仍写"P2 仅 REST，P3 随 core-edu 引入 gRPC"；iam.proto 仅 4 RPC 未补全 | [iam.proto](../../../packages/shared-proto/proto/iam.proto) 仅 4 RPC；[02 文档 §8.1](../../../services/iam/docs/02-architecture-design.md) 决策点 5 |
| I2 | 直接建 shared-ts Outbox 工具包，iam 首次实现即用 | ✅ **工具包已建立**：`packages/shared-ts/src/outbox/` 存在 outbox.service.ts + outbox.module.ts；⚠️ 02 文档 §8.1 决策点 4 仍写"iam 自建轻量 Outbox"，未回写 | [shared-ts/outbox](../../../packages/shared-ts/src/outbox/) |
| I3 | 首次实现即 DB 驱动 + Redis 缓存，废弃本地 map | ❌ **源码未改造**：[permission.guard.ts](../../../services/iam/src/middleware/permission.guard.ts) 第 30-39 行仍用硬编码 `ROLE_PERMISSIONS` map（admin/teacher）；02 文档 §8.1 决策点 9 描述为"待改造" | [permission.guard.ts](../../../services/iam/src/middleware/permission.guard.ts) |
| I4 | 首次实现即注册 AuthMiddleware，Controller 用 @Req() 注入 | ❌ **源码未注册**：[app.module.ts](../../../services/iam/src/app.module.ts) 仅注册 PermissionGuard 为 APP_GUARD，未在 configure() 消费 AuthMiddleware；02 文档 §1.1/§1.2/§8.1 决策点 10 仍写"P2 仍不注册" | [app.module.ts](../../../services/iam/src/app.module.ts) |
| I5 | P2 本地文件 IAM_PRIVATE_KEY_PATH / IAM_PUBLIC_KEY_PATH | ⚠️ **源码未实现**：[iam.service.ts](../../../services/iam/src/iam/iam.service.ts) 第 170-186 行仍用 `env.JWT_SECRET`（HS256 单密钥）；02 文档 §8.1 决策点 1 已对齐（本地文件→P6 Vault）但未落地 | [iam.service.ts](../../../services/iam/src/iam/iam.service.ts) |
| I6 | P2 即补全 iam_student_guardians 表 + GetChildrenByParent RPC + GET /iam/children | ❌ **02 文档表名错误**：[02 文档 §3.1.2](../../../services/iam/docs/02-architecture-design.md) 用 `iam_parent_student_relations`，裁决表名为 `iam_student_guardians`；源码未实现 | 02 文档 §3.1.2 |
| I7 | 采用 /iam/v1/* 前缀，Gateway 透传 | ❌ **02 文档未回写**：[02 文档 §4.1](../../../services/iam/docs/02-architecture-design.md) REST API 清单全部用 `/iam/*` 无 `/v1` 前缀；源码 Controller 用 `@Controller("iam")` 无版本前缀 | [iam.controller.ts](../../../services/iam/src/iam/iam.controller.ts)、[rbac.controller.ts](../../../services/iam/src/iam/rbac.controller.ts) |
| I8 | 统一 GET /iam/permissions/effective | ✅ **源码已对齐**：[rbac.controller.ts](../../../services/iam/src/iam/rbac.controller.ts) 第 33 行用 `@Get("permissions/effective")` | [rbac.controller.ts](../../../services/iam/src/iam/rbac.controller.ts) |
### 1.2 president-final-rulings 相关条款核查
| 条款 | 内容摘要 | 核查结论 |
| ----- | -------- | -------- |
| §2.15 | /iam/v1/* 版本化规则（Controller 加 v1 前缀） | ❌ 同 I7，未落地 |
| §2.16 | gRPC 与 REST 双入口策略（gateway HTTP 透传 + BFF gRPC 调用） | ⚠️ 02 文档未体现双入口设计，仅描述 REST 单入口；contract.md §1.2 写"无对外 HTTP 端点，仅 gRPC"与此冲突 |
| §3.2 | iam P2 拆分 P2.1（8 RPC 核心）+ P2.2（扩展） | ⚠️ workline.md 仅粗略列出 P2.1，P2.2-P6 未细化（见 worklines/iam_workline.md） |
| §5.5 | 审计日志归 iam（AuditEvent + edu.iam.audit.created topic + user_audit_log 表） | ❌ 02 文档未包含审计日志设计；events.proto 未定义 AuditEvent message |
| §5.1 | events.proto 补全 UserEvent/RoleEvent | ❌ events.proto 实际仅含 ClassEvent/ExamEvent/HomeworkEvent/GradeEvent，缺 UserEvent/RoleEvent/AuditEvent（coord-final-decisions §5.1 标注"✅ 已补全"与实际不符） |
### 1.3 coord.md ARB-001 / ARB-002 核查
| 仲裁 | 内容摘要 | 核查结论 |
| ------ | -------- | -------- |
| ARB-001 | teacher-bff GraphQL schema 第一版（5 Query） | ✅ schema 中 `me: User!`、`viewports` 依赖 iam，与 iam GetUserInfo/GetViewports RPC 对齐，无冲突 |
| ARB-002 | MF Shell 暴露清单 | ✅ 不涉及 iam 直接交付物，无冲突 |
---
## §2 新提请异议
### ISSUE-001-ai06：01/02 文档未回写 I1-I8 裁决，中间过渡方案残留
- **提请方**：ai06
- **日期**：2026-07-10
- **类型**：契约不明确 / 其他
- **描述**：coord-final-decisions §0.1 强制覆盖声明要求各 AI 在 3 个工作日内回写 02 文档，删除所有"中间过渡方案"。president-final-rulings §3.4 也明确要求 ai06 回写 iam 02（I1-I8，§3.4）。但当前 [01-understanding.md](../../../services/iam/docs/01-understanding.md) 和 [02-architecture-design.md](../../../services/iam/docs/02-architecture-design.md) 仍残留大量过渡方案：
- 02 §1/§7.1/§8.1 决策点 5：P2 仅 REST → P3 gRPC（违反 I1）
- 02 §8.1 决策点 4：iam 自建 Outbox（违反 I2）
- 02 §8.1 决策点 9：PermissionGuard 待改造（违反 I3）
- 02 §1.1/§1.2/§8.1 决策点 10：AuthMiddleware P2 不注册（违反 I4）
- 02 §3.1.2：表名 iam_parent_student_relations（违反 I6）
- 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 仲裁（确认回写范围与验收标准）
### ISSUE-002-ai06：events.proto 缺少 UserEvent/RoleEvent/AuditEvent message
- **提请方**：ai06
- **日期**：2026-07-10
- **类型**：前置依赖缺失
- **描述**：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 仲裁
### ISSUE-003-ai06：Topic 命名三方不一致（edu.identity.* vs edu.iam.*）
- **提请方**：ai06
- **日期**：2026-07-10
- **类型**：契约不明确
- **描述**：iam 事件 Topic 命名存在三方不一致：
- [004 §7.2](../../../docs/architecture/004_architecture_impact_map.md) 行 620-621：`edu.identity.user.created` / `edu.identity.user.updated`（用 `identity` 域名）
- [matrix.md §4](../matrix.md) / [iam_contract.md §1.4](../contracts/iam_contract.md)：`edu.iam.user.events` / `edu.iam.role.events` / `edu.iam.audit.created`（用 `iam` 域名）
- 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 仲裁
### ISSUE-004-ai06：DataScope 枚举三方不一致
- **提请方**：ai06
- **日期**：2026-07-10
- **类型**：契约不明确
- **描述**：DataScope 6 级枚举存在三方不一致：
- [004 §5.3 表](../../../docs/architecture/004_architecture_impact_map.md) 行 463-470：SELF/CLASS/GRADE/SCHOOL/DISTRICT/ALL
- [004 §5.3](../../../docs/architecture/004_architecture_impact_map.md) 行 505：all/grade_managed/class_taught/children/owned + 自定义（语义命名，与表不同）
- 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 仲裁
### ISSUE-005-ai06：iam.proto 仅 4 RPC，未补全至 12 RPC
- **提请方**：ai06
- **日期**：2026-07-10
- **类型**：前置依赖缺失
- **描述**：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 仲裁
### ISSUE-006-ai06：01/02 文档 AI 身份署名错误
- **提请方**：ai06
- **日期**：2026-07-10
- **类型**：其他
- **描述**：[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 仲裁
### ISSUE-007-ai06：contract.md §1.2 与双入口策略冲突
- **提请方**：ai06
- **日期**：2026-07-10
- **类型**：契约不明确
- **描述**：[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 仲裁
---
## 问题列表
<!--
@@ -21,4 +139,4 @@
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
（暂无问题）
见上方 §2 新提请异议（ISSUE-001 ~ ISSUE-007）。

194
docs/architecture/issues/objections/msg_issue.md
View File

@@ -6,19 +6,189 @@
---
## 问题列表
## §0 已有仲裁核查（ai10 复核）
<!--
追加条目格式：
> 本节核查 01-understanding.md / 02-architecture-design.md 中引用的已有仲裁，对照源码/proto 验证准确性。
### ISSUE-[编号]-[AI标识]：[标题]
### ISSUE-001-ai10：M8 ZodError 已修复 — 核查通过
- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
- **提请方**：ai10
- **日期**：2026-07-10
- **类型**：仲裁核查
- **描述**：01-understanding.md M8 称"GlobalErrorFilter 已识别 ZodError 返回 400"。核查 [global-error.filter.ts](../../../services/msg/src/shared/errors/global-error.filter.ts) L32-42：`else if (exception instanceof ZodError) { statusCode = 400; ... }`，确实已处理，返回 `MSG_VALIDATION_ERROR` + 400。
- **核查结论**：✅ 仲裁准确，M8 标记"已修复"无误
- **状态**：已裁决（核查通过，无需处理）
（暂无问题）
### ISSUE-002-ai10：M12 proto 包名规范 — 核查通过
- **提请方**：ai10
- **日期**：2026-07-10
- **类型**：仲裁核查
- **描述**：01-understanding.md M12 称"实际 `next_edu_cloud.msg.v1` 符合规范"。核查 [msg.proto](../../../packages/shared-proto/proto/msg.proto) L3：`package next_edu_cloud.msg.v1;`，与 01-understanding.md 描述一致。
- **核查结论**：✅ 仲裁准确，但存在规则冲突（见 ISSUE-007）
- **状态**：已裁决（核查通过）
### ISSUE-003-ai10：M2 msg 必须有 Outbox — 核查通过
- **提请方**：ai10
- **日期**：2026-07-10
- **类型**：仲裁核查
- **描述**：01-understanding.md M2 称"004 §7.2 明确 msg 生产 `edu.notification.events`，msg 必须有 Outbox"。核查 004 §7.3 L638 `NotificationRequested` 事件（Msg 投递通知到多渠道）+ known-issues §msg L346"Outbox 强制"。
- **核查结论**：✅ 仲裁准确，msg 必须实现 Outbox（P5 强制）
- **状态**：已裁决（核查通过）
### ISSUE-004-ai10：core-edu 事件 topic 命名统一 — 核查部分通过
- **提请方**：ai10
- **日期**：2026-07-10
- **类型**：仲裁核查
- **描述**：02-architecture-design.md §7.2 P11 称"coord 已仲裁采用 `edu.teaching.*` 新约定"。核查：
- 004 §7.2 L623-625 使用 `edu.teaching.assignment.submitted` / `edu.teaching.exam.published` / `edu.teaching.grade.recorded`（新约定）✅
- [events.proto](../../../packages/shared-proto/proto/events.proto) L9-13 注释仍用 `edu.exam.events` / `edu.homework.events`（旧约定）❌ 未同步
- [matrix.md](../matrix.md) §4 L112-115 使用 `edu.exam.events` / `edu.homework.events`（旧约定）❌ 未同步
- **核查结论**：⚠️ 仲裁已作出但未全量同步，events.proto 注释与 matrix.md 仍用旧约定，需 coord 统一更新
- **状态**：待 coord 同步（见 ISSUE-008）
### ISSUE-005-ai10：Push Gateway 调用方向歧义 — 核查通过
- **提请方**：ai10
- **日期**：2026-07-10
- **类型**：仲裁核查
- **描述**：02-architecture-design.md §7.2 P10 称"004 §4.1 写 PushGW→Msg，实际是 Msg→PushGW"。核查 004 §4.1 L413：`push-gateway → Msg | gRPC | 推送通道建立`，方向确实反了。实际流程是 msg 调 push-gateway 的 gRPC PushService.Push（见 [notifications.service.ts](../../../services/msg/src/notifications/notifications.service.ts) L179 fetch POST /internal/push 降级实现）。
- **核查结论**：✅ 歧义确认，建议 coord 修正 004 §4.1 表述为"Msg → push-gateway (gRPC)"
- **状态**：待 coord 修正 004
---
## §1 新发现问题（ai10 提请）
### ISSUE-006-ai10：events.proto P9 字段描述不准确
- **提请方**：ai10
- **日期**：2026-07-10
- **类型**：契约不明确
- **描述**：02-architecture-design.md §7.2 P9 称"events.proto ExamEvent / HomeworkEvent / GradeEvent 需补 `class_id` / `student_ids[]` 字段"。核查 events.proto：
- `ExamEvent` L32 **已有** `class_id` 字段 ✅
- `HomeworkEvent` L45 **已有** `class_id` 字段 ✅
- `GradeEvent` L50-59 **无** `class_id`（仅有 `student_id`）❌
- 三者均**无** `student_ids[]`（复数，用于 fan-out 广播）❌
- **建议方案**：修正 P9 表述为"`GradeEvent` 需补 `class_id`；全部事件需补 `student_ids[]` 字段（msg fan-out 广播通知需要）"
- **状态**：待 coord 仲裁
### ISSUE-007-ai10：proto 包名规则冲突（project_rules vs 实际）
- **提请方**：ai10
- **日期**：2026-07-10
- **类型**：契约不明确
- **描述**：[project_rules §5](../../../.trae/rules/project_rules.md) 规定"包名规范：`edu.<domain>.v1`（如 `edu.iam.v1`、`edu.core_edu.v1`）"，但实际所有 proto 文件使用 `next_edu_cloud.<domain>.v1`（如 msg.proto L3 `next_edu_cloud.msg.v1`、events.proto L3 `next_edu_cloud.events.v1`）。01-understanding.md 称"coord 已裁决采用 `next_edu_cloud.*`"，但 project_rules §5 未同步更新，仍写 `edu.<domain>.v1`。
- **建议方案**：coord 统一裁决，二选一：
- 方案 A：更新 project_rules §5 为 `next_edu_cloud.<domain>.v1`（与实际 proto 一致）
- 方案 B：重命名所有 proto package 为 `edu.<domain>.v1`（与规则一致，但改动大）
- **状态**：待 coord 仲裁
### ISSUE-008-ai10：Kafka topic 命名三套约定并存
- **提请方**：ai10
- **日期**：2026-07-10
- **类型**：契约不明确
- **描述**：msg 相关的 Kafka topic 命名存在三套约定：
- **约定 A（004 §7.2，per-event topic）**：`edu.identity.user.created` / `edu.teaching.exam.published` / `edu.notification.sent`
- **约定 B（matrix.md §4 + events.proto 注释，aggregate topic）**：`edu.iam.user.events` / `edu.exam.events` / `edu.notification.requested`
- **约定 C（msg_contract.md §1.4，aggregate topic + action 字段）**：`edu.msg.notification.events`（action: sent/read/recalled/failed）
- 02-architecture-design.md §5.1/§5.2 采用约定 A；msg_contract.md §1.4 采用约定 C；matrix.md 采用约定 B。known-issues §全局 L182 已标记此冲突。
- **建议方案**：coord 统一为一套约定。ai10 倾向约定 A（per-event topic），理由：
- 004 §7.2 已采用，是架构设计意图唯一源
- per-event topic 便于消费者按需订阅，避免反序列化无关事件
- 与 NotificationSent / NotificationRead 等事件命名（PascalCase）对齐
- **状态**：待 coord 仲裁
### ISSUE-009-ai10：RPC 数量超预算（17 vs 13）
- **提请方**：ai10
- **日期**：2026-07-10
- **类型**：工作量超批
- **描述**：[ai-allocation.md §3.2](../../ai-allocation.md) L112 与 [matrix.md](../matrix.md) §2 L90 均规定 msg 为"3 Service 13 RPC"。但 02-architecture-design.md §4.2 列出 17 RPC：
- NotificationService 9 RPC（SendNotification / BatchSendNotification / ListNotifications / GetUnreadCount / MarkAsRead / BatchMarkAsRead / MarkAllAsRead / SearchNotifications / RecallNotification）
- NotificationPreferenceService 2 RPC（GetPreferences / UpdatePreferences）
- NotificationTemplateService 6 RPC（CreateTemplate / GetTemplate / ListTemplates / UpdateTemplate / DeleteTemplate / RenderTemplate）
- 而 msg_contract.md §1.1 列出 13 RPC（分布不同：5+4+4），两文档互相不一致
- **建议方案**：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 仲裁
### ISSUE-010-ai10：markAsRead 权限点与设计不一致
- **提请方**：ai10
- **日期**：2026-07-10
- **类型**：契约不明确
- **描述**：[notifications.controller.ts](../../../services/msg/src/notifications/notifications.controller.ts) L74 markAsRead 使用 `MSG_NOTIFICATION_MANAGE` 权限，但 02-architecture-design.md §6.1 L730 规定 markAsRead 应使用 `MSG_NOTIFICATION_READ`。MANAGE 权限通常给管理员，学生标记自己通知已读不应需要 MANAGE 权限。
- **建议方案**：以 02-architecture-design.md §6.1 为准（READ），P5 实现时修正 controller 权限点
- **状态**：待 coord 确认
### ISSUE-011-ai10：DB→ES 降级方向与 ai-allocation §5 相反
- **提请方**：ai10
- **日期**：2026-07-10
- **类型**：契约不明确
- **描述**：
- [ai-allocation.md §5](../../ai-allocation.md) ai10 设计重点要求"ES 降级查询策略（**DB 不可用时走 ES 索引**）"——即 DB 故障时 ES 作为读模型兜底
- 02-architecture-design.md §3.2.2 / §3.4 描述"**ES 不可用时降级到 MySQL LIKE 查询**"——即 ES 故障时 DB 兜底
- 01-understanding.md M16 称"无 DB→ES 降级读路径"
- 三处描述方向相反，需统一
- **建议方案**：ai10 倾向双向降级（两种故障场景都覆盖）：
- ES 故障 → DB LIKE 查询（设计文档已覆盖）
- DB 故障 → ES 只读模式（ai-allocation 要求，设计文档需补充）
- 但 DB 故障时写操作无法降级（必须等 DB 恢复），仅读操作可走 ES
- **状态**：待 coord 仲裁
### ISSUE-012-ai10：设计文档缺 DLQ 与三层幂等防线
- **提请方**：ai10
- **日期**：2026-07-10
- **类型**：前置依赖缺失
- **描述**：[known-issues §msg](../../../docs/troubleshooting/known-issues.md) L344 / L356 已记录两项 ai10 设计点，但 02-architecture-design.md 未覆盖：
- **三层幂等防线**（L344）：L1 Redis SETNX / L2 msg_idempotency 表 / L3 notifications.source_event_id 唯一索引。设计文档 §5.5 仅描述两层（Redis + DB UNIQUE），缺中间层 msg_idempotency 表
- **死信队列**（L356）：消费失败超 3 次投递 `edu.notification.dlq`。设计文档 §5 完全未提及 DLQ 设计
- **建议方案**：02-architecture-design.md 补充：
- §3.1 补 `msg_idempotency` 表 schema（中间层）
- §5.5 改为三层幂等防线
- §5 补 DLQ 设计（重试 3 次后投递 `edu.notification.dlq` + 告警）
- **状态**：待 coord 确认（非阻塞，ai10 自行补充设计文档即可）
### ISSUE-013-ai10：events.proto 缺 4 类 message 阻塞 msg 消费
- **提请方**：ai10
- **日期**：2026-07-10
- **类型**：前置依赖缺失
- **描述**：[events.proto](../../../packages/shared-proto/proto/events.proto) 仅有 ClassEvent / ExamEvent / HomeworkEvent / GradeEvent 4 个 message。msg 消费还需要：
- `UserEvent`（iam 发布 user.created/updated/deleted/role_changed）— 阻塞欢迎通知/角色变更通知
- `RoleEvent`（iam 发布 role.created/updated）— 阻塞角色变更通知
- `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 消费链路）
### ISSUE-014-ai10：msg_contract.md 与 02-architecture-design.md RPC 清单不一致
- **提请方**：ai10
- **日期**：2026-07-10
- **类型**：契约不明确
- **描述**：两文档 RPC 清单存在差异：
- msg_contract.md 独有（02 缺）：GetPreferenceByChannel、ListPreferences
- 02-architecture-design.md 独有（contract 缺）：BatchSendNotification、GetUnreadCount、BatchMarkAsRead、MarkAllAsRead、UpdateTemplate、DeleteTemplate
- 即使忽略 ISSUE-009 的数量问题，两文档的 RPC 组合也不同
- **建议方案**：待 ISSUE-009 仲裁后，统一两文档 RPC 清单
- **状态**：待 coord 仲裁（依赖 ISSUE-009）
### ISSUE-015-ai10：msg_contract.md Kafka 发布事件与设计文档不一致
- **提请方**：ai10
- **日期**：2026-07-10
- **类型**：契约不明确
- **描述**：
- msg_contract.md §1.4：`edu.msg.notification.events` topic，单一 NotificationEvent 含 action 字段
- 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）

159
docs/architecture/issues/objections/parent-bff_issue.md
View File

@@ -6,8 +6,165 @@
---
## §0 已有仲裁核查结论（ai05 复审，2026-07-10）
> 对 parent-bff 相关的已仲裁决策（用户 U1-U4 + coord C1-C6 + coord-final-decisions I6）逐项核查执行情况。
### 0.1 核查通过项（已正确执行）
| 仲裁 | 主题 | 核查结论 |
| --- | --- | --- |
| U2 | push-gateway 豁免 gRPC，HTTP /internal/push | ✅ 02 §5.3/§7.1 已执行 HTTP 调用 push-gateway |
| C2 | 端口 3010，不暴露 gRPC | ✅ 02 §7.2 + matrix.md §3 已执行 |
| C3 | core-edu 错误码 CORE_EDU_* | ✅ 02 §6.2 已执行 |
| C5 | Kafka topic edu.notification.sent/read/recalled/failed | ✅ 02 §5.2 已执行（004 §7.2 同步属 coord 待办 #7，不阻塞 parent-bff） |
### 0.2 核查发现的问题（仲裁已裁决但文档未同步/执行有偏差）
以下问题均为"仲裁结论正确，但相关文档未同步"或"文档内部不一致"，提请 coord 确认处理方式。
---
## 问题列表
### ISSUE-001-ai05：01-understanding.md 未同步 ai05 接手与多项仲裁
- **提请方**：ai05
- **日期**：2026-07-10
- **类型**：文档同步缺失
- **描述**：01-understanding.md 头部仍标 "AI 标识：ai04"、"状态：待 coord 审核"，未反映 ai05 已正式接手（ai-allocation.md §3.2）。同时以下仲裁已裁决但 01 未同步：
- U3（GraphQL P2 引入）：01 §4.1 仍建议"P4 先对齐 teacher-bff REST 现状"，与 U3 仲裁冲突
- 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 仲裁
### ISSUE-002-ai05：02 文档内部 ChildGuard 缓存 TTL 不一致
- **提请方**：ai05
- **日期**：2026-07-10
- **类型**：文档内部不一致
- **描述**：02-architecture-design.md 内部 ChildGuard 绑定列表缓存 TTL 三处不一致：
- §3.1.1 Redis 缓存 Schema 表：写 "60s"（coord 推断原值）
- §9 #2 ai05 review 结论：调整为 "30s + 主动失效"
- §13 #7 黄金模板对齐表：写 "30s"
§3.1.1 表格未同步 §9 的调整，导致同一文档内 60s 与 30s 并存。
- **建议方案**：§3.1.1 表格 ChildGuard 行 TTL 改为 "30s"，与 §9 #2 + §13 #7 一致
- **状态**：待 coord 仲裁（ai05 建议直接修正，属于文档勘误）
### ISSUE-003-ai05：contract.md 仲裁引用编号错误（I3 → I6）
- **提请方**：ai05
- **日期**：2026-07-10
- **类型**：契约引用错误
- **描述**：contracts/parent-bff_contract.md §2.1 表格 + §3.1 引用 "I3/ISSUE-047 裁决" 作为 GetChildrenByParent 的仲裁依据。但核查 coord-final-decisions.md 发现：
- I3 是 "PermissionGuard 本地 map → DB 驱动" 裁决，与家长-学生关联无关
- I6 才是 "家长-学生关联：P2 即补全 iam_student_guardians 表 + GetChildrenByParent RPC" 裁决
- 全仓库未检索到 "ISSUE-047" 编号（grep 无结果），疑为虚构编号
- **建议方案**：contract.md 将 "I3/ISSUE-047 裁决" 修正为 "I6 裁决（coord-final-decisions.md §1）"
- **状态**：待 coord 仲裁（ai05 建议直接修正，属于引用勘误）
### ISSUE-004-ai05：004 §4 服务依赖图与 matrix.md §1 未同步 C6 仲裁
- **提请方**：ai05
- **日期**：2026-07-10
- **类型**：架构图未同步
- **描述**：C6 仲裁将 parent-bff 依赖扩展为 iam + core-edu + data-ana + msg，但：
- 004_architecture_impact_map.md §4 服务依赖图（line 376-377）仍只画 `PBFF --> IAM` + `PBFF --> CoreEdu`，未加 DataAna + Msg
- matrix.md §1 服务依赖矩阵（line 64-65）同样只画 `PBFF --> IAM` + `PBFF --> CORE`
- 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 仲裁
### ISSUE-005-ai05：parent-portal 01 文档与 parent-bff GraphQL 决策跨模块冲突
- **提请方**：ai05
- **日期**：2026-07-10
- **类型**：跨模块契约冲突
- **描述**：U3 仲裁决定 parent-bff P4 直接用 GraphQL（02 §4 已执行），但 parent-portal 01-understanding.md §3.1 仍按 REST 设计消费 parent-bff：
- parent-portal §3.1 列 `GET /parent/viewports`、`GET /parent/dashboard`、`GET /parent/children` 等 REST 端点
- parent-bff 02 §4.1 明确 "不实现 REST 业务端点（仅保留 /healthz /readyz /metrics）"
- parent-portal §3.1 还引用 `GET /iam/effective-permissions`（C4 仲裁已改为 `/iam/permissions/effective`）
- 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 仲裁
### ISSUE-006-ai05：proto 包名引用不一致（缺失 next_edu_cloud 前缀）
- **提请方**：ai05
- **日期**：2026-07-10
- **类型**：契约引用错误
- **描述**：02-architecture-design.md §3.3 DTO 映射表引用 proto message 为 `iam.v1.UserInfo`、`core_edu.v1.Grade[]`、`analytics.v1.StudentWeakness`、`msg.v1.Notification[]`。但实际 proto 文件包名均带 `next_edu_cloud.` 前缀：
- iam.proto: `package next_edu_cloud.iam.v1;`
- core_edu.proto: `package next_edu_cloud.core_edu.v1;`
- analytics.proto: `package next_edu_cloud.analytics.v1;`
- msg.proto: `package next_edu_cloud.msg.v1;`
引用不一致会导致 gRPC client 代码生成时 package 路径错误。
- **建议方案**：02 §3.3 DTO 映射表 proto message 列全部补 `next_edu_cloud.` 前缀；或确认是否统一去掉前缀（需 buf.yaml 配置一致）
- **状态**：待 coord 仲裁
### ISSUE-007-ai05：GraphQL Notification.childId 字段在 msg.proto 缺失
- **提请方**：ai05
- **日期**：2026-07-10
- **类型**：契约缺口
- **描述**：02 §4.2 GraphQL schema 定义 `Notification` type 含 `childId: ID` 字段（家长场景需知道通知关联哪个孩子）。但 msg.proto 的 Notification message 无 childId 字段：
```proto
message Notification {
string id = 1;
string user_id = 2;
string type = 3;
string title = 4;
string content = 5;
string channel = 6;
bool is_read = 7;
int64 created_at = 8;
}
```
parent-bff 无法从 msg 服务获取通知关联的孩子 ID，影响"按孩子过滤通知"场景。
- **建议方案**：coord 协调 ai10 在 msg.proto Notification message 补 `string child_id = 9;` 字段（可选，非家长通知为空）；或 parent-bff 从 notification.content 解析（脆弱，不推荐）
- **状态**：待 coord 仲裁
### ISSUE-008-ai05：core_edu.proto 缺 ClassService，02 §7.1 列为已有
- **提请方**：ai05
- **日期**：2026-07-10
- **类型**：契约缺口
- **描述**：02 §7.1 交互矩阵列 `core-edu ClassService.GetClass`（查孩子班级信息）状态为 "✅ 已有"。但核查 core_edu.proto 实际只有 ExamService / HomeworkService / GradeService 三个 service，无 ClassService。matrix.md §2 却声称 core-edu 有 "ClassService + ExamService + HomeworkService + GradeService + AttendanceService" 共 22 RPC。proto 与 matrix.md 不一致，且 02 错误标注为"已有"。
另：core_edu.proto 的 Grade.score 是 string 类型，02 GraphQL Grade.score 是 Float!，string→Float 转换规则未在 §3.3 说明。
- **建议方案**：
1. coord 确认 ClassService 归属（core-edu 还是 classes 服务），补 proto
2. 02 §7.1 ClassService.GetClass 状态从 "✅ 已有" 改为 "❌ 待补"
3. 02 §3.3 补 Grade.score string→Float 转换规则说明
- **状态**：待 coord 仲裁
### ISSUE-009-ai05：ai-allocation iam 责任方与 01/02 文档不一致
- **提请方**：ai05
- **日期**：2026-07-10
- **类型**：责任方引用过时
- **描述**：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 建议直接修正，属于引用勘误）
### ISSUE-010-ai05：02 缺少 ADR / NFR / 容量规划 / 威胁建模（业界规范差距）
- **提请方**：ai05
- **日期**：2026-07-10
- **类型**：架构文档规范缺失
- **描述**：对照业界通用架构文档规范（如 C4 model + ADR + NFR），02-architecture-design.md 存在以下规范差距：
1. **ADR 缺失**：虽有"已仲裁决策"表，但未按 ADR 格式（Context/Decision/Consequences）记录关键决策（如 GraphQL vs REST、ChildGuard 位置、多子女切换方案）。建议补 ADR 索引章节。
2. **NFR 未量化**：§10.4 P6 提"SLO 监控"，但文档前部未明确非功能性需求（P95 延迟、可用性、吞吐量目标）。业界规范要求架构文档开头列 NFR。
3. **容量规划缺失**：未估算家长端 QPS、并发数、数据量（家长数 × 孩子数 × 成绩数），无法指导 HPA 副本数和 Redis 容量规划。
4. **安全威胁建模缺失**：§6.2 列错误码但未做威胁建模（STRIDE）。家长场景涉及未成年人数据（COPPA/FERPA/PIPL），应补威胁模型。
5. **数据流图（DFD）缺失**：§1.2 只有 Dashboard 时序图，缺少 DFD 展示数据跨信任边界流动。
- **建议方案**：coord 确认是否在 02 补全上述章节，或作为 P6 硬化阶段补全；当前不阻塞 P4 实施
- **状态**：待 coord 仲裁
---
<!--
追加条目格式：
@@ -20,5 +177,3 @@
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
（暂无问题）

189
docs/architecture/issues/objections/parent-portal_issue.md
View File

@@ -6,6 +6,33 @@
---
## §0 已有仲裁核查（ai15 复核 ARB-001 / ARB-002 落地情况）
> ai15 接管 parent-portal 后，核查 coord 已发布的两项仲裁（ARB-001 teacher-bff GraphQL schema、ARB-002 MF Shell 暴露清单）在 parent-portal 文档中的落地情况。
### 0.1 ARB-001（teacher-bff GraphQL schema 第一版）核查
| 核查项 | ARB-001 结论 | parent-portal 落地情况 | 状态 |
| ------ | ------------ | ---------------------- | ---- |
| BFF 用 GraphQL（非 REST） | ✅ 已裁决 GraphQL | 01-understanding §3.1 + 02-architecture-design §4.1 全部描述为 REST 消费 | ❌ 未落地 |
| ActionState 信封 | ✅ 已裁决 | 01 §3.2 已对齐 | ✅ |
| 错误码前缀路由 | ✅ 已裁决 | 01 §3.2 + 02 §6.2 已对齐 | ✅ |
**结论**：ARB-001 的核心裁决（BFF = GraphQL）在 parent-portal 的 01/02 文档中**未落地**，01 §3.1 与 02 §4.1 仍按 REST 编写，与 [parent-bff_contract.md](../contracts/parent-bff_contract.md) §1.3（GraphQL 端点 :3010）和 [matrix.md](../matrix.md) §3（parent-bff GraphQL）直接冲突。提请 ISSUE-001。
### 0.2 ARB-002（MF Shell 暴露清单）核查
| 核查项 | ARB-002 结论 | parent-portal 落地情况 | 状态 |
| ------ | ------------ | ---------------------- | ---- |
| Shell 暴露 GraphQLProvider | ✅ 已裁决 | 01 §4 技术栈未列 urql/GraphQL client；02 §4.1 用 `useApi()`（REST ApiClient）而非 `useGraphQLClient()` | ❌ 未落地 |
| MF shared 含 urql/graphql/@edu/* | ✅ 已裁决 | 02 §1.2 `shared` 仅列 react/react-dom/@tanstack/react-query/zustand/nuqs，缺 urql/graphql/@edu/ui-tokens/@edu/ui-components/@edu/hooks | ❌ 未落地 |
| Shell 暴露 AppShell | ✅ 已裁决 | 01 §9.1 + 02 §7.1 已对齐 | ✅ |
| feature flag NEXT_PUBLIC_MF_ENABLED | ✅ 已裁决 | 01/02 均未提及 | ❌ 未落地 |
**结论**：ARB-002 关于 GraphQL client 与 MF shared 的裁决在 parent-portal 文档中**部分未落地**。提请 ISSUE-002。
---
## 问题列表
<!--
@@ -21,4 +48,164 @@
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
（暂无问题）
### ISSUE-001-ai15：01/02 文档 REST 消费 parent-bff 与 ARB-001 GraphQL 裁决冲突
- **提请方**：ai15
- **日期**：2026-07-10
- **类型**：契约不明确（文档与已裁决架构冲突）
- **描述**：
- 01-understanding.md §3.1 列出 parent-portal 经 REST 消费 parent-bff：`GET /parent/viewports`、`GET /parent/children`、`POST /parent/children/:childId/select`、`GET /parent/notifications`、`PUT /parent/notification-preferences` 等
- 02-architecture-design.md §4.1 `useParentApi` 实现全部基于 `api.get()`/`api.post()` REST 调用
- 但 ARB-001（coord.md §1）已裁决 BFF 用 GraphQL；[parent-bff_contract.md](../contracts/parent-bff_contract.md) §1.3 明确 parent-bff 提供 `POST /graphql`（:3010）；[matrix.md](../matrix.md) §3 确认 parent-bff = GraphQL
- parent-portal 自己的 [contract.md](../contracts/parent-portal_contract.md) §2.3-2.4 也写明消费 GraphQL（`POST /api/parent/graphql`，Query 域：currentUser/myChildren/childSummary/childGrades 等）
- **文档内部自相矛盾**：01/02 用 REST，contract.md 用 GraphQL
- **建议方案**：
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 仲裁
### ISSUE-002-ai15：MF shared 配置缺 urql/graphql/@edu/* 与 ARB-002 冲突
- **提请方**：ai15
- **日期**：2026-07-10
- **类型**：契约不明确（文档与已裁决 MF 配置冲突）
- **描述**：
- 02-architecture-design.md §1.2 MF `shared` 配置仅列：`react`、`react-dom`、`@tanstack/react-query`、`zustand`、`nuqs`
- ARB-002（coord.md §2）裁决的 `shared` 应包含：`react`、`react-dom`、`urql`、`graphql`、`@edu/ui-tokens`、`@edu/ui-components`、`@edu/hooks`
- 缺失 `urql`/`graphql` 会导致 Remote 与 Shell 各加载一份 GraphQL client 实例，破坏单例，引发缓存不一致与重复请求
- 缺失 `@edu/*` 会导致设计令牌/UI 组件/Hooks 各加载一份
- 同时 01 §4 技术栈表未列 GraphQL client（urql），与 ARB-002 Shell 暴露 GraphQLProvider 矛盾
- **建议方案**：
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 仲裁
### ISSUE-003-ai15：switch-child 端点在 01/02 文档间不一致
- **提请方**：ai15
- **日期**：2026-07-10
- **类型**：契约不明确（文档内部不一致）
- **描述**：
- 01-understanding.md §3.1 列 `POST /parent/children/:childId/select`
- 02-architecture-design.md §2.2 + §4.1 用 `POST /api/v1/parent/switch-child`（body 携带 childId）
- 两处路径与语义均不一致（URL param vs body param）
- parent-bff contract.md 未列 switch-child（其 §1.3 仅列 Query/Mutation 域，未细到 switch-child）
- **建议方案**：
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 仲裁
### ISSUE-004-ai15：登录端点在 01 / contract.md / matrix.md 间三方不一致
- **提请方**：ai15
- **日期**：2026-07-10
- **类型**：契约不明确（跨文档不一致）
- **描述**：
- 01-understanding.md §3.1 列 `POST /iam/login`
- parent-portal_contract.md §2.3 列 `POST /api/auth/login`
- matrix.md §5 规范 iam 经 api-gateway 代理路径为 `/api/v1/iam/*`
- 三处不一致，且 contract.md 的 `/api/auth/login` 路径在 matrix.md 中不存在
- **建议方案**：
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 仲裁
### ISSUE-005-ai15：02 §11.3 未决设计决策 #2 "GraphQL vs REST" 已由 ARB-001 裁决，应移除
- **提请方**：ai15
- **日期**：2026-07-10
- **类型**：其他（文档过时）
- **描述**：
- 02-architecture-design.md §11.3 第 2 项将 "GraphQL vs REST" 列为未决设计决策，建议 "P4 用 REST，后续若 BFF 切 GraphQL 再引入 urql"
- 但 ARB-001（coord.md §1）已于 2026-07-09 裁决 BFF 用 GraphQL，且 parent-bff contract.md 确认 GraphQL
- 此项已过时，会误导后续开发
- **建议方案**：
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 仲裁
### ISSUE-006-ai15：contract.md §1.2 将前端页面路由误标为 HTTP 端点
- **提请方**：ai15
- **日期**：2026-07-10
- **类型**：其他（文档分类错误）
- **描述**：
- parent-portal_contract.md §1.2 "HTTP 端点" 列出：`GET /`、`GET /children`、`GET /child/:id/summary`、`GET /child/:id/grades` 等
- 但 parent-portal 是 Next.js 前端应用，这些是**前端页面路由**（SSR/CSR 路由），不是对外 HTTP API 端点
- 将页面路由放在 "HTTP 端点" 表中会误导下游消费方以为这些是 REST API
- 且这些路由与 01 §8 L2 路由表（`/parent/dashboard`、`/parent/children` 等）路径还不一致（contract 用 `/children`，01 用 `/parent/children`）
- **建议方案**：
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 仲裁
### ISSUE-007-ai15：contract.md §1.6 module-federation.config.ts 与 02 next.config.js 不一致
- **提请方**：ai15
- **日期**：2026-07-10
- **类型**：其他（文档内部不一致）
- **描述**：
- parent-portal_contract.md §1.6 列 MF 配置文件为 `apps/parent-portal/module-federation.config.ts`
- 02-architecture-design.md §1.2 MF 配置写在 `next.config.js` 中（用 `NextFederationPlugin`）
- 两处文件名与位置不一致
- **建议方案**：
1. 统一为 `apps/parent-portal/next.config.js`（与 02 + teacher-portal Shell 一致，Next.js 项目 MF 配置应在 next.config.js）
2. ai15 修订 contract.md §1.6
- **状态**：待 coord 仲裁
### ISSUE-008-ai15：contract.md §2.3 GraphQL 路径前缀与 matrix.md 不一致
- **提请方**：ai15
- **日期**：2026-07-10
- **类型**：契约不明确（跨文档不一致）
- **描述**：
- parent-portal_contract.md §2.3 列 `POST /api/parent/graphql`
- matrix.md §5 规范 api-gateway 代理 parent-bff 路径为 `/api/v1/parent/*`
- 缺 `v1` 版本号
- **建议方案**：
1. 统一为 `POST /api/v1/parent/graphql`（与 matrix.md §5 一致）
2. ai15 修订 contract.md §2.3 + §2.4
- **状态**：待 coord 仲裁
### ISSUE-009-ai15：parent-bff GraphQL schema 是否包含 switchChild Mutation 未明确
- **提请方**：ai15
- **日期**：2026-07-10
- **类型**：前置依赖缺失（上游契约不全）
- **描述**：
- parent-bff_contract.md §1.3 列出的 Query/Mutation 域未包含 "switchChild"（切换当前选中子女）
- 01-understanding.md §2.2 + 02 §2.2 描述 parent-portal 需调用 `POST /parent/switch-child` 切换子女
- 若走 GraphQL（依 ISSUE-001），parent-bff 需提供 `mutation switchChild(childId: ID!): SwitchChildPayload!`
- 但 parent-bff contract 未列此 Mutation，且 iam.GetChildrenByParent 已返回子女列表，切换子女是否需后端记录（还是纯前端 localStorage）需明确
- **建议方案**：
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 仲裁
### ISSUE-010-ai15：iam GetChildrenByParent 接口缺失（P0 阻塞，跨模块）
- **提请方**：ai15
- **日期**：2026-07-10
- **类型**：前置依赖缺失（跨模块，承自 parent-bff §7.1）
- **描述**：
- 01-understanding.md §3.1 注明：iam 缺失 "家长-学生关联查询" 接口（`GetChildrenByParent` proto + `GET /iam/children` REST + `iam_student_guardians` 表三缺失）
- parent-bff_contract.md §2.1 也标注 "核心依赖 I3/ISSUE-047 裁决"
- parent-bff_contract.md §3.1 标注 "iam gRPC 50052 启用（ai06）—— 核心依赖 GetChildrenByParent（I3/ISSUE-047 裁决）"
- 此为 parent-portal 多子女场景的 P0 阻塞项，ai06（iam）需在 P3 收尾前补全
- ai15 在此提请，请 coord 跟踪 ai06 进度并确认补全时间点
- **建议方案**：
1. coord 确认 ai06 补全 `GetChildrenByParent` 的时间点（应在 P4 启动前）
2. 在补全前，parent-portal 用 mock（固定 2 个子女）开发，mock 数据与 parent-bff mock 一致（student-001 + student-002）
- **状态**：待 coord 仲裁
---
## §1 已裁决问题
（暂无已裁决问题）

169
docs/architecture/issues/objections/push-gateway_issue.md
View File

@@ -1,24 +1,167 @@
# push-gateway 问题记录
> 负责人：ai02
> 关联：[coord.md](../coord.md)、[contracts/push-gateway_contract.md](../contracts/push-gateway_contract.md)
> 关联：[coord.md](../coord.md)、[contracts/push-gateway_contract.md](../contracts/push-gateway_contract.md)、[push-gateway 02 架构设计](../../../services/push-gateway/docs/02-architecture-design.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态
---
## 问题列表
## §0 已有仲裁核查（ai02 复审 02 文档对总裁裁决的回写情况）
<!--
追加条目格式：
> 本节为 ai02 在批次 0 等待期对 president-final-rulings 已裁决事项的回写核查。
> 裁决来源：[president-final-rulings.md](../../president-final-rulings.md) §1.5 / §3.3 / §4.2 / §4.3 / §4.4 / §7.2 / §3.4
> 核查日期：2026-07-10
> 核查结论：5 项裁决中 **0 项已完全回写**、**1 项部分回写**、**4 项未回写**
### ISSUE-[编号]-[AI标识]：[标题]
### 核查矩阵
- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
| 裁决编号 | 主题 | 裁决要求（摘要） | 02 文档现状 | 核查结论 | 状态 |
| -------- | ---- | ---------------- | ----------- | -------- | ---- |
| ISSUE-053 | Kafka topic 命名 | 02 §5.1 topic 改为 `edu.notification.requested`，禁止抽象名 `edu.*.events` | §5.1 仍写 `edu.notification.events` / `NotificationRequested` | ❌ 未回写 | 待 ai02 修复 |
| ISSUE-055 | /readyz 软失败 | push-gateway /readyz 对 Kafka 软失败（失败仅告警 + `degraded: true` + 返 200，不返 503） | §6.7 仅 Redis PING 硬失败返 503，无 Kafka 软失败逻辑 | ❌ 未回写 | 待 ai02 修复 |
| ISSUE-056 | 设计决策记录章节 | 02 §5.4 改名为"设计决策记录：gRPC vs HTTP 协议选型（coord 已采纳 P1）"，正文标注"coord 已采纳" | 02 无"设计决策记录"章节 | ❌ 未回写 | 待 ai02 修复 |
| ISSUE-058 | Redis SET 启动重建 | 02 §3.1 补充"Hub 启动时遍历内存连接 SADD + EXPIRE 60s + 清空旧 instanceID 成员"；/readyz Redis 失败仅告警不阻塞；metrics 暴露 `push_gateway_redis_set_rebuild_total`；文档化 60s 不一致窗口 | §3.1/§8.4 仅描述运行期 SADD/SREM，无启动重建；§6.7 Redis 硬失败返 503（与"仅告警不阻塞"冲突）；无重建指标；无 60s 窗口说明 | ❌ 未回写 | 待 ai02 修复 |
| ARB /internal/push 契约（§4.2） | 第一版 /internal/push 契约 | coord "as-is" 采纳 ai02 02 §4.2 作为第一版契约，仅在 ai10 异议时调整 | 02 §4.2 已定义 `{user_id, event, data, ttl?}` → `{success, delivered, online}` | ✅ 已落地 | 无需动作 |
（暂无问题）
### 核查结论
- **ISSUE-053/055/056/058 共 4 项须 ai02 在批次 4 启动前回写到 02 文档**（president-final-rulings §3.4 明确"批次 4 启动前"完成回写）
- **ARB /internal/push 契约已落地**，无需动作；但 ai10 若提出异议（如 batch 接口/异步回调），coord 会公布差异点
- ISSUE-058 中"/readyz Redis 失败仅告警不阻塞"与 ISSUE-055"软失败规则"形成耦合：Redis 作为 push-gateway 必需依赖本应硬失败，但 ISSUE-058 裁决要求"仅告警不阻塞"以避免雪崩 —— **此耦合需 coord 明确优先级**（见下方 ISSUE-006-ai02）
---
## §1 问题列表（提请 coord 仲裁）
### ISSUE-001-ai02：SSE 端点是否提供（跨文档三方冲突）
- **提请方**：ai02
- **日期**：2026-07-10
- **类型**：契约不明确
- **描述**：SSE 端点（`/sse`）在三个文档中存在冲突：
- [push-gateway_contract.md](../contracts/push-gateway_contract.md) §1.2 列出 `GET /sse` 端点，认证 JWT
- [matrix.md](../matrix.md) §5 HTTP 接口矩阵列出 `push-gateway (ai02) | SSE | /sse`
- [02-architecture-design.md](../../../services/push-gateway/docs/02-architecture-design.md) §10 明确建议"不支持 SSE，WebSocket 已够用，避免协议膨胀"
- 01-understanding.md 完全未提及 SSE
- 实际代码无 `/sse` 实现，`gin-contrib/sse` 仅为 gin 间接依赖
- **建议方案**：采纳 02 文档建议 —— **push-gateway 不提供 SSE，仅 WebSocket**。理由：
1. 单一协议降低维护成本与测试矩阵
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 仲裁
### ISSUE-002-ai02：内部 API 鉴权命名三方不一致
- **提请方**：ai02
- **日期**：2026-07-10
- **类型**：契约不明确
- **描述**：内部 API 鉴权头与环境变量在四处不一致：
- **代码**（[handler.go#L30](../../../services/push-gateway/internal/ws/handler.go#L30) + [config.go#L41](../../../services/push-gateway/internal/config/config.go#L41)）：`X-Internal-Key` 头 + `INTERNAL_API_KEY` 环境变量
- **02 文档** §4.2/§6.1：`X-Internal-Token` 头 + `INTERNAL_API_TOKEN` 环境变量
- **ai-allocation.md** §5：`X-Internal-Key`
- **president-final-rulings.md** §7.2："X-Internal-Token 重命名"（暗示应改为 Token）
- **contract.md** §1.2：`内网 mTLS`（第四种方案！）
- **建议方案**：统一为 `X-Internal-Token` + `INTERNAL_API_TOKEN`（对齐总裁裁决 §7.2）。理由：
1. 总裁裁决已明确倾向 Token 命名
2. "Token"语义比"Key"更准确（共享密钥而非公私钥对）
3. mTLS 在 P5 阶段引入成本过高，且 K8s 内网已有 NetworkPolicy 隔离，共享密钥足够
- **影响方**：ai10（msg 调用方需用相同头名）、coord（更新 contract.md 与 matrix.md §5 移除 mTLS）
- **状态**：待 coord 仲裁
### ISSUE-003-ai02：单节点容量目标 50k vs 10w+ 冲突
- **提请方**：ai02
- **日期**：2026-07-10
- **类型**：契约不明确
- **描述**：单节点最大连接数目标在两份文档冲突：
- [modules/push-gateway/README.md](../../../docs/modules/push-gateway/README.md) §7："单节点最大连接数 50k，超出时拒绝新连接"
- [02-architecture-design.md](../../../services/push-gateway/docs/02-architecture-design.md) §11："单实例最大连接数 10w+"
- [01-understanding.md](../../../services/push-gateway/docs/01-understanding.md) §5 引用 pending-features："单节点支撑 10w+ 连接"
- **建议方案**：统一为 **10w+**（对齐 02 文档与 pending-features）。理由：
1. 10w+ 是 P5 设计目标（pending-features 权威）
2. Go goroutine-per-connection + 64KB send chan 单连接约 20-30KB，10w 连接约 2-3GB，单节点可承载
3. 50k 目标过于保守，与横向扩展方案不匹配
- **影响方**：coord（更新 modules/README.md §7）、ai02（02 §11 已正确）
- **状态**：待 coord 仲裁
### ISSUE-004-ai02：contract.md 内部端点路径 /internal/send vs /internal/push 冲突
- **提请方**：ai02
- **日期**：2026-07-10
- **类型**：契约不明确
- **描述**：内部单推端点路径在 contract.md 与代码/02 文档冲突：
- [contract.md](../contracts/push-gateway_contract.md) §1.2 + §2.4：`POST /internal/send`
- **代码**（[main.go#L58](../../../services/push-gateway/main.go#L58)）+ **02 文档** §4.2：`POST /internal/push`
- 总裁裁决 §4.2 已"as-is 采纳 ai02 02 §4.2"，即应使用 `/internal/push`
- **建议方案**：contract.md 统一改为 `POST /internal/push`（对齐总裁裁决与代码）。此为 ai02 自主回写范畴，不需 coord 仲裁动作，仅在此登记以便 coord 复核。
- **状态**：ai02 自行修复（见 contracts 回写）
### ISSUE-005-ai02：审计表（6 字段）设计缺失
- **提请方**：ai02
- **日期**：2026-07-10
- **类型**：契约不明确
- **描述**：[ai-allocation.md](../../ai-allocation.md) §5 将"审计表（6 字段）"列为 ai02 设计重点，但：
- 01-understanding.md §2 明确"不持有业务状态""无 DB"
- 02-architecture-design.md §3 明确"无数据库。所有状态在内存 + Redis"
- 两份文档均无审计表设计
- **疑问**：审计表是否要求 push-gateway 引入 MySQL/PostgreSQL？这与"无 DB"定位冲突。可能的解读：
1. push-gateway 引入轻量审计表（如 SQLite/Redis Stream 持久化推送记录）
2. 审计表由 msg 服务维护（msg 已落库），push-gateway 仅通过 Kafka 事件回流
3. ai-allocation 表述过度，审计需求由 msg 满足
- **建议方案**：方案 2（审计由 msg 维护，push-gateway 仅同步返结果）。理由：保持 push-gateway 无 DB 定位，避免引入持久化层增加运维复杂度。
- **影响方**：ai10（msg 需确认审计字段是否覆盖 push-gateway 推送结果）、coord（澄清 ai-allocation §5 表述）
- **状态**：待 coord 仲裁
### ISSUE-006-ai02：ISSUE-058 与 ISSUE-055 对 Redis /readyz 失败策略耦合冲突
- **提请方**：ai02
- **日期**：2026-07-10
- **类型**：契约不明确
- **描述**：两份裁决对 push-gateway /readyz Redis 检查失败的策略存在表述冲突：
- **ISSUE-055**（[president §3.3](../../president-final-rulings.md)）：将 Redis 列为"必需依赖"，失败返 503 触发 Pod 重启
- **ISSUE-058**（[president §4.3](../../president-final-rulings.md)）："/readyz Redis 检查失败时仅告警不阻塞，与 ISSUE-055 协调，避免雪崩"
- **冲突点**：Redis 是 push-gateway 跨实例广播的必需依赖（必需 → 503），但实例重启不能恢复 Redis 故障，且重启会丢失本地连接表加剧雪崩（应仅告警）
- **建议方案**：明确为 **Redis 软失败**（仅告警 + `degraded: true` + 返 200），从 ISSUE-055 必需依赖列表中移除 push-gateway → Redis。理由：
1. push-gateway 重启不解决 Redis 故障
2. Redis 故障时单实例仍能服务本地连接（仅跨实例广播失效）
3. 雪崩风险高于短暂不一致
- **影响方**：coord（澄清两裁决优先级）
- **状态**：待 coord 仲裁
### ISSUE-007-ai02：02 文档缺 ADR / 非功能性需求 / 失败模式章节（不符业界架构文档规范）
- **提请方**：ai02
- **日期**：2026-07-10
- **类型**：工作量超批
- **描述**：02-architecture-design.md 不符合业界架构文档规范（arc42 / C4 模型）：
1. **无 ADR 章节**：[modules/push-gateway/README.md](../../../docs/modules/push-gateway/README.md) §8 提到"待 P5 交付时补充 ADR 记录"，但 02 文档未落地。关键决策（gorilla/websocket 选型、Redis Pub/Sub vs Stream、心跳间隔 30s/60s 选型、10w 容量依据）无 ADR
2. **无非功能性需求章节**：无可用性 SLO（如 99.9%）、安全合规、容量 SLA
3. **无失败模式/混沌工程章节**：实例崩溃、Redis 故障、网络分区、Kafka 消费积压场景下的降级策略缺失
4. **§11 容量表无依据**：10w 连接的内存/CPU/网络带宽估算缺失
- **建议方案**：在批次 4（P5）补全 02 文档 §14-§17 四个章节（ADR / 非功能性需求 / 失败模式 / 容量估算）。预估工作量：1-1.5 天。
- **影响方**：ai02（自主补全）
- **状态**：待 coord 确认是否纳入 P5 Must Have
---
## §2 已自主修复的文档偏差（ai02 直接修复，不需 coord 仲裁）
> 以下为 01-understanding.md 与现码不符的偏差，ai02 在批次 0 自主修复
| # | 位置 | 偏差 | 修复方向 |
| - | ---- | ---- | -------- |
| 1 | 01 §3.2 | `/readyz` 标"无（待实现）"，实际已实现（仅未检查 Redis） | 改为"已实现，仅返连接数，待补 Redis PING" |
| 2 | 01 §3.2 | `/metrics` 标"无（待实现）"，实际已挂载 promhttp | 改为"已实现，待补自定义指标" |
| 3 | 01 §3.2 | `/internal/push` `/internal/broadcast` 标"待补鉴权"，实际已实现 X-Internal-Key | 改为"已实现 X-Internal-Key 校验（DevMode 跳过）" |
| 4 | 01 §6 + §7 | Dockerfile 标"❌ 单阶段"，实际为多阶段（缺非 root/healthcheck/ldflags） | 改为"⚠️ 多阶段但缺非 root + healthcheck + ldflags" |
| 5 | 01 §7.1 #6 | 引用 `main.go L44-46` 行号过期，鉴权状态错误 | 更新行号并改为"已实现" |
| 6 | 01 全文 | 未提及 SSE 端点（contract.md/matrix.md 列出但 02 建议不支持） | 待 ISSUE-001 仲裁后补充结论 |
| 7 | 01 全文 | 未提及审计表（ai-allocation §5 设计重点） | 待 ISSUE-005 仲裁后补充 |
---
## §3 历史问题
（暂无）

223
docs/architecture/issues/objections/student-bff_issue.md
View File

@@ -1,24 +1,221 @@
# student-bff 问题记录
> 负责人：ai04
> 关联：[coord.md](../coord.md)、[contracts/student-bff_contract.md](../contracts/student-bff_contract.md)
> 关联：[coord.md](../coord.md)、[contracts/student-bff_contract.md](../contracts/student-bff_contract.md)、[matrix.md](../matrix.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态
> 仲裁依据：[coord-final-decisions.md](../../coord-final-decisions.md) §2 BFF 专项裁决（B1-B8）、[president-final-rulings.md](../../president-final-rulings.md)
---
## 问题列表
## §0 已有仲裁核查总结（2026-07-10 审查）
<!--
追加条目格式：
> 本次审查对历史 issues.md 中 ai04 提请的 4 项问题（ISSUE-028/029/030/031-ai04）逐一核查总裁裁决落地情况。
### ISSUE-[编号]-[AI标识]：[标题]
| 编号 | 主题 | 总裁裁决章节 | 裁决要点 | 核查结果 |
| ---- | ---- | ------------ | -------- | -------- |
| ISSUE-028-ai04 | 02 文档与 B1+B2 裁决冲突需回写 | president §3.4 | ai04 须在批次 2 启动前回写 student-bff 02：B1 GraphQL + B2 gRPC + B8 DownstreamClient | ⚠️ **未执行**：02-architecture-design.md 仍为 REST 设计（§4 21 个 REST 端点 / §9.2 REST→GraphQL 演进 / §9.3 HTTP→gRPC 演进），违反 B1、B2 |
| ISSUE-029-ai04 | P3 启动前置依赖确认（4 项强阻塞） | president §4.1 / §6.1 | 批次 0 完成信号机制 + 批次 2 启动条件：批次 1 P2.1 完成 + ai03 DownstreamClient 抽象就绪 | ✅ **已裁决**：批次时间线 §6.1 明确批次 2 启动条件；前置依赖检查清单机制已建立 |
| ISSUE-030-ai04 | student-bff GraphQL schema 第一版仲裁时机 | president §2.2 | ai04 起草 schema（批次 1 等待期），coord 在批次 2 启动前仲裁第一版；存放 `packages/shared-ts/contracts/graphql/student-bff.schema.graphql` | ✅ **已裁决**：schema 仲裁机制已建立（§2.2）；但 schema 第一版尚未起草，需 ai04 在批次 1 等待期产出 |
| ISSUE-031-ai04 | issues.md 编号冲突 | president §0.4 | 保留原始内容不删除，用 `ISSUE-XXX-<提请AI>` 格式唯一定位，不重新编号 | ✅ **已裁决**：编号规则已生效，本文件即按新流程在 objections/ 下维护 |
- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
### 0.1 核查结论
（暂无问题）
- **唯一未落地项**：ISSUE-028-ai04（02 文档回写）。02-architecture-design.md 当前内容与 B1/B2/B8 裁决严重冲突，须在批次 2 启动前完成回写。
- **schema 第一版未起草**：ISSUE-030-ai04 虽已建立仲裁机制，但 ai04 尚未产出 student-bff GraphQL schema 草案，需在批次 1 等待期完成。
- **01-understanding.md 同步问题**：阶段 1 文档同样存在 REST 假设与错误码前缀错误（详见 §2），需与 02 文档一并修正。
---
## §1 待 coord 仲裁的新问题（本次审查发现）
### ISSUE-STU-001-ai04：01-understanding.md 与 B1/B2/B5 裁决冲突
- **提请方**：ai04
- **日期**：2026-07-10
- **类型**：裁决冲突（文档未回写）
- **描述**：阶段 1 文档 `services/student-bff/docs/01-understanding.md` 存在 3 项与已裁决规则的冲突：
1. **B1 冲突（API 风格）**：§3.2 暴露 14 个 REST 端点（`/student/dashboard` 等）；§4 / §4.1 明确"先对齐 teacher-bff 现状（REST + fetch）"，建议"P3 阶段先 REST，后续统一升级 GraphQL"。与 B1"P2 起直接 GraphQL"冲突，属禁止的"中间过渡方案"。
2. **B2 冲突（下游通信）**：§3.1 表述"BFF→Service 走 HTTP fetch（当前阶段）"；§4 技术栈"HTTP fetch（当前阶段，对齐 teacher-bff 模式）"。与 B2"首次实现即 gRPC 调用下游"冲突。
3. **B5 冲突（错误码前缀）**：§3.3 / §6 表格用 `STUDENT_BFF_` 前缀。与 B5"统一 BFF_ 前缀（BFF_TEACHER_ / BFF_STUDENT_ / BFF_PARENT_）"冲突。
- **建议方案**：与 ISSUE-028-ai04 合并处理，01 文档随 02 文档一并回写：
- 删除 REST 端点清单，改为 GraphQL Query/Mutation 清单
- 删除"HTTP fetch 对齐 teacher-bff 现状"表述，改为"gRPC 调用下游（@grpc/grpc-js + @bufbuild/protobuf）"
- 错误码前缀统一为 `BFF_STUDENT_`
- §7.2"待 coord 仲裁"项中，B1/B2/B3/B5/B6/B7 已裁决，删除重复提请
- **状态**：待 coord 确认回写范围（是否 01 文档也纳入回写义务）
### ISSUE-STU-002-ai04：02-architecture-design.md 引用不存在的 004 章节
- **提请方**：ai04
- **日期**：2026-07-10
- **类型**：契约不明确（文档引用错误）
- **描述**：02-architecture-design.md 多处引用"004 §11.4 错误码前缀矩阵"和"004 §11.5 统一响应信封 ActionState"，但实际 004_architecture_impact_map.md §11 仅包含：
- §11.1 Protobuf 契约体系
- §11.2 契约规则
- §11.3 BFF 聚合模式
- **不存在 §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 仲裁
### ISSUE-STU-003-ai04：02 文档 §8.3 列 12 项未决决策，其中 8 项已裁决
- **提请方**：ai04
- **日期**：2026-07-10
- **类型**：裁决冲突（文档未回写）
- **描述**：02-architecture-design.md §8.3"未决设计决策（待 coord 仲裁）"列出 12 项，但其中 8 项已被 coord-final-decisions §2 裁决：
| # | 决策点 | 02 文档建议 | 已裁决结论 | 裁决章节 |
| --- | ------ | ----------- | ---------- | -------- |
| 1 | BFF API 风格 | A（P3 REST） | **B1：P2 起直接 GraphQL** | coord-final-decisions §2 B1 |
| 2 | BFF 是否做权限校验 | A（不校验） | **B3：BFF 豁免 @RequirePermission** | coord-final-decisions §2 B3 |
| 3 | 自我越权防御 | B（做） | **B4：全部 BFF 强制自我越权防御** | coord-final-decisions §2 B4 |
| 4 | /readyz 检查逻辑 | A（P3 直接 ok） | **G2 + §2.4：按阶段扩展探针，必需依赖失败 503，可选依赖软失败** | president §2.4 |
| 5 | Kafka 事件订阅时机 | A（P3 不订阅） | **B7：P2-P4 不订阅 Kafka，P5 后订阅** | coord-final-decisions §2 B7 |
| 6 | 缓存策略 | B（Redis 5-30s） | **B6：Redis 5-30s 短缓存** | coord-final-decisions §2 B6 |
| 8 | 错误码前缀 | BFF_STUDENT_ | **B5：BFF_STUDENT_** | coord-final-decisions §2 B5 |
| 9 | DownstreamClient 回写 | B（回写） | **B8：回写 teacher-bff，3 个 BFF 统一** | coord-final-decisions §2 B8 |
仅剩 #7（端口 3009）、#10（CQRS 不引入）、#11（SSE 实现）、#12（熔断器引入）属合理的设计决策，但 #12 熔断器 president §2.4 已暗示按阶段评估。
- **建议方案**：02 文档回写时删除已裁决项的"待仲裁"标注，改为"已裁决（见 coord-final-decisions §2 BX）"
- **状态**：待 coord 确认（与 ISSUE-028-ai04 合并处理）
### ISSUE-STU-004-ai04：student-bff GraphQL schema 第一版尚未起草
- **提请方**：ai04
- **日期**：2026-07-10
- **类型**：前置依赖缺失
- **描述**：president §2.2 裁决"ai04 起草 student-bff schema（批次 1 等待期），coord 在批次 2 启动前仲裁第一版"。当前批次 1 已启动（2026-07-10），ai04 处于批次 1 等待期，但 schema 草案尚未产出。02-architecture-design.md 仍是 REST 设计，未定义 GraphQL Query/Mutation/Type。
- **影响**：阻塞 ai14（student-portal）P3 启动（依赖 schema 契约）；阻塞 coord 批次 2 启动前仲裁
- **建议方案**：ai04 在批次 1 等待期优先产出 student-bff GraphQL schema 草案，存放 `packages/shared-ts/contracts/graphql/student-bff.schema.graphql`，提交 coord 仲裁
- **状态**：ai04 自行执行（非 coord 仲裁项），记录待办
---
## §2 01-understanding.md 审查详情
### 2.1 准确性问题
| 位置 | 问题 | 严重度 |
| ---- | ---- | ------ |
| §1 通信方式（入/出） | 表述"HTTP REST（当前阶段）/ HTTP fetch（当前阶段）"，实际 B1/B2 裁决为 GraphQL + gRPC | 高 |
| §3.1 表格 | 列"当前 REST 端点（实际可用）"列，暗示走 REST，但 BFF 是新服务不存在"当前 REST 现状" | 高 |
| §3.2 端点表 | 14 个 REST 端点，违反 B1 GraphQL | 高 |
| §3.3 错误码前缀 | `STUDENT_BFF_` 违反 B5 `BFF_STUDENT_` | 中 |
| §4 技术栈 API 风格 | "HTTP REST（当前阶段）"，违反 B1 | 高 |
| §6 权限装饰器 | "⚠️ 不对齐"结论正确（B3 豁免），但理由应补充"已裁决 B3" | 低 |
| §7.2 决策点 1-5 | 列为"待 coord 仲裁"，但 B1/B2/B3/B5/B6/B7 均已裁决 | 高 |
### 2.2 遗漏项
| 遗漏内容 | 应补充位置 | 依据 |
| -------- | ---------- | ---- |
| GraphQL schema 设计意图（Query/Mutation/Type） | §3.2 | B1 + president §2.2 |
| gRPC 下游调用设计（@grpc/grpc-js + @bufbuild/protobuf） | §3.1 / §4 | B2 |
| DataLoader 防 N+1 策略 | §4 | 004 §11.3 + B1 |
| B4 自我越权防御（userId 强制比对） | §2.3 / §3 | B4 |
| B8 DownstreamClient 抽象（复用 teacher-bff） | §4 / §6 | B8 |
| GraphQL schema 存放路径 `packages/shared-ts/contracts/graphql/student-bff.schema.graphql` | §3.2 | president §2.2 |
| GraphQL errors 数组 + extensions.code + extensions.traceId 错误格式 | §3.3 | president §2.2 #5 |
| Relay Cursor Connections 分页规范 | §3.2 | president §2.2 #5 |
---
## §3 02-architecture-design.md 审查详情
### 3.1 架构合理性评估
| 维度 | 评估 | 说明 |
| ---- | ---- | ---- |
| 分层设计（§1） | ✅ 合理 | Controller → Service → Aggregator → Cache → DownstreamClient 五层清晰，DownstreamClient/Aggregator/Transformer 抽象优于 teacher-bff 现状，符合 B8 |
| 领域模型（§2） | ✅ 合理 | "场景聚合视图"概念恰当，BFF 无领域模型；DataScope=SELF 强制实现（§2.3）符合 B4 |
| 缓存设计（§3） | ✅ 合理 | Redis Key 规范、TTL 分档、失效策略完整，符合 B6 |
| API 设计（§4） | ❌ 严重冲突 | 21 个 REST 端点违反 B1 GraphQL；须改为 GraphQL Query/Mutation |
| 事件设计（§5） | ⚠️ 部分冲突 | 订阅清单合理，但 B7 裁决 P2-P4 不订阅 Kafka，§5 应明确"P5 才落地"且标注 B7 |
| 横切关注点（§6） | ✅ 合理 | logger/metrics/tracer/health/优雅关闭对齐黄金模板；错误码 BFF_STUDENT_ 正确（§0.2 已修正） |
| 契约矩阵（§7） | ⚠️ 需更新 | 下游通信"HTTP→gRPC P3+"表述违反 B2，应改为"gRPC 首次实现即用" |
| 风险与假设（§8） | ⚠️ 需更新 | §8.3 12 项未决决策中 8 项已裁决（见 ISSUE-STU-003） |
| 演进路线（§9） | ❌ 严重冲突 | §9.2 REST→GraphQL、§9.3 HTTP→gRPC 违反"不分阶段"原则（president §0.3） |
| 扩展点（§10） | ✅ 优秀 | 多端适配/国际化/多角色复用/离线模式/AI 增强/学习路径预留设计前瞻 |
| 性能容量（§11） | ✅ 合理 | SLO 分级、容量规划、限流策略完整 |
| 安全合规（§12） | ✅ 合理 | 身份认证/授权隔离/输入安全/数据合规/审计完整 |
| 可观测性（§13） | ✅ 合理 | 日志规范/span/告警/Grafana 面板完整 |
### 3.2 长远性评估
| 长远性维度 | 评估 | 说明 |
| ---------- | ---- | ---- |
| 多角色复用（§9.5） | ✅ | 学习委员/课代表/走读生差异化通过视口扩展，无需改代码 |
| 多端适配（§10.1） | ✅ | Transformer 层按 x-client-type 裁剪，H5/小程序可扩展 |
| GraphQL 演进（§9.2） | ❌ | 规划为"P6+ 可选"，但 B1 已裁决 GraphQL 是起点非终点，须移除"可选" |
| 通信协议演进（§9.3） | ❌ | 规划"P3 HTTP → P4 gRPC 混合 → P6 Service Mesh"，违反 B2"首次实现即 gRPC" |
| 推送通道演进（§9.4） | ✅ | P3 无推送 → P5 SSE → P5+ WebSocket → P6+ 移动端推送，渐进合理 |
| AI 答疑增强（§10.5） | ✅ | 预留 context 参数，支持多步编排 |
| 国际化（§10.2） | ✅ | 预留 I18nContext 接入点 |
### 3.3 业界架构文档规范符合度
| 规范项 | 符合度 | 说明 |
| ------ | ------ | ---- |
| 文档导航/导读 | ✅ | §0.3 文档结构清晰，16 章覆盖完整 |
| 设计原则 | ✅ | §0.1 列 P1-P9 九项原则 |
| 架构图（C4 模型） | ✅ | §1 物理分层图 + 调用链时序图，符合 C4 Level 2/3 |
| ADR 决策记录 | ⚠️ | §8.3 列决策但未用 ADR 格式，且已裁决项未更新 |
| 非功能性需求 | ✅ | §11 性能 SLO + §12 安全 + §13 可观测性 |
| 演进路线 | ⚠️ | 有 §9 但违反"不分阶段"原则 |
| 实施清单 | ✅ | §14 P3-P6 分阶段清单完整 |
| 风险登记 | ✅ | §8.1 技术风险 + §8.2 外部依赖假设 |
### 3.4 关键遗漏
| 遗漏内容 | 应补充位置 | 依据 |
| -------- | ---------- | ---- |
| GraphQL Schema 完整定义（Query/Mutation/Type/Enum） | 新增 §4.2 或独立 §5 | B1 + president §2.2 |
| DataLoader 批量策略（哪些 Query 需要 DataLoader） | §1.2 或 §6 | 004 §11.3 + B1 |
| gRPC client 设计（channel 复用、interceptor、metadata 透传） | §1.2 或 §7 | B2 |
| GraphQL errors 数组扩展 ActionState 字段规范 | §6.2 错误码清单 | president §2.2 #3 |
| Relay Cursor Connections 分页规范 | §4 API 设计 | president §2.2 #5 |
| GraphQL schema 存放路径与 codegen 配置 | §14 实施清单 | president §2.2 #4 |
| AuthorizationGuard 接口设计（B4 越权防御 P3 实现方式） | §2.3 或 §6 | president §2.9（参照 teacher-bff ISSUE-033-ai03） |
---
## §4 历史问题归档
> 以下问题原记录在 `docs/issues.md`（旧流程），现按新流程归档至此。总裁裁决详见 [president-final-rulings.md](../../president-final-rulings.md) §10 问题索引表。
### ISSUE-028-ai04：ai04 02-architecture-design.md 与 coord B1+B2 裁决冲突需回写
- **提请方**：ai04（student-bff + parent-bff）
- **日期**：2026-07-09
- **类型**：裁决冲突（文档回写义务）
- **描述**：02-architecture-design.md 与 coord-final-decisions B1（P2 起直接 GraphQL）+ B2（首次实现即 gRPC）存在 2 项重大冲突（§4 API 设计决策为 REST；§9.2 演进路线 REST→GraphQL）
- **裁决**：president §3.4 — ai04 须在批次 2 启动前回写 student-bff 02：B1 GraphQL + B2 gRPC + B8 DownstreamClient
- **状态**：⚠️ 未执行（详见 §0 核查）
### ISSUE-029-ai04：ai04 P3 启动前置依赖确认（4 项强阻塞）
- **提请方**：ai04（student-bff + parent-bff）
- **日期**：2026-07-09
- **类型**：前置依赖未就绪
- **描述**：P3 启动依赖 4 项强阻塞前置（core_edu.proto 补全 / buf.gen.yaml gRPC 插件 / ai03 DownstreamClient 抽象 / ai08 core-edu gRPC server）
- **裁决**：president §4.1 / §6.1 — 批次 0 完成信号机制 + 批次 2 启动条件明确
- **状态**：✅ 已裁决
### ISSUE-030-ai04：ai04⟷ai14 student-bff GraphQL schema 第一版仲裁时机
- **提请方**：ai04（student-bff + parent-bff）
- **日期**：2026-07-09
- **类型**：契约不明确
- **描述**：student-bff GraphQL schema 第一版仲裁时机未明确
- **裁决**：president §2.2 — ai04 起草 schema（批次 1 等待期），coord 在批次 2 启动前仲裁第一版
- **状态**：✅ 已裁决（schema 第一版待 ai04 起草，见 ISSUE-STU-004）
### ISSUE-031-ai04：issues.md 编号冲突
- **提请方**：ai04（student-bff + parent-bff）
- **日期**：2026-07-09
- **类型**：工作归属不明（文档规范）
- **描述**：issues.md ISSUE-024/025 编号冲突（ai11 与 ai09 重复）
- **裁决**：president §0.4 — 保留原始内容，用 `ISSUE-XXX-<提请AI>` 格式定位，不重新编号
- **状态**：✅ 已裁决

202
docs/architecture/issues/objections/student-portal_issue.md
View File

@@ -1,12 +1,208 @@
# student-portal 问题记录
> 负责人：ai14
> 关联：[coord.md](../coord.md)、[contracts/student-portal_contract.md](../contracts/student-portal_contract.md)
> 关联：[coord.md](../coord.md)、[contracts/student-portal_contract.md](../contracts/student-portal_contract.md)、[matrix.md](../matrix.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态
---
## 问题列表
## §1 已有仲裁核查（ARB-001 / ARB-002 对 student-portal 的影响）
### 1.1 ARB-001（teacher-bff GraphQL schema 第一版）对 student-portal 的影响核查
| 裁决点 | 对 student-portal 的适用性 | ai14 落实方案 | 状态 |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------ |
| Schema 存放位置 | ✅ 适用（原则一致）。student-bff GraphQL schema 应存放于 `packages/shared-ts/contracts/graphql/student-bff.graphql`（集中管理，与 teacher-bff 同源） | ai14 在 contract.md §1.3 已标注预期路径；实际由 ai04 创建，ai14 仅消费 | ⏳ 待 ai04 |
| P2 Query 范围 | ⚠️ 部分参考。ARB-001 是 teacher-bff 的 P2 范围；student-portal 起步于 P3（不在 P2），因此 student-bff 直接以 P3 全量 Query 起步 | ai14 在 P3 直接消费 student-bff 全量 Query（currentUser/myClasses/myExams/myHomework/myGrades/myAttendance/studentDashboard） | ✅ 已落实 |
| P2 Mutation 范围 | ⚠️ 部分参考。student-portal P3 起步即需要 submitHomework mutation（作业提交是 P3 核心场景） | ai14 P3 即消费 submitHomework mutation；ai04 P3 必须提供 | ⏳ 待 ai04 |
| DataLoader 防 N+1 | ✅ 适用。student-bff 聚合多 gRPC 时（如 studentDashboard 聚合 iam+core-edu+data-ana）必须使用 DataLoader | ai14 不直接实现，但依赖 student-bff 返回结构稳定（无 N+1 慢查询） | ⏳ 待 ai04 |
| 复杂度限制（depth ≤ 7） | ✅ 适用。student-portal 发起的 GraphQL query 深度必须 ≤ 7 | ai14 在 [02-architecture-design.md §4.2](../../../apps/student-portal/docs/02-architecture-design.md) 已设计扁平 query | ✅ 已落实 |
| ActionState 信封 | ✅ 适用。student-bff 必须返回 ActionState 信封（success/errors/data） | ai14 在 GraphQL 请求层（02 §3.2）已处理信封解包 + 降级字段识别 | ✅ 已落实 |
| 降级模式（方案 B） | ✅ 适用。部分聚合失败时 success=true + data 内 `extensions.degraded: true` | ai14 在 [02 §18.2 降级策略矩阵](../../../apps/student-portal/docs/02-architecture-design.md) 已设计 12 个降级场景 | ✅ 已落实 |
| admin 命名空间 | ❌ 不适用。student-portal 不涉及 admin 命名空间 | - | - |
**核查结论**：ARB-001 是 teacher-bff 的 P2 仲裁，但其设计原则（Schema 集中管理、ActionState 信封、降级模式方案 B、复杂度限制）适用于所有 BFF，student-portal 已在 02-architecture-design.md v2 中全面落实。
---
### 1.2 ARB-002（MF Shell 暴露清单）对 student-portal 的影响核查
| 裁决点 | 对 student-portal 的适用性 | ai14 落实方案 | 状态 |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| Shell 身份 | ✅ 适用。teacher-portal 是 MF Shell，student-portal 是 P3 首个 Remote | ai14 在 [02 §3.2 MF 配置](../../../apps/student-portal/docs/02-architecture-design.md) 已声明 `remotes: { teacher: 'teacher@http://localhost:4000/_next/static/chunks/remoteEntry.js' }` | ✅ 已落实 |
| P3 首个 Remote | ✅ 适用。ARB-002 §2.3 明确 P3 首个 Remote 是 student-portal | ai14 P3 任务启动即接入 MF Remote | ✅ 已落实 |
| GraphQL client 归属 | ✅ 适用。Shell 暴露 GraphQLProvider，student-portal 复用，**不重复创建 client** | ai14 在 [02 §3.2 GraphQL 请求层](../../../apps/student-portal/docs/02-architecture-design.md) 已使用 `useGraphQLClient()` 从 `@edu/hooks` 获取 | ✅ 已落实 |
| MF shared singleton 配置 | ✅ 适用。student-portal 必须将 react/react-dom/urql/graphql/@edu/* 声明为 singleton | ai14 在 [02 §3.2 next.config.js](../../../apps/student-portal/docs/02-architecture-design.md) 已声明全部 singleton | ✅ 已落实 |
| AppShell 复用 | ✅ 适用。student-portal 不重复实现 AppShell，复用 Shell 暴露的 AppShell | ai14 在 02 §3.2 已设计 `<AppShell>` 包裹 + 学生端导航覆写 | ✅ 已落实 |
| useAuth / usePermission 复用 | ✅ 适用。student-portal 复用 Shell 暴露的 useAuth/usePermission | ai14 在 [01-understanding.md §6](../../../apps/student-portal/docs/01-understanding.md) 已声明权限校验走 usePermission | ✅ 已落实 |
| ErrorBoundary / Loading / Empty 复用 | ✅ 适用。student-portal 复用 Shell 暴露的共享 UI 组件 | ai14 在 02 §6 组件设计已使用 `@edu/ui-components` | ✅ 已落实 |
| feature flag | ✅ 适用。`NEXT_PUBLIC_MF_ENABLED` 控制是否走 MF；P3 默认 true | ai14 在 02 §3.2 已设计独立壳回退（MF 关闭时独立渲染） | ✅ 已落实 |
| 登录页 | ✅ 适用。P2 登录页由 Shell 独占；student-portal 不实现登录页，未登录跳转 Shell `/login` | ai14 在 02 §3.2 已设计未认证 → 跳转 `window.location.href = 'http://localhost:4000/login?redirect=student'` | ✅ 已落实 |
**核查结论**：ARB-002 是 student-portal 接入 MF 的直接依据，ai14 已在 02-architecture-design.md v2 中全面落实。无异议。
---
### 1.3 ARB-001 / ARB-002 核查总结
| 仲裁 | 对 student-portal 的影响 | ai14 落实情况 | 异议 |
| ------ | ------------------------ | ------------- | ---- |
| ARB-001 | 设计原则适用（GraphQL + ActionState + 降级模式） | ✅ 已落实 | 无 |
| ARB-002 | 直接适用（P3 首个 Remote + Shell 暴露清单） | ✅ 已落实 | 无 |
> **ai14 声明**：ARB-001 / ARB-002 已在 02-architecture-design.md v2 中全面落实，无需新增仲裁。
---
## §2 新提请异议（待 coord 仲裁）
### ISSUE-014-01-ai14：GraphQL endpoint 路径不一致（`/api/student/graphql` vs `/api/v1/student/graphql`）
- **提请方**：ai14
- **日期**：2026-07-10
- **类型**：契约不明确
- **描述**：
- `student-portal_contract.md` §2.3 当前写 `POST /api/student/graphql`（无 `/v1/` 前缀）
- `matrix.md` §5 HTTP 接口矩阵明确写 `api-gateway` 反向代理 `student-portal` 的路径是 `/api/v1/student/*`
- `01-understanding.md` v2 §3.1 和 `02-architecture-design.md` v2 §4.1 已统一为 `POST /api/v1/student/graphql`
- 三处不一致，需要 coord 仲裁统一为 `/api/v1/student/graphql`（与 matrix.md §5 对齐，与 teacher-portal `/api/v1/teacher/graphql` 保持命名一致性）
- **建议方案**：
- 统一为 `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 仲裁
---
### ISSUE-014-02-ai14：student-bff GraphQL schema 文件存放位置不一致（集中管理 vs 应用内管理）
- **提请方**：ai14
- **日期**：2026-07-10
- **类型**：契约不明确
- **描述**：
- ARB-001 §1.3 关键裁决明确：teacher-bff GraphQL schema 存放于 `packages/shared-ts/contracts/graphql/teacher-bff.graphql`（集中管理，总裁裁决 §2.17 SDL-first + 集中管理）
- `student-bff_contract.md` §1.3 写：`apps/student-bff/src/schema/*.graphql`（应用内管理，与 ARB-001 原则不一致）
- `matrix.md` §3 GraphQL 接口提供方矩阵写：`packages/shared-ts/contracts/graphql/student-bff.graphql`（与 ARB-001 一致）
- 两处不一致，需要 coord 仲裁统一
- **建议方案**：
- 统一为 `packages/shared-ts/contracts/graphql/student-bff.graphql`（与 ARB-001 原则对齐，集中管理便于前端 codegen）
- ai14 在 student-portal 端使用 `graphql-codegen` 从该 schema 生成 TypeScript 类型
- 由 ai04（student-bff）创建该 schema 文件并维护
- **状态**：待 coord 仲裁
---
### ISSUE-014-03-ai14：考试作答页全屏策略与防作弊检测边界
- **提请方**：ai14
- **日期**：2026-07-10
- **类型**：契约不明确
- **描述**：
- student-portal 02-architecture-design.md §14 设计了防作弊检测（visibilitychange/copy/paste/fullscreen/contextmenu），但未明确以下边界：
1. **全屏 API 强制策略**：是否强制全屏（Fullscreen API）？退出全屏是否触发警告/记录？
2. **离开页面策略**：visibilitychange hidden 触发时，是仅记录还是自动提交？
3. **多标签检测**：BroadcastChannel 检测到多标签时，是警告还是阻止作答？
4. **防作弊事件上报**：前端采集的防作弊事件如何上报？走 student-bff GraphQL mutation 还是 push-gateway WebSocket？
- 这些决策影响 ai04（student-bff）是否需要提供 `recordExamViolation` mutation，以及 ai08（core-edu）是否需要存储违规记录
- **建议方案**：
- **全屏策略**：P3 推荐但不强制（提示"建议全屏作答"），P4 评估是否升级为强制（基于教师反馈）
- **离开页面策略**：visibilitychange hidden 触发时仅记录（不自动提交），累计 3 次警告后教师端可见
- **多标签检测**：警告 + 记录，不阻止作答（避免误伤合法场景如查词典）
- **防作弊事件上报**：走 student-bff GraphQL mutation `recordExamViolation(examId, type, payload)`，由 ai04 在 P3 提供
- **状态**：待 coord 仲裁
---
### ISSUE-014-04-ai14：主观题粘贴策略（防作弊 vs 学生体验）
- **提请方**：ai14
- **日期**：2026-07-10
- **类型**：契约不明确
- **描述**：
- 02-architecture-design.md §14 防作弊检测包含 `paste` 事件拦截，但学生作答主观题时可能需要粘贴（如从草稿本粘贴长文本）
- 策略不明确：全部禁止粘贴？仅主观题允许？仅客观题禁止？
- 影响学生体验和防作弊效果平衡
- **建议方案**：
- **客观题**：禁止粘贴（防作弊优先）
- **主观题（简答/论述）**：允许粘贴，但记录粘贴事件 + 粘贴内容长度，教师端批改时可见
- **作文题**：允许粘贴（学生体验优先），不记录
- 由 ai04（student-bff）在 P3 提供 `recordPasteEvent` mutation（或复用 ISSUE-014-03 的 `recordExamViolation`，type=`PASTE`）
- **状态**：待 coord 仲裁
---
### ISSUE-014-05-ai14：作业附件上传协议（GraphQL mutation vs REST multipart）
- **提请方**：ai14
- **日期**：2026-07-10
- **类型**：契约不明确
- **描述**：
- 学生提交作业时可能需要上传附件（图片/PDF/文档），GraphQL mutation 不适合处理大文件上传（multipart/form-data）
- 当前 contract.md 未明确附件上传协议
- 选项：
- A. 走 api-gateway REST 端点（`POST /api/v1/student/upload` → 对象存储），返回 URL，再走 GraphQL mutation 提交 URL
- B. 走 student-bff GraphQL multipart（graphql-upload，需要 ai04 支持）
- C. 走独立上传服务（如 push-gateway 扩展或新建 upload-service）
- **建议方案**：
- **推荐 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 仲裁
---
### ISSUE-014-06-ai14：考试延长/题目重排等实时事件命名未确认
- **提请方**：ai14
- **日期**：2026-07-10
- **类型**：契约不明确
- **描述**：
- student-portal 02-architecture-design.md §16 设计了 WebSocket 实时通知，但以下事件命名未在 matrix.md §4 Kafka 事件矩阵中确认：
1. **考试延长**（教师延长考试时间）：事件名 `ExamExtended`？还是 `ExamUpdated`？由 ai08（core-edu）发布？
2. **题目重排**（教师重排题目顺序）：事件名 `ExamQuestionReordered`？是否需要前端实时重排？
3. **考试强制提交**（教师强制收卷）：事件名 `ExamForceSubmitted`？前端收到后立即提交？
- 这些事件影响 student-portal 考试作答页的实时响应逻辑
- **建议方案**：
- **考试延长**：ai08（core-edu）发布 `ExamExtended` 事件到 `edu.exam.events` topic，msg（ai10）消费后通过 push-gateway 推送，student-portal 收到后更新倒计时
- **题目重排**：P3 不实现（题目顺序固定），P4 评估是否需要实时重排
- **考试强制提交**：ai08 发布 `ExamForceSubmitted` 事件，student-portal 收到后立即触发提交流程
- 由 ai08（core-edu）确认事件命名，由 ai10（msg）确认推送路径
- **状态**：待 coord 仲裁
---
### ISSUE-014-07-ai14：学生端 DataScope L0 边界（仅能查看自己数据）的强制执行层
- **提请方**：ai14
- **日期**：2026-07-10
- **类型**：契约不明确
- **描述**：
- 01-understanding.md §8 和 02-architecture-design.md §6 声明学生 DataScope L0（仅能查看自己数据）
- 但强制执行层不明确：
- A. student-bff 在 Resolver 层基于 JWT 的 `x-user-id` 强制过滤（推荐，前端无法绕过）
- B. student-portal 在 GraphQL query 中显式传 `studentId`（不安全，前端可篡改）
- 当前 02-architecture-design.md §4.2 的 GraphQL query 设计中，部分 query 显式传 `studentId`（如 `myClasses(studentId: ID!)`），这与 L0 强制执行矛盾
- **建议方案**：
- **统一为方案 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 仲裁
---
## §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 仲裁 |
---
<!--
追加条目格式：
@@ -20,5 +216,3 @@
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
（暂无问题）

36
docs/architecture/issues/objections/teacher-bff_issue.md
View File

@@ -21,4 +21,38 @@
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
（暂无问题）
### ISSUE-001-ai03：admin 命名空间 P2 预留与 ARB-001 "P2 不包含" 冲突
- **提请方**：ai03
- **日期**：2026-07-10
- **类型**：契约不明确
- **描述**：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 仲裁
### ISSUE-002-ai03：P2 dashboard classes 数据来源与 ARB-001 §1.4 调用链冲突
- **提请方**：ai03
- **日期**：2026-07-10
- **类型**：前置依赖缺失
- **描述**：coord.md ARB-001 §1.4 ai03 执行项第 4 条写 "dashboard Resolver 并行调用 iam（3 RPC）+ classes（1 RPC），用 DataLoader 防御 N+1"，暗示 P2 dashboard 需 gRPC 调 classes 服务。但存在三重冲突：
1. **classes P2 无 gRPC server**：classes.proto 注释 "P1: REST 实现，P3 起转 gRPC"；matrix.md §2 gRPC 接口提供方矩阵中 core-edu（含 classes 合并）gRPC 50053 状态为 P3 就绪。classes 服务 P2 阶段未启用 gRPC。
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 仲裁
### ISSUE-003-ai03：GraphQL schema 文件命名不一致（ARB-001 vs president §2.17）
- **提请方**：ai03
- **日期**：2026-07-10
- **类型**：编号冲突
- **描述**：GraphQL schema 文件存放目录两处一致（`packages/shared-ts/contracts/graphql/`），但文件名不一致：
- coord.md ARB-001 §1.3 + §1.4：`teacher-bff.graphql`
- president-final-rulings.md §2.17 第 1 条：`teacher-bff.schema.graphql`
ai03 创建文件时无法确定用哪个文件名。
- **建议方案**：以 president §2.17 为准（裁决优先级 president > coord），统一为 `teacher-bff.schema.graphql`。coord 修正 ARB-001 §1.3/§1.4 文件名。
- **状态**：待 coord 仲裁
---

25
docs/architecture/issues/objections/teacher-portal_issue.md
View File

@@ -155,6 +155,31 @@
---
### ISSUE-042-ai13：仲裁核查 - 01/02 文档未同步已裁决的 GraphQL 架构
- **提请方**：ai13
- **日期**：2026-07-10
- **类型**：文档同步遗漏（仲裁核查）
- **阶段**：P2
- **描述**：
- 按"对已有仲裁进行核查"要求，审查 ISSUE-036~041（均已裁决）在文档中的落地情况
- 核查发现：`apps/teacher-portal/docs/01-understanding.md` 和 `02-architecture-design.md` 仍为 ai07 标识 + REST 架构，**未同步**以下已裁决事项：
- F9（ISSUE-036）：P2 起 all-in GraphQL，无 REST 过渡 — 01 §1/§3.1 仍写"P2-P3 用 REST 过渡"；02 全文基于 REST（ApiClient/TanStack Query/契约清单）
- ARB-001（ISSUE-037）：teacher-bff GraphQL schema 第一版 5 Query — 01 §3.1 列 REST 端点；02 §4/§10 全 REST
- ARB-002（ISSUE-038/039）：MF Shell 暴露清单（GraphQLProvider + hooks + UI 组件 + urql/graphql singleton）— 01 未提；02 §1.2 exposes 仅 AppShell+shared-deps、P2 配 3 remotes、shared 无 urql
- 总裁 §2.17（ISSUE-038）：GraphQL client 单例方案 A — 02 §11.3.2 仍列"GraphQL vs REST"未决（已裁决）
- 对照已回写的 `03-long-term-architecture.md §1.4`（GraphQL 最终方案），01/02 严重滞后
- **建议方案**：
1. 01-understanding.md：ai07→ai13；§1 删除 REST 过渡；§3.1 REST 端点→GraphQL queries（ARB-001）；§4 技术栈补 urql；补 ARB-002 暴露清单
2. 02-architecture-design.md：ai07→ai13；全文 REST→GraphQL 重写（MF 配置对齐 ARB-002；API 层改 urql client；契约清单改 GraphQL；§11.3 未决决策改已决策）
- **状态**：✅ 已回写闭合（2026-07-10，审查批次）
- **coord 裁决**：无需新裁决（复用 ISSUE-036~040 已有裁决），本次为文档同步执行
- **回写执行**：
- `01-understanding.md`：已修正 ai07→ai13、§1 REST→GraphQL、§3.1 REST 端点→GraphQL queries（ARB-001）、§4 补 urql/GraphQL client 技术栈、补 ARB-002 暴露清单、端口对齐、字体令牌描述
- `02-architecture-design.md`：全量重写为 GraphQL 架构（§1 MF 图加 GraphQLProvider 层；§1.2 MF 配置对齐 ARB-002 exposes/shared/remotes=0；§2 领域模型数据源改 GraphQL Query；§3 缓存层改 urql cacheExchange；§4 API 设计改 urql client 单例 + ARB-001 Query/Mutation；§10 契约清单改 GraphQL；§11.3 未决决策改已决策表；端口 3000→4000）
---
**AI Agent**: ai13（teacher-portal）
**Branch**: feat/teacher-portal-issues-migrate-ai13
**Coordinator**: coord-ai