feat: auto committed

2026-07-10 15:06:12 +08:00
parent 9ba368477d
commit a7d8f92227
3 changed files with 633 additions and 79 deletions
--- a/docs/architecture/issues/contracts/parent-bff_contract.md
+++ b/docs/architecture/issues/contracts/parent-bff_contract.md
@@ -1,48 +1,98 @@
 # parent-bff 对接契约

 > 负责人：ai05
-> 关联：[matrix.md](./matrix.md)、[iam.proto](../../../packages/shared-proto/proto/iam.proto)、[core_edu.proto](../../../packages/shared-proto/proto/core_edu.proto)、[analytics.proto](../../../packages/shared-proto/proto/analytics.proto)、[msg.proto](../../../packages/shared-proto/proto/msg.proto)
+> 关联：[matrix.md](../matrix.md)、[iam.proto](../../../packages/shared-proto/proto/iam.proto)、[core_edu.proto](../../../packages/shared-proto/proto/core_edu.proto)、[analytics.proto](../../../packages/shared-proto/proto/analytics.proto)、[msg.proto](../../../packages/shared-proto/proto/msg.proto)、[02-architecture-design.md](../../../services/parent-bff/docs/02-architecture-design.md)
+> 修订：2026-07-10 ai05 复审（修正仲裁引用、proto 包名、契约缺口标注）
+
+---
+
+## §0 契约基线说明
+
+| 维度 | 内容 |
+| --- | --- |
+| proto 包名前缀 | 所有 proto 包名统一为 `next_edu_cloud.<domain>.v1`（如 `next_edu_cloud.iam.v1`），引用 proto message 时须带完整包名 |
+| GraphQL schema 文件 | `packages/shared-ts/contracts/graphql/parent-bff.graphql`（SDL-first 集中管理，对齐 coord ARB-001 模式） |
+| 错误码前缀 | `BFF_PARENT_`（C1 仲裁，BFF 在前） |
+| 端口 | HTTP 3010，不暴露 gRPC（C2 仲裁） |
+| API 风格 | GraphQL Yoga（U3 仲裁，P4 直接 GraphQL，不走 REST 过渡） |
+| 权限校验 | BFF 豁免 @RequirePermission（U4 仲裁），仅校验 x-user-id + ChildGuard 越权防御 |

 ---

 ## §1 我提供什么（对外接口）

-### 1.1 gRPC 接口（如有）
+### 1.1 gRPC 接口

-无对外 gRPC。parent-bff 是 GraphQL 聚合层。
+无对外 gRPC。parent-bff 是 GraphQL 聚合层，对上游仅暴露 HTTP/GraphQL（C2 仲裁）。

-### 1.2 HTTP 端点（如有）
+### 1.2 HTTP 端点

-| Method | Path     | 用途                                      | 认证                   |
-| ------ | -------- | ----------------------------------------- | ---------------------- |
-| POST   | /graphql | 家长 BFF GraphQL 端点                     | JWT 必需 + parent 角色 |
-| GET    | /graphql | GraphQL Playground（开发环境）            | 开发环境公开           |
-| GET    | /healthz | 健康检查（liveness）                      | 公开                   |
-| GET    | /readyz  | 就绪检查（readiness，含下游 gRPC 连通性） | 公开                   |
+| Method | Path | 用途 | 认证 | 阶段 |
+| --- | --- | --- | --- | --- |
+| POST | /graphql | 家长 BFF GraphQL 端点（U3 仲裁） | JWT 必需 + parent 角色 | P4 |
+| GET | /graphql | GraphQL Playground（仅开发环境） | 开发环境公开 | P4 |
+| GET | /healthz | 健康检查（liveness，直接返回 ok） | 公开 | P4 |
+| GET | /readyz | 就绪检查（readiness，含下游 gRPC 连通性，02 §9 #7） | 公开 | P4 |
+| GET | /metrics | Prometheus 指标（parent_bff_*） | 公开 | P4 |

-### 1.3 GraphQL schema（如 BFF）
+> 网关路径：`/api/v1/parent/*` → api-gateway 剥离 `/api/v1` 后代理到 parent-bff:3010
+> **不实现 REST 业务端点**（02 §4.1，仅保留 /healthz /readyz /metrics 基础端点）

