Merge worktree branch merge-15-modules-to-main-5ug5xJ

2026-07-10 15:28:20 +08:00
parent 60d7173545
commit df62ffc176
51 changed files with 11559 additions and 1908 deletions
--- a/docs/architecture/issues/worklines/parent-portal_workline.md
+++ b/docs/architecture/issues/worklines/parent-portal_workline.md
@@ -2,44 +2,331 @@

 > 负责人：ai15
 > 关联：[workline.md](../workline.md)、[coord.md](../coord.md)、[contracts/parent-portal_contract.md](../contracts/parent-portal_contract.md)
-> 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，最后统一集成测试）
+> 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，开发期间用 mock，最后统一集成测试）

 ---

 ## §1 总览

-parent-portal 是家长端微前端，通过 MF Remote 接入主应用，覆盖 Dashboard、多子女切换等场景。全阶段目标：P2 MF Remote 骨架 → P3 Dashboard+多子女切换 → P4-P6 持续优化。
+parent-portal 是家长端微前端（MF Remote），挂载到 teacher-portal Shell，覆盖家长仪表盘、多子女切换、子女学情查看、通知偏好等场景。
+
+- **MF 角色**：Remote（Shell = teacher-portal :4000）
+- **端口**：4002（dev/prod 一致，[port-allocation.md](../../../../infra/port-allocation.md) §4）
+- **阶段归属**：P4 启动（依赖 P4 的 parent-bff + data-ana 就绪）
+- **DataScope**：CHILDREN（仅查看自己绑定子女的数据）
+- **全阶段目标**：P4 MF Remote 骨架 + 核心页面 → P5 推送接入 + 通知中心 → P6 硬化（A11y/性能/安全/PWA/多语言）
+
+> **前置阻塞**（见 [objections/parent-portal_issue.md](../objections/parent-portal_issue.md) ISSUE-010）：
+> - iam `GetChildrenByParent` 接口缺失（P0 阻塞，ai06 补全），补全前用 mock（固定 2 个子女 student-001 + student-002）
+> - ISSUE-001 待 coord 仲裁（REST vs GraphQL），仲裁前按 GraphQL 预排期，mock 用 MSW 拦截 GraphQL

 ---

-## §2 全阶段甘特图（P2-P6，各 AI 自行细化）
+## §2 全阶段甘特图（P4-P6）

 ```mermaid
 gantt
-    title ai15 parent-portal 全阶段排期
+    title ai15 parent-portal 全阶段排期（P4-P6）
    dateFormat YYYY-MM-DD
    axisFormat %m-%d

-    section P2-P6
-    [阶段任务] :a15a, 2026-07-10, Xd
+    section P4 骨架与核心页面（11d）
+    4.1 MF Remote 骨架+next.config.js+健康检查 :crit, a15a, 2026-07-29, 2d
+    4.2 GraphQL client接入+MSW mock层 :crit, a15b, after a15a, 1d
+    4.3 ChildSwitcher+useChildSwitcher+Zustand slice :crit, a15c, after a15b, 2d
+    4.4 Dashboard页面+ParentDashboard组件 :a15d, after a15c, 2d
+    4.5 子女成绩页面+ChildGradeChart :a15e, after a15c, 1d
+    4.6 子女作业页面 :a15f, after a15e, 1d
+    4.7 通知偏好页面+PreferenceForm+Zod :a15g, after a15d, 1d
+    4.8 跨标签同步(BroadcastChannel) :a15h, after a15c, 1d
+
+    section P4 质量保障（并行）
+    4.9 Vitest单测+MSW集成测试 :a15i, after a15g, 2d
+    4.10 Dockerfile多阶段构建 :a15j, after a15a, 1d
+
+    section P5 推送与通知中心（5d）
+    5.1 WebSocket接入+事件处理 :crit, a15k, after a15i, 2d
+    5.2 通知中心页面+NotificationFeed :a15l, after a15k, 2d
+    5.3 推送降级(HTTP轮询) :a15m, after a15l, 1d
+
+    section P6 硬化（8d）
+    6.1 Web Vitals+OTel browser SDK :a15n, after a15m, 2d
+    6.2 A11y WCAG 2.2 AA审计+修复 :a15o, after a15n, 2d
+    6.3 性能优化+bundle分析 :a15p, after a15o, 1d
+    6.4 多语言扩展(en-US) :a15q, after a15p, 1d
+    6.5 PWA(Service Worker+manifest) :a15r, after a15q, 1d
+    6.6 安全硬化(CSP+敏感数据脱敏) :a15s, after a15r, 1d
 ```

