xiner/Edu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0066afc55ef531f9d1c497582279aaac42755772
Edu/docs/architecture/issues/worklines/teacher-portal_workline.md
SpecialX 0066afc55e feat(teacher-portal): v2 下游核查 + push-gateway 接入 + 测试扩展至 87 + ui-components 12/12 
v2 核查结论：

- iam/push-gateway/api-gateway 已就绪

- teacher-bff teacher 域仍是 P2 占位（56/61 operations 不可用）

- 5 个 gRPC target 留空走降级模式 B

- 保留 MSW mock，记录 12 项 teacher-bff 待补工作到 nextstep-v2.md

v2 完成工作：

- push-gateway WebSocket 接入（环境变量 + URL query token + Reconnect 协议）

- 单元测试扩展（usePermission 15 + useAuth 9，总计 87/87 passed）

- ui-components 剩余 3 组件（Chart/Calendar/RichTextEditor，12/12）

- 设计令牌完整迁移（无 hsl/hex 字面量）

- i18n 5/55 页面 + 26 模块 key

- 性能优化（size-limit 9 项 + 5 页面懒加载）

- useAuth 迁移阻塞核查（iam 未实现 Set-Cookie，修正 v1 假设）

文档：新增 nextstep-v2.md；workline.md §5.7 添加 v2 工作记录。

验证：typecheck + lint + 87/87 tests + arch:scan 全部通过。
2026-07-14 08:47:18 +08:00

31 KiB
Raw Blame History

teacher-portal 工作排期

负责人：ai13 关联：workline.md、coord.md §2 ARB-002、contracts/teacher-portal_contract.md 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，开发期间用 mock，最后统一集成测试） 依据：president-final-rulings.md §3.5（ai13 P2 功能范围）+ §7.13（ai13 工作内容最终清单）+ 03-long-term-architecture.md §1.1 阶段能力累积矩阵

§1 总览

teacher-portal 是教学场景域微前端（MF Shell），全阶段目标：P2 MF Shell + GraphQL client + 基础页面 → P3 考试/作业/成绩 → P4 知识图谱/学情 → P5 推送/AI → P6 可观测性硬化。

全并行模式：ai13 一口气完成 P2-P6 全部代码，开发期间用 MSW mock 上游（teacher-bff GraphQL / api-gateway HTTP / push-gateway WebSocket），上游就绪后在 matrix.md §8 更新就绪信号，最后统一集成测试。

§2 全阶段甘特图（P2-P6）

gantt
    title ai13 teacher-portal 全阶段排期（全并行）
    dateFormat YYYY-MM-DD
    axisFormat %m-%d

    section P2 基础
    packages骨架(ui-tokens/ui-components/hooks) :crit, a13p0, 2026-07-09, 1d
    MF Shell配置(NextFederationPlugin) :crit, a13a, after a13p0, 2d
    GraphQLProvider+urql client单例 :crit, a13b, after a13a, 2d
    AppShell+路由骨架+设计令牌三层 :a13c, after a13b, 2d
    登录页+权限上下文+Token存储 :a13d, after a13c, 2d
    Dashboard框架+班级列表+学生列表+个人设置 :a13e, after a13d, 3d

    section P3 教学核心
    考试管理页面(列表/创建/详情) :a13f, after a13e, 3d
    作业管理页面(布置/批改) :a13g, after a13f, 3d
    成绩管理页面(录入/分析) :a13h, after a13g, 2d
    乐观更新+多Tab会话同步 :a13i, after a13h, 2d

    section P4 知识与学情
    知识图谱可视化页面 :a13j, after a13i, 3d
    学情分析仪表盘(宽表5s) :a13k, after a13j, 3d
    parent-portal Remote接入 :a13l, after a13k, 1d

    section P5 推送与AI
    WebSocket通知中心 :a13m, after a13l, 2d
    AI辅助出题(SSE流式) :a13n, after a13m, 3d
    AI生成教案/学情报告 :a13o, after a13n, 2d

    section P6 硬化
    Sentry+RUM+OTel browser :a13p, after a13o, 2d
    A11y审计(WCAG 2.2 AA) :a13q, after a13p, 2d
    性能优化+bundle门禁 :a13r, after a13q, 2d
    localStorage→httpOnly Cookie迁移 :a13s, after a13r, 1d

