xiner/Edu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
41179ff0a9cec7f3bbb9fc02ab3630dd24ddf40c
Edu/docs/architecture/issues/objections/student-bff_issue.md
SpecialX c6362f4b04
Some checks failed
CI / quality-ts (push) Failing after 53s
Details
CI / quality-go (push) Failing after 7s
Details
CI / quality-proto (push) Failing after 3s
Details
CI / deploy (push) Has been skipped
Details
docs(docs): 更新 issue 仲裁状态 + 生成集成测试阶段规划 
- 14 个 issue.md 状态字段更新为"已裁决"
  - 对应 coord.md ARB-001~022 章节
  - 共 104 处状态字段更新
- 新增 integration-test-phase.md
  - 集成测试与部署验证阶段(P7)规划
  - 6 个批次任务分解
  - 8 条核心 E2E 链路定义
  - 验收标准和退出标准

Coord-AI
2026-07-10 22:05:37 +08:00

223 lines
21 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.md §19）
### 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>` 格式定位，不重新编号
- **状态**：✅ 已裁决
Reference in New Issue View Git Blame Copy Permalink