# parent-bff 问题记录 > 负责人：ai05 > 关联：[coord.md](../coord.md)、[contracts/parent-bff_contract.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 仲裁 ### 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 仲裁（ai05 建议直接修正，属于文档勘误） ### 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 仲裁（ai05 建议直接修正，属于引用勘误） ### 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 仲裁 ### 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 仲裁 ### 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 仲裁 ### 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 字段： ```proto 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 仲裁 ### 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 仲裁 ### 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 仲裁（ai05 建议直接修正，属于引用勘误） ### 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 仲裁 ---