# ai13 审核 report — teacher-portal 现有文档遗漏分析

> AI：ai13（TS/React · teacher-portal 正式负责人，依据 ai-allocation.md §3.2）
> 阶段：阶段 1/2 文档审核 + 长远架构补全
> 日期：2026-07-09
> 审核对象：
>
> - [01-understanding.md](./01-understanding.md)（ai07 于 2026-07-09 产出）
> - [02-architecture-design.md](./02-architecture-design.md)（ai07 于 2026-07-09 产出）
>
> 关联裁决：[coord 交叉审查报告](../../../docs/architecture/coord-cross-review.md) §4.1/§5.2/§5.5/§6（整改项 #2/#5/#17/#18）、[004 架构影响地图](../../../docs/architecture/004_architecture_impact_map.md) §1.2/§4.2/§7.2/§11.4

---

## 1. 归属与版本背景

| 维度     | ai07 版本（被审核）                           | ai13 版本（本次修正）                     |
| -------- | --------------------------------------------- | ----------------------------------------- |
| AI 标识  | ai07                                          | ai13（ai-allocation.md §3.2 正式负责人）  |
| 文档日期 | 2026-07-09                                    | 2026-07-09（同日审核+补全）               |
| 文档分支 | docs/teacher-portal-stage1-stage2-design-ai07 | docs/teacher-portal-ai13-audit-supplement |
| 触发原因 | ai07 临时承接 4 端合并设计                    | ai13 接管 teacher-portal 正式所有权       |

> **背景说明**：ai-allocation.md §3.2 矩阵中 ai07 正式职责是 classes（黄金模板），ai13 才是 teacher-portal 的负责人。前期因并行加速，ai07 临时承担 4 端合并设计并产出 `apps/teacher-portal/README.md`（945 行）与 docs/01-02 两份文档。coord 已在 [coord-cross-review.md](../../../docs/architecture/coord-cross-review.md) §6 整改清单 #2/#17/#18 中列出多项需修正项，但整改责任原标注为 ai07。本次 ai13 正式接管并一次性完成审核 + 修正 + 长远架构补全。

---

## 2. 需修正项（来自 coord 裁决）

### 2.1 P0 端口冲突修正（coord §4.1，整改 #2）

| 项             | ai07 原文档                | 正确值                                                        | 依据                               |
| -------------- | -------------------------- | ------------------------------------------------------------- | ---------------------------------- |
| teacher-portal | 3000                       | **4000**                                                      | 004 §1.2 + project_memory 端口约束 |
| student-portal | 3001                       | **4001**                                                      | 004 §1.2                           |
| parent-portal  | 3002                       | **4002**                                                      | 004 §1.2                           |
| admin-portal   | 3003                       | **4003**                                                      | 004 §1.2                           |
| MF remoteEntry | `localhost:3001/3002/3003` | `localhost:4001/4002/4003`                                    | 与端口矩阵一致                     |
| 后端冲突说明   | "3001-3003 已被避让"       | 删除（错误描述，3001-3003 仍被 classes/iam/teacher-bff 占用） | coord §4.1 表                      |

### 2.2 P1 端点契约对齐（coord §6 整改 #17，4 处端点不一致）

| ai07 原文档                                                  | 正确值（以后端服务为准）                                                  | 依据           |
| ------------------------------------------------------------ | ------------------------------------------------------------------------- | -------------- |
| `GET /api/v1/ai/generate-questions`（SSE）                   | `POST /api/v1/ai/chat/stream`（SSE）+ `POST /api/v1/ai/generate/question` | coord §3 表 #1 |
| `GET /iam/effective-permissions`                             | `GET /iam/permissions/effective`                                          | coord §3 表 #2 |
| `GET /iam/rbac/...`                                          | `GET /iam/viewports`、`GET /iam/roles`、`GET /iam/permissions/*`          | coord §3 表 #3 |
| `POST /parent/switch-child`（家长端，不影响 teacher-portal） | `POST /parent/children/:childId/select`                                   | coord §3 表 #4 |

### 2.3 P1 错误码前缀期望修正（coord §5.5，整改 #18）

| ai07 原文档                                    | 正确值                                                                 | 依据       |
| ---------------------------------------------- | ---------------------------------------------------------------------- | ---------- |
| 期望 `EXAMS_` / `HOMEWORK_` / `GRADES_` 子前缀 | 删除，统一为 `CORE_EDU_*`（classes 模块保留 `CLASSES_*` 黄金模板遗留） | coord §5.5 |
| BFF 错误码前缀 `BFF_TEACHER_`                  | 保留（coord §5.2 已裁决 3 BFF 统一为 `BFF_XXX_` 风格）                 | coord §5.2 |
| 期望 `GW_` 前缀                                | 保留（coord §5.4 已裁决 api-gateway 加 `GW_` 前缀）                    | coord §5.4 |

---

## 3. 长远架构遗漏分析（ai13 新增）