-> **注意**：以上为 coord 初始规划，ai15 接管后必须自行细化为完整 P2-P6 排期。
+> **总工期**：P4 11d + P5 5d + P6 8d = 24d（约 5 周）
+> **关键路径**（红色 crit）：MF 骨架 → GraphQL client → ChildSwitcher → 质量保障 → WebSocket → 通知中心

 ---

 ## §3 详细任务

-### 全阶段任务
+### P4 阶段任务
+
+#### P4-1：MF Remote 骨架 + next.config.js + 健康检查

 - **负责人**：ai15
- **交付物**：⚠️ 由 ai15 自行补充
- **依赖**：见 [contracts/parent-portal_contract.md](../contracts/parent-portal_contract.md)
- **验收标准**：⚠️ 由 ai15 自行补充
+- **依赖**：teacher-portal Shell MF 配置就绪（ARB-002，ai13 P2 交付）；ISSUE-002 仲裁（MF shared 清单）
+- **交付物**：
+  - `apps/parent-portal/next.config.js`（NextFederationPlugin，Remote 角色，`name: parent_app`，`exposes: ./pages + ./ChildSwitcher`，`shared` 含 ARB-002 全部 7 项）
+  - `apps/parent-portal/src/app/layout.tsx`（RootLayout，复用 Shell 暴露的字体/令牌/i18n Provider）
+  - `apps/parent-portal/src/app/api/health/route.ts`（`GET /api/health` → `{ status: 'ok', ts }`）
+  - `apps/parent-portal/src/app/api/ready/route.ts`（`GET /api/ready` → 检查 API_GATEWAY_URL 可达）
+  - `apps/parent-portal/tsconfig.json`（继承 tsconfig.base.json，strict）
+  - `apps/parent-portal/package.json`（依赖对齐 Shell：react 18.3 + next 14 + urql + @tanstack/react-query v5 + zustand + nuqs）
+- **验收标准**：
+  1. `pnpm --filter parent-portal dev` 启动 :4002
+  2. `GET /api/health` 返回 200
+  3. teacher-portal Shell 能加载 parent-portal remoteEntry.js（MF 拓扑验证）
+  4. feature flag `NEXT_PUBLIC_MF_ENABLED` 可控制 MF 开关
+
+#### P4-2：GraphQL client 接入 + MSW mock 层
+
+- **负责人**：ai15
+- **依赖**：P4-1；ISSUE-001 仲裁（确认 GraphQL）；teacher-portal Shell 暴露 GraphQLProvider（ARB-002）
+- **交付物**：
+  - `apps/parent-portal/src/lib/graphql-client.ts`（从 Shell 暴露的 `useGraphQLClient()` 获取 urql client 单例）
+  - `apps/parent-portal/src/graphql/queries/`（currentUser / myChildren / childSummary / childGrades / childHomework / childTrend / childWeakness 查询文档）
+  - `apps/parent-portal/src/graphql/mutations/`（markAsRead / updateNotificationPreferences mutation 文档）
+  - `apps/parent-portal/src/mocks/handlers.ts`（MSW 拦截 `POST /api/v1/parent/graphql`，按 operationName 返回 mock）
+  - `apps/parent-portal/src/mocks/fixtures/*.json`（固定 2 个子女 student-001 李同学 + student-002 李妹妹，与 parent-bff mock 一致）
+  - `apps/parent-portal/src/mocks/browser.ts`（MSW worker 初始化，`NEXT_PUBLIC_API_MOCKING=enabled` 控制）
+- **验收标准**：
+  1. MSW enabled 时，所有 GraphQL 查询返回 mock 数据
+  2. myChildren mock 返回 2 个子女，id 与 childGrades/childHomework mock 的 student_id 一致
+  3. urql client 单例跨组件共享（MF shared singleton 验证）
+
+#### P4-3：ChildSwitcher + useChildSwitcher + Zustand slice
+
+- **负责人**：ai15
+- **依赖**：P4-2；ISSUE-009 仲裁（switchChild 是 GraphQL Mutation 还是纯前端状态）
+- **交付物**：
+  - `apps/parent-portal/src/stores/childSwitcherSlice.ts`（Zustand slice：children / currentChildId / isLoading / error / switchChild / refreshChildren）
+  - `apps/parent-portal/src/hooks/useChildSwitcher.ts`（封装 myChildren GraphQL query + 切换逻辑 + invalidate 子女维度查询）
+  - `apps/parent-portal/src/components/ChildSwitcher.tsx`（variant: tab | dropdown，状态机：idle/switching/switched/error）
+  - `apps/parent-portal/src/components/MultiChildTabBar.tsx`（≤3 子女用 Tab，>3 用下拉，移动端友好）
+  - localStorage 持久化 `parent:currentChildId`（刷新恢复）
+- **验收标准**：
+  1. 切换子女后，`['parent','grades',currentChildId]` 等子女维度查询 invalidate 重拉
+  2. 刷新页面后 currentChildId 从 localStorage 恢复
+  3. 0 子女显示 EmptyChildState；1 子女不显示 TabBar；2-3 子女显示 Tab
+  4. 切换子女竞态：快速连续切换，旧请求 abort，新数据正确显示
+
+#### P4-4：Dashboard 页面 + ParentDashboard 组件
+
+- **负责人**：ai15
+- **依赖**：P4-3
+- **交付物**：
+  - `apps/parent-portal/src/app/(app)/parent/dashboard/page.tsx`
+  - `apps/parent-portal/src/components/ParentDashboard.tsx`（组合 useChildren + useChildSummary，插槽：summary-cards / todo-reminders / recent-grades / attendance / custom）
+  - `apps/parent-portal/src/components/ChildSummaryCard.tsx`（单子女概览：头像/姓名/年级/今日作业数/成绩趋势缩略图）
+  - `apps/parent-portal/src/components/AttendanceCalendar.tsx`（出勤日历热力图）
+- **验收标准**：
+  1. 多子女并列卡片展示
+  2. 权限校验：`PARENT_DASHBOARD_VIEW`，用 `<RequirePermission>`
+  3. SSR 首屏 + CSR 交互（依 02 §14.4 渲染策略）
+
+#### P4-5：子女成绩页面 + ChildGradeChart
+
+- **负责人**：ai15
+- **依赖**：P4-3
+- **交付物**：
+  - `apps/parent-portal/src/app/(app)/parent/grades/page.tsx`
+  - `apps/parent-portal/src/components/ChildGradeChart.tsx`（recharts 折线 + 班级均分对比 + 多子女对比模式）
+- **验收标准**：
+  1. 权限校验：`GRADES_READ_CHILD`
+  2. 切换子女后图表刷新
+  3. 多子女对比模式可选
+
+#### P4-6：子女作业页面
+
+- **负责人**：ai15
+- **依赖**：P4-3
+- **交付物**：`apps/parent-portal/src/app/(app)/parent/homework/page.tsx`
+- **验收标准**：
+  1. 权限校验：`HOMEWORK_READ_CHILD`
+  2. 复用 Shell 暴露的 DataTable 展示作业列表
+
+#### P4-7：通知偏好页面 + PreferenceForm + Zod
+
+- **负责人**：ai15
+- **依赖**：P4-4
+- **交付物**：
+  - `apps/parent-portal/src/app/(app)/parent/preferences/page.tsx`
+  - `apps/parent-portal/src/components/PreferenceForm.tsx`（矩阵式 UI：子女×事件×渠道，react-hook-form + zodResolver）
+  - `apps/parent-portal/src/schemas/notificationPreferences.ts`（Zod schema，见 02 §14.4）
+- **验收标准**：
+  1. 权限校验：`PARENT_PREFERENCES_UPDATE`
+  2. 不可用渠道 Toggle disabled + tooltip
+  3. 保存成功后 invalidate `['parent','preferences']`
+  4. 表单 dirty 状态追踪 + 离开页提示
+
+#### P4-8：跨标签同步（BroadcastChannel）
+
+- **负责人**：ai15
+- **依赖**：P4-3
+- **交付物**：
+  - `apps/parent-portal/src/lib/crossTabSync.ts`（见 02 §16.2 完整实现）
+  - 集成到 RootLayout（`useCrossTabSync()`）
+- **验收标准**：
+  1. Tab A 切换子女 → Tab B 同步更新
+  2. LWW 冲突解决（ts 大的胜出）
+  3. Safari 降级为 storage 事件
+
+#### P4-9：Vitest 单测 + MSW 集成测试
+
+- **负责人**：ai15
+- **依赖**：P4-4 ~ P4-7
+- **交付物**：
+  - `apps/parent-portal/vitest.config.ts`
+  - 单测：组件渲染/交互、Hook 逻辑、Zod schema 校验、纯函数 utils（覆盖率 ≥ 85%）
+  - 集成测试：useChildSwitcher + Zustand slice + invalidate 流程（MSW mock，覆盖率 ≥ 75%）
+- **验收标准**：
+  1. `pnpm --filter parent-portal test` 全绿
+  2. 覆盖率达标（单元 ≥ 85%，集成 ≥ 75%）
+
+#### P4-10：Dockerfile 多阶段构建
+
+- **负责人**：ai15
+- **依赖**：P4-1
+- **交付物**：`apps/parent-portal/Dockerfile`（builder + runtime，node:22-alpine）
+- **验收标准**：
+  1. `docker build` 成功
+  2. HEALTHCHECK 指向 `/api/health`
+  3. 镜像体积 < 300MB
+
+### P5 阶段任务
+
+#### P5-1：WebSocket 接入 + 事件处理
+
+- **负责人**：ai15
+- **依赖**：push-gateway :8081/ws 就绪（ai02）；parent-portal P4 完成
+- **交付物**：
+  - `apps/parent-portal/src/hooks/useWebSocket.ts`（连接 push-gateway ws，JWT 鉴权，自动重连）
+  - 事件处理：`NotificationRequested` → toast + 未读数+1；`GradeRecorded` → toast + 成绩 invalidate；`SchoolAnnouncement` → toast + dashboard invalidate
+- **验收标准**：
+  1. WS 连接建立后收事件正常
+  2. 断线自动重连（指数退避）
+
+#### P5-2：通知中心页面 + NotificationFeed
+
+- **负责人**：ai15
+- **依赖**：P5-1
+- **交付物**：
+  - `apps/parent-portal/src/app/(app)/parent/notifications/page.tsx`
+  - `apps/parent-portal/src/components/NotificationFeed.tsx`（按子女×类型×已读筛选，批量已读，跳转，置顶）
+- **验收标准**：
+  1. 权限校验：`NOTIFICATION_READ_OWN`
+  2. WebSocket 推送 invalidate 通知列表
+
+#### P5-3：推送降级（HTTP 轮询）
+
+- **负责人**：ai15
+- **依赖**：P5-1
+- **交付物**：WS 重试 5 次失败后降级为 HTTP 轮询（60s 拉取通知列表）
+- **验收标准**：降级后通知延迟 ≤ 60s，用户感知降级提示
+
+### P6 阶段任务
+
+#### P6-1：Web Vitals + OTel browser SDK
+
+- **交付物**：`next/web-vitals` 上报 + OTel browser SDK（复用 Shell 暴露的 TracerProvider）
+- **验收标准**：LCP/CLS/TTFB 指标上报到 Gateway
+
+#### P6-2：A11y WCAG 2.2 AA 审计 + 修复
+
+- **交付物**：axe-core 自动扫描 + 手动键盘导航测试，0 严重违规
+- **验收标准**：所有页面 0 严重 A11y 违规
+
+#### P6-3：性能优化 + bundle 分析
+
+- **交付物**：bundle 分析报告 + 代码分割优化（首屏 JS ≤ 80KB gzipped）
+- **验收标准**：Lighthouse 移动端 4G ≥ 90 分
+
+#### P6-4：多语言扩展（en-US）
+
+- **交付物**：`apps/parent-portal/src/i18n/messages/en-US/*.json`（镜像 zh-CN 结构）
+- **验收标准**：en-US 完成度 100%
+
+#### P6-5：PWA（Service Worker + manifest）
+
+- **交付物**：`public/manifest.json` + Service Worker 缓存策略（见 02 §18.4）
+- **验收标准**：可安装到主屏，离线可查看缓存的子女数据
+
+#### P6-6：安全硬化（CSP + 敏感数据脱敏）
+
+- **交付物**：CSP 头配置（复用 Shell）+ 截图脱敏 + 页面离开遮罩
+- **验收标准**：CSP 无违规报告；敏感数据不泄漏

 ---

 ## §4 依赖与就绪信号