-GraphQL schema 文件路径：`apps/parent-bff/src/schema/*.graphql`（端口 :3010）
+### 1.3 GraphQL schema

-核心 Query / Mutation 域：
+**schema 文件**：`packages/shared-ts/contracts/graphql/parent-bff.graphql`（SDL-first）
+**完整 schema 定义**：见 [02-architecture-design.md §4.2](../../../services/parent-bff/docs/02-architecture-design.md) GraphQL Schema 完整定义

- **auth**：currentUser（聚合 iam.GetUserInfo + GetEffectivePermissions + GetViewports）
- **children**：myChildren（聚合 iam.GetChildrenByParent，核心依赖 I3 裁决）
- **childSummary**：childSummary（聚合 data-ana.AnalyticsService.GetParentDashboard）
- **childGrades**：childGrades（聚合 core-edu.GradeService.ListGradesByStudent）
- **childAttendance**：childAttendance（聚合 core-edu.AttendanceService.ListAttendanceByStudent）
- **childHomework**：childHomework（聚合 core-edu.HomeworkService.ListHomeworkByClass）
- **childWeakness**：childWeakness（聚合 data-ana.AnalyticsService.GetStudentWeakness）
- **childTrend**：childTrend（聚合 data-ana.AnalyticsService.GetLearningTrend）
- **notifications**：myNotifications / markAsRead（聚合 msg.NotificationService）
+核心 Query / Mutation 域（按阶段分级）：

-### 1.4 Kafka 事件发布（如有）
+| 类型 | 字段 | 聚合下游 | ChildGuard | 阶段 |
+| --- | --- | --- | --- | --- |
+| Query | dashboard | iam + core-edu | 否（聚合所有孩子） | P4 |
+| Query | viewports | iam | 否 | P4 |
+| Query | me | iam | 否 | P4 |
+| Query | children | iam | 否 | P4 |
+| Query | child | iam + core-edu | 是 | P4 |
+| Query | childGrades | core-edu | 是 | P4 |
+| Query | childHomework | core-edu | 是 | P4 |
+| Query | childExams | core-edu | 是 | P4 |
+| Query | childAnalytics | data-ana | 是 | P4 |
+| Query | notifications | msg | 否 | P5 |
+| Query | notificationPreferences | msg | 否 | P5 |
+| Mutation | selectChild | （BFF 内部审计） | 是 | P4 |
+| Mutation | markNotificationRead | msg | 否 | P5 |
+| Mutation | updateNotificationPreferences | msg | 否 | P5 |

-无。parent-bff 不发布事件，仅做 gRPC 聚合。
+**统一响应信封**：GraphQL 规范（data/errors），错误扩展字段携带 `extensions.code = "BFF_PARENT_*"`（02 §4.5）
+
+### 1.4 Kafka 事件发布
+
+无。parent-bff 不发布领域事件（BFF 聚合层无业务状态变更，02 §5.6）。

 ### 1.5 错误码前缀

-`BFF_PARENT_`（如 BFF_PARENT_UPSTREAM_UNAVAILABLE、BFF_PARENT_AGGREGATION_FAILED、BFF_PARENT_NO_CHILDREN、BFF_PARENT_FORBIDDEN）
+`BFF_PARENT_`（C1 仲裁，BFF 在前；非 PARENT_BFF_）
+
+错误码清单（完整见 02 §6.2）：
+
+| 错误码 | HTTP | 触发条件 |
+| --- | --- | --- |
+| BFF_PARENT_VALIDATION_ERROR | 400 | Zod / GraphQL input 校验失败 |
+| BFF_PARENT_UNAUTHORIZED | 401 | 缺失 x-user-id 头 |
+| BFF_PARENT_CHILD_NOT_BOUND | 403 | ChildGuard 拦截：childId 不在家长绑定列表 |
+| BFF_PARENT_NOT_FOUND | 404 | 资源不存在 |
+| BFF_PARENT_BAD_GATEWAY | 502 | 下游服务返回非 ok 或 gRPC rejected |
+| BFF_PARENT_GATEWAY_TIMEOUT | 504 | 下游调用超时 |
+| BFF_PARENT_SERVICE_UNAVAILABLE | 503 | 熔断器开启（P6） |
+| BFF_PARENT_INTERNAL_ERROR | 500 | 未捕获异常 |
+
+**下游错误透传**（C3 仲裁：core-edu 统一 CORE_EDU_*）：
+
+| 下游服务 | 错误码前缀 | 示例 |
+| --- | --- | --- |
+| iam | IAM_ | IAM_USER_NOT_FOUND |
+| core-edu | CORE_EDU_ | CORE_EDU_GRADE_NOT_FOUND |
+| data-ana | DATA_ANA_ | DATA_ANA_ANALYTICS_NOT_READY |
+| msg | MSG_ | MSG_NOTIFICATION_NOT_FOUND |

 ---

