Edu/apps/teacher-portal/nextstep-v2.md

teacher-portal 模块 Next Steps v2

维护者：ai13（teacher-portal） 更新日期：2026-07-13 版本：v2（基于下游 nextstep 核查后更新） 关联：

• nextstep.md v1
• workline.md
• contract.md
• issue.md

v2 生成原因：用户通知"所有下游服务已经完成 nextstep.md 工作"，重新核查后发现的上下游差异和新增工作项。

---

1. v2 核查结论

1.1 核查范围

并行核查了 7 个下游服务的 nextstep.md：

服务	负责人	文档位置	核查结论
teacher-bff	ai03	services/teacher-bff/docs/nextstep.md	⚠️ 部分完成（详见 §2.1）
iam	ai06	services/iam/docs/nextstep.md	✅ 全部完成
push-gateway	ai09	services/push-gateway/docs/nextstep.md	✅ 全部完成
api-gateway	ai01	services/api-gateway/docs/nextstep.md	✅ 全部完成
core-edu	ai07	services/core-edu/docs/nextstep.md	⏳ 未对接（待 P3 联调）
content	ai08	services/content/docs/nextstep.md	⏳ 未对接
data-ana	ai11	services/data-ana/docs/nextstep.md	⏳ 未对接
msg	ai10	services/msg/docs/nextstep.md	⏳ 未对接
ai	ai12	services/ai/docs/nextstep.md	⏳ 未对接

1.2 关键发现

v1 期望：所有下游完成 nextstep → 切换真实 API。

v2 实际：

1. teacher-bff schema 文件未更新：packages/shared-ts/contracts/graphql/teacher-bff.schema.graphql 仍是 v1（admin 命名空间结构，仅 19 个顶层 Query + 5 个顶层 Mutation）。nextstep.md 声称的 v2 扁平命名（41 Query + 20 Mutation）未同步到 schema 文件。
2. teacher-bff teacher 域仍是 P2 占位：teacher.resolver.ts 第 60-95 行，exams / homework / grades 查询仍抛 BusinessError("not available in P2 (core-edu gRPC not ready, P3+)")。teacher-bff v2 主要完成 admin 域扁平命名重构 + iam 联调，teacher 域 P3+ 查询未实现。
3. teacher-portal 使用的 61 个 GraphQL operations 仅 5 个可用：dashboard / viewports / me / classes / class 这 5 个 P2 核心 Query 在 teacher-bff 真实可用；其他 56 个 operation（含 P3+ 扩展、P7 参考项目补全、admin 域）在 teacher-bff 中未实现或抛错。
4. 接入真实 API 不可行：若关闭 MSW（NEXT_PUBLIC_API_MOCKING=false），浏览器端 GraphQL 请求会到 teacher-bff，56 个查询会收到错误响应，30+ 页面会显示错误或空数据。

结论：v1 的"MSW mock → 真实 API 切换"工作无法在当前阶段完成，需等待 teacher-bff 完成 teacher 域 P3+ 全部查询和 mutation 实现后才能切换。

1.3 v2 决策

• 保留 MSW mock：teacher-portal 继续使用 MSW 在浏览器端拦截 GraphQL 请求，所有页面正常工作。
• SSR 阶段保留降级行为：next.config.js rewrites 仍将 SSR GraphQL 请求代理到 api-gateway，但 api-gateway 未启动时 SSR 会 500（仅开发模式）。Docker 部署时需先启动 api-gateway，或在生产环境关闭 SSR GraphQL 预取。
• 记录 v2 新工作项：本文档记录所有发现的上下游依赖和待完成工作。

---

2. 下游依赖工作（需协调 AI / 其他 AI 推进）

2.1 teacher-bff（ai03）— 最高优先级 ⚠️ 部分完成

v1 期望：v1 列出 11 类 GraphQL operations（详见 nextstep.md §2.1），期望 teacher-bff schema 上线后切换真实数据。

v2 核查结果：

