xiner/Edu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(parent-portal): 恢复 nextstep.md v1 原貌 + 新增 nextstep-v2.md 核查报告

Browse Source 
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
2026-07-14 10:14:43 +08:00
parent 0066afc55e
commit 74077c7083
2 changed files with 343 additions and 190 deletions
Download Patch File Download Diff File Expand all files Collapse all files

208
apps/parent-portal/docs/nextstep-v2.md Normal file
View 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 联调。

259
apps/parent-portal/docs/nextstep.md
View File

@@ -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,94 +35,71 @@ 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` | （前端未使用） | 后端已有但前端未对接，保留 |
### 修复步骤
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 个）
### 4.2 完全缺失的 Query（15 个，后端需新增）
| 前端 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 |
@@ -145,88 +118,71 @@ RUN corepack enable && corepack prepare pnpm@9.12.0 --activate
| `childDetail` | data-ana |
| `childGrowthArchive` | data-ana |
### 缺失的 Mutation（3 个）
### 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` | 命名不一致（后端 `markNotificationRead`） |
| -------------------- | ---------------------------------------------------------- |
| `markAsRead` | parent-bff（重命名 `markNotificationRead` → `markAsRead`） |
| `markAllAsRead` | parent-bff（新增） |
| `switchChild` | 命名不一致（后端 `selectChild`） |
| `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. **契约先行**：更新 `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` |
| ----------------------- | ----------------------- | ----------------------------------------------------------------------------------------------- |
| 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` |
| parent-bff pnpm-lock.yaml | ✅ 已添加 | `services/parent-bff/pnpm-lock.yaml`（241KB） |
---
## 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 错误）
---
@@ -234,32 +190,21 @@ docker pull golang:1.22-alpine
## 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 联调。