docs: ai 协作文档体系重构与多 ai 仲裁结果落地
1.AI 协作文档体系重构(objections/worklines/contracts+matrix.md) 2.coord 仲裁文档(final-decisions/cross-review/final-rulings/orchestration) 3.各服务 01/02 文档补全 4.共享包初始化(shared-ts/shared-go/hooks/ui-components/ui-tokens) 5.Proto 契约补全 6.004 架构影响地图更新 7.端口分配表 8.设计规格文档
This commit is contained in:
SpecialX
170
docs/architecture/issues/worklines/teacher-portal_workline.md
Normal file
170
docs/architecture/issues/worklines/teacher-portal_workline.md
Normal file
@@ -0,0 +1,170 @@
|
||||
# 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/teacher/graphql + POST /api/auth/login（见 contract.md §4.2）
|
||||
- **验收标准**：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/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 我的就绪信号（供下游消费）
|
||||
|
||||
| 信号 | 就绪标志 | 消费方 |
|
||||
| ------------------------------- | -------------------------------------- | ---------------------------------- |
|
||||
| teacher-portal dev server :4000 | next dev -p 4000 可访问 | 无（最前端） |
|
||||
| MF Shell 可加载 | 首页渲染 AppShell + 导航 | student/parent/admin Remote（P3+） |
|
||||
| 登录流程可用 | POST /api/auth/login → JWT → Dashboard | 无（最前端） |
|
||||
| GraphQL 查询可执行 | currentUser/myClasses 返回数据 | 无（最前端） |
|
||||
| parent-portal Remote 接入点 | MF remotes 配置就绪 | parent-portal（ai15 P4） |
|
||||
|
||||
---
|
||||
|
||||
## §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
|
||||
Reference in New Issue
Block a user