teacher-bff 承诺（nextstep §3.2）	实际状态	影响
teacher 域 14 Query 全部实现	❌ 仅 5 个 P2 核心真实实现（dashboard/viewports/me/classes/class），其他 9 个抛 P2 占位错误	30+ 页面无法切换真实数据
teacher 域 5 Mutation 全部实现	❓ 需核查（createExam/assignHomework/recordGrade 抛 P2 占位错误）	4 个创建页面无法切换
admin 域 41 Query + 20 Mutation（扁平命名）	✅ v2 已实现（admin.resolver.ts 扁平命名，admin-portal 已联调）	但 teacher-portal 不使用 admin 域
GraphQL schema introspection 41 Query + 20 Mutation	⚠️ 实际可用仅 5 个 teacher 域 P2 + 26 admin 域扁平命名	introspection 通过但字段抛错
Docker 镜像 + iam 真实联调	✅ 通过（currentUser/me/adminRoles 等返回真实 iam 数据）	—
SSE /v1/teacher/ai/chat/stream	✅ 已实现	teacher-portal AI 助手页可联调

v2 新发现 - teacher-bff 待补工作：

#	工作项	当前状态	阻塞影响
1	实现 teacher 域 exams(classId) 真实查询（core-edu gRPC ListExamsByClass）	❌ 抛 "not available in P2"	/exams 列表页无法切换
2	实现 teacher 域 homework(classId) 真实查询（core-edu gRPC ListHomeworkByClass）	❌ 抛 "not available in P2"	/homework 列表页无法切换
3	实现 teacher 域 grades(examId) 真实查询（core-edu gRPC ListGradesByExam）	❌ 抛 "not available in P2"	/grades 列表页无法切换
4	实现 teacher 域 classStudents(classId) 查询（iam 或 core-edu）	❌ 不在 schema 中	/students 列表页无法切换
5	实现 teacher 域 examDetail(id) 查询	❌ 不在 schema 中	/exams/[id] 详情页无法切换
6	实现 teacher 域 homeworkDetail(id) 查询	❌ 不在 schema 中	/homework/[id] 详情页无法切换
7	实现 teacher 域 updateUser(input) mutation	❌ 不在 schema 中（只有 admin.updateUser）	/settings 编辑页无法切换
8	实现 P7 参考项目补全的 50+ 查询（成绩/作业批改/考试组卷/题库/教材/考勤/班级/请假/调课/备课/诊断/错题/练习/选修课/富文本/监考/扫描批改/热力图）	❌ 不在 schema 中	30+ P7 页面无法切换
9	实现 P4 knowledgeGraph / classAnalytics / studentAnalytics 查询	❌ 不在 schema 中（schema 中是 knowledgePath/classPerformance/studentWeakness/learningTrend，命名不一致）	P4 3 页面无法切换
10	实现 P5 myNotifications / generateLessonPlan / generateReport	❌ 不在 schema 中（schema 中是 notifications / 无 generateLessonPlan / 无 generateReport）	P5 5 页面无法切换
11	同步 schema 文件为 v2 扁平命名	❌ schema 文件仍是 v1（admin 命名空间）	契约不一致
12	实现 core-edu gRPC 联调（CORE_EDU_GRPC_TARGET 当前留空走降级模式 B）	⏳ 待 core-edu 服务就绪	teacher 域所有扩展查询无法实现

协调方式：

1. ai03 完成 teacher 域 P3+ 扩展 query/mutation 实现后，通知 ai13 在 teacher-portal 设置 NEXT_PUBLIC_API_MOCKING=false
2. ai03 同步更新 packages/shared-ts/contracts/graphql/teacher-bff.schema.graphql 为 v2 扁平命名
3. teacher-portal 端到端测试每个页面字段映射

预计切换步骤（待 teacher-bff teacher 域补全后执行）：

1. 设置 NEXT_PUBLIC_API_MOCKING=false
2. 启动 teacher-bff 容器（接入 iam + core-edu + content + data-ana + msg + ai 全部上游）
3. 逐页面测试 GraphQL 查询
4. 修复字段映射差异（teacher-portal MSW fixture 字段 vs teacher-bff 实际返回字段）
5. 删除或停用 src/mocks/handlers-p*.ts（仅在切换全部成功后）

