xiner/NextEdu
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity
323 Commits 1 Branch 0 Tags
164dcd4c84c49c15aca4f80f9b64bcb734ed7001
Commit Graph

95 Commits

Author SHA1 Message Date
SpecialX
747344bfe3 chore: snapshot before P0 security phase (backup point) 2026-07-07 19:12:33 +08:00
SpecialX
3f68f3eb09 docs(plan): add enterprise architecture normalization implementation plan 2026-07-07 19:12:08 +08:00
SpecialX
205b463900 docs(architecture): add enterprise architecture normalization design spec 2026-07-07 19:09:40 +08:00
SpecialX
5d9981fd7d docs(architecture): update impact map, data, audit reports, superpowers docs
Some checks failed
CI / scheduled-backup (push) Has been skipped
Details
CI / backup-verify (push) Has been skipped
Details
CI / weekly-dr-drill (push) Failing after 0s
Details
CI / build-deploy (push) Has been cancelled
Details
CI / security-scan (push) Has been cancelled
Details 
- Update 004_architecture_impact_map.md and 005_architecture_data.json

- Add audit reports: data-access-audit-framework-v1, data-access-audit-v1-data.json,

  data-access-audit-v1, g1-g5 audit outputs

- Add superpowers plans and specs (logging-refactor, documentation-system-redesign)

- Update troubleshooting/known-issues.md
 2026-07-07 16:23:35 +08:00
SpecialX
4e6d397d8e docs(architecture): sync logging refactor to 004/005 and known-issues 
Task 15: 004 架构影响地图新增 1.1.7 日志系统重构章节(架构图、核心组件表、Request ID 贯穿链路、Edge Runtime 限制、替换范围、环境变量),shared/lib 清单新增 logger.ts/request-context.ts/with-request-context.ts/track-event.ts 更新,hooks 清单新增 use-error-report.ts。

Task 16: 005 架构数据 JSON 新增 3 个 shared/lib 文件节点、1 个 hooks 节点、1 个 apiRoute(/api/client-error)、5 个 dependencyMatrix 依赖关系,JSON 有效性验证通过。

Task 17: known-issues.md 新增二十八、日志系统规则章节,含 5 个规则表(pino 使用、Edge Runtime 限制、Request ID 贯穿、ESLint no-console、客户端错误上报)。
 2026-07-07 13:00:00 +08:00
SpecialX
94f098b0f2 perf(phase1-4): 补漏性能预算重构专项遗漏项 
Phase 1 配置基线：next.config.ts 新增 experimental.optimizePackageImports（lucide-react/recharts/@xyflow/react/@tiptap/* /@radix-ui/*/date-fns）+ serverExternalPackages 追加 tencentcloud-sdk-nodejs + exceljs；providers.tsx 注入 WebVitalsReporter 闭环 RUM 上报链路（之前组件存在但未注入导致生产环境零性能数据）。

Phase 2 Bundle 预算优化补漏：TipTap 三实例（shared/ui/rich-text-editor + exams/editor/exam-rich-editor + lesson-preparation/blocks/rich-text-block）之前仅文件拆分未真正 next/dynamic ssr:false,本次补齐 lazy wrapper + xxx-inner.tsx 拆分模式；ReactFlow knowledge-graph.tsx 改用 next/dynamic 加载 inner；chart.tsx 改 recharts 具名导入替代 import * as RechartsPrimitive barrel。

Phase 4 组件渲染优化补漏：12 个 recharts 图表组件（parent/grades/dashboard/homework 模块下）margin props 提取到模块级 CHART_MARGIN 常量避免 inline 重建；layout.tsx metadata 增强（metadataBase/openGraph/twitter/robots/authors/creator）+ getLocale/getMessages/auth 串行 await 改 Promise.all 并行。

同步架构文档 004/005 + known-issues.md：新增 Phase 1 配置基线规则章节 + Phase 2 文件清单修正（之前引用不存在的 question-rich-editor.tsx 和 paper-rich-editor.tsx,实际是 rich-text-editor.tsx 和 rich-text-block.tsx）+ Phase 4.9 metadata + Promise.all 规则补充。架构图 1.1.5 章节新增未完成项（React Compiler/force-dynamic 评估/Playwright 性能断言）。

验证：npx tsc --noEmit 零错误；npm run lint 零新增错误（3 errors + 12 warnings 均位于未修改的 pre-existing 文件）。
 2026-07-07 00:30:47 +08:00
