xiner/Edu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
21f2485749924d550223bc722567ab0a0b7efb8e
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

266 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 版本：
```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
```
---
## 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 使用本地已有镜像
```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
```
---
## 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