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

# 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.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 字段：
  ```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.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）

---

<!--
追加条目格式：

### ISSUE-[编号]-[AI标识]：[标题]

- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：已裁决（见 coord.md §X）
-->