ai07 原文档已覆盖阶段 1/2 模板要求（位置/限界/契约/技术栈/分层图/领域模型/数据模型/API/事件/横切/交互/风险），但**未充分覆盖以下"长远、全面、面向未来"的架构维度**。这些维度是通用前端架构标准（Next.js + Module Federation + 企业级 SaaS）必备项，本次审核需补全。

### 3.1 演进路线缺失

| 维度                | ai07 原文档           | 缺失内容                                          |
| ------------------- | --------------------- | ------------------------------------------------- |
| 当前 → MF 迁移路径  | 仅描述目标态          | 当前单端部署如何演进到 Shell+Remote 的分步路径    |
| 阶段间能力累积      | 仅 P2/P5/P6 三段      | P2/P3/P4/P5/P6 每阶段 teacher-portal 必备能力清单 |
| 后端契约演进对齐    | 无                    | 后端 P3 启用 gRPC 后前端是否需要切换、何时切换    |
| REST → GraphQL 切换 | 提一句"待 coord 仲裁" | 切换的触发条件、迁移策略、灰度方案                |

### 3.2 安全架构缺失

| 维度                | ai07 原文档       | 缺失内容                                                        |
| ------------------- | ----------------- | --------------------------------------------------------------- |
| Token 存储安全      | 仅说 localStorage | localStorage 的 XSS 风险 + httpOnly Cookie 替代方案 + CSRF 防护 |
| CSP（内容安全策略） | 无                | Next.js `csp()` / `nonce()` 配置，限制 script/style/img 来源    |
| XSS 防护            | 仅提 DOMPurify    | Tiptap 富文本的 XSS 防护、`dangerouslySetInnerHTML` 白名单      |
| CSRF 防护           | 无                | 若改用 Cookie 鉴权需 CSRF Token / SameSite                      |
| 点击劫持防护        | 无                | X-Frame-Options: DENY + CSP frame-ancestors                     |
| 子资源完整性 SRI    | 无                | MF remoteEntry.js 的 SRI 校验、CDN 静态资源 integrity           |
| 敏感数据脱敏        | 无                | 日志/错误上报中 token/PII 脱敏                                  |

### 3.3 性能架构缺失

| 维度                | ai07 原文档    | 缺失内容                                                           |
| ------------------- | -------------- | ------------------------------------------------------------------ |
| 性能预算（Budget）  | 无             | JS bundle ≤ 200KB / CSS ≤ 50KB / LCP ≤ 2.5s / CLS ≤ 0.1 等具体目标 |
| 路由级代码分割      | 无             | Next.js App Router 默认按路由分割 + 动态 import 重型组件           |
| SSR/CSR 决策矩阵    | 仅提"优先 CSR" | 每类页面（dashboard/exam-taking/lesson-prep）的 SSR/CSR 选择标准   |
| 字体加载策略        | 仅说 next/font | FOUT vs FOIT 选择、preload、font-display: swap                     |
| 图片优化            | 无             | next/image + AVIF/WebP + 响应式 sizes + lazy load                  |
| MF 共享依赖版本漂移 | 仅说 singleton | 共享依赖版本协商机制、peer deps 警告                               |
| Prefetch / Preload  | 无             | 路由 prefetch 策略、关键资源 preload                               |
| 长任务优化          | 无             | React 18 concurrent features、useTransition、useDeferredValue      |

### 3.4 可观测性深度缺失

| 维度           | ai07 原文档          | 缺失内容                                                         |
| -------------- | -------------------- | ---------------------------------------------------------------- |
| 错误上报       | 提"P6 接入 Sentry"   | Sentry DSN 配置、release tracking、source maps、采样率、PII 过滤 |
| 性能监控       | 仅列 4 项 Web Vitals | RUM（Real User Monitoring）方案、长任务监听、卡顿追踪            |
| 用户行为分析   | 无                   | 哪些事件需要埋点、埋点规范、隐私合规                             |
| Session Replay | 无                   | Sentry Replay / LogRocket 选型、隐私区域遮罩                     |
| 前端日志聚合   | 仅 console           | 浏览器日志如何汇聚到 Loki（pino-browser → Gateway → Loki）       |
| trace_id 透传  | 仅提"从响应头提取"   | 浏览器入口生成 trace_id、写入后续请求 header、跨 MF 透传         |

### 3.5 a11y 实施细节缺失

| 维度             | ai07 原文档     | 缺失内容                                   |
| ---------------- | --------------- | ------------------------------------------ |
| WCAG 2.2 AA 清单 | 仅列工具集      | 逐条对照 WCAG 2.2 AA 13 项准则 + 实施方式  |
| 键盘导航         | 仅提 focus-trap | 跳过链接、Tab 顺序、可见焦点、快捷键       |
| 屏幕阅读器测试   | 无              | NVDA/JAWS/VoiceOver 测试矩阵 + ARIA 模式   |
| 颜色对比度       | 无              | 自动化检测（axe-core）+ 设计令牌对比度审计 |
| 移动端 a11y      | 无              | 触摸目标 ≥ 44px、缩放支持、手势替代        |