SpecialX
6104e6a685 docs(architecture): 组件化重构专项遗漏补全 - 更新 005 lastUpdate + known-issues 25.4 节 
- 005 JSON: lastUpdate 追加遗漏补全 9 模块 20 组件迁移记录
- known-issues.md: 新增 25.4 遗漏补全规则章节
- 全量验证：49 个重复组件全部删除，modules/*/components/ 下无残留
 2026-07-06 22:24:17 +08:00
SpecialX
ee10380462 docs(architecture): 组件化重构专项完成 - 同步 005 lastUpdate + known-issues 第 25 章 
- 005 JSON: lastUpdate 更新为组件化重构专项全量完成摘要
- known-issues.md: 新增第 25 章（4 个小节：底座使用规则/拆分模式/迁移规则/验证规则）
- 9 个巨型文件全部 ≤500 行，49 个重复组件全部删除
 2026-07-06 20:57:14 +08:00
SpecialX
19a05091d3 refactor(grades,attendance,error-book,elective): 组件化重构第 1 批 - 低风险模块 
- grades: 拆分 batch-grade-entry (457→374) + grade-record-list (523→231)，新增 4 个子组件
- attendance: 迁移 stats-cards/filters 到 StatsGrid/FilterBar 底座
- error-book: 迁移 stats-cards/filters 到 StatsGrid/FilterBar 底座
- elective: 迁移 stats-cards/filters 到 StatsGrid/FilterBar 底座
- 删除 12 个重复组件，新增 app 层 filter 组件就近放置
- tsc 零错误，lint 无新增错误
 2026-07-06 19:01:57 +08:00
SpecialX
80d98e13e4 docs(plan): 组件化重构专项实施计划 v1 2026-07-06 17:49:14 +08:00
SpecialX
ef2040edf4 docs(spec): 组件化重构专项设计文档 v1 2026-07-06 17:44:15 +08:00
SpecialX
9ce8d6d3fd refactor(data-access): 补全剩余 37 个 data-access 文件迁移至 cacheFn 
迁移范围：lesson-preparation 11 文件、attendance 3 文件、settings 4 文件、classes-invitations、跨模块接口 4 文件、adaptive-practice/ai/onboarding/invitation-codes/search/standards/scheduling/leave-requests/audit。修复 3 个 cacheFn 块位置错误。同步架构文档迁移范围至 83 文件 250+ 函数。
 2026-07-06 15:12:30 +08:00
SpecialX
99f15ee37a docs(architecture): 同步缓存基础设施 + classes 标杆迁移 + 缓存策略规则 
- 004: 补全 shared/lib/cache 9 文件说明（types/memory-store/redis-store/store-factory/cache-fn/invalidation-map/client-invalidation-map/invalidate/index）+ shared/lib/redis-client + shared/lib/query-keys

- 005: shared.lib.exports.functions 补 5 个节点（MemoryCacheStore / RedisCacheStore / CLIENT_INVALIDATION_MAP / getRedisClient / queryKeys）

- known-issues.md 新增「二十四、缓存策略规则」章节，含 14 条规则表与涉及文件清单
 2026-07-05 19:04:03 +08:00
SpecialX
a3dc22cb9e refactor(classes): 客户端组件迁移至 useQuery + queryKeys 示范 
Task 19: 将 class-invitation-manager.tsx 从 initialCodes prop + 本地 codes state +
手动 Action 调用 + 手动 state 更新模式，迁移至 V5 缓存策略新 API:

- 列表查询: useActionQuery + queryKeys.classes.invitations(classId)
- 撤销 mutation: useActionMutation + actionId "classes.invitation.revoke"
  (成功后由 CLIENT_INVALIDATION_MAP 自动失效 ["classes", "invitations"] 前缀)
- 生成回调: queryClient.invalidateQueries 手动失效本班级 invitations 查询
- 移除 initialCodes prop + codes state + isSubmitting 手动管理

配套改动:
- actions-invitations.ts: 新增并导出 ClassInvitationCodeOption 强类型接口，
  listClassInvitationCodesAction 返回类型从 Array<Record<string, unknown>>
  收窄为 ClassInvitationCodeOption[]
- actions.ts barrel: 补充 type ClassInvitationCodeOption 与遗漏的
  bulkEnrollStudentsAction / bulkAssignSubjectTeachersAction 导出
- 架构文档 004/005 同步更新 hook 消费方与 actions.ts exports 清单
 2026-07-05 18:57:10 +08:00
SpecialX
dd7a49504f refactor(hooks): useActionQuery/useActionMutation 接入 QueryClient + 向后兼容 
- useActionQuery 新增 queryKey 入参模式：传入 queryKey 走 useQuery 跨页共享缓存；不传回退旧 useEffect + useState 模式。Hook 内部始终声明 useQuery/useState/useEffect 以遵守 React Hooks 规则，通过 isCacheMode 切换启用状态

- useActionMutation 新增 mutationFn + actionId 模式：成功后按 CLIENT_INVALIDATION_MAP[actionId] 自动 invalidateQueries；mutate(action?) 参数可选

- toast 替换为 notify（行为等价，便于未来替换 toast 库）

- 同步更新 004/005 架构文档签名说明
 2026-07-05 18:15:58 +08:00
SpecialX
0f9d8825e7 docs(cache): 同步 cacheFn 架构图与已知问题速查 2026-07-05 18:07:18 +08:00
SpecialX
be31da6223 docs(cache): 缓存策略落地实施计划 + 修正 INVALIDATION_MAP 占位符一致性 2026-07-05 01:37:15 +08:00
SpecialX
8afd7af6dc docs(cache): 缓存策略落地专项设计文档 v1 - 全栈缓存策略一致性（服务端数据缓存+客户端 TanStack Query+失效编排） 2026-07-05 01:30:59 +08:00
SpecialX
214ebec976 refactor(design-tokens): 全量体系化重建设计令牌 
Primitive + Semantic 双层令牌架构,HEX->HSL,明暗双份,@theme inline 暴露为 Tailwind 类。

- 新建 src/app/styles/tokens/ 6 个令牌文件(primitive/semantic-light/semantic-dark/lesson-preparation/tailwind-theme/index)
- globals.css 改为 @import 引入,477->258 行
- 清理 91 处 #hex 硬编码颜色 -> hsl(var(--*))
- 清理 10 处硬编码字体 -> var(--font-family-*)
- 清理 100 文件 Tailwind 任意值(Tier 1 映射/Tier 3 注释豁免)
- 清理 M3 Surface 死代码,升级 --lp-* 令牌(HEX->HSL + 暗色补全)
- 新建 ESLint 自定义规则 no-hardcoded-design-tokens(单词边界正则)
- eslint.config.mjs 新增 no-restricted-syntax 禁止 #hex + 自定义规则加载(pathToFileURL)
- 项目规则新增设计令牌规范强制章节
- 架构图 004/005 同步设计令牌体系节点
- known-issues.md 追加设计令牌问题分类(7 个规则表)

验证: tsc --noEmit 0 errors, npm run lint 0 errors/12 warnings(均为既有问题)
 2026-07-05 01:03:19 +08:00
SpecialX
d1ad7a1f75 docs(architecture): update impact map, data, troubleshooting, add mockups
Some checks failed
Security / deep-security-scan (push) Failing after 2m10s
Details
DR Drill / dr-drill (push) Failing after 1m32s
Details
CI / scheduled-backup (push) Failing after 31s
Details
CI / backup-verify (push) Has been skipped
Details
CI / weekly-dr-drill (push) Failing after 0s
Details
CI / build-deploy (push) Has been cancelled
Details
CI / security-scan (push) Has been cancelled
Details 
- Update 004_architecture_impact_map.md and 005_architecture_data.json

- Remove obsolete _update_004.cjs helper script

- Update troubleshooting/known-issues.md

- Add docs/mockups/ directory
 2026-07-04 23:02:14 +08:00
SpecialX
0780524c08 docs(troubleshooting): V4 备课编辑器规则 
新增 V4 备课编辑器（纸感重构）规则表，8 条规则：正文节点必须是 Tiptap 编辑器、锚点用 Tiptap Mark 内嵌、节点展开位置由 order 决定、节点类型色点用 --lp-dot-*、文档版本必须是 4、师生交互节点用 QaEditor、右键菜单触发对象区分、v3 锚点迁移失效提示。
 2026-07-04 12:01:06 +08:00
SpecialX
5ca2a76e3a docs(architecture): V4 纸感重构架构图同步 
004_architecture_impact_map.md: 更新 lesson-preparation 章节描述（V4 三栏布局）、新增 V4 纸感重构架构变更章节（H1/I1/J1/J2/J3/J4/J5 + 数据模型 v4）、更新文件清单（移除 9 个废弃文件，新增 paper-editor/structure-tree/detail-panel/interaction-block/anchor-migration-banner 等组件 + anchor-mark/export lib + history/expanded slices）。

005_architecture_data.json: 更新 lesson_preparation 节点——description 改为 V4 描述、dependencies 移除 @xyflow/react 改为 @tiptap/* 包、files 数组移除 9 个废弃文件并新增 V4 组件、auditFixes 新增 V4-PAPER-1~8 + V4-PAPER-DOC 条目。JSON 语法验证通过。
 2026-07-04 11:59:39 +08:00
SpecialX
ccf1618b1c docs(lesson-preparation): V4 纸感重构实现计划 
25 个任务，按阶段 A-J 分解：类型定义、状态管理、配色 i18n、Tiptap 锚点、纸区组件、结构树、详情面板、主编辑器改造、迁移 banner、清理验证。
 2026-07-04 11:08:28 +08:00
SpecialX
a1c283e10d docs(lesson-preparation): 备课编辑器无边记纸感重构设计 
新增设计文档，定义正文节点改造为真实 Tiptap 富文本编辑器、三栏布局（结构树 + 纸 + 详情面板）、节点展开到正文、师生交互节点、Tiptap Mark 锚点系统、v3→v4 数据迁移。
 2026-07-04 10:58:55 +08:00
SpecialX
872d5fb085 docs(architecture): update impact map, data, audit report, troubleshooting
Some checks failed
CI / scheduled-backup (push) Has been skipped
Details
CI / backup-verify (push) Has been skipped
Details
CI / weekly-dr-drill (push) Failing after 0s
Details
CI / build-deploy (push) Has been cancelled
Details
CI / security-scan (push) Has been cancelled
Details 
- Update 004_architecture_impact_map.md

- Update 005_architecture_data.json

- Add lesson-preparation-audit-report-v5.md

- Add troubleshooting docs
 2026-07-04 10:24:08 +08:00
SpecialX
6a22922ddd docs(architecture): sync architecture docs with code changes 
- Update 001_project_overview.md

- Update 004_architecture_impact_map.md

- Update 005_architecture_data.json

- Add 008_module_role_mapping.md

- Add _update_004.cjs helper script
 2026-07-03 10:32:15 +08:00
SpecialX
89b9e181d2 docs(audit): add audit reports for grades, homework, lesson-preparation, messaging, permissions, question-bank, settings, textbooks 
- Add grades-audit-report

- Add homework-audit-report and homework-exams-audit-report

- Add lesson-preparation-audit-report-v3 and v4

- Add messaging-audit-report

- Add permissions-audit-report

- Add question-bank-audit-report

- Add settings-profile-audit-report-v3

- Add textbooks-audit-report-v3
 2026-07-03 10:23:34 +08:00
SpecialX
6114607c1e feat(exams,homework): add rich text exam editor and scan-based grading 
- Add Tiptap-based rich text editor with custom extensions (dotted-mark,
  blank-node, image-node, group-block, question-block) for exam creation
- Add AI auto-marking action to convert pasted exam text to structured editor doc
- Add resizable split-panel layout for editor + live preview
- Add student scan upload (photo of paper answers) with drag-drop and reorder
- Add scan image viewer with zoom/rotate/fullscreen for teachers
- Add scan grading view with side-by-side questions and scan images
- Add /teacher/exams/new and /teacher/homework/submissions/[id]/scan-grading routes
- Fix getScansAction to support both teacher (HOMEWORK_GRADE) and student
  (HOMEWORK_SUBMIT) permission scopes
- Add i18n keys for rich editor, scan upload, and scan grading (zh-CN/en)
- Sync architecture diagrams (004/005) with new modules, routes, and deps
 2026-06-24 13:16:33 +08:00
SpecialX
0c64219cb8 docs: add exam rich editor and photo grading design plan
Some checks failed
CI / scheduled-backup (push) Has been skipped
Details
CI / backup-verify (push) Has been skipped
Details
CI / weekly-dr-drill (push) Failing after 1s
Details
CI / build-deploy (push) Has been cancelled
Details
CI / security-scan (push) Has been cancelled
Details 
- Add design plan for exam rich text editor and photo-based grading feature
 2026-06-24 12:04:26 +08:00
SpecialX
e4254f0f8e docs: update architecture map and add lesson-preparation usage fixes design 
- Update architecture impact map (004) and data (005) with new modules

- Add lesson-preparation usage fixes design spec

- Add teacher web test post-audit report
 2026-06-24 12:01:35 +08:00
SpecialX
7e320d78c1 feat(ai): 统一 AI 配置入口到 /admin/ai-settings 
## 新增
- 创建 /admin/ai-settings 统一配置页（AiProviderSettingsCard + AiUsageDashboard）
- admin 侧边栏新增"AI 配置"菜单项（权限 AI_CONFIGURE，图标 Sparkles）
- 新增 deleteAiProvider 数据访问层（事务删除 + 自动转移默认）
- 新增 deleteAiProviderAction Server Action（Zod 校验 + 权限校验）
- AiProviderSettingsCard 新增删除按钮（AlertDialog 确认 + destructive 变体）
- 新增 i18n 翻译键（delete/deleteConfirm/deleteSuccess 等，zh-CN + en）

## 移除
- 从 /settings 移除 AI 标签页（原 VALID_TABS 含 "ai"，现仅 4 标签页）
- 从考试页面移除 AI 配置弹窗（Dialog + AiProviderSettingsCard 内嵌）
- 从 ai-provider-selector.tsx 移除配置弹窗（managePanel/manageOpen props）
- 移除 settings-view.tsx 中 canConfigureAi 逻辑和未使用 import

## 变更
- 考试页面"管理"按钮改为 Link 跳转到 /admin/ai-settings
- ai-provider-selector.tsx"管理"按钮改为 Link 跳转到 /admin/ai-settings
- exam-form.tsx 移除 providerDialogOpen/providerDialogKey 状态
- 修正架构文档 004 中 Action 命名（getAiProvidersAction → getAiProviderSummaries 等）

## 架构文档同步
- 004 更新 settings 模块章节（V3 标记/修正 Action 名称/新增 deleteAiProvider）
- 005 新增 deleteAiProviderAction 节点 + /admin/ai-settings 路由
 2026-06-23 19:33:28 +08:00
SpecialX
27db170c0a docs: update architecture docs, audit reports, and bug tracking 
- Update architecture impact map, data, feature checklist, gap audit

- Add audit reports for dashboard, exam-homework, grades-diagnostic, settings-profile, textbooks

- Update bug reports (admin, teacher, lesson-preparation, others, shared)

- Update coding standards, DR plan, design docs, and README
 2026-06-23 17:36:18 +08:00
SpecialX
f75602d14e feat(announcements,messaging,notifications): 实现所有长期问题 — SSE 实时推送 + 通知日志持久化 + 优先级/归档 + 消息星标/草稿 + 公告已读回执/置顶 + 分类筛选/桌面推送 + 测试覆盖 
P1-8 通知实时推送（SSE）:
- 新增 /api/notifications/stream SSE 端点（15 秒推送，5 分钟超时）
- 新增 useNotificationStream Hook（SSE + 轮询降级）
- NotificationDropdown 改用 SSE 实时推送

P2-12 测试覆盖:
- notifications/dispatcher.test.ts（6 个测试，渠道选择逻辑）
- notifications/channels/in-app-channel.test.ts（9 个测试，类型映射）
- messaging/schema.test.ts（34 个测试，Zod 校验）
- tests/e2e/messages.spec.ts（消息模块 E2E 测试）
- vitest.unit.config.ts 添加 server-only stub

P2-13a 通知发送日志持久化:
- 新增 notification_logs 表（userId/title/channel/status/messageId/error/sentAt）
- logNotificationSend 改为 async 写入 DB（失败降级 console）
- dispatcher 传递 payload 用于持久化

P2-13b 通知优先级和归档:
- messageNotifications 表新增 priority（low/normal/high/urgent）和 isArchived 字段
- getNotifications 支持归档和优先级筛选
- 新增 archiveNotificationAction
- NotificationList 显示优先级 Badge 和归档按钮

P2-13c 消息星标和草稿:
- messages 表新增 isStarred 字段
- 新增 message_drafts 表
- 新增 toggleMessageStar + 草稿 CRUD Server Actions
- 新增 5 个草稿 data-access 函数

P2-13d 公告已读回执和置顶:
- announcements 表新增 isPinned 字段
- 新增 announcement_reads 表（唯一索引保证幂等）
- 新增 toggleAnnouncementPinAction + markAnnouncementAsReadAction
- getAnnouncements 排序置顶优先

P2-13e 通知分类筛选和桌面推送:
- NotificationList 添加按类型筛选按钮组
- 新增 useDesktopNotifications Hook（浏览器 Notification API）
- NotificationDropdown 集成桌面推送（新通知触发）

架构图同步:
- 004 和 005 均已更新（新增表、Action、Hook、组件描述）
 2026-06-23 10:13:57 +08:00
SpecialX
696346dc08 fix(ai): V3 长期问题修复+规则合规+竞品对标 
## P1 安全加固
- 原子化每日限额（tryConsumeDailyQuota）解决 TOCTOU 竞态
- 流式端点补齐 Zod 校验 + rate limit + 服务端强制 systemPrompt
- 配额回退机制（refundDailyQuota）：过滤/失败不扣配额
- PII 最小化：移除 AI prompt 中的学生姓名

## P1 数据一致性
- 修复 capability 埋点缺失 child_summary/study_path 类型
- 创建 data-access.ts：真实统计聚合替代硬编码零
- 修复 generateChildSummary/recommendStudyPath 的 capability 标记

## P2 可靠性
- AI 调用重试机制（withRetry 指数退避，429/5xx，2 次重试）
- 30s 超时配置
- 流式 controller 安全 enqueue（防已关闭抛错）
- localStorage 防抖持久化（500ms，流式过程中跳过）

## P2 TypeScript/规则合规
- 移除 as 断言（VariantType 类型守卫、Permission 类型、StreamErrorKey）
- 补齐返回类型标注（POST/getStatusFromError/DashboardLayout）
- 拆分 use-ai-chat-stream hook（190→107 行，函数体≤80 行）
- 抽取 stream-utils.ts（SSE 解析/错误映射/消息工具）
- Tailwind 任意值添加注释说明（max-w-[80%] 聊天气泡）

## P3 竞品对标
- 苏格拉底式辅导强化（对标 Khanmigo）：
  - SOCRATIC_TUTOR_SYSTEM_PROMPT 3 级提示升级
  - 强化 STUDENT_BLOCKED_PATTERNS 正则（中英文答案拦截）
  - validateSocraticOutput 服务端校验（问号结尾+连续陈述句限制）
  - socratic_warning SSE 事件类型
- 知识图谱集成（对标 Squirrel AI）：
  - StudyPathInput 新增 knowledgeGraph/textbookId 字段
  - recommendStudyPathAction 自动从 textbooks 模块获取图谱+掌握度
  - STUDY_PATH_SYSTEM_PROMPT 增加前置依赖链规则
  - WEAKNESS_ANALYSIS_SYSTEM_PROMPT 增加 rootCause 字段

## 架构文档同步
- 004 更新 AI 模块章节（V3 标记/新导出/依赖关系/安全机制/文件清单）
- 005 更新 modules.ai 节点（dependsOn/exports/dataAccess/streamUtils/dependencyMatrix）
 2026-06-23 09:39:18 +08:00
SpecialX
036a2f2839 feat(exams,homework,proctoring): 长期问题修复与竞品差距补齐 
P1-1 跨模块直查消除：
- homework/data-access-classes.ts 移除对 exams/subjects 表的 JOIN 直查
- 改为调用 exams/data-access.getExamSubjectIdMap + school/data-access.getSubjectNameMapByIds
- school/data-access.ts 新增 getSubjectNameMapByIds 批量科目名称映射函数

P1-2 as 断言消除（exam-mode-config.tsx）：
- 移除全部 10 处 as 类型断言
- 改用 useFormContext 替代 Control prop，避免 Control<T> 不变型问题
- exam-form.tsx 调用方简化为 <ExamModeConfig />（已集成到考试表单）

P1-3 as 断言消除（proctoring-dashboard.tsx）：
- 用类型守卫函数 isProctoringEventType + toProctoringEventTypes
  替代 Object.keys(...) as ProctoringEventType[] 断言

P0-竞品倒计时（对标智学网/猿题库）：
- 新增 hooks/use-exam-countdown.ts 考试倒计时 Hook
- homework-take-view.tsx 集成限时/监考模式倒计时显示与到时自动提交
- data-access.ts 的 getStudentHomeworkTakeData 新增 examModeConfig + startedAt 字段
- types.ts 扩展 StudentHomeworkTakeData 类型
- i18n 补充 timedExam/timeRemaining/timeUpAutoSubmit 翻译键

架构文档同步：
- 004/005 更新 homework/proctoring/school/exams 模块导出与依赖关系
- 005 新增 homework.hooks.useExamCountdown 与 school.dataAccess.getSubjectNameMapByIds
- 005 依赖矩阵 homework→school 补充 getSubjectNameMapByIds

验证：tsc --noEmit 零错误，eslint 零错误（3 个预存 warning 无关）
 2026-06-23 09:34:24 +08:00
SpecialX
2c0f81391b feat(dashboard): 实现所有长期问题修复（P2-1/P2-5/P2-7/P2-9） 
P2-9: TeacherSchedule 重复渲染优化
- 将移动端（lg:hidden）和桌面端（hidden lg:block）的双实例渲染改为单实例
- 使用 CSS flex order + grid col-start/row-start 实现响应式布局重排序
- 消除服务端 HTML 负载翻倍问题

P2-5: StudentTodayScheduleCard 时间过时修复
- 新增 useCurrentTime hook（src/shared/hooks/use-current-time.ts）
- 每分钟自动更新当前时间，useMemo 依赖 [items, now] 确保徽章不过时
- SSR 安全：初始渲染用 new Date()，挂载后 setInterval 更新

P2-1: 流式/Suspense 架构改造
- 新增 getAdminDashboardStreams（streams.ts）：返回各独立数据源的未解析 Promise
- Admin dashboard：7 个分区组件用 React use() 独立消费 Promise，各 Suspense 边界独立流式渲染
- Teacher/Student/Parent dashboard：传入未解析 Promise，视图用 use() 消费，启用 Suspense 流式
- 页面外壳（标题 + 快捷操作）立即渲染，数据到达后各分区按各自速度填充

P2-7: 组件测试 + 路由测试修复
- 修复 dashboard-routing.test.ts：移除误导性的 permissions 字段（实际用 resolvePermissions(roles)）
- 新增 fallback 路由测试（未知角色 → teacher dashboard）
- 新增 DashboardSection 组件测试（6 个测试：骨架屏变体 + 错误边界 + 正常渲染）
- 新增 useCurrentTime hook 测试（3 个测试：初始值 + 间隔更新 + 清理）

同步更新:
- docs/architecture/005_architecture_data.json 新增 7 个流式组件 + useCurrentTime hook + getAdminDashboardStreams 条目
 2026-06-23 09:04:40 +08:00
SpecialX
e2e0487a3b feat(attendance,elective): 实现所有 P2 长期改进项 
P2 修复（来自审计报告）：
- 2.4.4: Server Action 错误消息 i18n 化（attendance/elective 全部 Action）
- 2.5.3: 抽取 AttendancePageLayout 组件复用（admin/teacher 页面）
- 2.5.4: 抽取 ElectivePageLayout 组件复用（admin/teacher 列表页）
- 2.6.3: 考勤月历键盘导航（tabIndex + 方向键 + Home/End + role=grid）
- 2.8.2: getStudentAttendanceSummary 分页优化（SQL 聚合统计 + LIMIT 分页）
- 2.8.3: resolveCourseDisplayNames 缓存优化（React cache 去重）
- 2.1.4: elective data-access 跨模块依赖接口抽象（resolvers.ts 可注入）

P2 建议项：
- 选课时间冲突检测（parseSchedule + isScheduleConflict 纯函数 + checkScheduleConflict）
- 学分上限校验（MAX_CREDIT_PER_TERM + checkCreditLimit）
- 考勤/选课数据导出 Excel（export.ts + API 路由扩展）

新增文件：
- src/modules/attendance/components/attendance-page-layout.tsx
- src/modules/elective/components/elective-page-layout.tsx
- src/modules/elective/resolvers.ts
- src/modules/attendance/export.ts
- src/modules/elective/export.ts

校验：
- npm run lint 通过（exit 0）
- npx tsc --noEmit attendance/elective/parent 相关零错误
 2026-06-23 09:02:41 +08:00
SpecialX
c766951374 feat(school,classes): 实现 P2 长期问题全量改进项 
P2-2: 新增 OrgTreeNav 组件（学校→年级→班级三级树形导航，支持搜索过滤/选中高亮/展开折叠）

P2-3: 新增 promoteGradesAction 年级升级功能（中文数字/阿拉伯数字识别，按 order 降序避免冲突）

P2-4: 新增 bulkEnrollStudentsAction（CSV 批量导入学生）+ bulkAssignSubjectTeachersAction（CSV 批量分配教师）

P2-5: 为 department/academicYear/grade 的 9 个 CRUD Action 补充 logAudit 审计日志

同步更新架构图文档 004/005
 2026-06-23 08:55:21 +08:00
SpecialX
4da9194a5e feat(ai): V2 深度增强 — SSE 流式/全局助手/内容安全/多角色覆盖 
对标 Khanmigo/Duolingo Max/Squirrel AI/Century Tech 实现：

- SSE 流式响应：createAiChatCompletionStream AsyncGenerator + /api/ai/chat/stream SSE 端点 + useAiChatStream hook（AbortController 停止生成 + localStorage 持久化）

- Markdown 渲染：AiMarkdownRenderer（react-markdown + remark-gfm + 代码块/表格/列表 + hover 复制按钮）

- 全局 AI 助手：AiAssistantWidget 浮动按钮 + Sheet 侧抽屉 + usePathname 路由推断上下文（7 类场景系统提示）+ dashboard layout 全局注入 AiClientProvider

- 内容安全：content-safety.ts 多层过滤（输入/输出安全过滤 + 每日限制 student 50/teacher 200/parent 30/admin 500 + 学生苏格拉底模式），COPPA/FERPA K12 合规

- 多角色 AI 覆盖：家长端 AiChildSummary（学情摘要）+ 管理员端 AiUsageDashboard（使用监控）+ 学生端 AiStudyPath（个性化学习路径）

- i18n 修复：8 处错误键引用 + zh-CN/en ai.json 全面扩展

- 架构文档 004/005 同步更新
 2026-06-23 01:34:37 +08:00
SpecialX
a60105455e feat(exams,homework,parent): V3 审计深度修复 — 批量批改/考试分析/提交反馈/家长视图/移动端优化 
V3-5: exam-actions.tsx 集成 useExamHomeworkFeatures hook，按角色控制菜单项可见性
V3-7: 批量批改 — 新增 batchAutoGradeSubmissions data-access + Server Action + HomeworkBatchGradingView 组件
V3-8: 考试分析仪表盘 — 新增 getExamAnalytics stats-service + ExamAnalyticsDashboard 组件 + /teacher/exams/[id]/analytics 路由
V3-9: 提交后即时反馈页 — 新增 HomeworkSubmissionResult 组件 + /student/learning/assignments/[id]/result 路由
V3-11: 家长考试详情 — 新增 ChildExamDetail 组件 + getStudentExamResults data-access + child-detail-panel exams Tab
V3-12: 移动端触控优化 — 题目导航与考试操作按钮 44px 最小触控目标

修复: instrumentation.ts 适配器补全 questionCount/averageScore/overdueCount 字段
修复: exam-homework-port.ts 类型导入对齐 ExamWithQuestionsForHomework
修复: trend-line-chart.tsx 数据类型允许 undefined（classAverage 可选场景）

同步更新 004/005 架构文档
 2026-06-23 01:06:27 +08:00
SpecialX
21c5eba96c feat(ai): 新增 AI 模块并集成至备课/错题集/试卷/改题四大业务场景 
- 新增 src/modules/ai 独立模块，遵循三层架构（actions → services → shared/lib/ai）
- 通过 AiClientProvider + useAiClient 实现 React Context 依赖注入，业务组件零直接 import
- 6 个 Server Actions 均调用 requirePermission() 权限校验，返回 ActionState<T>
- withAiTracking 统一埋点，覆盖 chat/similar_question/grading_assist/lesson_content/question_variant/weakness_analysis
- 集成场景：作业批改 AiGradingAssist、错题集 AiErrorBookAnalysis、备课 AiLessonContentGenerator、试卷 AiQuestionVariantGenerator
- 全量 i18n（en/zh-CN ai.json），Error Boundary + Skeleton 边界处理
- 同步架构图 004/005，新增审计报告 ai-module-audit-report.md
 2026-06-23 00:52:39 +08:00
SpecialX
ec87cd9efa fix(textbooks): 规范核查修复 — 安全漏洞+功能缺失+i18n+类型安全 
安全：createPrerequisiteAction 补充 prerequisiteKpId 归属校验；deletePrerequisiteAction 补充双知识点归属校验，防止跨教材越权。

功能：实现图谱添加/删除前置依赖（Dialog + Select 选择知识点 + 调用 Server Action + 自动刷新图谱），替换原 no-op 回调。

i18n：修复 8 处硬编码英文字符串（textbook-reader/chapter-sidebar-list/textbook-card/textbook-form-dialog/textbook-settings-dialog/create-chapter-dialog/teacher-textbook-reader），新增 saveFailed/createFailed/updateFailed/deleteFailed/questionCreatorDefaultContent 等 key。

类型安全：graph-prerequisite-edge.tsx 使用 GraphEdgeData 类型经 unknown 安全转换，替代裸 as 断言。

规范：analytics.tsx 移动 use client 指令到文件第一行；同步架构文档 005 JSON 类型定义（GraphNodeData/GraphEdgeData/MasteryLevel）。

验证：教材模块 lint 零错误、tsc 零错误、193 个单元测试全部通过。
 2026-06-23 00:30:14 +08:00
SpecialX
58656da983 feat(textbooks): 知识图谱功能全面重构 — 前置依赖 + dagre 布局 + React Flow 可视化 + 师生双视角 
将教材模块图谱从基本无用状态升级为完整知识图谱可视化系统。

数据层：新增 knowledgePointPrerequisites 表（复合主键+双外键 cascade）；新增 data-access-graph.ts（server-only）知识点关联聚合、学生/班级掌握度查询；utils.ts 新增 hasCycleAfterAddingEdge（DFS 循环依赖检测）。

业务层：3 个新 Server Action（getKnowledgeGraphDataAction 三视图模式、createPrerequisiteAction 含循环检测、deletePrerequisiteAction）；graph-layout.ts 重写为 dagre 分层有向图布局。

视图层：knowledge-graph.tsx 重写为 React Flow 主组件（全书视图+搜索高亮+关联节点高亮+章节着色）；4 个新组件（graph-kp-node/graph-prerequisite-edge/graph-toolbar/graph-node-detail-panel）；use-graph-data.ts 派生值模式避免 effect 中 setState。

架构：严格三层架构，客户端通过 Server Action 间接访问 server-only 数据层；权限校验+ i18n 全覆盖；架构文档 004/005 同步。

测试：utils.test.ts 新增 5 个循环检测测试，graph-layout.test.ts 重写 5 个 dagre 布局测试，全部 30 个教材模块单元测试通过。

附带提交 drizzle/0005 error-book 迁移文件以保持 journal 一致性。
 2026-06-23 00:13:03 +08:00
SpecialX
15aa84b72c refactor(school,classes): 完成 school/grade/class 审计全量改进项 
P0-1/P0-2: 删除 grade-management 死模块，年级 CRUD 统一由 school 模块负责

P0-3: classes/actions.ts 从 974 行拆分为 6 个职责文件 + barrel re-export

P0-5: 13 个页面 i18n 全量接入（grades/departments/academic-year/classes/insights）

P1-1: 角色硬编码改为 hasAdminScope/hasTeacherScope/hasStudentScope 基于 dataScope.type

P1-3: 新增 SchoolErrorBoundary + SchoolListSkeleton/SchoolCardSkeleton，4 个页面包裹 Error Boundary

P1-4: classes/types.ts 跨领域类型添加归属决策注释

P1-5: schools-view.tsx 拆分为组合模式（SchoolFormDialog + SchoolDeleteDialog + SchoolListToolbar）

P1-6: 新增 getSchoolsForUser/getGradesForUser 权限感知查询函数

P2-1: 抽取 useSchoolData hook，对话框状态管理与 UI 分离

同步更新架构图文档 004/005
 2026-06-22 18:54:01 +08:00
SpecialX
97e59b95a1 refactor(lesson-preparation): V2 审计深度修复 — Server Actions i18n + 错误码模式 + 类型断言清零 + a11y 深度修复 + Tracker 埋点接入 
V2-1: 12 个 Server Action 通过 getTranslations 翻译错误消息；Service/DataAccess 层抛出错误码异常（PublishServiceError/LessonPlanDataError），Actions 层通过 PUBLISH_ERROR_KEY_MAP 翻译为 i18n 消息
V2-2: SYSTEM_TEMPLATES name/title 改为 i18n 键，createLessonPlan 接受 translateTitle 函数在服务端翻译后存储到 DB
V2-3: 8 处 as unknown as 断言替换为显式类型映射函数（mapRowToLessonPlan/mapRowToListItem/mapRowToTemplate/mapRowToVersion）+ 类型守卫（isLessonPlanStatus/isTemplateType/isTemplateScope）
V2-4: MiniMap nodeColor 复用 lib/node-summary.ts 的 getNodeColor
V2-5: a11y 深度修复 — lesson-plan-filters/exercise-block/inline-question-editor 的 select 添加 label htmlFor 关联；exercise-block 题目列表改为 ul/li；node-editor 画布添加 role=application + 键盘导航配置
V2-6: Tracker 埋点接入 — 新增 useLessonPlanTrackerSafe hook，在 create/save/publish/revert/duplicate/archive 6 处调用 tracker.track

同步更新架构图 004 和 005 文档
 2026-06-22 18:45:35 +08:00
SpecialX
1fe30984b6 refactor(announcements,messaging,notifications): V1+V2 审计重构 — i18n 命名空间独立 + 通知标题 i18n 化 + 服务端过滤 + 编排下沉 + 表单错误展示 + 架构图同步 
V1 改进（已完成）:
- P0-4/P1-4/P1-5: 通知组件和 CRUD Action 从 messaging 迁移至 notifications 模块
- P1-5: 新增 getMessagesPageData / getAdminAnnouncementsPageData 编排函数
- P1-6: announcements schema 添加 superRefine 条件校验
- P1-7: 新增 useMessageSearch hook（防抖 + 请求竞态取消）+ 客户端分页 UI
- P1-9: deleteMessage 事务化
- P2-11: 全模块 trackEvent 埋点
- 全模块 i18n 接入 + Error Boundary + a11y 改进

V2 改进（本次完成）:
- V2-P0-1: 通知 i18n 命名空间独立（notifications.json），useTranslations 从 "messages" 切换到 "notifications"
- V2-P0-2: 公告/消息通知标题 i18n 化，Server Action 中使用 getTranslations 生成通知标题
- V2-P1-1: AnnouncementList 纯服务端过滤，移除客户端 useState/useMemo
- V2-P1-2: MessageList 客户端过滤仅在初始数据时执行，搜索结果由服务端按 tab 过滤
- V2-P1-3: 消息详情页编排下沉，新增 getMessageDetailPageData 编排函数
- V2-P1-4: 表单服务端校验错误展示（fieldErrors + aria-invalid）
- V2-P2-1: 轮询间隔常量化（POLL_INTERVAL_MS）
- V2-P2-2: 架构图同步（004 + 005）
 2026-06-22 18:43:12 +08:00
SpecialX
682d385ee2 fix(dashboard): v3 审计修复 — 数据完整性、i18n、类型安全、死代码清理 
P0 修复（严重）:
- admin ContentRow 标签与值错配（stats.users→textbooks 等 6 处）
- admin/error.tsx 硬编码中文替换为 useTranslations
- UserGrowthChart 空数据时渲染 EmptyState（userGrowth/homeworkTrend 永远为空数组）

P1 修复（高）:
- 新增 admin/dashboard 和 student/dashboard 的 loading.tsx + error.tsx
- 抽取 DashboardLoadingSkeleton 和 DashboardErrorFallback 共享组件，消除 5 套重复文件
- formatDate/formatLongDate 传入用户 locale（admin/teacher/student 共 6 个组件）
- 移除死代码：getCachedAdminDashboard、AvatarImage src={undefined}、TeacherStats isLoading prop
- filterTodaySchedule 改为泛型函数，消除 as 类型断言
- 辅助函数 getStatus/getDueUrgency 新增显式返回类型
- UserGrowthChart 新增 labelKey prop 区分用户增长/作业提交趋势标签

P2 修复（中）:
- 4 个组件从客户端转为服务端组件（DashboardGreetingHeader、TeacherQuickActions、TeacherDashboardHeader、StudentDashboardHeader）
- Student dashboard 空状态新增 CTA（viewSchedule、viewAll）
- TeacherHomeworkCard 图标按钮新增 aria-label
- TeacherTodoCard 排序逻辑重写为可读的 if/return 模式

同步更新:
- docs/architecture/005_architecture_data.json 新增 DashboardLoadingSkeleton、DashboardErrorFallback 条目
- 新增 docs/architecture/audit/dashboard-audit-report-v3.md 审计报告
- dashboard.json 新增 6 个 i18n 键（textbooks/chapters/questions/exams/totalAssignments/totalSubmissions）
 2026-06-22 18:36:46 +08:00
SpecialX
76966581b8 docs(architecture): 同步 005 JSON — 补充备课模块 providers/services 文件清单 + i18n + auditFixes 字段 
- modules.lesson_preparation.files 新增 providers/lesson-plan-provider.tsx 和 services/default-data-service.ts
- 新增 i18n 字段记录 lessonPreparation 命名空间和消息文件路径
- 新增 auditFixes 字段记录 P0-1/P0-2/P0-3/P1-1/P1-2/P1-3/P1-4/P1-5/P1-7/P1-8/P2-1/P2-4 修复项
 2026-06-22 17:11:40 +08:00
SpecialX
5f3a1a4662 refactor(grades,diagnostic): 完成成绩和学情诊断模块审计 P1+P2 改进项 
P1-1: 抽取 stats-service.ts，将 8 个统计计算纯函数从 data-access 层分离
P1-5: 创建 WidgetBoundary 组件 + 补齐 teacher 路由 loading.tsx/error.tsx (14 文件)
P1-6: 同步架构图文档 004/005，新增 stats-service 与 widget-boundary 节点
P2-1: 补充 a11y ARIA 属性（5 图表 role=img + aria-label，2 表格 caption，3 列表 role=list，3 按钮 aria-label）
P2-3: 修复班级报告 studentId 字段语义错误（schema 改为可空 + 迁移 + 代码适配）
P2-4: 修复 grade_managed scope 返回空数据（改为子查询 classes 表按 gradeId 过滤）
P2-5: 新增 /parent/diagnostic/ 页面（多子女学情诊断聚合 + loading + error）
P2-6: 统一 SearchParams 工具（student/grades 和 management/grade/insights 改用 @/shared/lib/search-params）
 2026-06-22 17:07:32 +08:00
SpecialX
e997abaf5e refactor(dashboard): V2 审计重构 — i18n 补齐 + 共享抽象 + 单测 + a11y 
V2 审计报告（docs/architecture/audit/dashboard-audit-report-v2.md）发现并修复：

- P0 i18n：10 个子组件硬编码字符串全部接入 next-intl（teacher-quick-actions /
  teacher-classes-card / teacher-homework-card / teacher-schedule /
  recent-submissions / teacher-grade-trends / student-grades-card /
  student-today-schedule-card / student-upcoming-assignments-card /
  admin-dashboard），新增 ~50 个翻译键
- P1 共享抽象：新增 DashboardGreetingHeader 组件，消除 teacher/student
  头部 90% 重复代码，两个 Header 改为薄包装
- P2 单测：为 6 个纯函数添加 31 个单元测试
  （tests/integration/dashboard/dashboard-utils.test.ts）
- P2 a11y：admin 表格 caption、teacher/student 视图语义化标签
  （header / section aria-label / aside aria-label）
- 同步架构图 004/005
 2026-06-22 17:01:00 +08:00