diff --git a/apps/parent-portal/docs/01-understanding.md b/apps/parent-portal/docs/01-understanding.md index dc57806..33c07fd 100644 --- a/apps/parent-portal/docs/01-understanding.md +++ b/apps/parent-portal/docs/01-understanding.md @@ -1,9 +1,18 @@ # 模块理解确认书 — parent-portal -> AI：ai07（TS/React · 家长场景域前端 remote） -> 阶段：阶段 1 交付物 -> 日期：2026-07-09 -> 关联：[004 架构影响地图](../../../docs/architecture/004_architecture_impact_map.md) §1.1a/1.1b/§5.4、[AI 分配方案](../../../docs/architecture/ai-allocation.md) §5 ai05/ai07、[pending-features P4](../../../docs/architecture/roadmap/pending-features.md)、[known-issues §2.12](../../../docs/troubleshooting/known-issues.md)、[teacher-portal 阶段1](../../teacher-portal/docs/01-understanding.md)、[teacher-portal 阶段2](../../teacher-portal/docs/02-architecture-design.md) +> AI：ai15（TS/React · 家长场景域前端 remote） +> 阶段：阶段 1 交付物（v2 — ai15 接管审计与补全版） +> 初版日期：2026-07-09（ai07 起草） +> 审计日期：2026-07-09（ai15 修订：端口、所有权、长远架构遗漏补全） +> 关联：[004 架构影响地图](../../../docs/architecture/004_architecture_impact_map.md) §1.1a/1.1b/§5.4、[AI 分配方案](../../../docs/architecture/ai-allocation.md) §3.2 ai15、[pending-features P4](../../../docs/architecture/roadmap/pending-features.md)、[known-issues §2.12](../../../docs/troubleshooting/known-issues.md)、[teacher-portal 阶段1](../../teacher-portal/docs/01-understanding.md)、[teacher-portal 阶段2](../../teacher-portal/docs/02-architecture-design.md)、[parent-bff 阶段1](../../../services/parent-bff/docs/01-understanding.md) + +> **审计修订摘要**（ai15 → ai07 初稿）： +> +> 1. **端口修订**：3002 → **4002**（004 §1.2 强制 4 端 4000-4003，project memory 硬约束） +> 2. **MF URL 修订**：teacher/student/parent/admin 端 URL 全部从 3000-3003 修订为 4000-4003 +> 3. **所有权修订**：ai07 → **ai15**（ai-allocation.md §3.2） +> 4. **遗漏补全**：i18n 策略、移动端/PWA、多子女边界场景、通知偏好数据模型、隐私合规（COPPA/FERPA）、测试策略分层、韧性模式、性能预算、CSP/前端安全、跨标签同步、API 版本演进、未来扩展铺垫、长远愿景 +> 5. **新增章节**：§11 多子女边界场景、§12 隐私合规、§13 测试策略、§14 性能与预算、§15 前端安全、§16 跨标签与跨设备同步、§17 i18n 深化、§18 移动端与 PWA、§19 长远愿景与演进路径 --- @@ -11,11 +20,11 @@ - **层级**：L2 微前端层（004 §3.1 六层架构中的前端层） - **MF 角色**：**Remote 子应用**，挂载到 teacher-portal Shell -- **上游（谁调用我）**：浏览器（家长） +- **上游（谁调用我）**：浏览器（家长）— 含桌面 Chrome/Edge/Safari、移动端 iOS Safari/Android Chrome - **下游（同步）**：api-gateway（REST，经 Next.js `rewrites` 代理 `/api/v1/*`） -- **下游（推送，P5）**：push-gateway（WebSocket） -- **BFF 对接**：parent-bff（待 ai05 设计） -- **通信方式**：HTTP/REST（前端→Gateway）+ WebSocket（前端→push-gateway，P5） +- **下游（推送，P5）**：push-gateway（WebSocket，含 SSE 降级） +- **BFF 对接**：parent-bff（ai04 设计，端口 3010） +- **通信方式**：HTTP/REST（前端→Gateway）+ WebSocket（前端→push-gateway，P5）+ SSE 降级（P5+） - **不直连**：前端不直连任何业务服务或 BFF 后端实例，全部经 api-gateway 代理 **说明**： @@ -52,13 +61,25 @@ ### 3.1 消费的后端 API（经 api-gateway 代理） -| 路径前缀 | 下游 BFF/服务 | 关键端点 | -| ------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -| `/api/v1/parent/*` | parent-bff | `GET /parent/viewports`、`GET /parent/children`、`POST /parent/switch-child`、`GET /parent/notifications`、`PUT /parent/notification-preferences` | -| `/api/v1/iam/*` | iam | `POST /iam/login`、`GET /iam/me`、`GET /iam/effective-permissions` | -| `/api/v1/notifications/*` | msg | 通知中心（P5） | +| 路径前缀 | 下游 BFF/服务 | 关键端点 | +| ------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `/api/v1/parent/*` | parent-bff | `GET /parent/viewports`、`GET /parent/dashboard`、`GET /parent/children`、`POST /parent/children/:childId/select`、`GET /parent/children/:childId/exams`、`/homework`、`/grades`、`/analytics/trend`、`/analytics/weakness`、`GET /parent/notifications`、`PUT /parent/notification-preferences` | +| `/api/v1/iam/*` | iam | `POST /iam/login`、`GET /iam/me`、`GET /iam/effective-permissions`、`GET /iam/children`（**P0 阻塞**，待 ai02 补全） | +| `/api/v1/notifications/*` | msg | 通知中心（P5） | > parent-bff 聚合 iam + core-edu + data-ana + msg，对外暴露家长场景的统一接口（子女关联、视口、学情聚合）。 +> **P0 阻塞项**（来自 parent-bff §7.1）：iam 缺失"家长-学生关联查询"接口（`GetChildrenByParent` proto + `GET /iam/children` REST + `iam_student_guardians` 表三缺失）。在 ai02 补全前，parent-portal 的多子女场景无法落地，仅能假设单子女硬编码 childId 进行开发调试。 + +### 3.1.1 API 契约版本演进策略 + +| 版本信号 | 携带位置 | 演进规则 | +| ----------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------- | +| 主版本 | URL 路径 `/api/v1/*` → `/api/v2/*` | 破坏性变更升主版本，parent-portal 同时支持 v1 + v2 至少 1 个迭代周期（4 周），通过 Feature Flag 切换 | +| 子版本 | 响应头 `X-API-Version: 2026-07-09` | 向后兼容字段新增，前端忽略未知字段（Zod 默认行为） | +| Deprecation | 响应头 `Deprecation: true` + `Sunset: ` | 前端收到 Deprecation 头后上报埋点，跟踪使用率，确认 < 1% 后移除前端调用 | +| 字段裁剪 | 请求头 `X-Fields: grades[].id,grades[].score` | 父 portal 在低带宽移动场景按需裁剪（GraphQL 风格，BFF REST 透传支持） | + +> parent-portal 不主动驱动 API 版本升级；契约变更由 coord 协调各业务 AI 落地。parent-portal 仅负责消费侧的兼容与迁移。 ### 3.2 统一响应契约 @@ -208,11 +229,20 @@ apps/parent-portal/ - Form（react-hook-form + zodResolver 封装） - Chart（recharts 封装） -### 9.2 parent-portal 特有组件 +### 9.2 parent-portal 特有组件（完整清单） -| 组件 | 用途 | 来源 | -| --------------- | ---------------------------------------------------------- | ---- | -| `ChildSwitcher` | 多子女切换组件（顶部 Tab），切换后 invalidate 子女相关查询 | 新建 | +| 组件 | 用途 | 来源 | 是否 MF 暴露 | +| --------------------- | ----------------------------------------------------------------------- | ---- | -------------------- | +| `ChildSwitcher` | 多子女切换组件（顶部 Tab / 移动端下拉），切换后 invalidate 子女相关查询 | 新建 | ✅ `./ChildSwitcher` | +| `ChildSummaryCard` | 单个子女的概览卡片（头像/姓名/年级/今日作业数/近期成绩趋势缩略图） | 新建 | ❌ 内部使用 | +| `ParentDashboard` | 家长仪表盘容器（多子女并列卡片 + 全家聚合统计 + 待办提醒） | 新建 | ❌ 内部使用 | +| `ChildGradeChart` | 子女成绩趋势图（折线 + 班级均分对比 + 区间填充）+ 多子女对比模式 | 新建 | ❌ 内部使用 | +| `AttendanceCalendar` | 出勤日历热力图（按月网格展示出勤/缺勤/迟到/请假，全年概览） | 新建 | ❌ 内部使用 | +| `NotificationFeed` | 通知流（按子女×类型×已读筛选，支持批量已读、跳转、置顶） | 新建 | ❌ 内部使用 | +| `PreferenceForm` | 通知偏好设置表单（子女×事件×渠道三维矩阵，react-hook-form + Zod 校验） | 新建 | ❌ 内部使用 | +| `ChildComparisonView` | 多子女横向对比视图（成绩/出勤/作业完成率并排表格，P5+） | 新建 | ❌ 内部使用 | +| `EmptyChildState` | 无子女绑定引导（CTA 跳转绑定流程，含客服联系方式） | 新建 | ❌ 内部使用 | +| `MultiChildTabBar` | 多子女 Tab 栏（≤3 子女用 Tab，>3 子女用下拉，移动端友好） | 新建 | ❌ 内部使用 | ### 9.3 不使用的组件 @@ -220,6 +250,8 @@ apps/parent-portal/ - ExamTaking —— 学生考试专用 - SSEViewer —— AI 流式响应查看器（教师端专用） - UserManagementTable —— 管理员端专用 +- LessonPlanEditor —— 教师备课专用 +- KnowledgeGraphViewer —— 教师查看知识点图谱专用（家长端仅看诊断结论） ## 10. L4 数据层差异 @@ -228,8 +260,499 @@ apps/parent-portal/ | 主要数据源 | teacher-bff | parent-bff（聚合 iam + core-edu + data-ana + msg） | | 缓存策略 | 5-30s 短缓存 | 5-30s 短缓存，**子女切换 invalidate** 子女相关查询 | | 多子女状态 | N/A | ChildSwitcher Zustand slice，当前子女 ID 持久化到 localStorage | +| 跨标签同步 | N/A | BroadcastChannel API + Storage 事件同步当前子女 ID（见 §16） | +| 离线缓存 | N/A | P5+ PWA Service Worker 缓存最近查看的子女数据快照（见 §18） | --- -**AI Agent**: ai07 (parent-portal remote) -**Branch**: docs/parent-portal-stage1-stage2-design-ai07 +## 11. 多子女边界场景（家长端特有，必须覆盖） + +> 家长端的核心复杂度来自多子女，必须在架构中预留所有边界场景的处理。 + +### 11.1 子女数量边界 + +| 场景 | 触发条件 | 前端处理 | 后端契约依赖 | +| ---------------- | -------------------------- | ------------------------------------------------------------------------------------------ | -------------------------------------- | +| 0 子女（未绑定） | 新注册家长或子女关系被解除 | 显示 `EmptyChildState` 引导页，CTA 跳转绑定流程；隐藏 dashboard/grades/homework 等业务路由 | `GET /parent/children` 返回 `[]` | +| 1 子女 | 单子女家庭 | 不显示 `MultiChildTabBar`，直接进入业务页面；URL 不携带 `?childId=` | `GET /parent/children` 返回长度 1 数组 | +| 2-3 子女 | 多子女家庭（典型） | `MultiChildTabBar` 显示 Tab 形式，默认选中最近查看的子女 | 同上 | +| 4-10 子女 | 大家庭或重组家庭 | `MultiChildTabBar` 改为下拉选择器 + 头像缩略；Tab 栏超过 3 个时自动切换 | 同上 | +| >10 子女 | 校管理员或多监护人代管场景 | 强制下拉选择器 + 搜索框（按姓名/学号筛选）；列表分页加载 | `GET /parent/children` 支持分页 + 搜索 | + +### 11.2 子女档案变更边界 + +| 场景 | 触发条件 | 前端处理 | 事件来源 | +| ------------------------ | -------------------- | --------------------------------------------------------------------------------------------------------------- | --------------------------- | +| 子女被解绑 | 家长或管理员主动解绑 | 收到 WebSocket 事件 → invalidate children 列表 → 若当前选中子女被解绑，自动切换到第一个子女；若无子女则跳引导页 | `edu.identity.user.updated` | +| 子女档案被归档/转学 | 学校主动操作 | 收到事件后该子女标识为"已离校"，灰色显示但保留历史数据查看权限；不可选为当前子女 | `edu.identity.user.updated` | +| 子女姓名/头像变更 | 学校维护档案 | 收到事件 → invalidate children 列表 → UI 自动刷新；不中断当前操作 | `edu.identity.user.updated` | +| 当前子女被切到其他监护人 | 监护权变更 | 同"解绑"处理 | `edu.identity.user.updated` | +| 新增子女绑定 | 家长新增绑定子女 | 收到事件 → invalidate children 列表 → 显示 toast 提示"已添加子女：XXX" → 不自动切换当前选中子女 | `edu.identity.user.created` | + +### 11.3 跨标签与跨设备同步边界 + +| 场景 | 触发条件 | 前端处理 | +| ----------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------- | +| 同浏览器多标签切换子女 | 用户在 Tab A 切换子女 | Tab B 通过 `BroadcastChannel('parent-child-switch')` 收到消息 → 同步更新 Zustand slice → invalidate 子女维度查询 | +| 隐身模式 / 不同浏览器 | 用户在另一浏览器登录 | 各自独立状态；服务端最终一致（依赖 iam `currentChildId` 是否持久化，按 ai04 建议方案 A 不持久化，仅前端 localStorage） | +| 移动端 + 桌面端同时登录 | 用户多设备登录 | 各自独立 currentChildId；通知偏好等共享数据通过 WebSocket 实时同步 | +| 网络中断时切换子女 | 离线场景 | 切换操作入队列（IDB），网络恢复后批量同步；UI 显示"离线模式"标识 | + +### 11.4 子女数据访问越权 + +| 场景 | 触发条件 | 前端处理 | +| ---------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------- | +| URL 直接访问非绑定子女 | 用户篡改 `?childId=xxx` | BFF 在 `GET /parent/children/:childId/*` 端点做 DataScope=CHILDREN 校验，返回 403 → 前端 toast 错误并跳转默认子女 | +| 切换到刚解绑的子女 | 网络延迟，事件未到达 | BFF 校验失败 403 → 前端 invalidate children 列表 → 自动切换到第一个绑定子女 | +| 子女档案查看权限被回收 | 学校临时限制 | 同上，BFF 校验 | + +--- + +## 12. 数据隐私与合规 + +> 子女数据是高敏感数据，parent-portal 必须在设计阶段预留合规框架。本节是 ai15 新增，覆盖 COPPA、FERPA、PIPL 等法规对前端架构的要求。 + +### 12.1 适用法规矩阵 + +| 法规 | 适用范围 | 对前端的要求 | 阶段 | +| -------------- | ------------------ | --------------------------------------------------------------------------- | ----------- | +| COPPA | 美国 <13 岁儿童 | 收集前需家长可验证同意；展示同意记录入口；可删除子女数据请求入口 | P6 海外扩展 | +| FERPA | 美国教育记录 | 家长有权查看子女教育记录；学校有权限制家长访问（离婚/监护权争议场景） | P6 海外扩展 | +| PIPL | 中国个人信息保护法 | 隐私政策弹窗 + 同意按钮；敏感信息（成绩）展示前需二次确认；数据导出请求入口 | P4 起强制 | +| GDPR | 欧盟用户 | Cookie 同意管理；被遗忘权请求入口；数据可携带权导出 | P6 海外扩展 | +| 未成年人保护法 | 中国 <18 岁 | 14 岁以下需家长同意；展示适合年龄段的内容过滤 | P4 起强制 | + +### 12.2 前端合规设计 + +| 合规点 | 实现位置 | 阶段 | +| ------------------------- | ----------------------------------------------- | ---- | +| 隐私政策同意弹窗 | Shell RootLayout 首次登录后弹窗 | P4 | +| Cookie 同意管理（按类别） | Shell + parent-portal 复用 | P4 | +| 子女成绩展示二次确认 | `ChildGradeChart` 默认遮罩，点击"查看"展示 | P4 | +| 数据导出请求入口 | `/parent/preferences#data-export` 页面 | P5 | +| 数据删除请求入口 | `/parent/preferences#data-deletion` 页面 | P5 | +| 同意记录查看 | `/parent/preferences#consent-history` 页面 | P5 | +| 监护权变更影响展示 | 收到 BFF 403 时显示"请联系学校"提示，不暴露细节 | P4 | +| 敏感数据脱敏 | 截图/分享时自动遮罩成绩数字 | P5+ | + +### 12.3 数据保留策略（前端配合） + +| 数据类型 | 前端保留 | 后端保留 | 前端处理 | +| ---------------- | --------------------- | ---------- | ---------------------------- | +| 子女成绩列表缓存 | 30s（TanStack Query） | 永久 | staleTime 30s 后自动失效 | +| 通知列表 | 30s | 90 天 | 同上 | +| 子女列表 | 5min | 关系存续期 | 同上 | +| 当前选中子女 ID | localStorage 永久 | 不持久化 | 用户主动清除或解绑时清除 | +| 行为埋点 | 内存队列 100 条 | 90 天 | 队列满后批量上报，上报后清空 | + +--- + +## 13. 测试策略分层 + +> ai07 初稿仅提到"覆盖率 ≥ 80%"，未细化测试类型与覆盖率分目标。ai15 补全。 + +### 13.1 测试金字塔 + +| 层级 | 工具 | 覆盖率目标 | 测试范围 | +| --------- | ------------------------------------------ | ---------- | ----------------------------------------------------------------------------------------------------- | +| 单元测试 | Vitest + @testing-library/react | ≥ 85% | 所有组件渲染/交互、Hook 业务逻辑、Zod schema 校验、纯函数 utils | +| 集成测试 | Vitest + MSW（Mock Service Worker） | ≥ 75% | API 请求层 + TanStack Query hook 组合、ChildSwitcher + Zustand slice + invalidate 流程 | +| 视觉回归 | Playwright + Percy/Applitools（P6 引入） | 关键页面 | dashboard/children/grades/notifications/preferences 五个核心页面在 light/dark + mobile/desktop 4 组合 | +| E2E 测试 | Playwright | 关键路径 | 登录→看 dashboard→切换子女→查成绩→改通知偏好→登出 | +| A11y 测试 | axe-core + jest-axe + @axe-core/playwright | 0 严重违规 | 所有页面 WCAG 2.2 AA 自动扫描 + 手动键盘导航测试 | +| 性能测试 | Lighthouse CI | ≥ 90 分 | LCP < 2.5s / CLS < 0.1 / TBT < 200ms（移动端 4G 模拟） | +| 契约测试 | Pact（BFF ↔ parent-portal 双向，P6 引入） | 关键端点 | 防止 BFF 契约变更打破前端消费 | + +### 13.2 关键 E2E 场景（必须覆盖） + +```yaml +- name: multi_child_switch_flow + steps: + - login as parent_with_3_children + - assert MultiChildTabBar shows 3 tabs + - click tab "child-2" + - assert URL contains ?childId=child-2 + - assert grades list refreshes + - assert TanStack Query cache invalidated for child-1 grades + - reload page + - assert current child preserved (localStorage) + - open new tab + - assert new tab syncs to child-2 (BroadcastChannel) + +- name: zero_child_state + steps: + - login as parent_with_0_children + - assert EmptyChildState shown + - assert business routes hidden + - assert CTA "联系学校绑定子女" displayed + +- name: child_unbound_mid_session + steps: + - login as parent_with_2_children + - select child-1 + - simulate WebSocket event: child-1 unbound + - assert toast: "子女XXX已解绑" + - assert auto-switch to child-2 + - assert no error page + +- name: notification_preference_save + steps: + - login as parent + - navigate to /parent/preferences + - toggle "成绩推送" off for child-1 + - click save + - assert success toast + - assert TanStack Query cache invalidated + - reload + - assert preference persisted + +- name: offline_mode + steps: + - login as parent + - select child-1, view grades + - simulate offline (Playwright network condition) + - switch to child-2 + - assert queue indicator shown + - simulate online + - assert queued switch executed +``` + +### 13.3 Mock 数据策略 + +| 数据来源 | Mock 方式 | 维护方 | +| -------------- | -------------------------------------------------------------------- | ------ | +| BFF API 响应 | MSW handlers，按 `apps/parent-portal/src/mocks/handlers.ts` 集中管理 | ai15 | +| WebSocket 事件 | Mock WebSocket Server（Playwright fixture） | ai15 | +| i18n 文案 | 真实 next-intl messages（不 Mock） | coord | +| 设计令牌 | 真实 ui-tokens（不 Mock） | ai07 | +| 权限列表 | 按 fixture 角色预设（parent_with_X_children 等） | ai15 | + +--- + +## 14. 性能预算与代码分割 + +> ai07 初稿未提及性能预算。ai15 补全。 + +### 14.1 性能预算（Bundle Size） + +| 资源类型 | 预算（gzipped） | 备注 | +| ---------------------- | --------------- | ------------------------------------------------- | +| parent-portal 首屏 JS | ≤ 80 KB | 含 ChildSwitcher + ParentDashboard + 共享依赖分摊 | +| parent-portal 首屏 CSS | ≤ 20 KB | 含 Tailwind purged + 设计令牌 | +| 路由级懒加载 chunk | ≤ 30 KB/chunk | 每个二级路由单独 chunk | +| 图片 | ≤ 100 KB/页 | 子女头像、空态插画 | +| 总下载量（首屏） | ≤ 200 KB | 4G 网络下 LCP < 2.5s | + +### 14.2 代码分割策略 + +```typescript +// apps/parent-portal/src/app/(app)/parent/[route]/page.tsx +import dynamic from "next/dynamic"; + +const GradesPage = dynamic(() => import("./GradesPage"), { + loading: () => , + ssr: false, // MF Remote 默认 CSR +}); + +const NotificationsPage = dynamic(() => import("./NotificationsPage"), { + loading: () => , +}); + +// 通知偏好表单（重型：react-hook-form + zod）独立 chunk +const PreferencesPage = dynamic(() => import("./PreferencesPage"), { + loading: () => , +}); +``` + +### 14.3 预加载策略 + +| 触发时机 | 预加载内容 | +| ------------------------- | ----------------------------------------------------- | +| Dashboard 加载完成 | 预加载 grades chunk + homework chunk（最常访问） | +| 鼠标 hover Tab 栏子女头像 | 预加载该子女的 grades 数据（TanStack Query prefetch） | +| 通知未读数 > 0 | 预加载 notifications chunk | +| 用户进入 grades 页面 | 预加载 analytics chunk（趋势图 next-step） | + +### 14.4 渲染策略 + +| 页面 | 渲染模式 | 理由 | +| ----------------------- | ------------------------ | ---------------------- | +| `/parent/dashboard` | SSR（首屏）+ CSR（交互） | SEO + 首屏速度 | +| `/parent/children` | CSR | 认证后数据，无需 SEO | +| `/parent/grades` | CSR + Suspense | 数据频变，SSR 反而拖慢 | +| `/parent/notifications` | CSR + 流式渲染 | 实时性要求 | +| `/parent/preferences` | CSR | 表单交互 | + +--- + +## 15. 前端安全 + +> ai07 初稿仅在横切关注点提到 401 处理。ai15 补全完整前端安全策略。 + +### 15.1 安全头（HTTP Headers） + +由 teacher-portal Shell 在 `next.config.js` 配置，parent-portal 复用： + +| Header | 值 | 用途 | +| --------------------------- | ------------------------------------------------------------ | ------------------------------------ | +| `Content-Security-Policy` | `default-src 'self'; script-src 'self' 'unsafe-inline'; ...` | XSS 防护，MF 远程加载需放行 Shell 域 | +| `X-Frame-Options` | `SAMEORIGIN` | 防止 click-jacking | +| `X-Content-Type-Options` | `nosniff` | 防止 MIME 嗅探 | +| `Referrer-Policy` | `strict-origin-when-cross-origin` | 限制 referrer 泄漏 | +| `Permissions-Policy` | `camera=(), microphone=(), geolocation=()` | 禁用不需要的浏览器能力 | +| `Strict-Transport-Security` | `max-age=31536000; includeSubDomains` | 强制 HTTPS | + +### 15.2 XSS 防护 + +| 场景 | 防护措施 | +| ------------------------ | ---------------------------------------------- | +| 子女姓名/学校名称展示 | React 默认转义，禁止 `dangerouslySetInnerHTML` | +| 通知内容（含富文本） | DOMPurify 清洗后渲染（project_rules §4） | +| URL 参数 `?childId=` | Zod 校验为 UUID 格式，禁止任意字符 | +| localStorage 存储子女 ID | 仅存 UUID，不存敏感信息；用户登出时清除 | + +### 15.3 CSRF 防护 + +- parent-portal 仅消费 GET/POST/PUT/DELETE，所有 mutation 经 ApiClient +- ApiClient 自动注入 `X-Requested-With: XMLHttpRequest` 头 +- 后端 BFF 校验该头 + 同源 Cookie SameSite=Strict（project_rules §4） + +### 15.4 敏感数据处理 + +| 数据 | 敏感级别 | 前端处理 | +| -------------- | -------- | -------------------------------------------------- | +| 子女姓名 | 中 | 默认展示，截图时脱敏（P5+） | +| 子女成绩 | 高 | 默认展示，但页面离开 5s 后自动遮罩（防偷窥） | +| 子女出勤 | 中 | 同姓名 | +| 监护人联系方式 | 高 | 仅在 preferences 页面展示，掩码显示（138****1234） | +| 子女 ID | 低 | URL 可携带，但 BFF 校验绑定关系 | +| 通知内容 | 中 | 不缓存到 localStorage，仅 TanStack Query 内存缓存 | + +--- + +## 16. 跨标签与跨设备同步 + +### 16.1 同步机制矩阵 + +| 场景 | 同步机制 | 同步内容 | 冲突解决 | +| ----------------------- | ------------------------------- | ----------------------------------------- | ------------------- | +| 同浏览器多标签状态同步 | BroadcastChannel API | currentChildId、notification unread count | 最后写入胜出（LWW） | +| localStorage 跨标签变更 | `storage` 事件 | currentChildId 持久化值 | 最后写入胜出 | +| 跨设备状态同步 | WebSocket 事件（P5） | 通知偏好变更、子女关系变更 | 服务端为准 | +| 网络恢复后状态对齐 | 重连后批量 invalidate + refetch | 全部子女维度数据 | 服务端为准 | + +### 16.2 BroadcastChannel 实现 + +```typescript +// apps/parent-portal/src/lib/crossTabSync.ts +const channel = new BroadcastChannel("parent-child-switch"); + +// 发送：当前标签切换子女 +export function broadcastChildSwitch(childId: string) { + channel.postMessage({ type: "child-switched", childId, ts: Date.now() }); +} + +// 接收：其他标签同步切换 +export function subscribeChildSwitch(callback: (childId: string) => void) { + channel.onmessage = (event) => { + if (event.data?.type === "child-switched") { + callback(event.data.childId); + } + }; + return () => { + channel.onmessage = null; + }; +} +``` + +### 16.3 跨标签选中子女冲突处理 + +若 Tab A 在 10:00:00 切换到 child-1，Tab B 在 10:00:01 切换到 child-2： + +- 两个 Tab 都收到对方的 BroadcastChannel 消息 +- 采用 LWW：以 `ts` 字段为依据，ts 大的胜出 +- 胜出方写入 Zustand slice + localStorage +- 败方 UI 自动同步到胜出方的选中子女 +- 用户感知：可能看到一瞬间的切换抖动，可接受 + +--- + +## 17. i18n 深化 + +> ai07 初稿仅提到 next-intl。ai15 补全多语言策略。 + +### 17.1 支持语言矩阵 + +| 语言 | locale | 阶段 | 完成度要求 | +| --------------- | ------ | ----------- | ---------- | +| 简体中文 | zh-CN | P4 强制 | 100% | +| 英文 | en-US | P6 海外扩展 | 100% | +| 繁体中文 | zh-TW | P6 海外扩展 | 100% | +| 日文 | ja-JP | P6+ 未来 | ≥ 80% | +| 阿拉伯文（RTL） | ar-SA | P6+ 未来 | ≥ 80% | + +### 17.2 locale 路由策略 + +**采用 URL 前缀策略**（与 Shell 共享，由 Shell 配置）： + +``` +/zh-CN/parent/dashboard +/en-US/parent/dashboard +/parent/dashboard → 默认重定向到浏览器首选语言 +``` + +- Next.js 中间件根据 `Accept-Language` 头自动重定向 +- 用户主动切换语言时写入 Cookie `NEXT_LOCALE`，下次访问直接命中 +- parent-portal 不维护 locale 路由，复用 Shell 中间件 + +### 17.3 翻译文件组织 + +``` +apps/parent-portal/src/i18n/messages/ +├─ zh-CN/ +│ ├─ common.json # 通用文案（确认/取消/加载中等） +│ ├─ dashboard.json +│ ├─ children.json +│ ├─ grades.json +│ ├─ homework.json +│ ├─ notifications.json +│ ├─ preferences.json +│ └─ errors.json # 错误码 → i18n key 映射 +├─ en-US/ +│ └─ ... (镜像 zh-CN 结构) +└─ index.ts # 按需加载 messages +``` + +按路由切分 message bundle，避免首屏加载全部翻译。 + +### 17.4 国际化格式 + +| 数据类型 | 库 | 示例（zh-CN） | 示例（en-US） | +| -------- | ------------------------------------- | --------------------- | ------------------- | +| 日期 | `Intl.DateTimeFormat` | 2026年7月9日 | July 9, 2026 | +| 时间 | 同上 | 下午3:30 | 3:30 PM | +| 数字 | `Intl.NumberFormat` | 1,234.56 | 1,234.56 | +| 百分比 | 同上 | 85.5% | 85.5% | +| 货币 | 同上 | ¥1,234.50 | $1,234.50 | +| 成绩等级 | 自定义映射表 | 优秀/良好/及格/不及格 | A/B/C/D/F | +| 时区 | `Intl.DateTimeFormat` with `timeZone` | Asia/Shanghai | America/Los_Angeles | + +### 17.5 RTL 支持（P6+ 预留） + +- Tailwind CSS logical properties：`ms-*`/`me-*`/`ps-*`/`pe-*` 替代 `ml-*`/`mr-*`/`pl-*`/`pr-*` +- 设计令牌预留 RTL 语义令牌：`--space-inline-start` / `--space-inline-end` +- 图标方向敏感（如返回箭头）需根据 `dir` 属性翻转 + +--- + +## 18. 移动端与 PWA + +> 家长端是 4 端中移动端使用比例最高的（家长多在通勤/碎片时间查看），移动端策略必须前置。 + +### 18.1 响应式断点 + +| 断点 | 宽度 | 典型设备 | parent-portal 布局变化 | +| -------------- | ----------- | ---------------------- | --------------------------------------------------- | +| `sm` (default) | < 640px | iPhone/Android 手机 | 单列布局；MultiChildTabBar 改为下拉；侧栏导航抽屉化 | +| `md` | 640-1024px | iPad Mini/Android 平板 | 双列布局（侧栏 + 内容）；MultiChildTabBar 顶部 Tab | +| `lg` | 1024-1280px | iPad Pro/小笔记本 | 三列布局（侧栏 + 内容 + 详情）；多子女并列卡片 | +| `xl` | > 1280px | 桌面 | 三列布局；多子女对比视图横向滚动 | + +### 18.2 移动端交互优化 + +| 场景 | 移动端优化 | +| ------------ | ------------------------------------------ | +| 切换子女 | 下拉选择器 + 头像 + 姓名，单手操作可达 | +| 查看成绩 | 卡片式纵向滚动，避免横向表格；图表触摸缩放 | +| 通知列表 | 左滑标记已读、右滑删除（iOS 风格） | +| 通知偏好设置 | 大号 Toggle Switch，手指点击友好 | +| 表单提交 | 底部固定按钮；软键盘弹出时自动避让 | +| 长列表 | 无限滚动 + 骨架屏；不上拉加载更多按钮 | + +### 18.3 PWA 配置（P5+ 引入） + +```json +// apps/parent-portal/public/manifest.json +{ + "name": "Edu 家长端", + "short_name": "EduParent", + "start_url": "/parent/dashboard", + "display": "standalone", + "orientation": "portrait", + "background_color": "#ffffff", + "theme_color": "#1677ff", + "icons": [ + { "src": "/icons/parent-192.png", "sizes": "192x192", "type": "image/png" }, + { "src": "/icons/parent-512.png", "sizes": "512x512", "type": "image/png" } + ], + "shortcuts": [ + { "name": "子女成绩", "url": "/parent/grades" }, + { "name": "通知", "url": "/parent/notifications" } + ] +} +``` + +### 18.4 Service Worker 策略（P5+） + +| 资源类型 | 缓存策略 | TTL | +| ----------------------- | --------------------------- | ------- | +| 静态资源（JS/CSS/图片） | Cache First + 网络更新 | 24 小时 | +| 子女列表 | Stale While Revalidate | 5 分钟 | +| 子女成绩 | Network First，失败回退缓存 | 30 秒 | +| 通知列表 | Network Only | — | +| 通知偏好 | Network Only | — | +| API 401 响应 | 不缓存 | — | + +--- + +## 19. 长远愿景与演进路径 + +### 19.1 阶段演进路线 + +```mermaid +graph LR + P4[P4 内容分析
家长端 MVP
dashboard+grades+homework] --> P5[P5 沟通AI
通知中心+推送+通知偏好] + P5 --> P6[P6 硬化
PWA+A11y+性能+安全+多语言] + P6 --> P7[P7+ 扩展
家校沟通+缴费+活动 RSVP] + P7 --> P8[P8+ 多租户
学区/教育局版] +``` + +### 19.2 未来功能铺垫（架构预留） + +| 未来功能 | 架构预留点 | 启用阶段 | +| -------------------------- | ------------------------------------------------------------------------------ | -------- | +| 家校沟通（IM 聊天） | `NotificationFeed` 组件抽象为通用消息流；WebSocket 事件协议预留 `chat.*` 类型 | P7 | +| 缴费（学费/餐费） | `ParentDashboard` 卡片插槽；API 路由前缀 `/parent/fees/*` 预留 | P7 | +| 活动 RSVP（家长会/运动会） | `NotificationFeed` 支持 `rsvp` 类型消息；状态机：待回复/已确认/已拒绝 | P7 | +| 家长端 AI 助手 | API 路由 `/parent/ai/*` 预留；SSE 复用 teacher-portal 模式 | P7+ | +| 多子女横向对比报告 | `ChildComparisonView` 组件预留（P5+ 启用） | P5+ | +| 学区/教育局版多租户 | URL 路由前缀 `/{tenantId}/parent/*` 预留； TanStack Query key 加 tenantId 维度 | P8+ | +| 移动端原生壳 | PWA → Capacitor 打包；MF 不变 | P8+ | +| 离线模式 | Service Worker + IDB 队列（P5+ 引入） | P5+ | +| 推送通知（Web Push） | Service Worker PushManager + VAPID（P5+ 引入） | P5+ | + +### 19.3 模块解耦与演化 + +| 演化方向 | 触发条件 | 迁移策略 | +| ------------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------- | +| parent-portal 拆分为多个 Remote | bundle > 200KB 或团队规模 > 5 人 | 按场景域拆分：parent-core-remote（dashboard/grades）+ parent-comm-remote（notifications/preferences） | +| MF 2.0 → 3.0 升级 | MF 3.0 稳定且解决 SSR 问题 | Shell 端 `@module-federation/nextjs-mf` 升级；parent-portal 仅改 `name`/`filename` 字段 | +| 切换为原生 SSR（脱离 MF） | SEO 需求强烈或 MF 维护成本过高 | 保留 API 请求层和组件库；移除 MF 配置；独立部署为完整 Next.js 应用 | +| 状态管理迁移（Zustand → Jotai） | Zustand 性能瓶颈或团队偏好 | 逐 slice 迁移；Hook 接口保持不变 | + +### 19.4 监控与降级 + +| 监控项 | 阈值 | 触发动作 | +| ------------------------ | --------------- | ------------------------------------------------------ | +| parent-portal 5xx 错误率 | > 1% | 告警 SRE；自动切换到只读模式（隐藏 mutation 按钮） | +| MF Remote 加载失败 | 加载超时 10s | Fallback 到 Shell 内置的最小化 dashboard（静态引导页） | +| WebSocket 连接失败 | 重试 5 次仍失败 | 降级为 HTTP 轮询（每 60s 拉取通知列表） | +| BFF 响应延迟 | P95 > 3s | 前端展示"加载缓慢"提示；自动缩短缓存 TTL | +| 子女列表加载失败 | 3 次重试失败 | 显示"网络异常，请稍后重试"页面 + 重试按钮 | + +--- + +**AI Agent**: ai15 (parent-portal remote) +**Branch**: docs/parent-portal-stage1-stage2-design-ai15 +**Coordinator**: coord-ai +**Predecessor**: ai07（初版起草，ai15 接管审计与补全） diff --git a/apps/parent-portal/docs/02-architecture-design.md b/apps/parent-portal/docs/02-architecture-design.md index ae64fd4..0a24b71 100644 --- a/apps/parent-portal/docs/02-architecture-design.md +++ b/apps/parent-portal/docs/02-architecture-design.md @@ -1,11 +1,20 @@ # 模块架构设计文档 — parent-portal -> AI：ai07（TS/React · 家长场景域前端 remote） -> 阶段：阶段 2 交付物 -> 日期：2026-07-09 -> 关联：[阶段 1 理解确认书](./01-understanding.md)、[004 架构影响地图](../../../docs/architecture/004_architecture_impact_map.md) §5.4、[pending-features P4](../../../docs/architecture/roadmap/pending-features.md)、[teacher-portal 阶段2](../../teacher-portal/docs/02-architecture-design.md) +> AI：ai15（TS/React · 家长场景域前端 remote） +> 阶段：阶段 2 交付物（v2 — ai15 接管审计与补全版） +> 初版日期：2026-07-09（ai07 起草） +> 审计日期：2026-07-09（ai15 修订：端口、所有权、长远架构遗漏补全） +> 关联：[阶段 1 理解确认书](./01-understanding.md)、[004 架构影响地图](../../../docs/architecture/004_architecture_impact_map.md) §5.4、[pending-features P4](../../../docs/architecture/roadmap/pending-features.md)、[teacher-portal 阶段2](../../teacher-portal/docs/02-architecture-design.md)、[parent-bff 阶段1](../../../services/parent-bff/docs/01-understanding.md) > 状态：待 coord 交叉审查 +> **审计修订摘要**（ai15 → ai07 初稿）： +> +> 1. **端口修订**：3002 → **4002**（004 §1.2 强制 4 端 4000-4003） +> 2. **MF 配置端口修订**：teacher/student/parent/admin URL 全部从 3000-3003 修订为 4000-4003 +> 3. **所有权修订**：ai07 → **ai15**（ai-allocation.md §3.2） +> 4. **遗漏补全**：通知偏好数据模型细化、详细组件设计图、跨标签同步实现、API 版本演进、未来扩展铺垫、监控降级、模块演化策略 +> 5. **新增章节**：§14 通知偏好数据模型细化、§15 详细组件设计、§16 跨标签同步实现、§17 API 契约版本管理、§18 监控与降级、§19 模块演化与解耦、§20 长远架构愿景 + --- ## 1. 模块内部分层图（简化版，Remote 角色） @@ -91,7 +100,7 @@ graph TB const NextFederationPlugin = require("@module-federation/nextjs-mf"); const remotes = (isServer) => ({ - teacher: `teacher_app@http://localhost:3000/_next/static/${isServer ? "ssr" : "chunks"}/remoteEntry.js`, + teacher: `teacher_app@http://localhost:4000/_next/static/${isServer ? "ssr" : "chunks"}/remoteEntry.js`, }); module.exports = { @@ -129,7 +138,11 @@ module.exports = { }; ``` -> Shell 端配置对称：`teacher-portal/next.config.js` 的 `remotes.parent = parent_app@http://localhost:3002/_next/static/${isServer ? "ssr" : "chunks"}/remoteEntry.js`（详见 [teacher-portal 阶段2 §1.2](../../teacher-portal/docs/02-architecture-design.md#12-mf-配置teacher-portalnextconfigjs)）。 +> **端口约束**（004 §1.2 + project memory 硬约束）：4 端 portal 必须在 4000-4003 范围内。teacher-portal=4000、student-portal=4001、parent-portal=4002、admin-portal=4003。 +> +> **Shell 端配置对称**：`teacher-portal/next.config.js` 的 `remotes.parent = parent_app@http://localhost:4002/_next/static/${isServer ? "ssr" : "chunks"}/remoteEntry.js`（详见 [teacher-portal 阶段2 §1.2](../../teacher-portal/docs/02-architecture-design.md#12-mf-配置teacher-portalnextconfigjs)）。**注意**：teacher-portal 阶段2 文档中 MF URL 用 3000-3003 是过时的，应同步修订为 4000-4003（**coord 交叉审查整改项 #1**）。 +> +> **MF 配置预留**（未来扩展）：当 parent-portal 拆分为多 Remote 时（见 §19），可在此处增加 `exposes` 子模块（如 `./comm-remote`），Shell 端 `remotes.parent_comm = ...`。 ## 2. 领域模型（前端视角） @@ -470,9 +483,9 @@ Next.js 无长连接（除 SSE/WS），无需特殊处理。WS 在 P5 由 push-g | 端 | dev 端口 | 生产端口 | 备注 | | ------------- | -------- | -------- | ------------- | -| parent-portal | 3002 | 3002 | Remote 子应用 | +| parent-portal | 4002 | 4002 | Remote 子应用 | -> 与 [full-stack-runbook](../../../docs/standards/full-stack-runbook.md) 端口矩阵对齐。 +> 与 [004 §1.2](../../../docs/architecture/004_architecture_impact_map.md#12-服务清单) 与 [full-stack-runbook](../../../docs/standards/full-stack-runbook.md) 端口矩阵对齐。**4 端 portal 强制 4000-4003 范围**（project memory 硬约束）。 ### 12.2 依赖的共享包（需 coord 建立） @@ -538,9 +551,705 @@ Next.js 无长连接（除 SSE/WS），无需特殊处理。WS 在 P5 由 push-g 1. Web Vitals + OTel browser SDK 接入 2. A11y WCAG 2.2 AA 审计 3. 性能优化（MF shared 单例验证、bundle 分析） +4. 多语言扩展（en-US/zh-TW） +5. PWA 接入（Service Worker + manifest） +6. 安全硬化（CSP/CORS/敏感数据脱敏） + +### P7+（扩展阶段，预留） + +1. 家校沟通（IM 聊天）— `NotificationFeed` 抽象为通用消息流 +2. 缴费（学费/餐费）— `ParentDashboard` 卡片插槽 +3. 活动 RSVP（家长会/运动会）— 通知支持 `rsvp` 类型 +4. 家长端 AI 助手 — SSE 复用 teacher-portal 模式 --- -**AI Agent**: ai07 (parent-portal remote) -**Branch**: docs/parent-portal-stage1-stage2-design-ai07 +## 14. 通知偏好数据模型细化（ai15 新增） + +> ai07 初稿仅提到 `PUT /parent/notification-preferences`，未细化数据模型。家长端通知偏好是核心场景之一，必须细化。 + +### 14.1 三维偏好矩阵 + +通知偏好按 **子女 × 事件类型 × 渠道** 三维组织： + +```typescript +interface NotificationPreferences { + parentId: string; + // 三维矩阵：children[eventType][channel] = enabled + preferences: Record< + string, // childId（"*" 表示全部子女） + Record< + NotificationEventType, // 事件类型 + Record // 渠道 → 是否启用 + > + >; + // 全局默认（覆盖三维矩阵的默认值） + defaults: Record< + NotificationEventType, + Partial> + >; + updatedAt: string; // ISO 8601 +} + +type NotificationEventType = + | "grade_recorded" // 成绩发布 + | "homework_graded" // 作业批改完成 + | "homework_assigned" // 作业布置 + | "exam_published" // 考试发布 + | "attendance_alert" // 出勤异常 + | "school_announcement" // 学校通知 + | "teacher_message" // 教师沟通（P7+） + | "fee_reminder" // 缴费提醒（P7+） + | "event_invitation"; // 活动邀请（P7+） + +type NotificationChannel = + | "in_app" // 站内信 + | "push" // App 推送（P5+ Web Push） + | "sms" // 短信（msg 服务支持时） + | "email" // 邮件 + | "wechat"; // 微信（msg 服务支持时） +``` + +### 14.2 默认值矩阵 + +| 事件类型 | in_app | push | sms | email | wechat | +| ------------------- | ------ | ----- | ----- | ----- | ------ | +| grade_recorded | true | true | false | true | false | +| homework_graded | true | true | false | false | false | +| homework_assigned | true | false | false | false | false | +| exam_published | true | true | false | true | false | +| attendance_alert | true | true | true | true | false | +| school_announcement | true | false | false | true | true | +| teacher_message | true | true | false | false | false | +| fee_reminder | true | true | true | true | true | +| event_invitation | true | true | false | true | false | + +### 14.3 表单交互设计 + +`PreferenceForm` 组件采用矩阵式 UI： + +- 横轴：渠道（in_app/push/sms/email/wechat） +- 纵轴：事件类型 +- 顶部：子女切换（默认 "*" 全部子女，可切到具体子女覆盖） +- 单元格：Toggle Switch +- 底部：保存按钮（sticky）+ 重置默认按钮 + +### 14.4 Zod 校验 schema + +```typescript +const NotificationPreferencesSchema = z.object({ + parentId: z.string().uuid(), + preferences: z.record( + z.string(), // childId 或 "*" + z.record( + z.enum([ + "grade_recorded", + "homework_graded", + "homework_assigned", + "exam_published", + "attendance_alert", + "school_announcement", + "teacher_message", + "fee_reminder", + "event_invitation", + ]), + z.object({ + in_app: z.boolean().default(true), + push: z.boolean().default(false), + sms: z.boolean().default(false), + email: z.boolean().default(false), + wechat: z.boolean().default(false), + }), + ), + ), + defaults: z.record( + z.string(), + z.object({ + in_app: z.boolean().optional(), + push: z.boolean().optional(), + sms: z.boolean().optional(), + email: z.boolean().optional(), + wechat: z.boolean().optional(), + }), + ), + updatedAt: z.string().datetime(), +}); +``` + +### 14.5 渠道可用性校验 + +前端在渲染 `PreferenceForm` 前，需根据 BFF 返回的 `availableChannels` 字段禁用不可用渠道： + +```typescript +// BFF 响应 +{ + "preferences": {...}, + "availableChannels": { + "sms": false, // msg 服务未配置短信网关 + "wechat": false, // msg 服务未配置微信公众号 + "email": true, + "push": false, // push-gateway P5 才上线 + "in_app": true + } +} +``` + +不可用渠道的 Toggle 显示为 disabled + tooltip "此渠道暂未开通"。 + +--- + +## 15. 详细组件设计（ai15 新增） + +> ai07 初稿仅列出组件名。ai15 补全关键组件的 Props 接口与状态机。 + +### 15.1 ChildSwitcher 组件 + +```typescript +interface ChildSwitcherProps { + variant: "tab" | "dropdown"; // 由 MultiChildTabBar 根据子女数自动选择 + size: "sm" | "md" | "lg"; + showAvatar: boolean; + onChange?: (childId: string) => void; // 不传则使用内置 Zustand slice + className?: string; +} + +// 内部状态机 +type ChildSwitcherState = + | { status: "idle" } + | { status: "switching"; fromChildId: string; toChildId: string } + | { status: "switched"; childId: string } + | { status: "error"; error: ApiError }; +``` + +### 15.2 ParentDashboard 组件 + +```typescript +interface ParentDashboardProps { + // 不接受 props，全部数据来自 TanStack Query hooks + // 内部组合：useChildren() + useChildGrades(currentChildId) + useChildAnalytics(currentChildId) +} + +type ParentDashboardSlot = + | "summary-cards" // ChildSummaryCard 列表 + | "todo-reminders" // 待办提醒（未读作业、未确认通知） + | "recent-grades" // 近期成绩曲线 + | "attendance" // 出勤概览 + | "custom"; // 自定义插槽（P7+ 缴费/活动） +``` + +### 15.3 NotificationFeed 组件 + +```typescript +interface NotificationFeedProps { + filter?: { + childId?: string; // 按子女筛选 + eventType?: NotificationEventType[]; + unreadOnly?: boolean; + }; + sort?: "desc" | "asc"; + pageSize?: number; // 默认 20 + onNotificationClick?: (notification: Notification) => void; + onMarkAllRead?: () => void; +} + +type Notification = { + id: string; + childId: string | null; + eventType: NotificationEventType; + title: string; // i18n key + body: string; // i18n key + 参数 + read: boolean; + createdAt: string; + actionUrl?: string; // 点击跳转 + pinned?: boolean; +}; +``` + +### 15.4 PreferenceForm 组件 + +```typescript +interface PreferenceFormProps { + initialPreferences: NotificationPreferences; + availableChannels: Record; + onSubmit: (prefs: NotificationPreferences) => Promise; + onReset?: () => void; +} + +// 表单状态机 +type PreferenceFormState = + | { status: "idle" } + | { status: "dirty"; changes: Partial } + | { status: "submitting" } + | { status: "submitted" } + | { status: "error"; error: ApiError }; +``` + +### 15.5 ChildGradeChart 组件 + +```typescript +interface ChildGradeChartProps { + childId: string; + examIds?: string[]; // 不传则展示全部 + compareWithClass: boolean; // 是否叠加班级均分对比 + compareWithChildren?: string[]; // 多子女对比模式 + height?: number; + showLegend: boolean; +} + +type GradeDataPoint = { + examId: string; + examName: string; + examDate: string; + studentScore: number; + classAverage?: number; + classMax?: number; + classMin?: number; + gradeLevel: "A" | "B" | "C" | "D" | "F"; +}; +``` + +### 15.6 组件依赖关系图 + +```mermaid +graph TB + App[ParentApp Root] --> AppShell + App --> Router[Next.js Router] + Router --> DashboardPage + Router --> ChildrenPage + Router --> GradesPage + Router --> HomeworkPage + Router --> NotificationsPage + Router --> PreferencesPage + + DashboardPage --> ParentDashboard + ParentDashboard --> MultiChildTabBar + ParentDashboard --> ChildSummaryCard + ParentDashboard --> ChildGradeChart + ParentDashboard --> AttendanceCalendar + + GradesPage --> MultiChildTabBar + GradesPage --> ChildGradeChart + + NotificationsPage --> NotificationFeed + NotificationFeed --> FilterBar + + PreferencesPage --> PreferenceForm + + MultiChildTabBar --> ChildSwitcher + ChildSwitcher --> useChildSwitcher + useChildSwitcher --> ApiClient + useChildSwitcher --> ZustandStore[childSwitcherSlice] + useChildSwitcher --> TanStackQuery[parent, children] +``` + +--- + +## 16. 跨标签同步实现（ai15 新增） + +### 16.1 同步架构图 + +```mermaid +graph LR + subgraph TabA["Tab A（活跃）"] + UserAction[用户切换子女] + ZustandA[Zustand slice] + LSA[localStorage] + BCA[BroadcastChannel] + end + + subgraph TabB["Tab B（后台）"] + BCB[BroadcastChannel] + ZustandB[Zustand slice] + LSB[localStorage] + QueryB[TanStack Query cache] + end + + UserAction --> ZustandA + ZustandA --> LSA + ZustandA --> BCA + BCA -->|postMessage| BCB + BCB --> ZustandB + ZustandB --> QueryB + QueryB -->|invalidate| QueryB2[重新拉取该子女数据] + + LSA -->|storage event| LSB + LSB --> ZustandB +``` + +### 16.2 完整实现 + +```typescript +// apps/parent-portal/src/lib/crossTabSync.ts +import { useEffect } from "react"; +import { useQueryClient } from "@tanstack/react-query"; +import { useChildSwitcherStore } from "../stores/childSwitcherSlice"; + +const CHANNEL_NAME = "parent-child-switch"; +const STORAGE_KEY = "parent:currentChildId"; + +type SyncMessage = { + type: "child-switched" | "child-unbound" | "preferences-updated"; + childId?: string; + ts: number; + source: string; // 唯一标识当前 tab，避免自己处理自己的消息 +}; + +// 每个 tab 生成唯一 source ID +const TAB_SOURCE = `tab-${Date.now()}-${Math.random().toString(36).slice(2)}`; + +export function useCrossTabSync() { + const queryClient = useQueryClient(); + const setCurrentChildId = useChildSwitcherStore((s) => s.setCurrentChildId); + + useEffect(() => { + const channel = new BroadcastChannel(CHANNEL_NAME); + + // 接收其他 tab 的消息 + channel.onmessage = (event: MessageEvent) => { + const msg = event.data; + if (!msg || msg.source === TAB_SOURCE) return; // 忽略自己的消息 + + switch (msg.type) { + case "child-switched": + if (msg.childId) { + setCurrentChildId(msg.childId); + // 不 invalidate，让其他 tab 的数据缓存继续生效 + // 只有用户主动切换时才 invalidate + } + break; + case "child-unbound": + // 子女被解绑，全部 tab 都要清理 + queryClient.invalidateQueries({ queryKey: ["parent", "children"] }); + if (msg.childId) { + queryClient.removeQueries({ + queryKey: ["parent", "grades", msg.childId], + }); + queryClient.removeQueries({ + queryKey: ["parent", "homework", msg.childId], + }); + } + break; + case "preferences-updated": + queryClient.invalidateQueries({ + queryKey: ["parent", "preferences"], + }); + break; + } + }; + + // 监听 localStorage 跨 tab 同步（BroadcastChannel 的补充） + const onStorage = (e: StorageEvent) => { + if (e.key === STORAGE_KEY && e.newValue) { + const newChildId = e.newValue; + const currentChildId = useChildSwitcherStore.getState().currentChildId; + if (newChildId !== currentChildId) { + setCurrentChildId(newChildId); + } + } + }; + window.addEventListener("storage", onStorage); + + return () => { + channel.close(); + window.removeEventListener("storage", onStorage); + }; + }, [queryClient, setCurrentChildId]); +} + +// 在切换子女时调用 +export function broadcastChildSwitch(childId: string) { + const channel = new BroadcastChannel(CHANNEL_NAME); + channel.postMessage({ + type: "child-switched", + childId, + ts: Date.now(), + source: TAB_SOURCE, + } satisfies SyncMessage); + channel.close(); +} + +// 在子女被解绑时调用（通常来自 WebSocket 事件） +export function broadcastChildUnbound(childId: string) { + const channel = new BroadcastChannel(CHANNEL_NAME); + channel.postMessage({ + type: "child-unbound", + childId, + ts: Date.now(), + source: TAB_SOURCE, + } satisfies SyncMessage); + channel.close(); +} + +// 在通知偏好更新后调用 +export function broadcastPreferencesUpdated() { + const channel = new BroadcastChannel(CHANNEL_NAME); + channel.postMessage({ + type: "preferences-updated", + ts: Date.now(), + source: TAB_SOURCE, + } satisfies SyncMessage); + channel.close(); +} +``` + +### 16.3 集成到 RootLayout + +```typescript +// apps/parent-portal/src/app/layout.tsx +"use client"; + +import { useCrossTabSync } from "../lib/crossTabSync"; + +export default function ParentPortalLayout({ + children, +}: { + children: React.ReactNode; +}) { + useCrossTabSync(); // 启用跨 tab 同步 + return <>{children}; +} +``` + +--- + +## 17. API 契约版本管理（ai15 新增） + +### 17.1 版本兼容矩阵 + +| API 版本 | 引入阶段 | 弃用阶段 | 移除阶段 | parent-portal 兼容性 | +| -------- | -------- | -------- | -------- | ----------------------------- | +| v1 | P4 | - | - | ✅ P4+ 必须支持 | +| v2 | P6+ | - | - | ⚠️ P6+ 通过 Feature Flag 切换 | +| 字段裁剪 | P5+ | - | - | ⚠️ 可选，移动端低带宽时启用 | + +### 17.2 ApiClient 版本协商 + +```typescript +// packages/shared-ts/src/api-client.ts（coord 维护，ai15 提需求） +class ApiClient { + private apiVersion: string = "v1"; + + // 通过响应头感知版本 + private captureVersion(response: Response) { + const version = response.headers.get("X-API-Version"); + if (version) { + this.apiVersion = version; + } + const deprecation = response.headers.get("Deprecation"); + if (deprecation === "true") { + const sunset = response.headers.get("Sunset"); + logger.warn("API deprecated", { + path: response.url, + sunset, + }); + // 上报埋点，跟踪使用率 + metrics.increment("api.deprecated_call", { + path: response.url, + }); + } + } + + // 切换主版本 + setVersion(version: "v1" | "v2") { + this.apiVersion = version; + } + + // 字段裁剪 + setFields(fields: string) { + this.defaultHeaders["X-Fields"] = fields; + } +} +``` + +### 17.3 字段裁剪使用场景 + +| 场景 | 裁剪策略 | 节省带宽 | +| -------------------------- | --------------------------------------------------------------- | -------- | +| 移动端 4G 网络查看子女列表 | `children[].id,children[].name,children[].avatar` | ~70% | +| 通知列表快速浏览 | `notifications[].id,notifications[].title,notifications[].read` | ~60% | +| Dashboard 概览 | `grades[].examName,grades[].studentScore` | ~50% | +| 完整成绩详情（默认） | 不裁剪 | 0% | + +--- + +## 18. 监控与降级（ai15 新增） + +### 18.1 前端监控指标 + +| 指标 | 类型 | 采集方式 | 告警阈值 | +| -------------------------------- | --------- | ------------------------- | ------------------ | +| `parent_portal_lcp_seconds` | LCP | `next/web-vitals` | P95 > 2.5s | +| `parent_portal_cls` | CLS | 同上 | P95 > 0.1 | +| `parent_portal_ttfb_seconds` | TTFB | 同上 | P95 > 0.8s | +| `parent_portal_mf_load_failed` | Counter | MF Remote 加载错误捕获 | > 1% | +| `parent_portal_api_error_rate` | Counter | ApiClient 错误拦截 | 5xx > 1% | +| `parent_portal_ws_reconnect` | Counter | WebSocket 重连计数 | 单用户 > 5 次/小时 | +| `parent_portal_child_switch_p99` | Histogram | ChildSwitcher 切换耗时 | P99 > 1s | +| `parent_portal_cache_hit_rate` | Gauge | TanStack Query 缓存命中率 | < 60%（异常） | +| `parent_portal_offline_duration` | Histogram | 网络中断时长 | P95 > 30s | +| `parent_portal_a11y_violations` | Counter | axe-core 自动扫描 | 严重违规 > 0 | + +### 18.2 降级策略矩阵 + +| 触发条件 | 降级动作 | 用户感知 | +| --------------------------------- | ----------------------------------------------------------- | ---------------------------- | +| MF Remote 加载失败（10s 超时） | 显示 Shell 内置的最小化静态引导页 | "家长端加载失败，请稍后重试" | +| BFF 5xx 错误率 > 5% | 隐藏 mutation 按钮（保存/切换）；展示只读模式 banner | 顶部黄色 banner："只读模式" | +| BFF P95 延迟 > 5s | 缩短缓存 TTL 至 5s；展示"加载缓慢"提示 | 顶部提示条 | +| WebSocket 连接失败 5 次 | 降级为 HTTP 轮询（60s 拉取通知列表） | 通知延迟最多 60s | +| 子女列表加载失败 3 次 | 显示错误页 + 重试按钮 + 客服联系方式 | 错误页 | +| i18n message 加载失败 | Fallback 到 key 本身作为文案（如 `parent.dashboard.title`） | 显示英文 key，不影响功能 | +| 设计令牌加载失败 | Fallback 到 Tailwind 默认色板 | 视觉风格降级，不影响功能 | +| BroadcastChannel 不支持（Safari） | 仅依赖 storage 事件 | 跨 tab 同步延迟 ~500ms | +| localStorage 满 | 清理最旧的缓存项；提示用户清理浏览器缓存 | 写入失败 toast | + +### 18.3 错误恢复流程 + +```mermaid +flowchart TD + Error[发生错误] --> Classify{错误类型} + Classify -->|Network| Retry[指数退避重试 3 次] + Classify -->|401 Unauthorized| Refresh[刷新 token] + Classify -->|403 Forbidden| Toast[toast 提示无权限] + Classify -->|404 Not Found| Empty[显示空态] + Classify -->|5xx Server Error| Fallback[降级策略] + Classify -->|MF Load Failed| ShellFallback[Shell 兜底页] + + Retry -->|成功| Recover[恢复正常] + Retry -->|失败| Fallback + + Refresh -->|成功| Recover + Refresh -->|失败| Logout[跳转登录页] + + Fallback --> ReadOnlyMode[只读模式] + Fallback --> CachedData[展示缓存数据] + Fallback --> ErrorPage[错误页 + 重试] + + Toast --> Continue[继续当前操作] + Empty --> Continue + ShellFallback --> RetryMF[10s 后重试 MF] + ReadOnlyMode --> WaitForRecover[等待 BFF 恢复] + WaitForRecover --> Recover +``` + +--- + +## 19. 模块演化与解耦（ai15 新增） + +### 19.1 拆分触发条件 + +| 触发条件 | 拆分方向 | 阶段 | +| --------------------------------------- | --------------------------------------------------------------- | ---- | +| parent-portal bundle > 200KB（gzipped） | 按场景域拆分为 `parent-core-remote` + `parent-comm-remote` | P7+ | +| 团队规模 > 5 人同时维护 parent-portal | 同上 | P7+ | +| 家校沟通功能复杂度提升 | 拆出 `parent-comm-remote`（IM + 通知中心） | P7+ | +| 缴费功能引入 | 拆出 `parent-finance-remote` | P7+ | +| 多租户支持 | URL 前缀 `/{tenantId}/parent/*`；TanStack Query key 加 tenantId | P8+ | + +### 19.2 拆分后的 MF 配置 + +```javascript +// 拆分后：parent-core-remote（核心场景） +new NextFederationPlugin({ + name: "parent_core_app", + filename: "static/chunks/remoteEntry.js", + exposes: { + "./pages": "./src/pages", // dashboard/grades/homework/children + "./ChildSwitcher": "./src/components/ChildSwitcher", + }, + // ... +}); + +// 拆分后：parent-comm-remote（沟通场景） +new NextFederationPlugin({ + name: "parent_comm_app", + filename: "static/chunks/remoteEntry.js", + exposes: { + "./pages": "./src/pages", // notifications/preferences/chat + "./NotificationFeed": "./src/components/NotificationFeed", + }, + // ... +}); +``` + +### 19.3 状态管理迁移路径 + +| 迁移场景 | 触发条件 | 迁移策略 | +| ------------------------ | ------------------ | -------------------------------------------------------------- | +| Zustand → Jotai | 性能瓶颈或团队偏好 | 逐 slice 迁移；Hook 接口保持不变；新旧 slice 共存 1 个迭代周期 | +| localStorage → IndexedDB | 数据量 > 5MB | 抽象存储层；Hook 接口不变；迁移期双写 + 校验一致性 | +| TanStack Query v5 → v6 | TanStack 发布 v6 | 跟随社区升级；Breaking Change 通过 codemod 自动迁移 | + +### 19.4 MF 升级路径 + +| 升级场景 | 触发条件 | 风险与缓解 | +| ------------------------ | ------------------------------ | ----------------------------------------------------------------------- | +| MF 2.0 → 3.0 | MF 3.0 稳定且解决 SSR 问题 | Shell 端升级；parent-portal 仅改 `name`/`filename`；CI 验证 shared 单例 | +| MF → 原生 SSR（脱离 MF） | SEO 需求强烈或 MF 维护成本过高 | 保留 API 请求层和组件库；移除 MF 配置；独立部署为完整 Next.js 应用 | +| Next.js 14 → 15 | Next.js 15 稳定 | 跟随 Shell 升级；App Router API 兼容性验证 | +| React 18 → 19 | React 19 稳定 | 跟随 Shell 升级；use hook / Suspense 改进可简化 TanStack Query 集成 | + +--- + +## 20. 长远架构愿景（ai15 新增） + +### 20.1 三年架构演进路线 + +```mermaid +graph LR + Y1[Year 1
P4-P6 单体 Remote
MF 2.0] --> Y2[Year 2
P7+ 多 Remote 拆分
家校沟通+缴费+活动] + Y2 --> Y3[Year 3
P8+ 多租户+多区域
MF 3.0 / 原生 SSR] +``` + +### 20.2 架构原则（始终不变） + +1. **Remote 角色不变**：parent-portal 始终作为 teacher-portal Shell 的 Remote，不独立 Shell +2. **契约先行**：所有 API 变更先 proto/contracts，后实现 +3. **无状态前端**：所有持久化状态走 localStorage/IDB，不依赖服务端 session +4. **复用优先**：组件/Hook/工具优先复用 Shell 暴露的，避免重复实现 +5. **可降级**：任何依赖（BFF/WebSocket/Shell）故障都有降级方案 +6. **可观测**：所有用户行为、错误、性能指标都可观测 +7. **可测试**：所有组件/Hook/页面都有单测 + E2E 覆盖 +8. **可演化**：模块可拆分、状态管理可迁移、框架可升级 + +### 20.3 与其他 portal 的协同演化 + +| 演化方向 | parent-portal 角色 | 协同端 | +| -------------------------------------- | ------------------------------------ | ------------------------------------ | +| 共享组件抽取到 packages/ | 消费方（不再在 Remote 内自建组件） | teacher-portal（Shell）+ 其他 Remote | +| 共享 Hook 抽取到 packages/hooks/ | 消费方 | 同上 | +| 共享业务模型抽取到 packages/contracts/ | 消费方（类型定义） | 同上 | +| 多 portal 间通信（如教师↔家长） | 通过后端 BFF/gRPC，不直连其他 Remote | teacher-portal / student-portal | +| 跨 portal 路由跳转 | 通过 Shell 统一路由表 | 所有 portal | + +### 20.4 与后端架构的协同演化 + +| 后端演化 | parent-portal 适配 | +| ------------------------------ | ----------------------------------------------- | +| BFF REST → GraphQL | 引入 urql/apollo client；保持 ApiClient 接口 | +| BFF → BFF + 微前端 API Gateway | parent-portal 不感知；ApiClient baseUrl 不变 | +| 引入 Service Mesh（Istio） | parent-portal 不感知；网络层透明 | +| 引入 Feature Flag 服务 | 集成 FeatureFlagProvider；组件按 flag 渲染 | +| 引入 A/B Testing 平台 | 集成 ABTestProvider；UI 按 variant 渲染 | +| 后端多租户 | URL 加 `/{tenantId}/parent/*`；Query key 加维度 | +| 后端多区域 | ApiClient 按 region 路由；CDN 边缘缓存 | + +### 20.5 关键技术债务预警 + +| 债务项 | 当前状态 | 紧急度 | 清理建议 | +| ---------------------------------------- | ---------- | ------ | --------------------------------------------- | +| ai07 初稿端口错误（3002 vs 4002） | ✅ 已修订 | 高 | coord 同步修订 teacher-portal docs | +| ai07 初稿所有权错误（ai07 vs ai15） | ✅ 已修订 | 高 | 004 §15 文档矩阵已记录 ai15 = parent-portal | +| MF SSR 对齐 | 待验证 | 中 | P4 启动前 PoC 验证 MF 2.0 SSR；若失败降级 CSR | +| iam 家长-学生关联接口缺失（P0 阻塞） | 待 ai02 补 | 高 | coord 协调 ai02 在 P3 收尾前补全 | +| shared-ts / contracts 未建立 | 待 coord | 高 | P4 启动前必须建立；否则 ai15 自行实现后续提取 | +| ui-tokens / ui-components / hooks 未建立 | 待 ai07 | 高 | P4 启动前必须建立；ai07 在 P2 收尾交付 | +| MF Remote 加载失败的兜底 | 待实现 | 中 | P4 实现期落地 Shell 内置兜底页 | +| 跨 tab 同步在 Safari 的兼容性 | 待验证 | 低 | P6 硬化期验证；降级为 storage 事件 | + +--- + +**AI Agent**: ai15 (parent-portal remote) +**Branch**: docs/parent-portal-stage1-stage2-design-ai15 **Coordinator**: coord-ai +**Predecessor**: ai07（初版起草，ai15 接管审计与补全）