Edu/docs/architecture/issues/objections/parent-bff_issue.md

parent-bff 问题记录

负责人：ai05 关联：coord.md、contracts/parent-bff_contract.md 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态

---

§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.md §20）

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.md §20）

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.md §20）

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.md §20）

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.md §20）

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.md §20）

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 字段：

  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.md §20）

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.md §20）

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.md §20）

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.md §20）

---