2.2 iam（ai06）— 高优先级 ✅ 已完成

v2 核查结果：iam 已完成全部 nextstep.md 工作，包括：

• 15 个 gRPC RPC 全部实现
• REST CRUD 完整（角色/权限/视口/用户/TOTP）
• JWKS 端点（/.well-known/jwks.json）已就绪
• Redis 权限缓存（含指标）
• Outbox 事件发布
• Docker 镜像构建并验证通过

对 teacher-portal 的影响：

• ✅ JWT RS256 签发可用（teacher-portal 登录流程可走真实 iam）
• ✅ /api/auth/login 通过 api-gateway → iam REST /v1/iam/login 可用
• ✅ currentUser / me 查询通过 teacher-bff → iam gRPC 可用
• ⏳ F12 裁决的 refresh cookie 端点（POST /iam/auth/refresh 返回 httpOnly cookie）：iam nextstep §1.2 提到 RefreshToken gRPC 已实现，但 teacher-portal 的 useAuth hook 当前用 localStorage JWT 模式，迁移到 httpOnly cookie 模式仍需 ai13 修改 useAuth

v2 新发现 - iam 相关待补工作：

#	工作项	当前状态	阻塞影响
1	teacher-portal useAuth hook 迁移到 httpOnly cookie 模式（F12 裁决）	⏳ 待 ai13 实现	长会话保活不安全（localStorage XSS 风险）
2	teacher-portal 登录流程接入真实 iam /api/auth/login	⏳ 待 teacher-bff teacher 域补全后切换	当前用 MSW mock 登录响应

2.3 push-gateway（ai09）— 中优先级 ✅ 已完成

v2 核查结果：push-gateway 已完成全部 nextstep.md 工作：

• WebSocket /ws 端点（JWT RS256 + DevMode dev-token）
• /internal/push / /internal/broadcast / /internal/online/:userID HTTP API
• Kafka 消费 edu.notification.requested
• Redis Pub/Sub 跨实例消息扇出
• P6 Reconnect 协议（session_id + last_seq + ring buffer）
• 幂等性（event_id Redis SETNX 24h 去重）
• Docker 镜像构建并验证通过

对 teacher-portal 的影响：

• ✅ teacher-portal /notifications 页面的 WebSocket 通知通道可用
• ✅ teacher-portal useNotificationsWebSocket hook（P5 实现）可直接接入 push-gateway
• ⏳ teacher-portal 当前 MSW mock WebSocket，切换真实 push-gateway 需要配置 NEXT_PUBLIC_PUSH_GATEWAY_WS_URL

v2 新发现 - push-gateway 相关待补工作：

#	工作项	当前状态	阻塞影响
1	teacher-portal 配置 NEXT_PUBLIC_PUSH_GATEWAY_WS_URL=ws://push-gateway:8081/ws	⏳ 待添加环境变量	通知中心无法接收真实推送
2	teacher-portal useNotificationsWebSocket hook 接入真实 push-gateway	⏳ 待切换 mock → 真实	通知中心仍是 mock 数据
3	JWT token 传递给 WebSocket 连接（当前 dev-token 模式）	⏳ 待生产环境配置	生产环境需要真实 JWT

2.4 api-gateway（ai01）— ✅ 已完成

v2 核查结果：api-gateway 已完成全部 nextstep.md 工作：

