# parent-portal 下游待办事项（Next Steps） > 版本：v2 > 日期：2026-07-14 > 用途：记录 parent-portal 切换至真实 API 集成所需的下游模块工作 > 背景：parent-portal 已完成 Docker Desktop 验证（容器健康、25 路由生成、/login 200、/api/health 200），现需下游服务就绪才能完成端到端真实 API 联调 --- ## 1. 当前状态摘要（v2 核查结果） | 项目 | 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 构建 | ❌ 失败 | ❌ **仍失败** | 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 实现 | --- ## 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。 ### 核查证据 - `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")` ### 修复位置（parent-bff 模块） | 文件 | 当前 | 应改为 | | -------------------------------------------------------- | ----------------------------- | ------------------------------------------ | | `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. P0 阻塞项：parent-bff Docker 构建失败（pnpm 版本问题） ### 问题描述 `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` 安装失败。 ### 核查证据 Docker 构建日志： ``` #10 19.19 [ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: @nestjs/core@10.4.22, protobufjs@7.6.5 ``` ### 修复方案 将 Dockerfile 第 4 行和第 14 行改为固定 pnpm 版本： ```dockerfile # 修复前 RUN npm install -g pnpm # 修复后 RUN npm install -g pnpm@9.12.0 ``` 或使用 `corepack`： ```dockerfile RUN corepack enable && corepack prepare pnpm@9.12.0 --activate ``` --- ## 4. P0 阻塞项：parent-bff GraphQL Schema 未扩充 + extended-resolvers 未集成 ### 问题描述 | 类别 | 前端定义 | 后端 schema | 后端 resolver | 差距 | | -------- | -------- | ----------- | ------------------------------------- | --------- | | Query | 32 个 | 10 个 | 10 个（extended-resolvers.ts 未集成） | 22 个缺失 | | Mutation | 6 个 | 3 个 | 3 个（extended-resolvers.ts 未集成） | 3 个缺失 | ### 核查证据 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. **扩充 types.ts**：在 `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` 中导入并合并 extended-resolvers 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（新增） | --- ## 5. P0 阻塞项：api-gateway Docker 构建失败（基础镜像无法拉取） ### 问题描述 `services/api-gateway/Dockerfile` 第 5 行 `FROM golang:1.22-alpine`，但 docker.io 被墙无法拉取。本地仅有 `golang:1.25-alpine`。 ### 核查证据 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 使用本地已有镜像 ```dockerfile # 修复前 FROM golang:1.22-alpine AS builder # 修复后 FROM golang:1.25-alpine AS builder ``` 方案 B：通过 daocloud 拉取 ```dockerfile FROM docker.m.daocloud.io/library/golang:1.22-alpine AS builder ``` 方案 C：提前手动拉取 ```bash docker pull golang:1.22-alpine ``` --- ## 6. 已就绪的下游服务（无需等待） | 服务 | 状态 | 验证位置 | | ------------------------- | ----------------------- | ------------------------------------------------- | | iam.GetChildrenByParent | ✅ gRPC + HTTP 均已实现 | `services/iam/src/iam/iam.grpc.controller.ts:116` | | push-gateway /ws | ✅ 完整实现 | `services/push-gateway/internal/ws/handler.go` | | parent-bff pnpm-lock.yaml | ✅ 已添加 | `services/parent-bff/pnpm-lock.yaml`（241KB） | --- ## 7. 验证 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 错误） --- ## 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/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 构建（待修复：基础镜像） | --- ## 9. 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 无法拉取 | --- **总结**：parent-portal 前端已完全就绪（Docker 镜像构建成功、容器 healthy、25 路由可用、mock 已禁用、typecheck + lint 零错误）。v2 核查发现下游 parent-bff 仍有 4 项 P0 阻塞未解决（端点路径、Docker 构建、schema 扩充、extended-resolvers 集成），api-gateway 仍有 1 项 P0 阻塞（基础镜像）。需下游修复后才能完成端到端真实 API 联调。