From 74077c7083f43a0f94fb2b07b4fbbb5e2dc6fb1c Mon Sep 17 00:00:00 2001 From: SpecialX <47072643+wangxiner55@users.noreply.github.com> Date: Tue, 14 Jul 2026 10:14:43 +0800 Subject: [PATCH] =?UTF-8?q?docs(parent-portal):=20=E6=81=A2=E5=A4=8D=20nex?= =?UTF-8?q?tstep.md=20v1=20=E5=8E=9F=E8=B2=8C=20+=20=E6=96=B0=E5=A2=9E=20n?= =?UTF-8?q?extstep-v2.md=20=E6=A0=B8=E6=9F=A5=E6=8A=A5=E5=91=8A?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit v1 保持原样（2026-07-13 初版下游待办） v2 新增（2026-07-14 核查结果）：1 项已完成（pnpm-lock），4 项仍未完成（端点路径/Docker/schema/api-gateway 镜像） v2 新发现：extended-resolvers.ts 存在但未集成且引用不存在的类型；parent-bff Dockerfile pnpm 版本未固定 --- apps/parent-portal/docs/nextstep-v2.md | 208 ++++++++++++++++ apps/parent-portal/docs/nextstep.md | 325 ++++++++++--------------- 2 files changed, 343 insertions(+), 190 deletions(-) create mode 100644 apps/parent-portal/docs/nextstep-v2.md diff --git a/apps/parent-portal/docs/nextstep-v2.md b/apps/parent-portal/docs/nextstep-v2.md new file mode 100644 index 0000000..74b6828 --- /dev/null +++ b/apps/parent-portal/docs/nextstep-v2.md @@ -0,0 +1,208 @@ +# parent-portal 下游待办事项 v2（核查结果） + +> 版本：v2 +> 日期：2026-07-14 +> 用途：核查 v1 记录的下游工作完成情况，记录仍未完成项与新发现的问题 +> 前置文档：[nextstep.md](./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 版本： + +```dockerfile +# 修复前 +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 联调。 diff --git a/apps/parent-portal/docs/nextstep.md b/apps/parent-portal/docs/nextstep.md index f44b98d..a37d865 100644 --- a/apps/parent-portal/docs/nextstep.md +++ b/apps/parent-portal/docs/nextstep.md @@ -1,32 +1,28 @@ # parent-portal 下游待办事项（Next Steps） -> 版本：v2 -> 日期：2026-07-14 +> 版本：v1 +> 日期：2026-07-13 > 用途：记录 parent-portal 切换至真实 API 集成所需的下游模块工作 > 背景：parent-portal 已完成 Docker Desktop 验证（容器健康、25 路由生成、/login 200、/api/health 200），现需下游服务就绪才能完成端到端真实 API 联调 --- -## 1. 当前状态摘要（v2 核查结果） +## 1. 当前状态摘要 -| 项目 | 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 实现 | +| 项目 | 状态 | 说明 | +| -------------------------- | ----------------- | ---------------------------------------------------------------------- | +| 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 端点路径错配（仍未修复） +## 2. P0 阻塞项：parent-bff 端点路径错配 ### 问题描述 @@ -39,227 +35,176 @@ api-gateway 代理路径转换： 但 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")` | +| 文件 | 当前 | 应改为 | +| ----------------------------------------------------- | ----------------------------- | -------------------------------------------------------------- | +| `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 Docker 构建失败（pnpm 版本问题） +## 3. P0 阻塞项：parent-bff 缺失 pnpm-lock.yaml ### 问题描述 -`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 -``` +`services/parent-bff/Dockerfile` 第 6 行 `RUN pnpm install --frozen-lockfile` 失败，因为 `services/parent-bff/` 目录下没有 `pnpm-lock.yaml` 文件。 ### 修复方案 -将 Dockerfile 第 4 行和第 14 行改为固定 pnpm 版本： +在 `services/parent-bff/` 目录执行 `pnpm install` 生成 lockfile，并提交到仓库。 -```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 +```bash +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 未扩充 + extended-resolvers 未集成 +## 4. P0 阻塞项：parent-bff GraphQL Schema 严重不对齐 ### 问题描述 -| 类别 | 前端定义 | 后端 schema | 后端 resolver | 差距 | -| -------- | -------- | ----------- | ------------------------------------- | --------- | -| Query | 32 个 | 10 个 | 10 个（extended-resolvers.ts 未集成） | 22 个缺失 | -| Mutation | 6 个 | 3 个 | 3 个（extended-resolvers.ts 未集成） | 3 个缺失 | +| 类别 | 前端定义 | 后端实现 | 差距 | +| -------- | -------- | -------- | --------------------------------------------------------------- | +| Query | 32 个 | 11 个 | 21 个缺失（含 6 个命名不一致 + 15 个完全缺失 + 3 个签名不一致） | +| Mutation | 6 个 | 3 个 | 3 个缺失（含 2 个命名不一致 + 1 个完全缺失 + 1 个签名不一致） | -### 核查证据 +### 4.1 命名不一致的 Query（6 个） -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 +| 前端 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. **扩充 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（新增） | +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. P0 阻塞项：api-gateway Docker 构建失败（基础镜像无法拉取） +## 5. P1 阻塞项：api-gateway 镜像构建问题 ### 问题描述 -`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 -``` +`services/api-gateway/Dockerfile` 使用 `golang:1.22-alpine` 和 `alpine:3.20` 基础镜像，但本地 Docker Desktop 未拉取这两个镜像，且 daocloud 镜像源返回 401。 ### 修复方案 -方案 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 -``` +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` | -| push-gateway /ws | ✅ 完整实现 | `services/push-gateway/internal/ws/handler.go` | -| parent-bff pnpm-lock.yaml | ✅ 已添加 | `services/parent-bff/pnpm-lock.yaml`（241KB） | +| 服务 | 状态 | 验证位置 | +| ----------------------- | ----------------------- | ----------------------------------------------------------------------------------------------- | +| 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（下游修复后执行） +## 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-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/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 构建（待修复：基础镜像） | +| 文件 | 用途 | +| --------------------------------------------------------- | ---------------------------------------------------- | +| `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 构建（待修复：基础镜像缺失） | --- -## 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 联调。 +**总结**：parent-portal 前端已完全就绪（Docker 镜像构建成功、容器健康、25 路由可用、mock 已禁用），等待下游 parent-bff 完成端点路径修复 + schema 扩充 + resolver 实现后，即可完成端到端真实 API 联调。