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

docs: ai 协作文档体系重构与多 ai 仲裁结果落地

Browse Source 
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.设计规格文档
This commit is contained in:
SpecialX
2026-07-10 12:58:22 +08:00
parent 2a2a56f541
commit faaaf29f67
120 changed files with 23201 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

199
apps/teacher-portal/docs/00-ai13-audit-report.md Normal file
View File

@@ -0,0 +1,199 @@
# 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)