From ee103804627eda6c1bb5d4c9b22735ede2cb4bd0 Mon Sep 17 00:00:00 2001 From: SpecialX <47072643+wangxiner55@users.noreply.github.com> Date: Mon, 6 Jul 2026 20:57:14 +0800 Subject: [PATCH] =?UTF-8?q?docs(architecture):=20=E7=BB=84=E4=BB=B6?= =?UTF-8?q?=E5=8C=96=E9=87=8D=E6=9E=84=E4=B8=93=E9=A1=B9=E5=AE=8C=E6=88=90?= =?UTF-8?q?=20-=20=E5=90=8C=E6=AD=A5=20005=20lastUpdate=20+=20known-issues?= =?UTF-8?q?=20=E7=AC=AC=2025=20=E7=AB=A0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 005 JSON: lastUpdate 更新为组件化重构专项全量完成摘要 - known-issues.md: 新增第 25 章（4 个小节：底座使用规则/拆分模式/迁移规则/验证规则） - 9 个巨型文件全部 ≤500 行，49 个重复组件全部删除 --- docs/architecture/005_architecture_data.json | 2 +- docs/troubleshooting/known-issues.md | 47 ++++++++++++++++++++ 2 files changed, 48 insertions(+), 1 deletion(-) diff --git a/docs/architecture/005_architecture_data.json b/docs/architecture/005_architecture_data.json index 6071897..1311d42 100644 --- a/docs/architecture/005_architecture_data.json +++ b/docs/architecture/005_architecture_data.json @@ -5,7 +5,7 @@ "generatedAt": "2026-06-17", "formatVersion": "1.1", "rule": "每次文件修改后须同步更新本文件", - "lastUpdate": "Phase 4.6 grades 模块组件化重构闭环完成（2026-07-06）：(1) 拆分 batch-grade-entry.tsx 巨型文件 — 将试卷/班级选择器（含未选态引导）拆至 batch-grade-entry-selectors.tsx、底部工具栏（清除/保存/粘贴提示）拆至 batch-grade-entry-toolbar.tsx，主组件从 457 行降至 374 行，容器仅负责状态编排与 Server Action 调用；(2) 拆分 grade-record-list.tsx 巨型文件 — 行渲染（桌面表格 + 移动端卡片堆叠）拆至 grade-record-row.tsx、编辑/单条删除/批量删除对话框集合拆至 grade-record-detail.tsx（导出 EditableFields 类型 + toEditableFields 工具函数），主组件从 523 行降至 231 行；(3) 迁移 4 个重复组件到共享底座并删除原文件 — grade-stats-card.tsx → StatsGrid + StatItem 组合（class-grade-report.tsx 内联 8 个统计项）、grade-filters.tsx → app 层 student-grade-filters.tsx（复用 FilterBar + FilterSearchInput + Select + nuqs useQueryState）、grade-query-filters.tsx → app 层 teacher-grade-query-filters.tsx（复用 FilterBar + Select + useRouter/useSearchParams）、analytics-filters.tsx → app 层 analytics-grade-filters.tsx（复用 FilterBar + ChipNav，保留原 buildHref URL 构造逻辑）。同步更新：StatItem/ChipNav/FilterBar/FilterSearchInput 的 usedBy 列表、GradeStats/isGradeType/isSemester 的 usedBy 列表、BatchGradeEntry 与 GradeRecordList 与 ClassGradeReport 的 purpose/props/deps、新增 4 个子组件条目（BatchGradeEntrySelectors/BatchGradeEntryToolbar/GradeRecordRow/GradeRecordDetail）、删除 4 个旧组件条目（GradeStatsCard/GradeQueryFilters/AnalyticsFilters 及 grades/components/grade-filters 隐式条目）。验证：npx tsc --noEmit 零错误；npm run lint 仅 3 个 pre-existing react-hooks/refs 错误（位于未修改的 use-exam-preview-tasks.ts）；grep 确认旧组件名（GradeStatsCard/GradeFilters/GradeQueryFilters/AnalyticsFilters）无业务代码残留。前次更新：缓存策略落地专项重构完成（2026-07-05），覆盖全部 28 个模块，新增 shared/lib/cache/ 9 个文件 + INVALIDATION_MAP 203 个 actionId，data-access 83 文件 250+ 查询函数迁移至 cacheFn 双导出模式，actions 43 文件 247 处 revalidatePath 替换为 invalidateFor，详细见 004 第 1.1.6 节。", + "lastUpdate": "组件化重构专项全量完成（2026-07-06）：三批 10 个模块闭环 + Phase 1 底座补全。Phase 1：新增 ErrorBoundary 基础类组件、StatsGrid 容器、SkeletonCard variant，收敛 SectionErrorBoundary/RouteErrorBoundary/WidgetBoundary 为 preset。第 1 批（grades/attendance/error-book/elective）：拆分 batch-grade-entry (457→375) + grade-record-list (523→231)，迁移 12 个重复组件到 StatsGrid/FilterBar 底座。第 2 批（homework/exams/textbooks）：拆分 homework-take-view (428→330) + homework-grading-view (507→170) + exam-assembly (467→268) + textbook-reader (458→318) + knowledge-graph-inner (411→295)，删除 textbooks 同名 section-error-boundary.tsx，迁移 3 个 filter 组件。第 3 批（lesson-preparation/ai/dashboard）：拆分 lesson-plan-editor (594→273) + ai-chat-panel (417→218)，新增 DashboardShell 布局壳统一 4 角色 dashboard，迁移 filters/skeletons/error-boundaries 到底座。总计：9 个巨型文件全部 ≤500 行（最大 375），49 个重复组件全部删除无残留，tsc 零错误，lint 无新增错误。前次更新：Phase 4.6 grades 模块组件化重构闭环完成（2026-07-06）。", "lastUpdated": "2026-07-06" }, "architectureOverview": { diff --git a/docs/troubleshooting/known-issues.md b/docs/troubleshooting/known-issues.md index 1dc4647..13f4f50 100644 --- a/docs/troubleshooting/known-issues.md +++ b/docs/troubleshooting/known-issues.md @@ -1301,3 +1301,50 @@ if (announcement.type === "school") { | 多余的 `}` 或 `)` 字符 | 迁移后用 tsc 全量校验 | 手动编辑后未运行 tsc（TS1005/TS1128 语法错误） | | questions/data-access.ts 等大文件分批迁移 | 完整迁移所有 `cache(...)` 调用至 cacheFn | 部分迁移导致 `import { cache }` 已删但调用仍存 | +--- + +## 25. 组件化重构专项（2026-07-06） + +### 25.1 共享底座使用规则 + +| 规则 | 正确写法 | 错误写法 | +|------|---------|---------| +| 错误边界必须用 preset | `` | 自行实现类组件 | +| 统计卡片必须用 StatsGrid | `` | 手写 grid + StatCard 循环 | +| 骨架卡片必须用 SkeletonCard | `` | 手写 Card + Skeleton 布局 | +| 新增 `*-filters.tsx` 禁止 | 用 `` + `` 组合 | 新建模块专属筛选器文件 | +| ErrorBoundary 基础类不直接使用 | 通过 SectionErrorBoundary/WidgetBoundary preset | 直接 `` | +| FilterBar 是 children-based 组合式 | `