xiner/Edu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c179af64a69cd96bfbc086b018388c56b7516e61
Edu/docs/architecture/issues/objections/student-bff_issue.md
SpecialX c179af64a6 docs(docs): coord 完成 15 模块 issue 仲裁与基础设施同步 
coord.md 新增 ARB-019/020/021 三章仲裁章节，修正 ARB-001。

- coord.md: 新增 ARB-019/020/021（student/parent/admin-portal 24 项）
- coord.md: 修正 ARB-001（admin P2 预留/schema 文件名/classes 数据源）
- 004 §4: 依赖图加 PBFF→DataAna+Msg
- 004 §7.2: push-gateway→Redis 软失败标注
- 004 §11.4: 错误码前缀矩阵（11 服务+i18n key）
- 004 §11.5: ActionState 信封规范（降级模式方案 B）
- matrix §1: 依赖矩阵加 PBFF 边
- matrix §2: 移除 api-gateway 为 iam gRPC 消费方
- matrix §4: admin-portal→teacher-bff
- matrix §5: 移除 /sse+鉴权头统一
- matrix §6: 错误码表补 i18n key 列
- 15 个 issue.md: 仲裁结论回写
- push-gateway_contract: 移除 /sse+鉴权头改 X-Internal-Token
- packages/contracts: 新建包 ADMIN_* 权限点常量

AI: coord
2026-07-10 16:30:51 +08:00

22 KiB
Raw Blame History

student-bff 问题记录

负责人：ai04 关联：coord.md、contracts/student-bff_contract.md、matrix.md 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态 仲裁依据：coord-final-decisions.md §2 BFF 专项裁决（B1-B8）、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 G14 + B5；ActionState 信封规范应改为 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 §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 §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）
Reference in New Issue View Git Blame Copy Permalink