faaaf29f67
1.AI 协作文档体系重构(objections/worklines/contracts+matrix.md) 2.coord 仲裁文档(final-decisions/cross-review/final-rulings/orchestration) 3.各服务 01/02 文档补全 4.共享包初始化(shared-ts/shared-go/hooks/ui-components/ui-tokens) 5.Proto 契约补全 6.004 架构影响地图更新 7.端口分配表 8.设计规格文档
6.8 KiB
6.8 KiB
parent-bff 对接契约
负责人：ai05 关联：matrix.md、iam.proto、core_edu.proto、analytics.proto、msg.proto
§1 我提供什么（对外接口）
1.1 gRPC 接口（如有）
无对外 gRPC。parent-bff 是 GraphQL 聚合层。
1.2 HTTP 端点（如有）
| Method | Path | 用途 | 认证 |
|---|---|---|---|
| POST | /graphql | 家长 BFF GraphQL 端点 | JWT 必需 + parent 角色 |
| GET | /graphql | GraphQL Playground（开发环境） | 开发环境公开 |
| GET | /healthz | 健康检查（liveness） | 公开 |
| GET | /readyz | 就绪检查（readiness，含下游 gRPC 连通性） | 公开 |
1.3 GraphQL schema（如 BFF）
GraphQL schema 文件路径：apps/parent-bff/src/schema/*.graphql（端口 :3010）
核心 Query / Mutation 域：
- 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）
1.4 Kafka 事件发布（如有）
无。parent-bff 不发布事件，仅做 gRPC 聚合。
1.5 错误码前缀
BFF_PARENT_（如 BFF_PARENT_UPSTREAM_UNAVAILABLE、BFF_PARENT_AGGREGATION_FAILED、BFF_PARENT_NO_CHILDREN、BFF_PARENT_FORBIDDEN）
§2 我消费什么（依赖上游）
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 |
2.2 Kafka 事件订阅（异步）
无。parent-bff 不订阅 Kafka 事件，仅做同步 gRPC 聚合。
2.3 HTTP 调用（如有）
无。
§3 就绪信号
3.1 我依赖的上游就绪标志
- iam gRPC 50052 启用（ai06）—— 核心依赖 GetChildrenByParent（I3/ISSUE-047 裁决）
- core-edu gRPC 50053 启用（ai08）
- data-ana gRPC 50055 启用（ai11）
- msg gRPC 50056 启用（ai10）
3.2 我的就绪标志（供下游消费）
- parent-bff GraphQL :3010 启用（/healthz 返回 200）
- /readyz 返回 200（含 4 个下游 gRPC 连通性检查）
- GraphQL schema 可内省（POST /graphql 返回 schema）
- 核心 Query 可执行：currentUser / myChildren / childSummary / childGrades
- 核心 Mutation 可执行：markAsRead
- 数据范围校验生效（家长只能查自己孩子的数据，基于 iam.GetChildrenByParent 返回的 user_id 校验）
§4 Mock 策略
4.1 我提供的 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 条通知
4.2 我消费的 mock
在真实上游就绪前，parent-bff 使用以下 mock（详见 §2.1 mock 策略列）：
- iam mock：固定 UserInfo + 家长权限 + 固定视口 + 固定 2 个 ChildInfo（家长-学生关联核心数据）
- core-edu mock：固定孩子成绩/考勤/作业
- data-ana mock：固定家长仪表盘/孩子薄弱点/趋势
- msg mock：固定通知列表 + MarkAsRead success
关键：iam.GetChildrenByParent 的 mock 必须返回与 core-edu mock 数据一致的 student_id，否则数据范围校验会失败。parent-bff 启动时校验 myChildren 返回的 user_id 与下游查询的 student_id 一致性。