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

docs(admin-portal): 新增 nextstep-v2.md 记录下游核查结果

Browse Source 
v1 声称完成的下游工作经核查实际未完成：
- api-gateway: /api/admin/graphql 路由未注册，go vet 编译失败
- teacher-bff: resolver 已完成但 schema 未同步（命名空间 vs 扁平）
- iam: proto 缺 BatchGetUsers rpc 声明

v2 记录详细核查证据和修复要求
This commit is contained in:
SpecialX
2026-07-14 08:26:27 +08:00
parent 99580fa13a
commit 0b42302a64
42 changed files with 4804 additions and 637 deletions
Download Patch File Download Diff File Expand all files Collapse all files

216
apps/teacher-portal/nextstep.md
View File

@@ -12,19 +12,19 @@
## 1. 当前状态总览
| 阶段 | 状态 | 说明 |
| ---- | ---- | ---- |
| P2 MF Shell + 基础页面 | ✅ 完成 | AppShell + urql GraphQL Provider + 6 基础页面 |
| P3 考试/作业/成绩 | ✅ 完成 | 详情 + 批改 + 乐观更新 + 多 Tab 同步 |
| P4 知识图谱 + 学情分析 | ✅ 完成 | SVG 可视化 + 班级/单生学情 |
| P5 通知 + AI 助手 | ✅ 完成 | WebSocket + SSE 流式 AI 出题/教案/学情报告 |
| P6 可观测性硬化 | ✅ 完成 | Sentry + WebVitals + OTel + A11y + 性能预算 |
| P7 参考项目差距闭环 | ✅ 完成 | 新增 35 页面，覆盖参考项目全部 16 业务模块 |
| Docker Desktop 验证 | ✅ 通过 | standalone 模式构建 + 27 静态 + 11 动态路由全部 200 |
| MSW mock → 真实 API 切换 | ⏳ 待上游 | 需 teacher-bff GraphQL schema 上线 |
| 单元测试 | ⏳ 待补 | vitest 配置 + 关键 hook/组件测试 |
| 设计令牌硬化 | ⏳ 待补 | globals.css hsl() 字面量修复 |
| i18n 集成 | ⏳ 待补 | 中文硬编码 → next-intl |
| 阶段 | 状态 | 说明 |
| ------------------------ | --------- | --------------------------------------------------- |
| P2 MF Shell + 基础页面 | ✅ 完成 | AppShell + urql GraphQL Provider + 6 基础页面 |
| P3 考试/作业/成绩 | ✅ 完成 | 详情 + 批改 + 乐观更新 + 多 Tab 同步 |
| P4 知识图谱 + 学情分析 | ✅ 完成 | SVG 可视化 + 班级/单生学情 |
| P5 通知 + AI 助手 | ✅ 完成 | WebSocket + SSE 流式 AI 出题/教案/学情报告 |
| P6 可观测性硬化 | ✅ 完成 | Sentry + WebVitals + OTel + A11y + 性能预算 |
| P7 参考项目差距闭环 | ✅ 完成 | 新增 35 页面，覆盖参考项目全部 16 业务模块 |
| Docker Desktop 验证 | ✅ 通过 | standalone 模式构建 + 27 静态 + 11 动态路由全部 200 |
| MSW mock → 真实 API 切换 | ⏳ 待上游 | 需 teacher-bff GraphQL schema 上线 |
| 单元测试 | ⏳ 待补 | vitest 配置 + 关键 hook/组件测试 |
| 设计令牌硬化 | ⏳ 待补 | globals.css hsl() 字面量修复 |
| i18n 集成 | ⏳ 待补 | 中文硬编码 → next-intl |
---
@@ -38,19 +38,19 @@
**具体清单**：
| 模块 | GraphQL operations 数 | 上游要求 |
| ---- | -------------------- | -------- |
| 基础（P2） | 5 Query + 1 Mutation | MeQuery / ViewportsQuery / ClassesQuery / ExamsQuery / HomeworkQuery / GradesQuery / LoginMutation |
| 考试/作业/成绩（P3） | 5 Query + 3 Mutation | ExamDetailQuery / HomeworkDetailQuery / CreateExamMutation / AssignHomeworkMutation / RecordGradeMutation |
| 知识图谱/学情（P4） | 3 Query | KnowledgeGraphQuery / ClassAnalyticsQuery / StudentAnalyticsQuery |
| 通知/AI（P5） | 2 Query + 3 Mutation | MyNotificationsQuery / MarkAsReadMutation / GenerateQuestionMutation / GenerateLessonPlanMutation / GenerateReportMutation |
| 成绩增强（P7-A） | 4 Query + 1 Mutation | GradeEntryQuery / SaveGradeEntriesMutation / GradeStatsQuery / GradeAnalyticsQuery / ReportCardQuery |
| 作业批改（P7-A） | 3 Query + 1 Mutation | HomeworkSubmissionsQuery / HomeworkAssignmentSubmissionsQuery / GradeSubmissionMutation |
| 考试组卷（P7-B） | 2 Query + 1 Mutation | ExamBuildQuery / SaveExamBuildMutation / ExamAnalyticsQuery |
| 题库/教材（P7-B） | 5 Query + 4 Mutation | QuestionsLibraryQuery / QuestionCreate/Update/DeleteMutation / QuestionBatchImportMutation / QuestionBatchExportQuery / TextbooksQuery / TextbookDetailQuery / TextbookCreateMutation |
| 考勤/班级/请假/调课（P7-C） | 8 Query + 4 Mutation | AttendanceListQuery / AttendanceSheetQuery / SaveAttendanceSheetMutation / AttendanceStatsQuery / AttendanceReportQuery / ClassDetailQuery / ClassScheduleQuery / LeaveRequestsQuery / ApproveLeaveRequestMutation / SubmitLeaveRequestMutation / SubmitScheduleChangeMutation / ScheduleChangesQuery |
| 备课/诊断/错题/练习（P7-D） | 12 Query + 5 Mutation | LessonPlansQuery / LessonPlanDetailQuery / CreateLessonPlanMutation / UpdateLessonPlanMutation / AIGenerateLessonPlanMutation / LessonPlanLibraryQuery / ForkLessonPlanMutation / LessonPlanCalendarQuery / LessonPlanHeatmapQuery / CoursePlansQuery / CoursePlanDetailQuery / CreateCoursePlanMutation / UpdateCoursePlanMutation / DiagnosticReportsQuery / ClassDiagnosticQuery / StudentDiagnosticQuery / ErrorBookQuery / PracticeAnalyticsQuery |
| 选课/富文本/监考/扫描批改/热力图（P7-E） | 8 Query + 5 Mutation | ElectiveCoursesQuery / ElectiveCourseDetailQuery / CreateElectiveCourseMutation / UpdateElectiveCourseMutation / PublishElectiveCourseMutation / CancelElectiveCourseMutation / ExamRichEditorQuery / SaveExamRichContentMutation / ProctoringStatusQuery / ProctoringEventMutation / SubmissionScanGradingQuery / SaveScanGradingMutation / LessonPlanHeatmapQuery |
| 模块 | GraphQL operations 数 | 上游要求 |
| ---------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 基础（P2） | 5 Query + 1 Mutation | MeQuery / ViewportsQuery / ClassesQuery / ExamsQuery / HomeworkQuery / GradesQuery / LoginMutation |
| 考试/作业/成绩（P3） | 5 Query + 3 Mutation | ExamDetailQuery / HomeworkDetailQuery / CreateExamMutation / AssignHomeworkMutation / RecordGradeMutation |
| 知识图谱/学情（P4） | 3 Query | KnowledgeGraphQuery / ClassAnalyticsQuery / StudentAnalyticsQuery |
| 通知/AI（P5） | 2 Query + 3 Mutation | MyNotificationsQuery / MarkAsReadMutation / GenerateQuestionMutation / GenerateLessonPlanMutation / GenerateReportMutation |
| 成绩增强（P7-A） | 4 Query + 1 Mutation | GradeEntryQuery / SaveGradeEntriesMutation / GradeStatsQuery / GradeAnalyticsQuery / ReportCardQuery |
| 作业批改（P7-A） | 3 Query + 1 Mutation | HomeworkSubmissionsQuery / HomeworkAssignmentSubmissionsQuery / GradeSubmissionMutation |
| 考试组卷（P7-B） | 2 Query + 1 Mutation | ExamBuildQuery / SaveExamBuildMutation / ExamAnalyticsQuery |
| 题库/教材（P7-B） | 5 Query + 4 Mutation | QuestionsLibraryQuery / QuestionCreate/Update/DeleteMutation / QuestionBatchImportMutation / QuestionBatchExportQuery / TextbooksQuery / TextbookDetailQuery / TextbookCreateMutation |
| 考勤/班级/请假/调课（P7-C） | 8 Query + 4 Mutation | AttendanceListQuery / AttendanceSheetQuery / SaveAttendanceSheetMutation / AttendanceStatsQuery / AttendanceReportQuery / ClassDetailQuery / ClassScheduleQuery / LeaveRequestsQuery / ApproveLeaveRequestMutation / SubmitLeaveRequestMutation / SubmitScheduleChangeMutation / ScheduleChangesQuery |
| 备课/诊断/错题/练习（P7-D） | 12 Query + 5 Mutation | LessonPlansQuery / LessonPlanDetailQuery / CreateLessonPlanMutation / UpdateLessonPlanMutation / AIGenerateLessonPlanMutation / LessonPlanLibraryQuery / ForkLessonPlanMutation / LessonPlanCalendarQuery / LessonPlanHeatmapQuery / CoursePlansQuery / CoursePlanDetailQuery / CreateCoursePlanMutation / UpdateCoursePlanMutation / DiagnosticReportsQuery / ClassDiagnosticQuery / StudentDiagnosticQuery / ErrorBookQuery / PracticeAnalyticsQuery |
| 选课/富文本/监考/扫描批改/热力图（P7-E） | 8 Query + 5 Mutation | ElectiveCoursesQuery / ElectiveCourseDetailQuery / CreateElectiveCourseMutation / UpdateElectiveCourseMutation / PublishElectiveCourseMutation / CancelElectiveCourseMutation / ExamRichEditorQuery / SaveExamRichContentMutation / ProctoringStatusQuery / ProctoringEventMutation / SubmissionScanGradingQuery / SaveScanGradingMutation / LessonPlanHeatmapQuery |
**切换步骤**：
@@ -167,15 +167,15 @@
### 4.2 必需环境变量
| 变量 | 用途 | 默认值 |
| ---- | ---- | ------ |
| `NEXT_PUBLIC_API_MOCKING` | 启用 MSW mock（true 时浏览器端拦截 GraphQL） | `true`（mock 阶段）/ `false`（接入上游后） |
| `NEXT_PUBLIC_MF_ENABLED` | 启用 Module Federation Remote 加载 | `false`（P2 阶段）/ `true`（P3+ Remote 上线后） |
| `API_GATEWAY_URL` | rewrites 代理目标 | `http://localhost:8080`（dev）/ `http://api-gateway:8080`（docker compose） |
| `NODE_ENV` | Node 环境 | `production` |
| `PORT` | 监听端口 | `4000` |
| `NEXT_PUBLIC_SENTRY_DSN` | Sentry DSN（可选） | — |
| `NEXT_PUBLIC_OTEL_ENDPOINT` | OpenTelemetry OTLP 端点（可选） | — |
| 变量 | 用途 | 默认值 |
| --------------------------- | -------------------------------------------- | --------------------------------------------------------------------------- |
| `NEXT_PUBLIC_API_MOCKING` | 启用 MSW mock（true 时浏览器端拦截 GraphQL） | `true`（mock 阶段）/ `false`（接入上游后） |
| `NEXT_PUBLIC_MF_ENABLED` | 启用 Module Federation Remote 加载 | `false`（P2 阶段）/ `true`（P3+ Remote 上线后） |
| `API_GATEWAY_URL` | rewrites 代理目标 | `http://localhost:8080`（dev）/ `http://api-gateway:8080`（docker compose） |
| `NODE_ENV` | Node 环境 | `production` |
| `PORT` | 监听端口 | `4000` |
| `NEXT_PUBLIC_SENTRY_DSN` | Sentry DSN（可选） | — |
| `NEXT_PUBLIC_OTEL_ENDPOINT` | OpenTelemetry OTLP 端点（可选） | — |
### 4.3 已知限制
@@ -189,91 +189,91 @@
### 5.1 静态路由（27 个，全部 HTTP 200 验证通过）
| 路径 | 模块 | 阶段 |
| ---- | ---- | ---- |
| `/` | 重定向 | P2 |
| `/login` | 登录 | P2 |
| `/dashboard` | 仪表盘 | P2 |
| `/classes` | 班级列表 | P2 |
| `/exams` | 考试列表 | P2 |
| `/exams/new` | 新建考试 | P3 |
| `/homework` | 作业列表 | P2 |
| `/homework/new` | 布置作业 | P3 |
| `/grades` | 成绩列表（含录入/统计/分析/报告卡入口） | P2+P7 |
| `/grades/entry` | 批量录入成绩 | P7 |
| `/grades/stats` | 班级成绩统计 | P7 |
| `/grades/analytics` | 成绩分析仪表盘 | P7 |
| `/grades/report-card` | 学生成绩报告卡 | P7 |
| `/analytics` | 学情分析 | P4 |
| `/knowledge-graph` | 知识图谱 | P4 |
| `/notifications` | 通知中心 | P5 |
| `/ai-assist` | AI 辅助出题 | P5 |
| `/ai-lesson-plan` | AI 教案 | P5 |
| `/ai-report` | AI 学情报告 | P5 |
| `/attendance` | 考勤记录 | P7 |
| `/attendance/sheet` | 批量录入考勤 | P7 |
| `/attendance/stats` | 考勤统计 | P7 |
| `/attendance/report` | 考勤报告 | P7 |
| `/questions` | 题库 | P7 |
| `/textbooks` | 教材列表 | P7 |
| `/lesson-plans` | 课案列表 | P7 |
| `/lesson-plans/new` | 新建课案 | P7 |
| `/lesson-plans/library` | 校内课案库 | P7 |
| `/lesson-plans/calendar` | 课案日历 | P7 |
| `/lesson-plans/heatmap` | 课标覆盖热力图 | P7 |
| `/course-plans` | 课程计划列表 | P7 |
| `/diagnostic` | 诊断报告列表 | P7 |
| `/error-book` | 错题本 | P7 |
| `/practice` | 练习分析 | P7 |
| `/elective` | 选修课列表 | P7 |
| `/elective/create` | 创建选修课 | P7 |
| `/leave` | 请假审批 | P7 |
| `/schedule-changes` | 调课申请 | P7 |
| `/settings` | 个人设置 | P2 |
| `/students` | 学生列表 | P2 |
| 路径 | 模块 | 阶段 |
| ------------------------ | --------------------------------------- | ----- |
| `/` | 重定向 | P2 |
| `/login` | 登录 | P2 |
| `/dashboard` | 仪表盘 | P2 |
| `/classes` | 班级列表 | P2 |
| `/exams` | 考试列表 | P2 |
| `/exams/new` | 新建考试 | P3 |
| `/homework` | 作业列表 | P2 |
| `/homework/new` | 布置作业 | P3 |
| `/grades` | 成绩列表（含录入/统计/分析/报告卡入口） | P2+P7 |
| `/grades/entry` | 批量录入成绩 | P7 |
| `/grades/stats` | 班级成绩统计 | P7 |
| `/grades/analytics` | 成绩分析仪表盘 | P7 |
| `/grades/report-card` | 学生成绩报告卡 | P7 |
| `/analytics` | 学情分析 | P4 |
| `/knowledge-graph` | 知识图谱 | P4 |
| `/notifications` | 通知中心 | P5 |
| `/ai-assist` | AI 辅助出题 | P5 |
| `/ai-lesson-plan` | AI 教案 | P5 |
| `/ai-report` | AI 学情报告 | P5 |
| `/attendance` | 考勤记录 | P7 |
| `/attendance/sheet` | 批量录入考勤 | P7 |
| `/attendance/stats` | 考勤统计 | P7 |
| `/attendance/report` | 考勤报告 | P7 |
| `/questions` | 题库 | P7 |
| `/textbooks` | 教材列表 | P7 |
| `/lesson-plans` | 课案列表 | P7 |
| `/lesson-plans/new` | 新建课案 | P7 |
| `/lesson-plans/library` | 校内课案库 | P7 |
| `/lesson-plans/calendar` | 课案日历 | P7 |
| `/lesson-plans/heatmap` | 课标覆盖热力图 | P7 |
| `/course-plans` | 课程计划列表 | P7 |
| `/diagnostic` | 诊断报告列表 | P7 |
| `/error-book` | 错题本 | P7 |
| `/practice` | 练习分析 | P7 |
| `/elective` | 选修课列表 | P7 |
| `/elective/create` | 创建选修课 | P7 |
| `/leave` | 请假审批 | P7 |
| `/schedule-changes` | 调课申请 | P7 |
| `/settings` | 个人设置 | P2 |
| `/students` | 学生列表 | P2 |
### 5.2 动态路由（11 个，全部 HTTP 200 验证通过）
| 路径 | 模块 | 阶段 |
| ---- | ---- | ---- |
| `/exams/[id]` | 考试详情 | P3 |
| `/exams/[id]/build` | 组卷 | P7 |
| `/exams/[id]/analytics` | 考后分析 | P7 |
| `/exams/[id]/edit-rich` | 富文本编辑 | P7 |
| `/exams/[id]/proctoring` | 监考 | P7 |
| `/homework/[id]` | 作业详情 + 批改 | P3 |
| `/homework/assignments/[id]/submissions` | 批量批改 | P7 |
| `/homework/submissions/[submissionId]` | 单份批改 | P7 |
| `/homework/submissions/[submissionId]/scan-grading` | 扫描批改 | P7 |
| `/classes/[id]` | 班级详情聚合页 | P7 |
| `/classes/schedule` | 班级课表 | P7 |
| `/analytics/[studentId]` | 单生学情 | P4 |
| `/diagnostic/class/[classId]` | 班级诊断 | P7 |
| `/textbooks/[id]` | 教材阅读器 | P7 |
| `/lesson-plans/[planId]/edit` | 课案编辑器 | P7 |
| `/course-plans/[id]` | 课程计划详情 | P7 |
| `/elective/[id]/edit` | 编辑选修课 | P7 |
| 路径 | 模块 | 阶段 |
| --------------------------------------------------- | --------------- | ---- |
| `/exams/[id]` | 考试详情 | P3 |
| `/exams/[id]/build` | 组卷 | P7 |
| `/exams/[id]/analytics` | 考后分析 | P7 |
| `/exams/[id]/edit-rich` | 富文本编辑 | P7 |
| `/exams/[id]/proctoring` | 监考 | P7 |
| `/homework/[id]` | 作业详情 + 批改 | P3 |
| `/homework/assignments/[id]/submissions` | 批量批改 | P7 |
| `/homework/submissions/[submissionId]` | 单份批改 | P7 |
| `/homework/submissions/[submissionId]/scan-grading` | 扫描批改 | P7 |
| `/classes/[id]` | 班级详情聚合页 | P7 |
| `/classes/schedule` | 班级课表 | P7 |
| `/analytics/[studentId]` | 单生学情 | P4 |
| `/diagnostic/class/[classId]` | 班级诊断 | P7 |
| `/textbooks/[id]` | 教材阅读器 | P7 |
| `/lesson-plans/[planId]/edit` | 课案编辑器 | P7 |
| `/course-plans/[id]` | 课程计划详情 | P7 |
| `/elective/[id]/edit` | 编辑选修课 | P7 |
### 5.3 API 路由
| 路径 | 用途 |
| ---- | ---- |
| `/api/health` | liveness 健康检查 |
| `/api/ready` | readiness 健康检查 |
| 路径 | 用途 |
| ------------------------- | --------------------------------------- |
| `/api/health` | liveness 健康检查 |
| `/api/ready` | readiness 健康检查 |
| `/api/v1/teacher/graphql` | GraphQL 端点（rewrites 到 api-gateway） |
| `/api/auth/*` | 登录端点（rewrites 到 iam） |
| `/api/auth/*` | 登录端点（rewrites 到 iam） |
---
## 6. 已知问题
| 问题 | 影响 | 临时方案 |
| ---- | ---- | -------- |
| GraphQL SSR 请求在 api-gateway 未启动时 500 | 首次加载 SSR 阶段会报错 | 部署时确保 api-gateway 先启动 |
| pnpm symlink 在 Docker runtime 下 react 解析失败 | 容器无法启动 | 已用 `output: "standalone"` 解决 |
| `tsconfig.base.json` 未在 Dockerfile 中 COPY | 构建阶段报 TS5083 | 已在 Dockerfile line 13 修复 |
| MSW mock 在 production 模式下仅浏览器端生效 | SSR 阶段无法 mock | 接入真实 API 后自动解决 |
| `node:20-alpine` 镜像在 Docker Hub 被墙 | 国内构建失败 | 配置 registry-mirror 或 retag 本地 node:22-alpine |
| 问题 | 影响 | 临时方案 |
| ------------------------------------------------ | ----------------------- | ------------------------------------------------- |
| GraphQL SSR 请求在 api-gateway 未启动时 500 | 首次加载 SSR 阶段会报错 | 部署时确保 api-gateway 先启动 |
| pnpm symlink 在 Docker runtime 下 react 解析失败 | 容器无法启动 | 已用 `output: "standalone"` 解决 |
| `tsconfig.base.json` 未在 Dockerfile 中 COPY | 构建阶段报 TS5083 | 已在 Dockerfile line 13 修复 |
| MSW mock 在 production 模式下仅浏览器端生效 | SSR 阶段无法 mock | 接入真实 API 后自动解决 |
| `node:20-alpine` 镜像在 Docker Hub 被墙 | 国内构建失败 | 配置 registry-mirror 或 retag 本地 node:22-alpine |
---