# teacher-portal 工作排期

> 负责人：ai13
> 关联：[workline.md](../workline.md)、[coord.md §2 ARB-002](../coord.md)、[contracts/teacher-portal_contract.md](../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](../matrix.md) §8 更新就绪信号，最后统一集成测试。

---

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

```mermaid
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）+ 通知中心实时更新

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

- **负责人**：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](../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