@@ -50,28 +100,59 @@ GraphQL schema 文件路径：`apps/parent-bff/src/schema/*.graphql`（端口 :3

 ### 2.1 gRPC 调用（同步）

-| 被调用方        | Service.RPC                               | 用途                     | mock 策略                                              |
-| --------------- | ----------------------------------------- | ------------------------ | ------------------------------------------------------ |
-| iam (ai06)      | IamService.GetUserInfo                    | 获取当前家长信息         | iam 就绪前返回固定 UserInfo（parent 角色）             |
-| iam (ai06)      | IamService.GetEffectivePermissions        | 权限校验                 | iam 就绪前返回家长权限集                               |
-| iam (ai06)      | IamService.GetViewports                   | 家长导航菜单             | iam 就绪前返回固定视口列表                             |
-| iam (ai06)      | IamService.GetChildrenByParent            | 查询关联孩子列表（核心） | iam 就绪前返回固定 2 个 ChildInfo（I3/ISSUE-047 裁决） |
-| core-edu (ai08) | GradeService.ListGradesByStudent          | 孩子成绩                 | core-edu 就绪前返回固定 5 个 Grade                     |
-| core-edu (ai08) | AttendanceService.ListAttendanceByStudent | 孩子考勤                 | core-edu 就绪前返回固定 10 条 Attendance               |
-| core-edu (ai08) | HomeworkService.ListHomeworkByClass       | 孩子作业                 | core-edu 就绪前返回固定 3 个 Homework                  |
-| data-ana (ai11) | AnalyticsService.GetParentDashboard       | 家长仪表盘               | data-ana 就绪前返回固定仪表盘（child_avg_score=85.0）  |
-| data-ana (ai11) | AnalyticsService.GetStudentWeakness       | 孩子薄弱点               | data-ana 就绪前返回固定 3 个 weak_points               |
-| data-ana (ai11) | AnalyticsService.GetLearningTrend         | 孩子学习趋势             | data-ana 就绪前返回固定趋势数据                        |
-| msg (ai10)      | NotificationService.ListNotifications     | 家长通知                 | msg 就绪前返回固定 10 条通知                           |
-| msg (ai10)      | NotificationService.MarkAsRead            | 标记已读                 | msg 就绪前返回 success=true                            |
+> proto 包名均为 `next_edu_cloud.<domain>.v1`
+> **状态标注**：✅ 已有 = proto 已定义；❌ 待补 = proto 缺失；⚠️ 待仲裁 = ai05 提请 coord 仲裁中

