# 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） |