xiner/Edu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
74474a2d0432b866be164ba91f64d35aafb35d7d
Edu/apps/teacher-portal/docs/00-ai13-audit-report.md
SpecialX faaaf29f67 docs: ai 协作文档体系重构与多 ai 仲裁结果落地 
1.AI 协作文档体系重构(objections/worklines/contracts+matrix.md)

2.coord 仲裁文档(final-decisions/cross-review/final-rulings/orchestration)

3.各服务 01/02 文档补全

4.共享包初始化(shared-ts/shared-go/hooks/ui-components/ui-tokens)

5.Proto 契约补全

6.004 架构影响地图更新

7.端口分配表

8.设计规格文档
2026-07-10 12:58:22 +08:00

15 KiB
Raw Blame History

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

AI：ai13（TS/React · teacher-portal 正式负责人，依据 ai-allocation.md §3.2） 阶段：阶段 1/2 文档审核 + 长远架构补全 日期：2026-07-09 审核对象：

关联裁决：coord 交叉审查报告 §4.1/§5.2/§5.5/§6（整改项 #2/#5/#17/#18）、004 架构影响地图 §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 §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)

Reference in New Issue View Git Blame Copy Permalink