-### 2.2 Kafka 事件订阅（异步）
+| 被调用方 | Service.RPC | proto message 包名 | 用途 | mock 策略 | 状态 |
+| --- | --- | --- | --- | --- | --- |
+| iam (ai06) | IamService.GetUserInfo | next_edu_cloud.iam.v1.UserInfo | 获取当前家长信息 | 返回固定 UserInfo（parent 角色） | ✅ 已有 |
+| iam (ai06) | IamService.GetViewports | next_edu_cloud.iam.v1.Viewport[] | 家长导航菜单 | 返回固定视口列表 | ❌ 待 ai06 补（coord-cross-review #1） |
+| iam (ai06) | IamService.GetEffectivePermissions | next_edu_cloud.iam.v1.EffectivePermissions | 权限校验 | 返回家长权限集 | ❌ 待 ai06 补 |
+| iam (ai06) | **IamService.GetChildrenByParent** | next_edu_cloud.iam.v1.Child[] | 查询关联孩子列表（**P0 核心依赖**） | 返回固定 2 个 ChildInfo | ❌ 待 ai06 补（**I6 裁决**，P0 阻塞） |
+| core-edu (ai08) | GradeService.ListGradesByStudent | next_edu_cloud.core_edu.v1.Grade[] | 孩子成绩 | 返回固定 5 个 Grade | ✅ 已有 |
+| core-edu (ai08) | HomeworkService.ListHomeworkByClass | next_edu_cloud.core_edu.v1.Homework[] | 孩子作业 | 返回固定 3 个 Homework | ✅ 已有 |
+| core-edu (ai08) | ExamService.ListExamsByClass | next_edu_cloud.core_edu.v1.Exam[] | 孩子考试 | 返回固定 3 个 Exam | ✅ 已有 |
+| core-edu (ai08) | **ClassService.GetClass** | next_edu_cloud.core_edu.v1.Class | 孩子班级信息 | 返回固定 ClassInfo | ❌ 待补（**ISSUE-008**：proto 缺 ClassService，待 coord 仲裁归属） |
+| core-edu (ai08) | AttendanceService.ListAttendanceByStudent | next_edu_cloud.core_edu.v1.Attendance[] | 孩子考勤（P5+） | 返回固定 10 条 | ❌ 待 ai08 补（coord-cross-review #5，P3 补全） |
+| data-ana (ai11) | AnalyticsService.GetStudentWeakness | next_edu_cloud.analytics.v1.StudentWeakness | 孩子薄弱点 | 返回固定 3 个 weak_points | ✅ 已有 |
+| data-ana (ai11) | AnalyticsService.GetLearningTrend | next_edu_cloud.analytics.v1.LearningTrend | 孩子学习趋势 | 返回固定趋势数据 | ✅ 已有 |
+| data-ana (ai11) | AnalyticsService.GetClassPerformance | next_edu_cloud.analytics.v1.ClassPerformance | 班级学情对比 | 返回固定班级数据 | ✅ 已有 |
+| data-ana (ai11) | **AnalyticsService.GetParentDashboard** | — | 家长仪表盘聚合（多子女防 N+1） | 返回固定仪表盘 | ⚠️ 待仲裁（02 §14 #3，ai05 提请，proto 未定义） |
+| msg (ai10) | NotificationService.ListNotifications | next_edu_cloud.msg.v1.Notification[] | 家长通知 | 返回固定 10 条通知 | ✅ 已有 |
+| msg (ai10) | NotificationService.MarkAsRead | next_edu_cloud.msg.v1.Empty | 标记已读 | 返回 success | ✅ 已有 |
+| msg (ai10) | **NotificationPreferenceService.*** | — | 通知偏好配置 | 返回固定偏好 | ❌ 待 ai10 补（proto + 实现均缺失，P5） |

-无。parent-bff 不订阅 Kafka 事件，仅做同步 gRPC 聚合。
+**类型映射注意**（ISSUE-008）：

-### 2.3 HTTP 调用（如有）
+- `core_edu.v1.Grade.score` 是 `string` 类型，GraphQL `Grade.score` 是 `Float!`，BFF response-mapper 需做 `Number.parseFloat(score)` 转换，转换失败抛 BFF_PARENT_BAD_GATEWAY
+- `msg.v1.Notification.is_read` 映射为 GraphQL `Notification.read`（字段名重命名）
+- `msg.v1.Notification` 无 `child_id` 字段（ISSUE-007），GraphQL `Notification.childId` 暂从 notification.type+content 解析或置 null，待 ai10 补 proto 字段