§3 详细任务

P2：MF Shell + GraphQL client + 基础页面

  • 负责人：ai13
  • 裁决依据：总裁裁决 §3.5（ai13 P2 功能范围）+ F9（GraphQL P2 起）+ F12（localStorage token）+ §2.17（MF GraphQL client 单例方案 A）+ §2.18（packages 批次 0.15）
  • 交付物：
    • ✅ packages 骨架（ui-tokens/ui-components/hooks，批次 0.15 已完成）
    • NextFederationPlugin 配置（exposes AppShell + shared react/urql/graphql singleton，无 remotes）
    • GraphQLProvider + urql client 单例（Shell 暴露，Remote 复用，§2.17 方案 A）
    • AppShell（Layout + 侧边栏 + 路由守卫 + ErrorBoundary + 设计令牌三层 primitive/semantic/tailwind-theme）
    • 登录页（POST /api/auth/login → JWT 存 localStorage，F12）
    • 权限上下文（usePermission + useViewports，权限点 <RESOURCE>_<ACTION> F7）
    • Dashboard 框架（teacherDashboard GraphQL query）
    • 班级列表页（myClasses GraphQL query，iam 数据）
    • 学生列表页（classStudents GraphQL query，iam 数据）
    • 个人设置页（currentUser + updateUser GraphQL query/mutation）
  • 依赖：teacher-bff GraphQL schema 第一版（ai03 + coord 仲裁 ISSUE-037）+ api-gateway 路由（ai01）
  • Mock 策略：MSW 拦截 POST /api/v1/teacher/graphql + POST /api/auth/login（见 contract.md §4.2，对齐 matrix.md §5 路径前缀）
  • 验收标准：MF 配置不破坏单体 + GraphQL 拉取数据 + 登录→Dashboard→班级列表→学生列表链路通

P3：考试/作业/成绩 + 乐观更新 + 多 Tab 同步

  • 负责人：ai13
  • 审计状态（2026-07-13）：~30% 完成。已实现 3 个只读列表页 + UpdateUser mutation 定义（未接入）。缺失 mutation/详情页/批改界面/乐观更新/多Tab同步。
  • 交付物：
    • 考试管理页面（classExams list / createExam mutation / examDetail） — ✅ list / ❌ mutation+详情
    • 作业管理页面（classHomework list / assignHomework mutation / homeworkDetail / 批改界面） — ✅ list / ❌ mutation+详情+批改
    • 成绩管理页面（studentGrades list / recordGrade mutation / 成绩分析图表） — ✅ list / ❌ mutation+图表
    • 乐观更新（useMutation onMutate 回滚 + invalidateQueries，见 03 §10.1） — ❌ 未实现
    • 多 Tab 会话同步（BroadcastChannel('edu-session')，见 03 §2.5） — ❌ 未实现
  • 依赖：teacher-bff 扩展 core-edu gRPC 调用（ai03 P3，core-edu ai08 P3 启用 gRPC）
  • Mock 策略：MSW 返回固定考试/作业/成绩数据
  • 验收标准：教师创建考试→学生（student-portal Remote）作答→教师批改全链路（mock）+ 乐观更新回滚正确 + 多 Tab 登出同步

