xiner/Edu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
fb23c5234e30bdbe4564d0d31464640e131d777f
Edu/apps/parent-portal/docs/nextstep-v2.md
SpecialX 81a539b9ab
Some checks failed
CI / quality-ts (push) Failing after 6s
Details
CI / quality-go (push) Failing after 25s
Details
CI / quality-proto (push) Failing after 6s
Details
CI / deploy (push) Has been skipped
Details
chore(deps): 统一依赖管理 - pnpm 11 + node:22 + golang:1.25 + python:3.12 + shared-* 集中化 
- Node.js 统一到 node:22-alpine，Go 统一到 golang:1.25-alpine，Python 统一到 python:3.12-slim

- pnpm 升级到 11.13.0（corepack），新增 allowBuilds 白名单解决 ERR_PNPM_IGNORED_BUILDS

- 新增 packages/shared-py 集中 Python 共享依赖，shared-ts 补充 graphql-yoga/prom-client

- api-gateway 修复 go.mod 的 shared-go 依赖 + Dockerfile 改用 repo 根作 context

- Python 服务（data-ana/ai）Dockerfile 改用 repo 根作 context + 声明 uv workspace sources

- 16 个服务的 Dockerfile + CI + docker-compose.tools.yml 全部对齐版本矩阵

- known-issues.md 沉淀 9 条 pnpm 11 / uv workspace / Go shared-go 迁移经验

- 验证：4 服务完全成功（api-gateway /healthz 200），其余 install 成功（build 失败为预存 TS 错误）
2026-07-14 12:04:49 +08:00

199 lines
14 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 下游待办事项 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 联调。
Reference in New Issue View Git Blame Copy Permalink