xiner/Edu

Files

SpecialX 1eacd1ed87 feat(teacher-portal): 完整实现 teacher-portal 微前端

包含 settings/students/api、graphql、mocks、ui-tokens 设计令牌等

2026-07-10 19:10:20 +08:00

12 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
交付物：
- 考试管理页面（classExams list / createExam mutation / examDetail）
- 作业管理页面（classHomework list / assignHomework mutation / homeworkDetail / 批改界面）
- 成绩管理页面（studentGrades list / recordGrade 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
交付物：
- 知识图谱可视化页面（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
交付物：
- 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）+ 通知中心实时更新

负责人：ai13
交付物：
- 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 启动	⏳ 待 ai12 P5
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 契约）

§5 全并行开发说明

按 matrix.md §全并行模式：

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

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

12 KiB Raw Blame History Unescape Escape