### 3.6 i18n 实施细节缺失

| 维度           | ai07 原文档     | 缺失内容                                               |
| -------------- | --------------- | ------------------------------------------------------ |
| next-intl 配置 | 仅提"next-intl" | locale 路由策略（前缀 vs 域名）、SSR i18n、locale 检测 |
| fallback 策略  | 无              | 缺失翻译时回退到默认语言、缺失 key 在 dev 环境警告     |
| 复数/性别      | 无              | ICU MessageFormat 复数规则、性别变化                   |
| 日期/数字格式  | 无              | Intl.DateTimeFormat / Intl.NumberFormat 按 locale      |
| RTL 支持       | 无              | 是否需要支持阿拉伯语/希伯来语（影响布局）              |
| 翻译协作流程   | 无              | 翻译文件位置、协作工具（Crowdin/Transifex）、CI 校验   |

### 3.7 部署拓扑缺失

| 维度          | ai07 原文档      | 缺失内容                                             |
| ------------- | ---------------- | ---------------------------------------------------- |
| 部署目标      | 仅说 Docker      | Docker Compose（P1-P5）→ K8s（P6）演进路径           |
| CDN/Edge 缓存 | 无               | Next.js 静态资源 CDN、edge middleware、ISR 缓存      |
| 多环境配置    | 无               | dev/staging/prod 环境变量管理、Next.js runtimeConfig |
| 健康检查端点  | 仅说 /api/health | /api/health vs /api/ready 区别、K8s probe 配置       |
| 灰度发布      | 无               | MF remoteEntry 版本协商、灰度发布策略                |
| 回滚策略      | 仅说 git revert  | 前端回滚特殊性：CDN 缓存失效、用户会话保持           |

### 3.8 测试策略细节缺失

| 维度           | ai07 原文档     | 缺失内容                                                |
| -------------- | --------------- | ------------------------------------------------------- |
| 单元测试       | 仅说 Vitest     | 测试什么（hooks/utils/pure components）、mocking 策略   |
| 集成测试       | 无              | 组件树集成、API mock（MSW）、TanStack Query 集成测试    |
| E2E 测试       | 仅说 Playwright | 关键路径（登录/dashboard/班级 CRUD）、CI 并发、稳定策略 |
| 视觉回归测试   | 无              | Storybook + Chromatic / Percy 选型                      |
| 覆盖率目标分层 | 仅说 ≥80%       | hooks ≥90% / utils ≥90% / components ≥80% / pages ≥60%  |
| 性能测试       | 无              | Lighthouse CI / WebPageTest 集成                        |

### 3.9 文件/目录结构目标态缺失

ai07 原文档 §6/§7 列出共享组件库/Hooks/令牌的"待建包"，但**未给出 teacher-portal 自身的目录结构目标态**（当前 vs 目标对比）。

### 3.10 移动端策略缺失

ai07 原文档未提及：

- 是否需要响应式适配（教师在家备课用手机查看）？
- 是否需要 PWA / Service Worker（离线批改作业）？
- 是否需要后续原生 App（React Native / Electron 桌面端）？
- 移动端手势、触摸目标规范

### 3.11 MF 演进策略缺失

ai07 原文档描述了 MF 2.0 目标态，但**未回答关键演进问题**：

- 当前 teacher-portal 是单端部署（无 MF），何时引入 MF？
- 引入 MF 后如何保持现有路由不被破坏？
- MF 失败时的降级方案（remoteEntry.js 加载失败怎么办）？
- MF 版本协商（Shell 与 Remote 的合约版本）？

### 3.12 数据流与乐观更新缺失

ai07 原文档 §4.2 提了 TanStack Query mutation，但**未覆盖**：

- 乐观更新策略（提交作业、批改成绩时如何乐观更新 UI）
- 冲突解决（多教师同时批改同一作业）
- 失败回滚机制
- 缓存失效链路（mutate A 后哪些 B/C/D 需要失效）

---

## 4. 本次审核产出

ai13 本次审核产出 **3 份文档**：

1. **本报告**：`apps/teacher-portal/docs/00-ai13-audit-report.md`（审核报告，永久保留作为审核凭证）
2. **更新** `apps/teacher-portal/docs/01-understanding.md`：修正归属/端口/端点/前缀，补充长远维度
3. **更新** `apps/teacher-portal/docs/02-architecture-design.md`：修正归属/端口/端点/前缀，补充横切与演进章节
4. **新建** `apps/teacher-portal/docs/03-long-term-architecture.md`：长远架构补全（演进/安全/性能/可观测/a11y/i18n/部署/测试/移动端/MF 演进）

---

**AI Agent**: ai13 (teacher-portal)
**Branch**: docs/teacher-portal-ai13-audit-supplement
**Coordinator**: coord-ai
**Audited**: ai07 stage1+2 outputs (2026-07-09)