xiner/Edu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
41179ff0a9cec7f3bbb9fc02ab3630dd24ddf40c
Edu/apps/parent-portal/docs/nextstep.md
SpecialX 41179ff0a9 docs(parent-portal): nextstep.md v2 核查下游服务完成情况 
v2 核查结果：parent-bff pnpm-lock 已添加，但端点路径/schema/Docker 构建/extended-resolvers 集成仍未完成

api-gateway Docker 构建仍失败（golang:1.22-alpine 无法拉取）

parent-portal 自身 Docker 镜像构建成功，容器 healthy，typecheck + lint 零错误
2026-07-14 08:29:25 +08:00

15 KiB
Raw Blame History

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 版本：

# 修复前
RUN npm install -g pnpm

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

或使用 corepack：

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 使用本地已有镜像

# 修复前
FROM golang:1.22-alpine AS builder

# 修复后
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

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 联调。

Reference in New Issue View Git Blame Copy Permalink