Edu/apps/parent-portal/docs/nextstep.md

parent-portal 下游待办事项（Next Steps）

版本：v1 日期：2026-07-13 用途：记录 parent-portal 切换至真实 API 集成所需的下游模块工作 背景：parent-portal 已完成 Docker Desktop 验证（容器健康、25 路由生成、/login 200、/api/health 200），现需下游服务就绪才能完成端到端真实 API 联调

---

1. 当前状态摘要

项目	状态	说明
parent-portal Docker 镜像	✅ 已就绪	edu-parent-portal:test，standalone 模式，25 路由
parent-portal 容器健康检查	✅ 通过	/api/health 200，/login 200，/parent/dashboard 307 auth redirect
Mock 数据	✅ 已禁用	NEXT_PUBLIC_API_MOCKING=disabled
GraphQL 端点配置	✅ 已配置	NEXT_PUBLIC_GRAPHQL_ENDPOINT=/api/v1/parent/v1/graphql
parent-bff 服务	❌ 未就绪	端点路径错配 + 27 query / 5 mutation 缺失
api-gateway 路由	⚠️ 已配置但未验证	/api/v1/parent/* → parent-bff:3010，但 parent-bff 未运行
iam GetChildrenByParent	✅ 已就绪	gRPC + HTTP 均已实现
push-gateway /ws	✅ 已就绪	完整 WebSocket 实现

---

2. P0 阻塞项：parent-bff 端点路径错配

问题描述

前端调用 GraphQL 端点：/api/v1/parent/v1/graphql（ARB-022 §24.4 ISSUE-003 方案 A 双 /v1 前缀）

api-gateway 代理路径转换：

• 入站：/api/v1/parent/v1/graphql
• 剥离 /api 后转发：/v1/parent/v1/graphql → parent-bff:3010

但 parent-bff 当前 controller 仅注册 /graphql，导致 /v1/parent/v1/graphql 在 parent-bff 找不到匹配的 handler，返回 404。

修复位置（parent-bff 模块）

文件	当前	应改为
services/parent-bff/src/entry/graphql.controller.ts	@Controller("graphql")	@Controller("v1/parent/v1/graphql") 或使用 setGlobalPrefix
services/parent-bff/src/graphql/yoga.ts	graphqlEndpoint: "/graphql"	graphqlEndpoint: "/v1/parent/v1/graphql"
services/parent-bff/src/graphql/graphql.module.ts	forRoutes("graphql")	forRoutes("v1/parent/v1/graphql")

验证步骤

1. 修改后构建 parent-bff 镜像
2. 启动 parent-bff 容器，验证 http://parent-bff:3010/v1/parent/v1/graphql 返回 200
3. 经 api-gateway 代理访问 http://api-gateway:8080/api/v1/parent/v1/graphql 返回 200

---

3. P0 阻塞项：parent-bff 缺失 pnpm-lock.yaml

问题描述

services/parent-bff/Dockerfile 第 6 行 RUN pnpm install --frozen-lockfile 失败，因为 services/parent-bff/ 目录下没有 pnpm-lock.yaml 文件。

修复方案

在 services/parent-bff/ 目录执行 pnpm install 生成 lockfile，并提交到仓库。

cd services/parent-bff
pnpm install
git add pnpm-lock.yaml
git commit -m "chore(parent-bff): add pnpm-lock.yaml for Docker build"

---

4. P0 阻塞项：parent-bff GraphQL Schema 严重不对齐

问题描述

类别	前端定义	后端实现	差距
Query	32 个	11 个	21 个缺失（含 6 个命名不一致 + 15 个完全缺失 + 3 个签名不一致）
Mutation	6 个	3 个	3 个缺失（含 2 个命名不一致 + 1 个完全缺失 + 1 个签名不一致）

4.1 命名不一致的 Query（6 个）

前端 operation	后端 operation	修复方式
currentUser	me	二选一统一命名（建议后端改 me → currentUser）
myChildren	children	二选一统一命名（建议后端改 children → myChildren）
myNotifications	notifications	二选一统一命名（建议后端改 notifications → myNotifications）
myNotificationPreferences	notificationPreferences	二选一统一命名
childSummary	child	字段不同，需明确语义
childAnalytics	（前端未使用）	后端已有但前端未对接，保留

4.2 完全缺失的 Query（15 个，后端需新增）

前端 operation	涉及下游服务
childAttendance	core-edu
childWeakness	data-ana
childTrend	data-ana
childExamResult	core-edu
childClasses	classes
childLearningPath	data-ana
childLeaveRequests	core-edu
academicYears	core-edu
childReportCard	core-edu
childErrorBookStats	data-ana
childTopWrongQuestions	data-ana
childWeakKps	data-ana
childMasterySummary	data-ana
childDiagnosticReports	data-ana
childPracticeStats	data-ana
childPracticeSessions	data-ana
childCoursePlans	core-edu
childCoursePlanDetail	content
childLessonPlans	core-edu
childLessonPlanDetail	content
childElective	content
childDetail	data-ana
childGrowthArchive	data-ana

4.3 签名不一致的 Query（3 个）

前端 operation	不一致点
childGrades	前端 (childId, subject, limit) vs 后端 (childId, page, pageSize, subject)；返回字段不同（前端 examName/examDate/studentScore/classMax/classMin/gradeLevel vs 后端 examId/examTitle/score/rank/gradedAt）
childHomework	前端有 status 过滤参数，后端无；字段差异大（前端 subject/className/assignedDate/score/maxScore/feedback vs 后端 title/classId/dueDate/status）
childExams	字段差异大（前端 name/subject/startsAt/expiresAt/durationSeconds/questionCount/totalScore vs 后端 title/examDate/publishedAt）

4.4 缺失的 Mutation（3 个）

前端 operation	涉及下游服务
markAsRead	parent-bff（重命名 markNotificationRead → markAsRead）
markAllAsRead	parent-bff（新增）
switchChild	parent-bff（重命名 selectChild → switchChild）
createLeaveRequest	core-edu（新增）
exportChildGrades	core-edu（新增）

4.5 签名不一致的 Mutation（1 个）

前端 operation	不一致点
updateNotificationPreferences	前端 (parentId, preferences: JSON, defaults: JSON) vs 后端 (input: UpdateNotificationPreferencesInput)

修复步骤

1. 契约先行：更新 packages/shared-ts/contracts/graphql/parent-bff.graphql，扩充至前端 32 query + 6 mutation
2. resolver 实现：在 services/parent-bff/src/graphql/resolvers/ 新增对应 resolver
3. 下游 gRPC client：在 services/parent-bff/src/clients/ 新增/对接 core-edu / data-ana / content / classes 的 gRPC client
4. 测试：parent-bff 单测 + parent-portal 端到端联调

---

5. P1 阻塞项：api-gateway 镜像构建问题

问题描述

services/api-gateway/Dockerfile 使用 golang:1.22-alpine 和 alpine:3.20 基础镜像，但本地 Docker Desktop 未拉取这两个镜像，且 daocloud 镜像源返回 401。

修复方案

1. 提前在服务器执行：docker pull golang:1.22-alpine && docker pull alpine:3.20
2. 或在 Dockerfile 中改用本地已有的镜像源

---

6. 已就绪的下游服务（无需等待）

服务	状态	验证位置
iam.GetChildrenByParent	✅ gRPC + HTTP 均已实现	services/iam/src/iam/iam.grpc.controller.ts:116、services/iam/src/iam/iam.controller.ts:116
push-gateway /ws	✅ 完整实现	services/push-gateway/internal/ws/handler.go

---

7. 验证 Checklist（下游就绪后执行）

• parent-bff 添加 pnpm-lock.yaml
• parent-bff GraphQL 端点路径改为 /v1/parent/v1/graphql
• parent-bff schema 扩充至 32 query + 6 mutation
• parent-bff 所有 resolver 实现完成
• api-gateway 镜像可构建
• 在 Docker Desktop 启动完整服务栈：api-gateway + parent-bff + iam + core-edu + data-ana + content + classes + push-gateway
• parent-portal 端到端联调：登录 → /parent/dashboard → 各功能页面
• 验证 WebSocket 推送：通知功能
• 验证 25 个路由全部可访问（无 500 错误）

---

8. 关键文件路径

文件	用途
apps/parent-portal/Dockerfile	parent-portal Docker 构建（已修复，standalone 模式）
apps/parent-portal/next.config.js	Next.js 配置（已添加 output: "standalone"）
apps/parent-portal/src/lib/graphql-client.ts	GraphQL 客户端配置
apps/parent-portal/src/lib/graphql/operations.ts	前端所有 GraphQL operations 定义
apps/parent-portal/.env.example	环境变量模板（NEXT_PUBLIC_API_MOCKING=disabled）
services/parent-bff/Dockerfile	parent-bff Docker 构建（待修复：缺 pnpm-lock.yaml）
services/parent-bff/src/entry/graphql.controller.ts	GraphQL 端点路径（待修复）
services/parent-bff/src/graphql/yoga.ts	GraphQL Yoga 配置（待修复）
services/parent-bff/src/graphql/graphql.module.ts	GraphQL 模块路由（待修复）
services/parent-bff/src/graphql/resolvers/index.ts	resolver 实现（待扩充）
packages/shared-ts/contracts/graphql/parent-bff.graphql	GraphQL schema 契约（待扩充）
services/api-gateway/main.go:86	parent 代理注册
services/api-gateway/Dockerfile	api-gateway Docker 构建（待修复：基础镜像缺失）

---

总结：parent-portal 前端已完全就绪（Docker 镜像构建成功、容器健康、25 路由可用、mock 已禁用），等待下游 parent-bff 完成端点路径修复 + schema 扩充 + resolver 实现后，即可完成端到端真实 API 联调。