-无。
+### 2.2 Kafka 事件订阅（异步，P5 可选）
+
+> P4 阶段不订阅事件（02 §5.1）。P5 阶段可选订阅以下 topic 用于实时推送 + 缓存失效（02 §5.2）。
+
+| Topic | 事件 | 发布方 | 消费动作 | 幂等性 | 阶段 |
+| --- | --- | --- | --- | --- | --- |
+| edu.notification.sent | 通知发送 | msg | 推送给家长（push-gateway HTTP） | event_id SETNX | P5 |
+| edu.notification.read | 通知已读 | msg | 失效 bff:parent:notifications:* | event_id SETNX | P5 |
+| edu.notification.recalled | 通知撤回 | msg | 失效通知缓存 + 推送撤回 | event_id SETNX | P5 |
+| edu.notification.failed | 通知失败 | msg | 记录日志 + 告警 | event_id SETNX | P5 |
+| edu.teaching.grade.recorded | 成绩录入 | core-edu | 失效 bff:parent:grades:{childId} + 推送 | event_id SETNX | P5 |
+| edu.teaching.homework.graded | 作业批改 | core-edu | 失效 bff:parent:homework:{childId} + 推送 | event_id SETNX | P5 |
+| edu.teaching.exam.published | 考试发布 | core-edu | 失效 bff:parent:exams:{childId} + 推送 | event_id SETNX | P5 |
+
+**消费者组**：`parent-bff-event-subscriber`（02 §5.5）
+**DLQ**：`edu.parent-bff.dlq`
+**提交策略**：manual commit
+
+### 2.3 HTTP 调用（非 gRPC）
+
+| 被调用方 | Method | Path | 用途 | 认证 | 阶段 |
+| --- | --- | --- | --- | --- | --- |
+| push-gateway (ai02) | POST | /internal/push | 推送给在线家长（**U2 仲裁**：push-gateway 豁免 gRPC） | X-Internal-Key | P5 |
+
+> push-gateway HTTP 调用在 P5 阶段启用，P4 不涉及。

 ---

@@ -79,43 +160,73 @@ GraphQL schema 文件路径：`apps/parent-bff/src/schema/*.graphql`（端口 :3

 ### 3.1 我依赖的上游就绪标志

- [ ] iam gRPC 50052 启用（ai06）—— **核心依赖 GetChildrenByParent（I3/ISSUE-047 裁决）**
+- [ ] iam gRPC 50052 启用（ai06）—— **核心依赖 GetChildrenByParent（I6 裁决，P0 阻塞）**
+- [ ] iam 补 GetViewports / GetEffectivePermissions RPC（coord-cross-review #1）
+- [ ] iam_student_guardians 表已建立（I6 裁决）
 - [ ] core-edu gRPC 50053 启用（ai08）
+- [ ] core-edu ClassService.GetClass proto 补全（ISSUE-008 待仲裁）
 - [ ] data-ana gRPC 50055 启用（ai11）
- [ ] msg gRPC 50056 启用（ai10）
+- [ ] msg gRPC 50056 启用（ai10）—— P5
+- [ ] msg.proto Notification 补 child_id 字段（ISSUE-007 待仲裁）—— P5
+- [ ] msg NotificationPreferenceService 补全 —— P5
+- [ ] push-gateway /internal/push 启用（ai02）—— P5
+- [ ] api-gateway /parent 路由注册（ai01）
+- [ ] Kafka topic 已创建（C5 仲裁）—— P5
+- [ ] Redis 已部署且网络可达
+- [ ] buf.gen.yaml 补 gRPC TS 插件（coord）

 ### 3.2 我的就绪标志（供下游消费）

 - [ ] parent-bff GraphQL :3010 启用（/healthz 返回 200）
- [ ] /readyz 返回 200（含 4 个下游 gRPC 连通性检查）
+- [ ] /readyz 返回 200（含 4 个下游 gRPC 连通性检查：iam + core-edu + data-ana + Redis，02 §9 #7）
 - [ ] GraphQL schema 可内省（POST /graphql 返回 schema）
- [ ] 核心 Query 可执行：currentUser / myChildren / childSummary / childGrades
- [ ] 核心 Mutation 可执行：markAsRead
- [ ] 数据范围校验生效（家长只能查自己孩子的数据，基于 iam.GetChildrenByParent 返回的 user_id 校验）
+- [ ] 核心 Query 可执行：dashboard / children / childGrades / childAnalytics
+- [ ] 核心 Mutation 可执行：selectChild（P4）/ markNotificationRead（P5）
+- [ ] DataScope=CHILDREN 校验生效（家长只能查自己孩子的数据，ChildGuard 基于 iam.GetChildrenByParent 返回的列表校验）
+- [ ] /metrics 暴露 parent_bff_* 指标

 ---

 ## §4 Mock 策略

-### 4.1 我提供的 mock
+### 4.1 我提供的 mock（供下游 parent-portal ai15）

-在 parent-bff 真实就绪前，为下游（parent-portal）提供以下 mock：
+在 parent-bff 真实就绪前，为 parent-portal 提供以下 mock：

