xiner/Edu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(teacher-portal): ai07 阶段1+2 拆分到4端portal的docs目录

Browse Source 
删除合并版README，按portal拆分8份文档(每端01-understanding+02-architecture-design)

teacher-portal(shell/P2)+student-portal(remote/P3)+parent-portal(remote/P4)+admin-portal(remote/P6)

AI Agent: ai07 (4 portals)

Branch: docs/portals-stage1-stage2-design-ai07
This commit is contained in:
SpecialX
2026-07-09 18:23:27 +08:00
parent fd5b6e19ae
commit e691cd267d
9 changed files with 3457 additions and 945 deletions
Download Patch File Download Diff File Expand all files Collapse all files

546
apps/parent-portal/docs/02-architecture-design.md Normal file
View File

@@ -0,0 +1,546 @@
# 模块架构设计文档 — 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)
> 状态：待 coord 交叉审查
---
## 1. 模块内部分层图（简化版，Remote 角色）
```mermaid
graph TB
subgraph Browser["浏览器"]
URL[URL 路由]
end
subgraph Shell["teacher-portal（Shell 宿主）"]
AppShell[AppShell<br/>左栏导航 + 主内容区]
RootLayout[RootLayout<br/>字体/令牌/i18n Provider]
Router[Next.js App Router]
SharedDeps["共享依赖暴露<br/>react/react-dom/@tanstack/react-query/zustand/nuqs<br/>ui-components/ui-tokens/contracts/hooks/shared-ts"]
end
subgraph RemoteParent["parent-portal（Remote 模块）"]
ParentPages[家长场景页面<br/>dashboard/children/grades/homework/notifications/preferences]
ChildSwitcher["ChildSwitcher<br/>多子女切换 + Zustand slice"]
end
subgraph Shared["共享层（packages/）"]
UITokens[ui-tokens<br/>三层设计令牌]
UIComponents[ui-components<br/>shadcn + A11y + ErrorBoundary]
Contracts[contracts<br/>Permissions 常量 + 类型]
Hooks[hooks<br/>usePermission/useAuth/useA11y]
LibTS[shared-ts<br/>ApiClient/Logger/通用工具]
end
subgraph Gateway["api-gateway"]
GW[Gin 路由/鉴权/限流]
end
subgraph PushGW["push-gateway（P5）"]
WS[WebSocket Server]
end
Browser --> URL
URL --> RootLayout
RootLayout --> AppShell
AppShell --> Router
Router -->|动态加载 /parent/*| RemoteParent
RemoteParent --> SharedDeps
Shell --> UITokens
Shell --> UIComponents
Shell --> Contracts
Shell --> Hooks
RemoteParent --> UITokens
RemoteParent --> UIComponents
RemoteParent --> Contracts
RemoteParent --> Hooks
RemoteParent --> LibTS
AppShell -->|fetch /api/v1/iam/effective-permissions| Hooks
Hooks -->|透传 token| GW
RemoteParent -->|fetch /api/v1/parent/*| GW
RemoteParent -->|fetch /api/v1/iam/*| GW
RemoteParent -->|fetch /api/v1/notifications/*| GW
RemoteParent -.P5 WebSocket.-> WS
```
### 1.1 MF 拓扑选型
| 方案 | 选否 | 理由 |
| ----------------------------------------------------- | ---- | --------------------------------------------------------------------------------------------- |
| 4 端独立部署 + 独立域名 + 各自 Shell | ❌ | 4 套 Shell 重复，登录态/权限/组件库要重复实现 |
| 单 Shell + 4 Remote（**采用**，teacher-portal Shell） | ✅ | teacher-portal 作为 Shell 宿主，parent-portal 作为 Remote 动态加载，复用 Shell 的全部基础设施 |
| 单一 Next.js 应用 + 4 路由组 | ❌ | 违反"微前端独立部署"目标（ADR-012） |
**Remote 职责**（parent-portal）：
- 家长场景页面（dashboard / children / grades / homework / notifications / preferences）
- ChildSwitcher 多子女切换组件 + Zustand slice（L3 客户端业务状态）
- 不提供 RootLayout / 登录页 / 字体加载 / 令牌初始化（由 Shell 提供）
- 路由前缀 `/parent/*`
### 1.2 MF 配置（parent-portal/next.config.js，Remote 角色）
```javascript
// parent-portal/next.config.js（Remote）
const NextFederationPlugin = require("@module-federation/nextjs-mf");
const remotes = (isServer) => ({
teacher: `teacher_app@http://localhost:3000/_next/static/${isServer ? "ssr" : "chunks"}/remoteEntry.js`,
});
module.exports = {
reactStrictMode: true,
webpack(config, { isServer }) {
config.plugins.push(
new NextFederationPlugin({
name: "parent_app",
filename: "static/chunks/remoteEntry.js",
remotes: remotes(isServer),
exposes: {
"./pages": "./src/pages",
"./ChildSwitcher": "./src/components/ChildSwitcher",
},
shared: {
react: { singleton: true, requiredVersion: "^18.3.0" },
"react-dom": { singleton: true, requiredVersion: "^18.3.0" },
"@tanstack/react-query": { singleton: true },
zustand: { singleton: true },
nuqs: { singleton: true },
},
extraOptions: { exposePages: false },
}),
);
return config;
},
async rewrites() {
return [
{
source: "/api/v1/:path*",
destination: `${process.env.API_GATEWAY_URL || "http://localhost:8080"}/api/v1/:path*`,
},
];
},
};
```
> 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)）。
## 2. 领域模型（前端视角）
前端不持有业务聚合根，仅持有"视图模型"（ViewModel）和"会话状态"。
### 2.1 会话状态（Session） / 视口（Viewport） / 权限（Permission）
**与 teacher-portal 共享**，定义详见 [teacher-portal 阶段2 §2.1-2.3](../../teacher-portal/docs/02-architecture-design.md#21-会话状态session)。parent-portal 作为 Remote 复用 Shell 暴露的 Session/Viewport/Permission 类型与 Zustand slice：
- `Session`：Zustand sessionSlice（L3）+ localStorage 持久化 + TanStack Query 缓存 `['session']`（L2）
- `ViewportItem`：来源 `GET /api/v1/parent/viewports`（parent-bff 聚合 iam 视口配置），AppShell 按 `scope: 'parent'` 过滤渲染
- `PermissionState`：来源 `GET /api/v1/iam/effective-permissions`，前端 TanStack Query 缓存 5min
### 2.2 多子女状态（ChildSwitcher，家长端特有）
```typescript
interface ChildSwitcherState {
children: ChildInfo[]; // 当前家长关联的所有子女
currentChildId: string | null; // 当前选中的子女 ID
isLoading: boolean; // 加载状态
error: string | null; // 错误信息
switchChild: (childId: string) => Promise<void>; // 切换子女
refreshChildren: () => Promise<void>; // 刷新子女列表
}
interface ChildInfo {
id: string; // 子女 user_id
name: string; // 子女姓名
avatar?: string; // 头像 URL
grade: string; // 年级（i18n key）
schoolName: string; // 学校名称
classId: string; // 班级 ID
}
```
存储：Zustand childSwitcherSlice（L3）+ localStorage 持久化 `currentChildId`（刷新恢复）+ TanStack Query 缓存 `['parent', 'children']`（L2）。
**切换行为**：调用 `POST /api/v1/parent/switch-child` 成功后，invalidate 所有 `['parent', 'children', currentChildId]` 前缀的查询（成绩、作业、学情等子女维度数据）。
## 3. 数据模型（前端）
前端无数据库，仅有缓存层：
| 数据类型 | 存储 | TTL | 失效策略 |
| ---------------------------- | ----------------------------------------- | --------------------------- | ------------------------------------------ |
| Session（token + user） | localStorage + Zustand（Shell 共享） | access 15min / refresh 7day | 401 自动 refresh，refresh 失败跳登录 |
| 权限列表 | TanStack Query cache（Shell 共享） | 5min | 角色变更事件 invalidate |
| 视口列表 | TanStack Query cache | 5min | 同上 |
| 子女列表 | TanStack Query cache + Zustand slice | 5min | staleTime 5min，切换子女不 invalidate 列表 |
| 当前选中子女 ID | localStorage + Zustand childSwitcherSlice | — | 永久（刷新恢复） |
| 子女成绩列表 | TanStack Query cache | 30s | **子女切换 invalidate** + 30s staleTime |
| 子女作业列表 | TanStack Query cache | 30s | **子女切换 invalidate** + 30s staleTime |
| 子女学情宽表 | TanStack Query cache | 30s | **子女切换 invalidate** + 30s staleTime |
| 通知偏好 | TanStack Query cache | 5min | mutation 后 invalidate |
| 通知列表（P5） | TanStack Query cache | 30s | WebSocket 推送 invalidate |
| URL 状态（分页/筛选/子女ID） | nuqs | — | 永久（可分享） |
| 表单临时态（通知偏好设置） | react-hook-form | — | 卸载即销毁 |
### 3.1 子女切换 invalidate 策略
```typescript
// packages/hooks/src/useChildSwitcher.ts（ai07 维护）
const useChildSwitcher = () => {
const queryClient = useQueryClient();
const switchChild = async (childId: string) => {
await api.post("/api/v1/parent/switch-child", { childId });
// 更新 Zustand slice
useChildSwitcherStore.getState().setCurrentChildId(childId);
// invalidate 所有子女维度数据
queryClient.invalidateQueries({ queryKey: ["parent", "children"] }); // 排除列表本身
queryClient.invalidateQueries({ queryKey: ["parent", "grades"] });
queryClient.invalidateQueries({ queryKey: ["parent", "homework"] });
queryClient.invalidateQueries({ queryKey: ["parent", "analytics"] });
};
return { switchChild, ...useChildSwitcherStore() };
};
```
## 4. API 设计（前端 → 后端）
前端不设计后端 API，仅声明消费的端点。详见 [01-understanding.md §3.1](./01-understanding.md#31-消费的后端-api经-api-gateway-代理)。
### 4.1 统一 API 请求层
**复用 Shell 暴露的 ApiClient**，定义详见 [teacher-portal 阶段2 §4.1](../../teacher-portal/docs/02-architecture-design.md#41-统一-api-请求层lib-apits)。parent-portal 通过 MF `shared` 单例获取 ApiClient 实例：
```typescript
// parent-portal/src/lib/api.ts
import { useApi } from "teacher/hooks"; // 从 Shell 暴露的 hooks 包获取
export const useParentApi = () => {
const api = useApi(); // Shell 暴露的 ApiClient 单例
return {
getViewports: () => api.get("/api/v1/parent/viewports"),
getChildren: () => api.get("/api/v1/parent/children"),
switchChild: (childId: string) =>
api.post("/api/v1/parent/switch-child", { childId }),
getNotifications: (params?: Record<string, string>) =>
api.get("/api/v1/parent/notifications", params),
updateNotificationPreferences: (prefs: unknown) =>
api.put("/api/v1/parent/notification-preferences", prefs),
getChildGrades: (childId: string) =>
api.get(`/api/v1/parent/children/${childId}/grades`),
getChildHomework: (childId: string) =>
api.get(`/api/v1/parent/children/${childId}/homework`),
getChildAnalytics: (childId: string) =>
api.get(`/api/v1/parent/children/${childId}/analytics`),
};
};
```
### 4.2 TanStack Query 约定
```typescript
// Query Key 命名：[scope, resource, ...args]
queryKey: ["parent", "children"]; // 子女列表
queryKey: ["parent", "grades", currentChildId]; // 子女成绩（含子女 ID 维度）
queryKey: ["parent", "homework", currentChildId]; // 子女作业
queryKey: ["parent", "analytics", currentChildId]; // 子女学情
queryKey: ["parent", "notifications"]; // 通知列表
queryKey: ["parent", "preferences"]; // 通知偏好
queryKey: ["session", "viewports", "parent"]; // 家长端视口
// Mutation 约定
const switchChildMutation = useMutation({
mutationFn: (childId: string) =>
api.post("/api/v1/parent/switch-child", { childId }),
onSuccess: (_, childId) => {
useChildSwitcherStore.getState().setCurrentChildId(childId);
queryClient.invalidateQueries({ queryKey: ["parent", "grades"] });
queryClient.invalidateQueries({ queryKey: ["parent", "homework"] });
queryClient.invalidateQueries({ queryKey: ["parent", "analytics"] });
},
});
const updatePreferencesMutation = useMutation({
mutationFn: (prefs) =>
api.put("/api/v1/parent/notification-preferences", prefs),
onSuccess: () =>
queryClient.invalidateQueries({ queryKey: ["parent", "preferences"] }),
onError: (e: ApiError) => toast.error(e.message),
});
```
## 5. 事件设计
前端不发布 Kafka 事件，仅消费 WebSocket 推送（P5）。
### 5.1 WebSocket 推送（P5）
| 事件 | 触发 | parent-portal 前端动作 |
| ----------------------- | ---------------- | ------------------------------- |
| `NotificationRequested` | msg 服务投递 | toast 提示 + 通知中心未读数 +1 |
| `GradeRecorded` | 教师录入子女成绩 | toast + 子女成绩列表 invalidate |
| `SchoolAnnouncement` | 学校通知 | toast + dashboard invalidate |
> WebSocket 连接由 Shell 建立（统一连接管理），parent-portal 通过 Zustand ui-store 订阅事件流。事件路由按 `event.type` 分发到对应 Remote 的 handler。
## 6. 横切关注点对齐清单
### 6.1 权限（前端等价）
| 路由 | requiredPermission |
| ----------------------- | --------------------------- |
| `/parent/dashboard` | `PARENT_DASHBOARD_VIEW` |
| `/parent/children` | `PARENT_CHILDREN_VIEW` |
| `/parent/grades` | `GRADES_READ_CHILD` |
| `/parent/homework` | `HOMEWORK_READ_CHILD` |
| `/parent/notifications` | `NOTIFICATION_READ_OWN` |
| `/parent/preferences` | `PARENT_PREFERENCES_UPDATE` |
> 完整权限点常量集中在 `packages/contracts/src/permissions.ts`（待建立，coord 负责）。L3 组件级视口用 `<RequirePermission perm="PARENT_PREFERENCES_UPDATE"><Button>保存</Button></RequirePermission>`。
### 6.2 错误码清单（前端 i18n 路由）
| 前缀 | 来源服务 | i18n key 模式 |
| ------------- | ----------- | ------------------------- |
| `IAM_` | iam | `iam.error.{{code}}` |
| `CORE_EDU_` | core-edu | `coreEdu.error.{{code}}` |
| `GRADES_` | core-edu | `grades.error.{{code}}` |
| `HOMEWORK_` | core-edu | `homework.error.{{code}}` |
| `BFF_PARENT_` | parent-bff | `bff.error.{{code}}` |
| `GW_` | api-gateway | `gateway.error.{{code}}` |
| `NETWORK_` | 前端网络层 | `network.error.{{code}}` |
### 6.3 Logger
```typescript
// 复用 packages/shared-ts/src/logger.ts（与 teacher-portal 共享）
// 实现：开发环境 console + 结构化；生产环境 → Sentry（P6）
// 必含字段：trace_id（从响应头提取）、user_id、scope=parent、path
```
### 6.4 Metrics（Web Vitals）
| 指标 | 类型 | 上报 |
| ---------------------------- | ---- | --------------------------------------------------- |
| `parent_portal_lcp_seconds` | LCP | `next/web-vitals` → `POST /api/v1/admin/web-vitals` |
| `parent_portal_cls` | CLS | 同上 |
| `parent_portal_fid_seconds` | FID | 同上 |
| `parent_portal_ttfb_seconds` | TTFB | 同上 |
P6 接入，P4-P5 暂缓。
### 6.5 Tracer（OTel browser SDK，P6）
```typescript
// 复用 packages/shared-ts/src/tracer.ts（与 teacher-portal 共享）
import { WebTracerProvider } from "@opentelemetry/sdk-trace-web";
// BatchSpanProcessor → OTLP exporter → collector → Tempo
// 自动埋点：fetch、XMLHttpRequest、document load、user interaction
// parent-portal 通过 MF shared 单例复用 Shell 的 TracerProvider
```
### 6.6 健康检查
| 端点 | 用途 | 实现 |
| ----------------- | ---------------------- | -------------------------------------------------------------- |
| `GET /api/health` | Dockerfile HEALTHCHECK | Next.js Route Handler，返回 `{ status: 'ok', ts: Date.now() }` |
| `GET /api/ready` | K8s readinessProbe | 检查 `process.env.API_GATEWAY_URL` 可达 + 内存 < 阈值 |
### 6.7 优雅关闭
Next.js 无长连接（除 SSE/WS），无需特殊处理。WS 在 P5 由 push-gateway 管理，前端断线自动重连。
## 7. 共享组件库（复用 Shell 暴露 + parent 特有）
### 7.1 复用 Shell 暴露的组件
| 组件 | 用途 | 来源 |
| ------------------------------------------ | ---------------------------------- | ------------------------- |
| `AppShell` | 左侧栏 + 主内容区布局 | teacher-portal Shell 暴露 |
| `RequirePermission` | L3 组件级视口控制 | teacher-portal Shell 暴露 |
| `ErrorBoundary` | React 渲染异常兜底（fallback UI） | teacher-portal Shell 暴露 |
| `Loading` | 骨架屏（Skeleton） | teacher-portal Shell 暴露 |
| `Empty` | 空态（插画 + 文案 + CTA） | teacher-portal Shell 暴露 |
| `Modal` / `Dialog` | 全局 Modal | teacher-portal Shell 暴露 |
| `Toast` | 全局 toast | teacher-portal Shell 暴露 |
| `Button` / `Input` / `Select` / `Textarea` | 基础表单 | teacher-portal Shell 暴露 |
| `DataTable` | 表格（排序/分页/筛选） | teacher-portal Shell 暴露 |
| `Chart` | 图表封装（recharts） | teacher-portal Shell 暴露 |
| `Form` | react-hook-form + zodResolver 封装 | teacher-portal Shell 暴露 |
| `A11y` 工具集 | useA11yId / mergeA11yProps 等 | teacher-portal Shell 暴露 |
### 7.2 parent-portal 特有组件
| 组件 | 用途 | 来源 |
| --------------- | ---------------------------------------------------------- | ---- |
| `ChildSwitcher` | 多子女切换组件（顶部 Tab），切换后 invalidate 子女相关查询 | 新建 |
> `ChildSwitcher` 通过 MF `exposes` 暴露给 Shell，但实际只在 parent-portal 路由内使用。组件内部封装：子女列表查询 + 切换 mutation + Zustand slice 同步 + invalidate 逻辑。
## 8. 共享 Hooks（复用 Shell 暴露 + parent 特有）
### 8.1 复用 Shell 暴露的 Hooks
| Hook | 职责 |
| --------------------- | --------------------------------------------------- |
| `useAuth()` | 会话状态（user/token/refresh/login/logout） |
| `usePermission()` | 权限查询（hasPermission/hasAny/hasAll + dataScope） |
| `useViewports(scope)` | 视口列表（按 scope 过滤） |
| `useApi()` | ApiClient 实例（注入 token + 401 处理） |
| `useA11yId()` | 唯一 ARIA ID 生成 |
| `useAriaLive()` | aria-live 区域管理 |
| `useToast()` | 全局 toast（Zustand ui-store） |
### 8.2 parent-portal 特有 Hook
| Hook | 职责 |
| -------------------- | --------------------------------------------------------- |
| `useChildSwitcher()` | 多子女切换（children/currentChildId/switchChild/refresh） |
## 9. 设计令牌三层（复用 packages/ui-tokens）
**与 teacher-portal 共享**，定义详见 [teacher-portal 阶段2 §9](../../teacher-portal/docs/02-architecture-design.md#9-设计令牌三层packagesui-tokens待建立ai07-维护)。parent-portal 通过 MF `shared` 单例复用 `packages/ui-tokens`，不在本应用内重复定义令牌。
**强制规则**（project_rules §3.10）：
- 禁止 `#hex` 字面量（ESLint `no-restricted-syntax`）
- 禁止 `'Inter'`/`'Fraunces'`/`'JetBrains Mono'` 字面量（ESLint `design-tokens/no-hardcoded-fonts`）
- 禁止 `font-size: Npx`（用 `var(--font-size-1~9)`）
- 禁止 Tailwind 任意值 `w-[Npx]`（用 `--space-*` 或默认阶梯）
## 10. 与其他模块的交互点（契约清单）
| 方向 | 对方服务 | 协议 | 接口/事件 | 用途 | 阶段 |
| ------ | ------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | ---- |
| 调用 | api-gateway | HTTP/REST | `/api/v1/*` 代理 | 全部业务请求 | P1+ |
| 调用 | push-gateway | WebSocket | `ws://push-gateway/ws` | 实时推送 | P5 |
| 被调用 | — | — | — | 前端不暴露接口给其他服务 | — |
| 消费 | parent-bff | HTTP（经 Gateway） | `GET /parent/viewports`、`GET /parent/children`、`POST /parent/switch-child`、`GET /parent/notifications`、`PUT /parent/notification-preferences` | 家长场景聚合 | P4+ |
| 消费 | iam | HTTP（经 Gateway） | `/iam/*` | 登录/权限/视口 | P2+ |
| 消费 | core-edu | HTTP（经 Gateway） | `/grades/*` `/homework/*` | 教学核心（子女视角） | P3+ |
| 消费 | data-ana | HTTP（经 Gateway） | `/analytics/*` | 学情分析 | P4+ |
| 消费 | msg | HTTP（经 Gateway） | `/notifications/*` | 通知中心 | P5+ |
| 依赖 | coord 维护 | — | `packages/shared-proto` | TS 类型（仅 contracts 部分） | P1+ |
| 依赖 | coord 维护 | — | `packages/shared-ts`（待建） | ApiClient/Logger/通用工具 | P4+ |
| 依赖 | ai07 维护 | — | `packages/ui-tokens`（待建） | 三层设计令牌 | P4+ |
| 依赖 | ai07 维护 | — | `packages/ui-components`（待建） | shadcn + 共享组件 | P4+ |
| 依赖 | ai07 维护 | — | `packages/hooks`（待建） | usePermission/useAuth 等 | P4+ |
| 依赖 | coord 维护 | — | `packages/contracts`（待建） | Permissions 常量 + 类型 | P4+ |
> **proto 不直接消费**：前端不调用 gRPC，BFF 把 gRPC 聚合为 REST 暴露给前端。前端仅消费 `packages/contracts/src/permissions.ts` 中的权限点常量（TS 文件，非 proto 生成）。
## 11. 风险与假设
### 11.1 假设
1. **假设 coord 建立 `packages/shared-ts`、`packages/contracts`**：包含 ApiClient、Logger、Permissions 常量、通用类型。若 coord 未建立，ai07 自行在 `apps/parent-portal/src/shared/` 内实现，后续提取到 packages。
2. **假设 ai05 parent-bff 提供 `GET /parent/viewports`、`GET /parent/children`、`POST /parent/switch-child`、`GET /parent/notifications`、`PUT /parent/notification-preferences`**：当前 parent-bff 待 ai05 设计（P4）。
3. **假设 teacher-portal Shell 已就绪**：AppShell + 共享依赖暴露（react/react-dom/@tanstack/react-query/zustand/nuqs/ui-components/ui-tokens/contracts/hooks/shared-ts）+ MF 配置（`remotes.parent`）已配置完成。详见 [teacher-portal 阶段2](../../teacher-portal/docs/02-architecture-design.md)。
4. **假设 Next.js 14+ Module Federation 2.0 稳定**：`@module-federation/nextjs-mf` 在 Next.js App Router 下可用。若不稳定，降级为 4 端独立部署 + 各自 Shell（重复实现 AppShell）。
### 11.2 技术风险
| 风险 | 影响 | 缓解 |
| ----------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------- |
| MF SSR 对齐复杂 | Remote 在 SSR 时需 Shell 提供上下文 | 优先 CSR，SSR 仅用于首屏 dashboard；MF 2.0 支持 SSR |
| 共享依赖版本漂移 | Remote 与 Shell 的 react/react-dom 版本不一致导致运行时错误 | MF `shared.singleton: true` + CI 检查版本对齐 |
| Token 刷新竞态 | 多请求同时 401 触发多次 refresh | ApiClient 全局单例（Shell 共享）+ refresh promise 复用 |
| 权限缓存陈旧 | 角色变更后前端 5min 内仍用旧权限 | iam 角色变更发 Kafka 事件 → msg 推送 WebSocket → 前端 invalidate |
| 子女切换竞态 | 快速连续切换子女导致请求乱序，旧请求覆盖新数据 | TanStack Query `queryKey` 含 `currentChildId` + 切换时 invalidate + abort 旧请求 |
| parent-bff 契约未定 | ai05 parent-bff 接口契约尚未最终确认，可能与本文档假设不一致 | P4 启动前与 ai05 对齐契约，必要时调整 `useParentApi` 实现 |
| TanStack Query 缓存膨胀 | 长时间使用后缓存项过多（多个子女的历史查询） | `gcTime` 5min + `staleTime` 按数据类型分级 + 切换子女时清理非当前子女的缓存 |
### 11.3 未决设计决策（需 coord 仲裁）
> 以下 4 项与 teacher-portal 一致，详见 [teacher-portal 阶段2 §11.3](../../teacher-portal/docs/02-architecture-design.md#113-未决设计决策需-coord-仲裁)。
1. **packages 归属**：`ui-tokens` / `ui-components` / `hooks` 是 ai07 维护还是 coord 维护？建议：ai07 维护（前端专属），coord 仅维护 `shared-ts` / `contracts`（跨语言/跨服务）。
2. **GraphQL vs REST**：004 §11.3 提到 BFF GraphQL Yoga + DataLoader，但当前 parent-bff 实现为 REST。前端 API 请求层是否需要 GraphQL client（urql/apollo）？建议：P4 用 REST，后续若 BFF 切 GraphQL 再引入 urql。
3. **i18n key 命名**：`iam.error.IAM_INVALID_CREDENTIALS` 还是 `error.iam.invalid_credentials`？建议：`error.{{service}}.{{code_snake_case}}`，与错误码前缀对齐。
4. **MF 暴露粒度**：Shell 暴露整个 AppShell 还是暴露更细粒度的组件（Sidebar、Header、Content）？建议：暴露 AppShell 整体 + 各 Remote 自行决定内部布局。
## 12. coord 交叉审查所需信息
### 12.1 端口矩阵
| 端 | dev 端口 | 生产端口 | 备注 |
| ------------- | -------- | -------- | ------------- |
| parent-portal | 3002 | 3002 | Remote 子应用 |
> 与 [full-stack-runbook](../../../docs/standards/full-stack-runbook.md) 端口矩阵对齐。
### 12.2 依赖的共享包（需 coord 建立）
| 包 | 路径 | 维护方 | 内容 |
| --------------- | ------------------------- | ------------ | ------------------------------------------------------ |
| `shared-ts` | `packages/shared-ts/` | coord | ApiClient、Logger、通用工具 |
| `contracts` | `packages/contracts/` | coord | Permissions 常量、ActionState 类型、UserInfo 类型 |
| `ui-tokens` | `packages/ui-tokens/` | ai07（建议） | 三层设计令牌 |
| `ui-components` | `packages/ui-components/` | ai07（建议） | shadcn + ErrorBoundary + RequirePermission |
| `hooks` | `packages/hooks/` | ai07（建议） | usePermission、useAuth、useViewports、useChildSwitcher |
### 12.3 依赖的后端契约（需对应 AI 确认）
| 契约 | 提供方 | 当前状态 |
| ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ------------------- |
| `POST /iam/login`、`GET /iam/effective-permissions`、`GET /iam/me` | iam | ✅ 已实现 |
| `GET /parent/viewports`、`GET /parent/children`、`POST /parent/switch-child`、`GET /parent/notifications`、`PUT /parent/notification-preferences` | parent-bff (ai05) | 📐 待 P4 设计 |
| `/grades/*` `/homework/*`（子女视角） | core-edu | ✅ 已实现（P3） |
| `/analytics/*` | data-ana | ✅ 已实现（P4 CDC） |
| `/notifications/*` + WebSocket 推送 | msg + push-gateway | 📐 待 P5 |
### 12.4 错误码前缀（前端 i18n 路由依赖）
前端不产生错误码，仅消费。需各服务确认错误码前缀不重叠：
| 前缀 | 服务 | 状态 |
| ------------- | ----------- | --------------- |
| `IAM_` | iam | ✅ 已用 |
| `CORE_EDU_` | core-edu | ✅ 已用 |
| `GRADES_` | core-edu | ⚠️ 待确认 |
| `HOMEWORK_` | core-edu | ⚠️ 待确认 |
| `BFF_PARENT_` | parent-bff | ⚠️ 待 ai05 确认 |
| `GW_` | api-gateway | ✅ 已用 |
| `NETWORK_` | 前端 | ai07 自有 |
### 12.5 不产生 Kafka 事件
前端不发布/消费 Kafka 事件。WebSocket 推送由 push-gateway 消费 Kafka 转发。
## 13. 实施路线（ai07 自用）
### P4（parent-portal 启动）
1. 建 `apps/parent-portal/`（Remote 角色），配置 `next.config.js` MF（Remote）
2. 实现 Dashboard 页面（家长仪表盘，聚合子女学情概览）
3. 实现 ChildSwitcher 组件 + `useChildSwitcher` Hook + Zustand childSwitcherSlice
4. 实现子女列表页面（`/parent/children`）
5. 实现子女成绩查看页面（`/parent/grades`，复用 Shell 的 DataTable + Chart）
6. 实现子女作业查看页面（`/parent/homework`）
7. 实现通知偏好设置页面（`/parent/preferences`，react-hook-form + zodResolver）
8. 配置 `/api/health` + `/api/ready` route
9. 补 Vitest 单测 + Playwright E2E（覆盖率 ≥ 80%）
10. 配置 Dockerfile 多阶段构建（builder + runtime）
### P5（推送接入）
1. parent-portal 接入 WebSocket（push-gateway）
2. 实现 `NotificationRequested` / `GradeRecorded` / `SchoolAnnouncement` 事件处理
3. 实现通知中心页面（`/parent/notifications`）
### P6（硬化）
1. Web Vitals + OTel browser SDK 接入
2. A11y WCAG 2.2 AA 审计
3. 性能优化（MF shared 单例验证、bundle 分析）
---
**AI Agent**: ai07 (parent-portal remote)
**Branch**: docs/parent-portal-stage1-stage2-design-ai07
**Coordinator**: coord-ai