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

parent-portal 下游待办事项 v2（核查结果）

版本：v2 日期：2026-07-14 用途：核查 v1 记录的下游工作完成情况，记录仍未完成项与新发现的问题 前置文档：nextstep.md（v1，2026-07-13）

---

1. 核查结论

v1 记录的 5 项下游待办中：

• ✅ 1 项已完成：parent-bff pnpm-lock.yaml 已添加
• ❌ 4 项仍未完成：端点路径、Docker 构建、schema 扩充、api-gateway 镜像

parent-portal 自身经验证仍完全就绪：Docker 镜像构建成功（standalone 模式，25 路由），容器 healthy，/api/health 200，/login 200，typecheck + lint 零错误。

---

2. 核查结果对照表

项目	v1 状态	v2 核查	说明
parent-portal Docker 镜像	✅ 已就绪	✅ 仍就绪	edu-parent-portal:test，standalone 模式，25 路由，容器 healthy
parent-portal 容器健康检查	✅ 通过	✅ 仍通过	/api/health 200，/login 200，容器状态 healthy
Mock 数据	✅ 已禁用	✅ 仍禁用	NEXT_PUBLIC_API_MOCKING=disabled
GraphQL 端点配置	✅ 已配置	✅ 仍配置	NEXT_PUBLIC_GRAPHQL_ENDPOINT=/api/v1/parent/v1/graphql
parent-bff pnpm-lock.yaml	❌ 缺失	✅ 已完成	241KB，可被 Docker 使用
parent-bff 端点路径	❌ 错配	❌ 仍未修复	controller 仍为 /graphql，应为 /v1/parent/v1/graphql
parent-bff GraphQL schema	❌ 未扩充	❌ 仍未扩充	仍为 10Q+3M，前端需 32Q+6M
parent-bff extended-resolvers.ts	—	❌ 未集成（新发现）	文件存在（990+ 行）但未被 resolvers/index.ts 导入，且引用 27+ 个 types.ts 中不存在的类型
parent-bff Docker 构建	❌ 缺 lockfile	❌ 新失败原因	pnpm 11.x ERR_PNPM_IGNORED_BUILDS（Dockerfile 用 npm install -g pnpm 安装最新版而非固定 9.12.0）
api-gateway Docker 构建	❌ 缺基础镜像	❌ 仍失败	golang:1.22-alpine 无法拉取（docker.io 被墙），本地仅有 golang:1.25-alpine
iam.GetChildrenByParent	✅ 已就绪	✅ 仍就绪	gRPC + HTTP 均已实现
push-gateway /ws	✅ 已就绪	✅ 仍就绪	完整 WebSocket 实现

---

3. 仍未完成的 P0 阻塞项

3.1 parent-bff 端点路径错配（仍未修复）

核查证据：

• services/parent-bff/src/entry/graphql.controller.ts:13 → @Controller("graphql")
• services/parent-bff/src/graphql/yoga.ts:77 → graphqlEndpoint: "/graphql"
• services/parent-bff/src/graphql/graphql.module.ts:66 → forRoutes("graphql")

修复位置：

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

3.2 parent-bff Docker 构建失败（新发现：pnpm 版本问题）

核查证据（Docker 构建日志）：

#10 19.19 [ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: @nestjs/core@10.4.22, protobufjs@7.6.5

原因：services/parent-bff/Dockerfile 第 4 行 RUN npm install -g pnpm 安装最新版 pnpm（11.x），而 lockfile 是用 pnpm 9.x 生成。pnpm 11.x 引入 ERR_PNPM_IGNORED_BUILDS 错误，导致 --frozen-lockfile 失败。

修复方案：将 Dockerfile 第 4 行和第 14 行改为固定 pnpm 版本：

# 修复前
RUN npm install -g pnpm

# 修复后
RUN npm install -g pnpm@9.12.0

3.3 parent-bff GraphQL Schema 未扩充 + extended-resolvers 未集成（新发现）

核查证据：

1. schema 文件未扩充：packages/shared-ts/contracts/graphql/parent-bff.graphql 仍只有 10Q+3M
2. extended-resolvers.ts 未集成：services/parent-bff/src/graphql/resolvers/index.ts 未导入 extended-resolvers.ts
3. extended-resolvers.ts 引用不存在的类型：引用 27+ 个类型（如 AcademicYearType、AttendanceRecordType、ChildBriefType 等），但 services/parent-bff/src/graphql/types.ts 中只有 24 个原始类型定义，这些新类型不存在
4. graphql.module.ts 未引用 extended-resolvers：buildResolvers(deps) 调用的仍是原始 resolver

修复步骤：

