96a936e154
Dockerfile 改用 standalone 模式 next.config.js 添加 output standalone 修复 cssnano-simple 构建失败：globals.css 注释含 */ 被误解析 tailwind.config.js 覆盖 boxShadow 为 rgba 格式 + 禁用 ringWidth 组件修复：替换 / 语法为 inline style 或自定义类 otel.ts 添加 webpackIgnore 跳过 optionalDependencies 静态分析 .env.example 默认禁用 mock 新增 .dockerignore 和 docs/nextstep.md 删除 postcss.config.js 验证：Docker 镜像构建成功，容器 healthy，typecheck + lint 零错误
211 lines
13 KiB
Markdown
211 lines
13 KiB
Markdown
# parent-portal 下游待办事项（Next Steps）
|
||
|
||
> 版本：v1
|
||
> 日期：2026-07-13
|
||
> 用途：记录 parent-portal 切换至真实 API 集成所需的下游模块工作
|
||
> 背景：parent-portal 已完成 Docker Desktop 验证（容器健康、25 路由生成、/login 200、/api/health 200），现需下游服务就绪才能完成端到端真实 API 联调
|
||
|
||
---
|
||
|
||
## 1. 当前状态摘要
|
||
|
||
| 项目 | 状态 | 说明 |
|
||
| -------------------------- | ----------------- | ---------------------------------------------------------------------- |
|
||
| 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 端点路径错配
|
||
|
||
### 问题描述
|
||
|
||
前端调用 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。
|
||
|
||
### 修复位置（parent-bff 模块）
|
||
|
||
| 文件 | 当前 | 应改为 |
|
||
| ----------------------------------------------------- | ----------------------------- | -------------------------------------------------------------- |
|
||
| `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 缺失 pnpm-lock.yaml
|
||
|
||
### 问题描述
|
||
|
||
`services/parent-bff/Dockerfile` 第 6 行 `RUN pnpm install --frozen-lockfile` 失败，因为 `services/parent-bff/` 目录下没有 `pnpm-lock.yaml` 文件。
|
||
|
||
### 修复方案
|
||
|
||
在 `services/parent-bff/` 目录执行 `pnpm install` 生成 lockfile，并提交到仓库。
|
||
|
||
```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 严重不对齐
|
||
|
||
### 问题描述
|
||
|
||
| 类别 | 前端定义 | 后端实现 | 差距 |
|
||
| -------- | -------- | -------- | --------------------------------------------------------------- |
|
||
| Query | 32 个 | 11 个 | 21 个缺失（含 6 个命名不一致 + 15 个完全缺失 + 3 个签名不一致） |
|
||
| Mutation | 6 个 | 3 个 | 3 个缺失（含 2 个命名不一致 + 1 个完全缺失 + 1 个签名不一致） |
|
||
|
||
### 4.1 命名不一致的 Query（6 个）
|
||
|
||
| 前端 operation | 后端 operation | 修复方式 |
|
||
| --------------------------- | ------------------------- | ---------------------------------------------------------------- |
|
||
| `currentUser` | `me` | 二选一统一命名（建议后端改 `me` → `currentUser`） |
|
||
| `myChildren` | `children` | 二选一统一命名（建议后端改 `children` → `myChildren`） |
|
||
| `myNotifications` | `notifications` | 二选一统一命名（建议后端改 `notifications` → `myNotifications`） |
|
||
| `myNotificationPreferences` | `notificationPreferences` | 二选一统一命名 |
|
||
| `childSummary` | `child` | 字段不同，需明确语义 |
|
||
| `childAnalytics` | （前端未使用） | 后端已有但前端未对接，保留 |
|
||
|
||
### 4.2 完全缺失的 Query（15 个，后端需新增）
|
||
|
||
| 前端 operation | 涉及下游服务 |
|
||
| ------------------------ | ------------ |
|
||
| `childAttendance` | core-edu |
|
||
| `childWeakness` | data-ana |
|
||
| `childTrend` | data-ana |
|
||
| `childExamResult` | core-edu |
|
||
| `childClasses` | classes |
|
||
| `childLearningPath` | data-ana |
|
||
| `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 |
|
||
|
||
### 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` | parent-bff（重命名 `markNotificationRead` → `markAsRead`） |
|
||
| `markAllAsRead` | parent-bff（新增） |
|
||
| `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. P1 阻塞项：api-gateway 镜像构建问题
|
||
|
||
### 问题描述
|
||
|
||
`services/api-gateway/Dockerfile` 使用 `golang:1.22-alpine` 和 `alpine:3.20` 基础镜像，但本地 Docker Desktop 未拉取这两个镜像，且 daocloud 镜像源返回 401。
|
||
|
||
### 修复方案
|
||
|
||
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`、`services/iam/src/iam/iam.controller.ts:116` |
|
||
| push-gateway /ws | ✅ 完整实现 | `services/push-gateway/internal/ws/handler.go` |
|
||
|
||
---
|
||
|
||
## 7. 验证 Checklist（下游就绪后执行）
|
||
|
||
- [ ] 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 错误）
|
||
|
||
---
|
||
|
||
## 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-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 构建（待修复：基础镜像缺失） |
|
||
|
||
---
|
||
|
||
**总结**：parent-portal 前端已完全就绪（Docker 镜像构建成功、容器健康、25 路由可用、mock 已禁用），等待下游 parent-bff 完成端点路径修复 + schema 扩充 + resolver 实现后，即可完成端到端真实 API 联调。
|