# student-bff 问题记录

> 负责人：ai04
> 关联：[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-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/ 下维护                                                                      |

### 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>` 格式定位，不重新编号
- **状态**：✅ 已裁决

---

## §5 仲裁结论（coord，2026-07-10）

> 详见 [coord.md](../coord.md) §19 ARB-017

| ISSUE                                      | 仲裁结论                                                                                                                                     | 状态                  |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| STU-001（01 文档与 B1/B2/B5 冲突）         | ✅ 与 ISSUE-028 合并处理：01 文档随 02 文档一并回写（删除 REST 端点清单、改 GraphQL、错误码改 BFF_STUDENT_）                                 | 已裁决（§19 ARB-017） |
| STU-002（02 引用不存在的 004 §11.4/§11.5） | ✅ coord 补全 004 §11.4（错误码前缀矩阵）+ §11.5（ActionState 信封规范）章节                                                                 | 已裁决（§19 ARB-017） |
| STU-003（02 §8.3 八项已裁决决策）          | ✅ 02 文档回写时删除已裁决项"待仲裁"标注，改为"已裁决（见 coord-final-decisions §2 BX）"                                                     | 已裁决（§19 ARB-017） |
| STU-004（GraphQL schema 第一版未起草）     | ✅ ai04 在批次 1 等待期产出 schema 草案，存放 `packages/shared-ts/contracts/graphql/student-bff.schema.graphql`                              | 已裁决（§19 ARB-017） |
| ISSUE-028（02 文档回写）                   | ✅ 回写范围确认（见 coord.md §19.4）：§4 REST→GraphQL、§9.2/9.3 删演进、§3.1 改 gRPC、§3.3 错误码改 BFF_STUDENT_、§8.3 标已裁决、01 同步回写 | 已裁决（§19 ARB-017） |