• /api/v1/teacher/* 反向代理到 teacher-bff:3003/*（路径重写剥离 /api/v1/teacher）
• /api/admin/graphql 反向代理到 teacher-bff:3003/graphql
• /api/v1/student/* / /api/v1/parent/* 反向代理
• JWT RS256 验签中间件
• 限流 / 熔断 / CORS / X-Request-Id 注入
• Docker 镜像构建并验证通过

对 teacher-portal 的影响：

• ✅ teacher-portal SSR 阶段 GraphQL 请求通过 next.config.js rewrites 到 api-gateway
• ✅ teacher-portal 登录流程 POST /api/auth/login → api-gateway → iam

v2 新发现 - api-gateway 相关待补工作：无（api-gateway 已全部完成）。

2.5 core-edu / content / data-ana / msg / ai 服务 — ⏳ 未对接

v2 核查结果：这 5 个服务各自完成了 nextstep.md 列出的 P2-P6 工作，但 teacher-bff 中 CORE_EDU_GRPC_TARGET / CONTENT_GRPC_TARGET / DATA_ANA_GRPC_TARGET / MSG_GRPC_TARGET / AI_GRPC_TARGET 全部留空，走降级模式 B（返回空结果 + warning）。

对 teacher-portal 的影响：

• teacher-bff teacher 域扩展查询（exams/homework/grades/knowledgePath/classPerformance 等）依赖这些下游服务
• 这些服务就绪后，ai03 需要在 teacher-bff 配置 gRPC target 并实现真实查询
• 然后 ai13 才能切换 teacher-portal MSW mock → 真实 API

v2 新发现 - 下游服务联调待补工作：

#	工作项	当前状态	阻塞影响
1	core-edu 服务暴露 gRPC :50053 并实现 ListExamsByClass/ListHomeworkByClass/ListGradesByExam/CreateExam/AssignHomework/RecordGrade	⏳ 待 ai07	teacher 域 P3 查询无法实现
2	content 服务暴露 gRPC :50054 并实现 GetKnowledgePath/ListTextbooks/ListChapters	⏳ 待 ai08	teacher 域 P4 查询无法实现
3	data-ana 服务暴露 gRPC :50055 并实现 GetClassPerformance/GetStudentWeakness/GetLearningTrend	⏳ 待 ai11	teacher 域 P4 查询无法实现
4	msg 服务暴露 gRPC :50056 并实现 ListNotifications/MarkNotificationRead	⏳ 待 ai10	teacher 域 P5 查询无法实现
5	ai 服务暴露 gRPC :50058 并实现 GenerateQuestion + SSE /v1/ai/chat/stream	⏳ 待 ai12	teacher 域 P5 AI 助手无法实现
6	teacher-bff 配置 5 个 gRPC target（从留空改为实际地址）	⏳ 待 ai03	降级模式 B 持续生效

---

3. 本模块待补工作（v2 更新）

3.1 v1 已完成项（详见 nextstep.md §3）

• ✅ P1-A 单元测试（63 tests passed）
• ✅ P1-B 设计令牌硬化（ESLint tokens 零违规）
• ✅ P2-C i18n 集成（5 示范页面 + LocaleSwitcher）
• ✅ P2-D ui-components 扩展（5/8 组件）
• ✅ P2-E 性能 + A11y（PerformanceDashboard + 5 核心页面 A11y 修复）

3.2 v2 新增待补工作

3.2.1 MSW mock → 真实 API 切换（依赖 teacher-bff teacher 域补全）

阻塞条件：teacher-bff 实现 teacher 域 P3+ 全部扩展 query/mutation（详见 §2.1 表格 12 项）

清单：

• 等待 teacher-bff teacher 域补全后设置 NEXT_PUBLIC_API_MOCKING=false
• 端到端测试 27 静态路由 + 11 动态路由
• 修复字段映射差异（MSW fixture 字段 vs 实际返回字段）
• 删除或停用 src/mocks/handlers-p*.ts（5 个 handlers 文件）
• 删除或停用 src/mocks/fixtures/*.ts（13 个 fixtures 文件）
• 删除 src/mocks/browser.ts / src/mocks/server.ts / src/mocks/init-mocks.ts
• 从 package.json 移除 msw devDependency
• 从 package.json 移除 "msw": { "workerDirectory": ["public"] } 配置
• 从 src/app/providers.tsx 移除 MSW 初始化逻辑

3.2.2 useAuth hook 迁移到 httpOnly cookie（F12 裁决）

阻塞条件：无（iam 已就绪）

清单：

• 修改 packages/hooks/src/use-auth.ts：从 localStorage JWT 改为 httpOnly cookie
• 修改 src/app/(auth)/login/page.tsx：登录成功后不再手动存 JWT 到 localStorage
• 修改 src/lib/graphql-client.ts：urql fetcher 不再手动添加 Authorization header（浏览器自动带 cookie）
• 修改 next.config.js rewrites：添加 credentials: 'include' 到 SSR fetcher
• 添加 CSRF 防护（double-submit cookie 模式）
• 测试：登录 → Dashboard → 刷新页面 → 保持登录态

3.2.3 push-gateway WebSocket 接入

阻塞条件：无（push-gateway 已就绪）

清单：

• 添加环境变量 NEXT_PUBLIC_PUSH_GATEWAY_WS_URL=ws://localhost:8081/ws（开发） / ws://push-gateway:8081/ws（Docker）
• 修改 src/hooks/use-notifications-websocket.ts：从 mock WebSocket 改为真实 push-gateway 连接
• 修改 JWT token 传递方式：URL query param ?token=<jwt> 或 Sec-WebSocket-Protocol header
• 测试：通知中心实时接收推送

3.2.4 i18n 扩展（剩余 30+ 页面）

阻塞条件：无

清单：

• 其余 30+ 页面中文硬编码替换为 t("...") 调用
• 补充 src/messages/zh-CN.json 和 src/messages/en.json 缺失的 key
• 测试：切换 locale 后所有页面文本正确显示

3.2.5 性能优化扩展

阻塞条件：无（非紧急）

清单：

• 接入 CI 阻断（size-limit + bundle analyzer）
• 路由懒加载：剩余重型页面（exams/[id]/build、knowledge-graph 等）使用 next/dynamic
• 图片优化：next/image 替换 <img>（需配置 remotePatterns）
• 字体优化：next/font 替换 CSS @font-face

3.2.6 单元测试扩展

阻塞条件：无（非紧急）

清单：

• 测试 usePermission hook（权限矩阵）
• 测试 useAuth hook（登录/登出/会话保活）— 注意：迁移到 httpOnly cookie 后需更新测试
• 测试关键页面组件：AppShell / grades/entry / homework/submissions/[submissionId]
• 配置 CI 运行 pnpm --filter @edu/teacher-portal test

3.2.7 设计令牌完整迁移

阻塞条件：无（非紧急）

清单：

• src/app/styles/globals.css：将 hsl(0 0% 100%) 等字面量迁移到 primitive.css
• tailwind.config.js：将 hsl(...) 字面量迁移到 @theme inline 块

3.2.8 ui-components 剩余组件

阻塞条件：无（非紧急，待业务真实需求时抽取）

清单：

• RichTextEditor 组件（Tiptap 封装，lesson-plans/edit + exams/edit-rich 复用）
• Chart 组件（SVG 图表统一封装）
• Calendar 组件（lesson-plans/calendar 复用）

---

4. v2 集成测试方案（待 teacher-bff 补全后执行）

4.1 前置条件

• teacher-bff teacher 域全部 query/mutation 实现（§2.1 表格 12 项全部 ✅）
• teacher-bff schema 文件同步为 v2 扁平命名
• teacher-bff 配置 5 个 gRPC target（core-edu / content / data-ana / msg / ai）
• core-edu / content / data-ana / msg / ai 服务全部启动并健康

4.2 集成测试步骤

1. 启动顺序（docker compose up）：

   • edu-mysql / edu-redis / edu-kafka
   • iam :3002 :50052
   • core-edu :50053 / content :50054 / data-ana :50055 / msg :50056 / ai :50058 :3008
   • teacher-bff :3003
   • push-gateway :8081
   • api-gateway :8080
   • teacher-portal :4000（NEXT_PUBLIC_API_MOCKING=false）

2. 验证项：

   #	验证项	预期结果
   1	登录流程	POST /api/auth/login → JWT → Dashboard 渲染
   2	Dashboard 查询	query Dashboard 返回真实 iam + core-edu 数据
   3	班级列表	query Classes 返回真实 iam 数据
   4	考试列表	query ClassExams 返回真实 core-edu 数据
   5	作业列表	query ClassHomework 返回真实 core-edu 数据
   6	成绩列表	query ExamGrades 返回真实 core-edu 数据
   7	创建考试	mutation CreateExam 写入 core-edu DB
   8	通知中心	WebSocket 连接 push-gateway，实时接收推送
   9	AI 助手	SSE /v1/teacher/ai/chat/stream 流式响应
   10	知识图谱	query KnowledgeGraph 返回真实 content 数据
   11	学情分析	query ClassAnalytics 返回真实 data-ana 数据
   12	所有 27 静态路由	HTTP 200，无 SSR 500 错误
   13	所有 11 动态路由	HTTP 200，无 SSR 500 错误

3. 回滚策略：

   • 若集成测试失败，设置 NEXT_PUBLIC_API_MOCKING=true 回退到 MSW mock
   • 修复问题后重新测试

---

5. v2 已知问题（新增）

问题	影响	临时方案
teacher-bff schema 文件未同步为 v2 扁平命名	契约不一致，teacher-portal 端无法基于 schema 生成类型	等待 ai03 同步 schema 文件
teacher-bff teacher 域 P3+ 查询仍抛 "not available in P2"	56 个 GraphQL operations 无法切换真实数据	继续使用 MSW mock
teacher-bff 5 个 gRPC target 留空走降级模式 B	teacher 域扩展查询返回空	等待 ai03 配置实际 gRPC 地址
teacher-portal useAuth 使用 localStorage JWT	XSS 风险（F12 裁决要求 httpOnly cookie）	待 ai13 迁移（§3.2.2）
teacher-portal WebSocket 使用 mock	通知中心无法接收真实推送	待 ai13 接入 push-gateway（§3.2.3）

---

6. v2 总结

6.1 已完成（v1 + v2）

工作项	完成度
P2 MF Shell + 基础页面	✅ 100%
P3 考试/作业/成绩	✅ 100%（MSW mock）
P4 知识图谱 + 学情分析	✅ 100%（MSW mock）
P5 通知 + AI 助手	✅ 100%（MSW mock）
P6 可观测性硬化	✅ 100%
P7 参考项目差距闭环	✅ 100%（35 页面，MSW mock）
Docker Desktop 验证	✅ 通过（standalone 模式）
P1-A 单元测试	✅ 63/63 tests passed
P1-B 设计令牌硬化	✅ ESLint tokens 零违规
P2-C i18n 集成	✅ 5 示范页面 + LocaleSwitcher
P2-D ui-components 扩展	✅ 5/8 组件
P2-E 性能 + A11y	✅ PerformanceDashboard + 5 核心页面修复

6.2 待完成（v2 新增）

工作项	优先级	阻塞条件
MSW mock → 真实 API 切换	P0	teacher-bff teacher 域补全（12 项）
useAuth 迁移到 httpOnly cookie	P1	无（iam 已就绪）
push-gateway WebSocket 接入	P1	无（push-gateway 已就绪）
i18n 扩展（30+ 页面）	P2	无
性能优化扩展	P2	无
单元测试扩展	P2	无
设计令牌完整迁移	P2	无
ui-components 剩余组件	P3	无

6.3 阻塞分析

teacher-portal 当前唯一阻塞项：teacher-bff teacher 域 P3+ 扩展查询/mutation 未实现（依赖 ai03 + ai07/08/11/10/12 联调）。

解除阻塞后：可一次性完成 MSW mock → 真实 API 切换（§3.2.1），其余工作（§3.2.2-3.2.8）均不阻塞。

---

本文件维护规则：v2 基于 2026-07-13 下游 nextstep 核查生成。当下游状态变化时（特别是 teacher-bff teacher 域补全），更新本文档对应条目。