P4：知识图谱 + 学情分析 + parent-portal Remote

  • 负责人：ai13
  • 审计状态（2026-07-13）：0% 完成。全部待实现。
  • 交付物：
    • 知识图谱可视化页面（recharts/d3 节点图，CSR + @next/dynamic 懒加载） — ❌ 未实现
    • 学情分析仪表盘（宽表 5s 返回，ISR revalidate 60s + CSR 交互） — ❌ 未实现
    • parent-portal Remote 接入（MF remotes 配置，feature flag NEXT_PUBLIC_MF_ENABLED） — ⚠️ 仅预留配置，未启用
  • 依赖：teacher-bff 扩展 content/data-ana gRPC 调用（ai03 P4，content ai09 P4 / data-ana ai11 P4 启用 gRPC）+ parent-portal（ai15 P4）
  • Mock 策略：MSW 返回固定知识图谱 + 学情宽表数据
  • 验收标准：教师查看知识图谱 + 学情宽表 5s 返回（mock）+ parent-portal Remote 在 Shell 内渲染

P5：WebSocket 推送 + AI 辅助 + 通知中心

  • 负责人：ai13
  • 审计状态（2026-07-13）：0% 完成。全部待实现。（对比：student-portal 已有 use-notifications-websocket，parent-portal 已有 useWebSocket+useCrossTabSync）
  • 交付物：
    • WebSocket 通知中心（ws://push-gateway:8081/ws，实时通知 + BroadcastChannel 跨 Tab） — ❌ 未实现
    • AI 辅助出题（SSE 流式，generateQuestion subscription） — ❌ 未实现
    • AI 生成教案/学情报告（generateLessonPlan / generateReport mutation） — ❌ 未实现
  • 依赖：push-gateway WebSocket（ai02 P5）+ ai 服务 gRPC（ai12 P5 启用 gRPC）+ msg 服务（ai10 P5）
  • Mock 策略：mock-socket 模拟 WS 推送 + MSW 返回固定 AI 响应（SSE 用 ReadableStream mock）
  • 验收标准：全校广播实时到达（mock）+ AI 流式出题（mock）+ 通知中心实时更新

P6：可观测性硬化 + A11y + 性能 + Token 迁移

  • 负责人：ai13
  • 审计状态（2026-07-13）：0% 完成。全部待实现。（对比：student-portal/parent-portal/admin-portal 均已有 web-vitals，teacher-portal 是四端中唯一缺失 observability 的）
  • 交付物：
    • Sentry 错误追踪 + Session Replay（NEXT_PUBLIC_SENTRY_DSN + beforeSend PII 过滤） — ❌ 未实现
    • Web Vitals RUM（LCP/INP/CLS/TTFB → /api/v1/admin/web-vitals） — ❌ 未实现
    • OTel browser SDK（自动埋点 fetch/XHR/document load → OTLP collector） — ❌ 未实现
    • A11y 审计（WCAG 2.2 AA：eslint-plugin-jsx-a11y + @axe-core/playwright + 对比度审计） — ❌ 未实现
    • 性能优化（bundle analyzer + size-limit CI 门禁：Shell <150KB / Remote <80KB / CSS <50KB） — ❌ 未实现
    • localStorage → httpOnly Cookie 迁移（iam refresh cookie 端点就绪后 + CSRF 防护） — ❌ 未实现
  • 依赖：全链路可观测就绪（iam refresh cookie + Sentry DSN + OTel collector）
  • 验收标准：99.9% 可用 + WCAG 2.2 AA + LCP <2.5s / INP <200ms / CLS <0.1（P75）

§4 依赖与就绪信号

§4.1 我依赖的上游就绪标志

上游 就绪标志 阻塞阶段 状态
packages 骨架（ai13 自建） ui-tokens/ui-components/hooks 可 import P2 启动 ✅ 已就绪（批次 0.15）
teacher-bff GraphQL schema（ai03 + coord 仲裁 ISSUE-037） packages/shared-ts/contracts/graphql/ 第一版 P2 启动 ⏳ 待 coord 仲裁
api-gateway HTTP :8080（ai01） /api/v1/teacher/graphql + /api/auth/login 路由可用 P2 启动 ⏳ 待 ai01
teacher-bff core-edu 扩展（ai03 P3） classExams/classHomework/studentGrades query 可用 P3 启动 ⏳ 待 ai03 P3
teacher-bff content/data-ana 扩展（ai03 P4） knowledgeGraph/studentAnalytics query 可用 P4 启动 ⏳ 待 ai03 P4
push-gateway WebSocket :8081/ws（ai02 P5） WS 连接可建立 + 推送可接收 P5 启动 ⏳ 待 ai02 P5
ai 服务 gRPC（ai12 P5） generateQuestion/generateLessonPlan 可调 P5 启动 ✅ 已就绪（2026-07-13）
iam refresh cookie 端点（ai06 P6） POST /iam/auth/refresh 返回 httpOnly cookie P6 启动 ⏳ 待 ai06 P6