- **GraphQL mock**：使用 Apollo Server mockProviders 或 MSW 拦截 POST /graphql
-  - currentUser 返回固定家长（id="parent-001", name="王家长", roles=["parent"]）
-  - myChildren 返回固定 2 个孩子（id="student-001" 李同学 + id="student-002" 李妹妹）
-  - childSummary 返回固定仪表盘（child_avg_score=85.0, child_class_rank=5）
-  - childGrades 返回固定 5 个成绩
-  - childAttendance 返回固定 10 条考勤
-  - myNotifications 返回固定 10 条通知
+- **GraphQL mock**：使用 MSW 拦截 POST /graphql 或 Apollo Server mockProviders
+  - `dashboard` 返回固定家长（id="parent-001", name="王家长", roles=["parent"]）+ 2 个孩子 + unreadNotifications=3
+  - `children` 返回固定 2 个孩子（id="student-001" 李同学 + id="student-002" 李妹妹）
+  - `childGrades` 返回固定 5 个成绩（含 score 字段，Float 类型）
+  - `childAnalytics` 返回固定学情（child_avg_score=85.0, class_rank=5）
+  - `childHomework` 返回固定 3 个作业
+  - `childExams` 返回固定 3 个考试
+  - `notifications`（P5）返回固定 10 条通知（含 childId 字段）

-### 4.2 我消费的 mock
+### 4.2 我消费的 mock（上游未就绪时）

 在真实上游就绪前，parent-bff 使用以下 mock（详见 §2.1 mock 策略列）：

 - **iam mock**：固定 UserInfo + 家长权限 + 固定视口 + 固定 2 个 ChildInfo（家长-学生关联核心数据）
- **core-edu mock**：固定孩子成绩/考勤/作业
- **data-ana mock**：固定家长仪表盘/孩子薄弱点/趋势
- **msg mock**：固定通知列表 + MarkAsRead success
+- **core-edu mock**：固定孩子成绩/作业/考试/班级信息
+- **data-ana mock**：固定孩子薄弱点/趋势/班级对比
+- **msg mock**（P5）：固定通知列表（含 childId）+ MarkAsRead success + 固定偏好配置
+- **push-gateway mock**（P5）：fetch mock 返回 success
+- **Redis**：Testcontainers 真实 Redis 实例（不用 mock）
+- **Kafka**（P5）：kafkajs mock + jest.mock

-> 关键：iam.GetChildrenByParent 的 mock 必须返回与 core-edu mock 数据一致的 student_id，否则数据范围校验会失败。parent-bff 启动时校验 myChildren 返回的 user_id 与下游查询的 student_id 一致性。
+> **关键约束**：iam.GetChildrenByParent 的 mock 必须返回与 core-edu mock 数据一致的 student_id（student-001 + student-002），否则 ChildGuard 越权校验会失败。parent-bff 启动时校验 myChildren 返回的 user_id 与下游查询的 student_id 一致性。
+
+---
+
+## §5 跨模块契约冲突跟踪
+
+> 以下为 ai05 复审发现的跨模块契约问题，详见 [objections/parent-bff_issue.md](../objections/parent-bff_issue.md)
+
+| ISSUE | 问题 | 影响 | 状态 |
+| --- | --- | --- | --- |
+| ISSUE-003 | contract.md 仲裁引用编号错误（I3 → I6） | 引用勘误，已修正本文档 | 待 coord 确认 |
+| ISSUE-004 | 004 §4 + matrix.md §1 未同步 C6 仲裁（缺 DataAna + Msg） | 新 AI 误判依赖 | 待 coord 仲裁 |
+| ISSUE-005 | parent-portal 01 文档仍按 REST 消费 parent-bff | 跨模块契约冲突 | 待 coord 仲裁 |
+| ISSUE-006 | proto 包名引用缺 next_edu_cloud 前缀 | gRPC 代码生成错误，已修正本文档 | 待 coord 确认 |
+| ISSUE-007 | msg.proto Notification 缺 child_id 字段 | 按孩子过滤通知失效 | 待 coord 仲裁 |
+| ISSUE-008 | core_edu.proto 缺 ClassService + Grade.score 类型不一致 | 班级信息查询 + 类型转换 | 待 coord 仲裁 |