# 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.13.0 + `--ignore-scripts` 解决 `ERR_PNPM_IGNORED_BUILDS`（build 仍失败为预存 TS 错误）                    |
| api-gateway Docker 构建          | ❌ 缺基础镜像  | ✅ **依赖统一已修复**   | 升级 `golang:1.25-alpine` + 修复 go.mod shared-go 依赖 + Dockerfile 用 repo 根作 context，构建成功 + /healthz 200 |
| 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 构建失败（✅ 依赖统一已修复）

> **2026-07-14 更新**：统一依赖管理迁移已解决此问题。Dockerfile 升级为 `corepack pnpm@11.13.0` + `--ignore-scripts`，`pnpm install --frozen-lockfile` 成功。`pnpm build` 仍失败为预存 TS 错误（extended-resolvers.ts 49 个类型错误），与依赖管理无关。

**历史记录**（已过时）：

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

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