docs(parent-portal): 恢复 nextstep.md v1 原貌 + 新增 nextstep-v2.md 核查报告
v1 保持原样（2026-07-13 初版下游待办） v2 新增（2026-07-14 核查结果）：1 项已完成（pnpm-lock），4 项仍未完成（端点路径/Docker/schema/api-gateway 镜像） v2 新发现：extended-resolvers.ts 存在但未集成且引用不存在的类型；parent-bff Dockerfile pnpm 版本未固定
This commit is contained in:
SpecialX
208
apps/parent-portal/docs/nextstep-v2.md
Normal file
208
apps/parent-portal/docs/nextstep-v2.md
Normal file
@@ -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 联调。
|
||||
Reference in New Issue
Block a user