1. 扩充 services/parent-bff/src/graphql/types.ts：新增 extended-resolvers.ts 引用的 27+ 个类型定义
2. 扩充 schema：更新 packages/shared-ts/contracts/graphql/parent-bff.graphql 至 32Q+6M
3. 集成 extended-resolvers：在 services/parent-bff/src/graphql/resolvers/index.ts 中导入并合并
4. 验证编译：pnpm build 通过

缺失的 Query（22 个）：

前端 operation	涉及下游服务
currentUser	命名不一致（后端 me）
myChildren	命名不一致（后端 children）
childSummary	完全缺失
childAttendance	core-edu
childWeakness	data-ana
childTrend	data-ana
childExamResult	core-edu
childClasses	classes
childLearningPath	data-ana
myNotifications	命名不一致（后端 notifications）
myNotificationPreferences	命名不一致（后端 notificationPreferences）
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

缺失的 Mutation（3 个）：

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

3.4 api-gateway Docker 构建失败（仍失败）

核查证据（Docker 构建日志）：

#3 ERROR: failed to authorize: failed to fetch oauth token:
Post "https://auth.docker.io/token": dial tcp 157.240.20.18:443: connectex: ...

本地镜像：

golang   1.25-alpine   56961d79ea81   6 days ago   329MB

修复方案（三选一）：

• 方案 A（推荐）：修改 Dockerfile 使用本地已有镜像 FROM golang:1.25-alpine AS builder
• 方案 B：通过 daocloud 拉取 FROM docker.m.daocloud.io/library/golang:1.22-alpine AS builder
• 方案 C：提前手动拉取 docker pull golang:1.22-alpine

---

4. v1 → v2 变更记录

项目	v1 状态	v2 核查结果
parent-bff pnpm-lock.yaml	❌ 缺失	✅ 已完成
parent-bff 端点路径	❌ 错配	❌ 仍未修复
parent-bff GraphQL schema	❌ 未扩充	❌ 仍未扩充，且发现 extended-resolvers.ts 存在但未集成
parent-bff Docker 构建	❌ 缺 lockfile	❌ 新失败原因：pnpm 11.x ERR_PNPM_IGNORED_BUILDS
api-gateway Docker 构建	❌ 缺基础镜像	❌ 仍失败：golang:1.22-alpine 无法拉取

---

5. 验证 Checklist（下游修复后执行）

• parent-bff Dockerfile 固定 pnpm 版本为 9.12.0
• parent-bff GraphQL 端点路径改为 /v1/parent/v1/graphql（3 处）
• parent-bff types.ts 新增 27+ 个类型定义
• parent-bff schema 扩充至 32Q+6M
• parent-bff resolvers/index.ts 集成 extended-resolvers.ts
• parent-bff pnpm build 编译通过
• parent-bff Docker 镜像构建成功
• api-gateway Dockerfile 改用 golang:1.25-alpine 或提前拉取 golang:1.22-alpine
• api-gateway Docker 镜像构建成功
• 在 Docker Desktop 启动完整服务栈
• parent-portal 端到端联调：登录 → /parent/dashboard → 各功能页面
• 验证 25 个路由全部可访问（无 500 错误）

---

6. 关键文件路径

文件	用途
apps/parent-portal/Dockerfile	parent-portal Docker 构建（已就绪，standalone 模式）
apps/parent-portal/next.config.js	Next.js 配置（已就绪，output: standalone）
apps/parent-portal/src/lib/graphql/operations.ts	前端所有 GraphQL operations（32Q+6M）
services/parent-bff/Dockerfile	parent-bff Docker 构建（待修复：pnpm 版本）
services/parent-bff/src/entry/graphql.controller.ts:13	GraphQL 端点路径（待修复）
services/parent-bff/src/graphql/yoga.ts:77	GraphQL Yoga 配置（待修复）
services/parent-bff/src/graphql/graphql.module.ts:66	GraphQL 模块路由（待修复）
services/parent-bff/src/graphql/resolvers/index.ts	resolver 入口（待集成 extended-resolvers）
services/parent-bff/src/graphql/resolvers/extended-resolvers.ts	扩展 resolver（已写但未集成）
services/parent-bff/src/graphql/types.ts	类型定义（待扩充 27+ 个类型）
packages/shared-ts/contracts/graphql/parent-bff.graphql	GraphQL schema 契约（待扩充至 32Q+6M）
services/api-gateway/Dockerfile:5	api-gateway Docker 构建（待修复：基础镜像）

---

总结：parent-portal 前端已完全就绪（Docker 镜像构建成功、容器 healthy、25 路由可用、mock 已禁用、typecheck + lint 零错误）。v2 核查发现下游 parent-bff 仍有 4 项 P0 阻塞未解决（端点路径、Docker 构建、schema 扩充、extended-resolvers 集成），api-gateway 仍有 1 项 P0 阻塞（基础镜像）。需下游修复后才能完成端到端真实 API 联调。