- **我依赖**：⚠️ 由 ai15 自行补充（见 contract.md）
- **我的就绪信号**：⚠️ 由 ai15 自行补充
+### 4.1 我依赖的上游就绪标志
+
+| 上游 | 就绪信号 | 提供方 | 状态 | 阻塞影响 |
+| ---- | -------- | ------ | ---- | -------- |
+| teacher-portal Shell | MF exposes（AppShell + GraphQLProvider + hooks + UI 组件）+ shared singleton | ai13 | ⏳ P2 | P4 无法启动 |
+| parent-bff GraphQL | `POST /graphql` :3010 + currentUser/myChildren/childSummary/childGrades Query | ai05 | ⏳ P4 | 核心数据源 |
+| iam GetChildrenByParent | gRPC 50052 + `iam_student_guardians` 表 | ai06 | ⏳ P3 补全 | P0 多子女阻塞（见 ISSUE-010） |
+| core-edu | gRPC 50053 + GradeService/HomeworkService/AttendanceService | ai08 | ⏳ P3 | 成绩/作业数据 |
+| data-ana | gRPC 50055 + AnalyticsService | ai11 | ⏳ P4 | 学情分析数据 |
+| msg | gRPC 50056 + NotificationService | ai10 | ⏳ P5 | 通知中心 |
+| push-gateway | :8081/ws WebSocket | ai02 | ⏳ P5 | 实时推送 |
+| shared-ts | ApiClient/Logger（coord 维护） | coord | ⏳ | 基础工具 |
+| contracts | Permissions 常量（coord 维护） | coord | ⏳ | 权限校验 |
+| ui-tokens / ui-components / hooks | 三层令牌 + shadcn + usePermission/useAuth（ai07/ai13 维护） | ai07/ai13 | ⏳ P2 收尾 | UI 基础 |
+
+### 4.2 我的就绪信号（供下游消费）
+
+| 信号 | 说明 | 阶段 |
+| ---- | ---- | ---- |
+| parent-portal :4002 dev server 启用 | MF Remote 可被 Shell 加载 | P4-1 完成 |
+| MF Remote remoteEntry.js 可加载 | Shell 端 `remotes.parent` 可解析 | P4-1 完成 |
+| 核心 GraphQL 查询可执行 | currentUser / myChildren / childSummary 返回数据（mock 或真实） | P4-2 完成 |
+| 多子女切换可用 | ChildSwitcher + invalidate 流程通过 | P4-3 完成 |
+| Dashboard 可访问 | 家长登录 → 看到 Dashboard（含子女卡片） | P4-4 完成 |
+| 健康检查通过 | `GET /api/health` + `GET /api/ready` 200 | P4-1 完成 |
+| 测试覆盖率达标 | 单元 ≥ 85% + 集成 ≥ 75% | P4-9 完成 |
+| Docker 镜像可构建 | `docker build` 成功 | P4-10 完成 |
+
+### 4.3 全并行 Mock 策略
+
+| 消费接口 | Mock 方式 | 切换真实时机 |
+| -------- | --------- | ------------ |
+| parent-bff GraphQL | MSW 拦截 `POST /api/v1/parent/graphql`，按 operationName 返回 fixtures | parent-bff GraphQL :3010 就绪 ✅ |
+| iam login | MSW 返回固定 JWT（parent 角色） | api-gateway + iam 就绪 ✅ |
+| push-gateway WebSocket | mock-socket 模拟 WS 推送（每 30s 1 条通知） | push-gateway :8081 就绪 ✅ |
+| 子女数据一致性 | myChildren mock 返回 student-001 + student-002，与所有 child* 查询 student_id 一致 | iam GetChildrenByParent 就绪 |
+
+> Mock 由 `NEXT_PUBLIC_API_MOCKING=enabled` 环境变量控制，上游就绪后设为 `disabled`。
+
+---
+
+## §5 风险与缓解
+
+| 风险 | 影响 | 缓解 |
+| ---- | ---- | ---- |
+| ISSUE-001/002 未仲裁（REST vs GraphQL） | P4-2 GraphQL client 接入方向不确定 | 先按 GraphQL 预排期；仲裁若改 REST，P4-2 重写（预计 1d） |
+| iam GetChildrenByParent 缺失（ISSUE-010） | 多子女场景无法落地 | mock 固定 2 子女开发；coord 跟踪 ai06 P3 补全 |
+| MF SSR 对齐复杂 | Remote SSR 需 Shell 上下文 | 优先 CSR，仅 Dashboard 首屏 SSR；P4-1 PoC 验证 |
+| parent-bff 契约未最终确认 | GraphQL schema 可能变动 | P4 启动前与 ai05 对齐 schema；MSW mock 解耦 |
+| TanStack Query 缓存膨胀 | 多子女历史查询堆积 | gcTime 5min + 切换子女清理非当前子女缓存 |
+
+---
+
+## §6 质量门禁
+
+每个任务完成前必须通过：
+
+- `pnpm --filter parent-portal lint` 零错误
+- `pnpm --filter parent-portal typecheck` 零错误
+- `pnpm --filter parent-portal test` 全绿（P4-9 起强制）
+- 设计令牌三层规则（无 `#hex` / 无硬编码字体 / 无任意值，ESLint 强制）
+- A11y：jsx-a11y error 级零违规
+
+> 提交前校验见 [project_rules §8](../../../../.trae/rules/project_rules.md)，commit 遵循 Conventional Commits：`feat(parent-portal): ...`