# 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
- **审计状态**（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`

---

## §6 全并行开发说明

按 [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