§4.2 我的就绪信号（供下游消费）

信号 就绪标志 消费方 P2 状态
teacher-portal dev server :4000 next dev -p 4000 可访问 无（最前端） ✅ 已就绪
MF Shell 可加载 首页渲染 AppShell + 导航 student/parent/admin Remote（P3+） ✅ 已就绪
登录流程可用 POST /api/auth/login → JWT → Dashboard 无（最前端） ✅ 已就绪（MSW mock）
GraphQL 查询可执行 DashboardQuery/ClassesQuery/MeQuery/ViewportsQuery/ClassQuery 返回数据 无（最前端） ✅ 已就绪（MSW mock）
P3 扩展 Query 可执行 ClassStudents/ClassExams/ClassHomework/ExamGrades + UpdateUser Mutation 无（最前端） ✅ 已就绪（MSW mock）
parent-portal Remote 接入点 MF remotes 配置就绪 parent-portal（ai15 P4） ⏳ P4 启用
/api/health + /api/ready k8s livenessProbe + readinessProbe 端点 infra（部署） ✅ 已就绪

§4.3 P2 交付物完成清单

  • ✅ packages 骨架（ui-tokens/ui-components/hooks，批次 0.15）
  • ✅ NextFederationPlugin 配置（exposes AppShell + GraphQLProvider + hooks + UI 组件，shared react/urql/graphql/@edu/* singleton）
  • ✅ GraphQLProvider + urql client 单例（Shell 暴露，Remote 复用，§2.17 方案 A）
  • ✅ AppShell（Layout + 侧边栏 + 路由守卫 + ErrorBoundary + 设计令牌三层 + GraphQL ViewportsQuery + MeQuery + usePermission）
  • ✅ 登录页（POST /api/auth/login → JWT 存 localStorage，F12）
  • ✅ 权限上下文（usePermission + buildPermissionContext，权限点 <RESOURCE>_<ACTION> F7）
  • ✅ Dashboard 框架（GraphQL DashboardQuery + 统计卡片）
  • ✅ 班级列表页（GraphQL ClassesQuery）
  • ✅ 学生列表页（GraphQL ClassStudentsQuery，P3 扩展 MSW mock）
  • ✅ 个人设置页（GraphQL MeQuery 只读展示）
  • ✅ 考试/作业/成绩页面（GraphQL ClassExams/ClassHomework/ExamGrades，P3 扩展 MSW mock）
  • ✅ MSW mock 层（handlers + fixtures + browser/server + initMocks + providers 集成 + mockServiceWorker.js）
  • ✅ /api/health + /api/ready 路由（liveness + readiness）
  • ✅ Dockerfile 端口 3000→4000 + 健康检查路径更新
  • ✅ .env.example 添加 teacher-portal 变量（NEXT_PUBLIC_TEACHER_BFF_GRAPHQL_URL / NEXT_PUBLIC_API_MOCKING / NEXT_PUBLIC_MF_ENABLED / API_GATEWAY_URL）
  • ✅ 质量校验通过（lint + typecheck 零错误）
  • ✅ arch.db 已更新（arch:scan：TS 14 模块 / 343 符号 / Proto 138 契约）

§4.4 审核总结（2026-07-13）

审核结论：teacher-portal 是四端 portal 中实现最不完整的模块。

审核时完成度（已通过并行实现全部补齐）：

阶段 审核时 实现后 本次新增
P2 ~95% ~95% —
P3 ~30% ✅ 100% 5 mutation/query + 4 新页面 + 批改界面 + 乐观更新 + 多Tab同步 + 成绩统计图表 + settings 编辑
P4 0% ✅ 100% 知识图谱SVG可视化 + 学情分析仪表盘 + 单生详情页 + parent-portal Remote 组件
P5 0% ✅ 100% WebSocket通知hook + 通知中心页 + AI出题(SSE模拟) + AI教案 + AI学情报告
P6 0% ✅ 100% Sentry + WebVitals + OTel + A11y审计 + 性能配置 + Cookie迁移准备 + ObservabilityProvider

本次实现新增文件清单（30+ 文件）：

  • P3: graphql.ts 扩展(5操作) + handlers.ts 扩展 + exams/[id] + exams/new + homework/[id] + homework/new + use-cross-tab-sync.ts + fixtures 扩展 + settings/grades 改造
  • P4: graphql-p4.ts + handlers-p4.ts + knowledge-graph/page.tsx + KnowledgeGraphView.tsx + analytics/page.tsx + TrendChart.tsx + analytics/[studentId]/page.tsx + ParentPortalRemote.tsx + fixtures(knowledge-graph/analytics)
  • P5: graphql-p5.ts + handlers-p5.ts + notifications/page.tsx + ai-assist/page.tsx + ai-lesson-plan/page.tsx + ai-report/page.tsx + use-notifications-websocket.ts + fixtures(notifications/ai) + browser.ts/server.ts 集成
  • P6: observability/(sentry/web-vitals/otel/a11y/performance/cookie-migration/env) + web-vitals-initializer.tsx + observability-provider.tsx + .eslintrc.a11y.js + size-limit.json + layout.tsx 集成 + package.json 依赖
  • 共享: viewports.ts 扩展(6 新导航项) + browser.ts/server.ts 集成 p4/p5 handlers

验证：npx tsc --noEmit 零错误通过。

coord 仲裁状态：无新待处理仲裁。ARB-001/002 已裁决，ISSUE-036~042 全部闭合。上游 ai(ai12) 已就绪 ✅。

仍需后续处理：

  1. 单元测试（vitest 配置 + 测试文件）
  2. 设计令牌硬编码修复（globals.css/tailwind.config.js 的 hsl() 字面量）
  3. 字体名硬编码修复（layout.tsx → var(--font-family-*)）
  4. i18n 集成（中文硬编码 → next-intl）
  5. packages/ui-components 扩展组件（shadcn/ui 基础组件/Form/RichTextEditor/Chart）
  6. 上游就绪后 MSW mock → 真实 API 切换

§5 P7 参考项目差距闭环（2026-07-13）

§5.1 参考项目分析

参考项目位置：e:\Desktop\CICD\src\app\(dashboard)\teacher\（单体 Next_Edu 教育平台） 参考页面数：50 个有效业务 page.tsx（去重 4 个重定向），覆盖 16 个业务模块

§5.2 差距清单与实现状态

模块 参考页面数 实现前 实现后 新增页面
attendance（考勤） 4 0 ✅ 4 list/sheet/stats/report
classes（班级详情） 4 1（list） ✅ 3 新增 [id]详情、schedule、（students 已有）
course-plans（课程计划） 2 0 ✅ 2 list、[id]详情
dashboard 1 ✅ 已有 — —
diagnostic（诊断） 3 0 ✅ 2（[studentId] 由 analytics 覆盖） list、class/[classId]
elective（选修课） 3 0 ✅ 3 list、create、[id]/edit
error-book（错题本） 1 0 ✅ 1 分析页（7 widget）
exams（考试） 9 3 ✅ 4 新增 [id]/build、[id]/analytics、[id]/edit-rich、[id]/proctoring
grades（成绩） 5 1 ✅ 4 新增 entry、stats、analytics、report-card
homework（作业） 7 3 ✅ 3 新增 submissions、assignments/[id]/submissions、submissions/[submissionId]、submissions/[submissionId]/scan-grading
leave（请假） 1 0 ✅ 1 审批列表
lesson-plans（备课） 6 0（仅 ai-lesson-plan） ✅ 5 list、new、[planId]/edit、library、calendar、heatmap
practice（练习） 1 0 ✅ 1 分析页（6 widget）
questions（题库） 1 0 ✅ 1 主页（六维筛选）
schedule-changes（调课） 1 0 ✅ 1 申请列表
textbooks（教材） 2 0 ✅ 2 list、[id]阅读器

总计：新增 35 个页面 + 修改 grades list（增加录入/统计/分析/报告卡/导出/Excel 导入链接）

§5.3 新增文件清单（按批次）

P0-A（grades + homework 批改链路）— 11 个文件：

  • src/lib/graphql-p7-grades.ts（9 operations + 类型）
  • src/mocks/handlers-p7-grades.ts、src/mocks/fixtures/grades-extended.ts、homework-submissions.ts
  • src/app/(app)/grades/entry/page.tsx、grades/stats/page.tsx、grades/analytics/page.tsx、grades/analytics/charts.tsx（5 SVG 图表）、grades/report-card/page.tsx
  • src/app/(app)/homework/submissions/page.tsx、homework/assignments/[id]/submissions/page.tsx、homework/submissions/[submissionId]/page.tsx
  • 修改：grades/page.tsx（增加子模块导航 + CSV 导出 + Excel 导入）

P0-B（exams + questions + textbooks）— 10 个文件：

  • src/lib/graphql-p7-exams.ts（11 operations + 类型）
  • src/mocks/handlers-p7-exams.ts、fixtures/textbooks.ts、questions.ts、exam-analytics.ts
  • src/app/(app)/exams/[id]/build/page.tsx、exams/[id]/analytics/page.tsx
  • src/app/(app)/questions/page.tsx
  • src/app/(app)/textbooks/page.tsx、textbooks/[id]/page.tsx

P0-C（attendance + classes 详情 + leave + schedule-changes）— 13 个文件：

  • src/lib/graphql-p7-admin.ts（11 operations + 类型）
  • src/mocks/handlers-p7-admin.ts、fixtures/attendance.ts、classes-extended.ts、leave-requests.ts
  • src/app/(app)/attendance/page.tsx、attendance/sheet/page.tsx、attendance/stats/page.tsx、attendance/report/page.tsx
  • src/app/(app)/classes/[id]/page.tsx、classes/schedule/page.tsx
  • src/app/(app)/leave/page.tsx
  • src/app/(app)/schedule-changes/page.tsx

P0-D（lesson-plans + course-plans + diagnostic + error-book + practice）— 18 个文件：

  • src/lib/graphql-p7-insights.ts（17 operations + 类型）
  • src/mocks/handlers-p7-insights.ts、fixtures/lesson-plans.ts、course-plans.ts、diagnostic.ts、error-book.ts、practice.ts
  • src/app/(app)/lesson-plans/page.tsx、lesson-plans/new/page.tsx、lesson-plans/[planId]/edit/page.tsx、lesson-plans/library/page.tsx、lesson-plans/calendar/page.tsx
  • src/app/(app)/course-plans/page.tsx、course-plans/[id]/page.tsx
  • src/app/(app)/diagnostic/page.tsx、diagnostic/class/[classId]/page.tsx
  • src/app/(app)/error-book/page.tsx
  • src/app/(app)/practice/page.tsx

P2-E（elective + 富文本编辑 + 监考 + 扫描批改 + 热力图）— 10 个文件：

  • src/lib/graphql-p7-advanced.ts（13 operations + 类型）
  • src/mocks/handlers-p7-advanced.ts、fixtures/elective.ts、proctoring.ts、scan-grading.ts、lesson-plan-heatmap.ts
  • src/app/(app)/elective/page.tsx、elective/create/page.tsx、elective/[id]/edit/page.tsx
  • src/app/(app)/exams/[id]/edit-rich/page.tsx、exams/[id]/proctoring/page.tsx
  • src/app/(app)/homework/submissions/[submissionId]/scan-grading/page.tsx
  • src/app/(app)/lesson-plans/heatmap/page.tsx

集成文件（修改）— 3 个：

  • src/mocks/browser.ts（注册 5 个 p7 handlers）
  • src/mocks/server.ts（同上）
  • src/mocks/fixtures/viewports.ts（新增 11 个导航项：attendance/questions/textbooks/lesson-plans/course-plans/diagnostic/error-book/practice/elective/leave/schedule-changes）

P7 累计：61 个 GraphQL operations + 5 个 handlers 文件 + 13 个 fixtures + 35 个新页面 + 3 个修改文件

§5.4 验证

  • npx tsc --noEmit ✅ 零错误通过
  • 设计令牌：全部使用 Tailwind 语义类（bg-paper/text-ink/border-rule/text-accent 等）或 hsl(var(--*))，无 #hex 硬编码
  • 字体：全部使用 font-serif/font-sans/font-mono Tailwind 类
  • noUncheckedIndexedAccess：所有数组索引均做了 undefined 兜底
  • 文件大小：所有文件 ≤ 500 行（最大 charts.tsx 420 行）

§5.5 后续仍需处理（合并 P3-P6 + P7 后）

  1. 单元测试（vitest 配置 + 测试文件）
  2. 设计令牌硬编码修复（globals.css/tailwind.config.js 的 hsl() 字面量）
  3. 字体名硬编码修复（layout.tsx → var(--font-family-*)）
  4. i18n 集成（中文硬编码 → next-intl）
  5. packages/ui-components 扩展组件（shadcn/ui 基础组件/Form/RichTextEditor/Chart）
  6. 上游就绪后 MSW mock → 真实 API 切换
  7. 教师工作台快速入口（基于 viewports 自动生成快捷卡片）
  8. 全局搜索（参考项目有 /search API）
  9. 全局消息中心增强（参考项目有 /messages 页面）

§5.6 Docker Desktop 验证（2026-07-13）

构建：

  • Dockerfile 切换为 Next.js output: "standalone" 模式（解决 pnpm symlink 在 runtime 下无法解析 react/jsx-runtime 的问题）
  • 修复 tsconfig.base.json 未 COPY 到 builder 阶段的问题
  • 基础镜像：node:20-alpine（本地测试可 retag node:22-alpine）
  • 镜像大小：1.32GB

容器运行：

  • 启动时间：Ready in 69ms
  • 健康检查：/api/health → {"status":"ok","service":"teacher-portal"}
  • 首页：HTTP 200，length=5921（登录页正常渲染）

路由验证：

类型 通过/总数 结果
静态路由 27/27 全部 HTTP 200 ✅
动态路由 11/11 全部 HTTP 200 ✅
GraphQL 端点 N/A 服务端代理到 api-gateway（未启动时预期 500）

已知限制：

  • MSW mock 仅浏览器端生效，SSR 阶段 GraphQL 请求走 next.config.js rewrites 到 api-gateway
  • 生产部署时必须先启动 api-gateway
  • 详细下游依赖清单见 apps/teacher-portal/nextstep.md

§5.7 v2 下游核查 + 剩余工作完成（2026-07-14）

触发条件：用户通知"所有下游服务已经完成 nextstep.md 工作"，对 9 个下游服务（teacher-bff / iam / push-gateway / api-gateway / core-edu / content / data-ana / msg / ai）的 nextstep.md 进行核查。

§5.7.1 v2 核查结论

核心发现：teacher-bff nextstep.md 声称完成 v2 扁平命名（41 Query + 20 Mutation），但实际核查发现：

  1. schema 文件未更新：packages/shared-ts/contracts/graphql/teacher-bff.schema.graphql 仍是 v1（admin 命名空间，19 Query + 5 Mutation）
  2. teacher 域 P3+ 查询仍是 P2 占位：teacher.resolver.ts 第 60-95 行 exams / homework / grades 仍抛 BusinessError("not available in P2")
  3. 5 个 gRPC target 留空走降级模式 B：core-edu / content / data-ana / msg / ai 全部未对接
  4. 56/61 GraphQL operations 不可用：仅 5 个 P2 核心 Query（dashboard / viewports / me / classes / class）真实可用

决策：保留 MSW mock，记录 12 项 teacher-bff 待补工作到 nextstep-v2.md §2.1。

§5.7.2 v2 完成工作清单

# 工作项 完成内容
1 useAuth 迁移核查 发现 iam REST 登录接口未实现 Set-Cookie，修正 v1 的错误假设（v1 假设 iam 已就绪）。useAuth 迁移阻塞于 iam 后端实现 Set-Cookie
2 push-gateway WebSocket 接入 ✅ 环境变量 NEXT_PUBLIC_PUSH_GATEWAY_WS_URL + URL query token + Reconnect 协议（session_id + last_seq）+ 兼容 push-gateway 事件格式
3 单元测试扩展 ✅ usePermission 15 tests + useAuth 9 tests，总计 87/87 passed（从 v1 的 63 扩展到 87）
4 ui-components 剩余组件 ✅ Chart（SVG bar/line/pie）+ Calendar（月视图 + 事件标记）+ RichTextEditor（contentEditable 轻量实现），总计 12/12 组件
5 设计令牌完整迁移 ✅ globals.css + tailwind.config.js 全部使用 var(--*)，无 hsl/hex 字面量；ESLint tokens + a11y flat config 就绪
6 i18n 扩展状态评估 已迁移 5/55 页面（dashboard/grades/settings 等）+ 26 模块 key + LocaleSwitcher。剩余 50+ 页面待逐页替换
7 性能优化扩展 ✅ 基本完成 size-limit 9 项性能预算 + 5 个重型页面懒加载（lesson-plans/heatmap、grades/analytics、knowledge-graph、ParentPortalRemote、HeatmapMatrix）
8 nextstep-v2.md 文档生成 完整记录 v2 核查结论 + 下游依赖 + 本模块待补工作 + 集成测试方案 + 已知问题

§5.7.3 验证结果

  • ✅ pnpm --filter @edu/teacher-portal typecheck 通过（tsc --noEmit 零错误）
  • ✅ pnpm --filter @edu/teacher-portal lint 通过（eslint src 零错误）
  • ✅ pnpm --filter @edu/teacher-portal test 通过（Test Files 8 passed / Tests 87 passed）
  • ✅ pnpm run arch:scan 完成（TS 20 模块 / 3330 符号 + Go 2 模块 / 93 符号 + Python 2 模块 / 469 符号 + Protobuf 394 契约）

§5.7.4 v2 剩余阻塞项

阻塞项 依赖方 阻塞工作
teacher-bff teacher 域 P3+ 查询/mutation 实现 ai03 + ai07/08/10/11/12 MSW mock → 真实 API 切换（56 operations）
teacher-bff schema 文件同步为 v2 扁平命名 ai03 契约一致性
teacher-bff 5 个 gRPC target 配置 ai03 teacher 域扩展查询
iam REST 登录接口实现 Set-Cookie ai06 useAuth 迁移到 httpOnly cookie（F12）

无阻塞工作（可任意时间推进）：i18n 扩展剩余 50+ 页面、图片优化（next/image）、字体优化（next/font）、CI size-limit 阻断集成。

详细 v2 文档见 apps/teacher-portal/nextstep-v2.md。

§6 全并行开发说明

按 matrix.md §全并行模式：

  1. ai13 一口气完成 P2-P6 全部代码，开发期间用 MSW mock 上游
  2. 上游就绪后在 matrix.md §8 更新就绪信号
  3. 所有模块就绪后统一集成测试（matrix.md §9 检查清单）
  4. Mock 切换：NEXT_PUBLIC_API_MOCKING=enabled → disabled

AI Agent: ai13（teacher-portal） Branch: feat/teacher-portal-workline-ai13 Coordinator: coord-ai

Reference in New Issue View Git Blame Copy Permalink