NextEdu/docs/work_log.md

Work Log

2026-06-17

架构全面审查与文档重构

问题背景

用户反馈:架构文档阅读后仍无法理解各模块、函数关系,说明文档质量不足或代码耦合度过高。006/007 及其他文档长期未更新。

完成工作

1. 全项目逐文件审查(4 份审查报告)

• docs/architecture/audit/shared-audit.md - shared 基础设施层(69 文件,15 问题)
• docs/architecture/audit/core-business-audit.md - 核心业务模块(exams/homework/questions/textbooks/grades)
• docs/architecture/audit/management-modules-audit.md - 管理模块(school/classes/scheduling/attendance/users/audit/course-plans/announcements)
• docs/architecture/audit/new-and-other-modules-audit.md - 新增模块和其他模块(elective/proctoring/diagnostic/notifications/dashboard/messaging/parent/settings/files/auth/layout/student)
• docs/architecture/audit/00_summary.md - 汇总报告

2. 发现的关键问题

P0 严重问题(6 项):

1. classes/data-access.ts 2104 行,超硬上限 2.1 倍,混入 homework/scheduling/grades 逻辑
2. homework/data-access.ts 1038 行,超硬上限,混入排名计算
3. shared/lib ↔ auth 循环依赖
4. dashboard/data-access.ts 直查 11 张跨模块表
5. messaging 绕过 notifications 直接写通知
6. classSchedule 表三处写入口(数据完整性风险)

P1 较严重问题(6 项):

• 跨模块直接 DB 查询普遍存在(classes 被 8+ 处直接查询)
• actions 层混入数据访问逻辑
• auth.ts 混合 5 类职责
• users/import-export.ts 四重职责
• proctoring/exam-mode-config.tsx 死代码
• notifications 反向依赖 messaging

3. 重写架构文档(5 份)

• 004 架构影响地图:从"罗列函数签名"重构为"图优先 + 结构化",含分层架构图、模块依赖关系图(标注合理/违规/循环依赖)、数据流向图、核心调用链路、26 个模块清单、P0/P1/P2 问题分级与解耦建议
• 005 架构数据 JSON:新增 architectureOverview、moduleDependencyGraph(25 节点 37 边)、knownIssues(12 问题)、dbTables(54 表按业务域分组)节点;补全 permissions(52→54)、apiRoutes(10→11)
• 006 功能清单:添加"当前实现状态"列,143 个功能项标注 ✅/⚠️/❌,P0 覆盖率 80%→92%
• 007 差距审计报告:v2→v3,总体完成度 P0 69%→84%,P2 路线图 8/14=57%,新增架构技术债章节
• 001 项目概览:更新为 6 角色/54 权限/26 模块/54 表,新增架构原则和项目状态章节

4. 文档治理

• 创建 docs/README.md 文档索引(架构/审查/专题/归档分类)
• 11 个过时文档添加"已归档"标注(002×2/003/设计文档×8)
• 所有文档保持活跃维护与归档分离

验证

• 待验证 lint + tsc

---

P2 质量保障类实现（5 项全部完成）

1. 屏幕阅读器兼容性增强（a11y）

• 新增无障碍工具库：src/shared/lib/a11y.ts（useA11yId/mergeA11yProps/describeInput/loadingAria）
• 新增 Hook：src/shared/hooks/use-aria-live.ts（aria-live 区域管理）
• 新增组件：src/shared/components/a11y/（skip-link/visually-hidden/focus-trap/aria-status）
• 增强 UI 组件：table.tsx 添加系统性 ARIA role，dialog.tsx 添加 aria-modal
• 审计文档：docs/accessibility/a11y-audit.md（含 WCAG 2.1 AA 合规清单）

2. 视觉回归测试（Visual Regression）

• 配置：tests/visual/visual.config.ts（3 视口 × 2 主题）
• 测试套件：homepage/admin-dashboard/teacher-dashboard/student-dashboard
• 辅助函数：auth.ts（登录态管理）、visual-helpers.ts（视口/主题/遮罩）
• 更新 playwright.config.ts：新增 visual-chromium 项目，maxDiffPixelRatio 0.01
• 文档：docs/testing/visual-regression.md

3. 短信/微信推送渠道集成（notifications）

• 新增模块：src/modules/notifications/
• 渠道实现：SMS（阿里云/腾讯云/Mock）、WeChat（公众号模板消息）、Email（Nodemailer SMTP）、In-App
• 分发器：按用户通知偏好并行多渠道发送
• Server Actions：sendNotificationAction、sendClassNotificationAction
• 外部 SDK 动态 import，Mock 模式开发环境可用
• 配置：.env.example，文档：docs/notifications/channels.md

4. 漏洞扫描 CI 集成（security）

• 增强 CI：security-scan job（npm audit + Snyk + Trivy FS + OWASP ZAP）
• 独立工作流：.gitea/workflows/security.yml（每周一深度扫描，含容器镜像扫描）
• 配置：.gitea/suppressions.json（Snyk 抑制）、.trivyignore（Trivy CVE 忽略）
• 本地脚本：scripts/security-scan.sh + scripts/security-scan.ps1
• 文档：docs/security/scanning.md（含 SLA：critical 24h/high 7d/medium 30d/low 90d）

5. 灾备方案（DR）

• 脚本：backup-verify.sh（完整性校验）、backup-offsite-sync.sh（S3/OSS/NFS 异地同步）、dr-drill.sh/ps1（灾备演练）、failover.sh（故障切换）、health-check.sh（健康检查）
• CI 增强：scheduled-backup 添加校验+异地同步，新增 weekly-dr-drill job
• 独立工作流：.gitea/workflows/dr-drill.yml（每周一凌晨 4 点自动演练）
• 文档：docs/dr/dr-plan.md（RTO 4h/RPO 24h）、docs/dr/dr-runbook.md（6 大故障场景操作手册）
• 配置：.env.example 灾备环境变量

验证

• npx tsc --noEmit：0 错误
• npm run lint：0 错误 0 警告

---

P2 功能扩展类实现（功能扩展 + 质量保障首批）

1. 选课管理模块（elective）

• 新增 schema 表：electiveCourses（选修课程）、courseSelections（选课记录）
• 新增权限：ELECTIVE_MANAGE、ELECTIVE_READ、ELECTIVE_SELECT
• 模块文件：src/modules/elective/（types/schema/data-access×3/actions/components×3）
• 路由：admin/teacher/student 三端 elective 页面
• 支持：先到先得 + 抽签两种选课模式，容量控制，退选

2. 考试监考模块（proctoring）

• 新增 schema：exams 表扩展 examMode/durationMinutes/antiCheatEnabled 等字段；新增 examProctoringEvents 表
• 新增权限：EXAM_PROCTOR、EXAM_PROCTOR_READ
• 模块文件：src/modules/proctoring/（types/data-access/actions/components×3）
• API 路由：/api/proctoring/event 接收学生端上报
• 页面：教师监考面板 + 学生端防作弊监控（tab切换/复制粘贴/右键/开发者工具/全屏退出/空闲超时检测）

3. 学情诊断报告模块（diagnostic）

• 新增 schema：knowledgePointMastery（知识点掌握度）、learningDiagnosticReports（诊断报告）
• 新增权限：DIAGNOSTIC_MANAGE、DIAGNOSTIC_READ
• 模块文件：src/modules/diagnostic/（types/data-access×2/actions/components×4）
• 功能：基于提交答案自动计算知识点掌握度，生成个人/班级诊断报告（强项/弱项/建议），雷达图可视化
• 页面：teacher 诊断管理 + 学生查看自己报告

4. 项目规则更新

• .trae/rules/project_rules.md 单文件行数限制从 300 行调整为企业级规范：
  • React 组件 ≤ 500 行（复杂场景可放宽至 800）
  • Server Actions / Data Access ≤ 800 行
  • 硬性上限 1000 行

5. 种子脚本 lint 修复

• scripts/seed.ts 消除全部 any 类型（17 个 error → 0）
• 定义内部类型：SeedQuestion/SeedQuestionBank/SeedGradeRecord/SeedAttendanceRecord
• 移除未使用参数，函数签名精简

6. 架构文档同步

• docs/architecture/004_architecture_impact_map.md 新增 elective/proctoring/diagnostic 三个模块章节
• docs/architecture/005_architecture_data.json 同步权限点、角色映射、dbTables、modules、dependencyMatrix、routes

验证

• npx tsc --noEmit：0 错误
• npm run lint：0 错误 0 警告

---

前序工作（同日早些时候）

1. Next.js 16 Proxy 修复

• src/proxy.ts 导出函数从 middleware 重命名为 proxy（Next.js 16 要求）
• 修复 getToken() 在 edge 运行时缺少 secret 导致的 MissingSecret 错误
• 显式传入 secret: process.env.NEXTAUTH_SECRET
• 主要修改：proxy.ts

2. MySQL 端口切换 + 数据库创建脚本

• .env 中 MySQL 端口从 13002 改为 14013
• 新增 scripts/create-db.ts：连接 MySQL（不指定库）后执行 CREATE DATABASE IF NOT EXISTS next_edu，字符集 utf8mb4_unicode_ci
• 主要修改：.env、create-db.ts

3. 种子脚本完全重写（小学场景）

• 完全重写 scripts/seed.ts，实现小学完整场景初始化
• 数据规模：
  • 1 所学校（实验小学）、2 个年级（一/二年级）、每年级 2 个班级
  • 8 名教师（每班 2 名：1 班主任 + 1 科任，跨班覆盖语数外 3 科）
  • 24 名学生（每班 6 名）+ 24 名家长
  • 3 科教材（语数外各 1 本）+ 章节 + 知识点
  • 15 道题目（每科 5 道：单选/文本/判断）
  • 2 套试卷（语文/数学）+ 24 份提交 + 120 个答案
  • 2 套作业 + 6 份提交 + 30 个答案
  • 课表、成绩、考勤、课程计划、公告等完整数据
  • 6 个角色 + 47 个权限点的 RBAC 映射（149 条记录）
• 17 个顺序步骤，耗时约 127s
• 主要修改：seed.ts

4. 迁移脚本系统重构

• 问题：旧迁移系统存在多个缺陷
  • 0011_ai_providers.sql 未在 _journal.json 中注册，导致 drizzle-kit migrate 失败
  • 缺少多数 snapshot 文件（仅存 0008、0009）
  • 迁移 SQL 使用复杂 PREPARE/EXECUTE 条件模式，维护困难
• 修复：清理全部旧迁移文件与 meta 目录，使用 drizzle-kit generate 从 schema 重新生成
  • 生成单一迁移文件 0000_perfect_pestilence.sql，包含全部 49 张表
  • journal 重置为单条记录，snapshot 完整
• 新增 npm 脚本（package.json）：
  • db:create：创建数据库
  • db:push：直接同步 schema（开发用）
  • db:setup：一键 create → migrate → seed
• 主要修改：package.json、drizzle/ 目录

5. 验证

• 干净数据库全流程测试：db:create → db:migrate → db:seed 全部通过
• 49 张表成功创建，种子数据完整写入
• 测试账号（密码均为 123456）：
  • 管理员: admin@xiaoxue.edu.cn
  • 语文老师/一年级1班班主任: t_chinese_1@xiaoxue.edu.cn
  • 数学老师: t_math_1@xiaoxue.edu.cn
  • 英语老师: t_english_1@xiaoxue.edu.cn
  • 学生: student_g1c1_1@xiaoxue.edu.cn
  • 家长: parent_g1c1_1@xiaoxue.edu.cn

2026-03-19

1. 作业与权限测试覆盖补齐（第二阶段）

• 新增角色路由与代理守卫集成测试：
  • tests/integration/dashboard-routing.test.ts
  • tests/integration/proxy-guard.test.ts
• 扩展 onboarding 完成接口集成测试，覆盖班级-学科映射与教师分配逻辑：
  • tests/integration/api-onboarding-complete.route.test.ts
• 新增认证业务流 E2E（注册 -> 登录 -> 受保护区域）：
  • tests/e2e/auth-business-flow.spec.ts
• 新增并补齐作业流程集成测试，覆盖创建、开始作答、提交、批改、保存答案：
  • tests/integration/homework-create-assignment.test.ts
  • tests/integration/homework-actions.test.ts
• saveHomeworkAnswerAction 增加关键分支用例：
  • started 状态首次保存答案（insert）
  • started 状态更新已有答案（update）

2. 验证

• npm run test:integration：通过（7 文件，38 用例）
• npm run lint：通过
• npm run typecheck：通过
• npm run test:e2e：通过（40 通过，1 跳过）
• 语言诊断：无错误

2026-03-18

1. 企业级测试体系落地（第一阶段）

• 新增集成测试与 E2E 基础设施：
  • vitest.config.ts
  • playwright.config.ts
  • tests/setup/integration.setup.ts
• 新增接口集成测试：
  • tests/integration/api-ai-chat.route.test.ts
  • tests/integration/api-onboarding-status.route.test.ts
  • tests/integration/api-onboarding-complete.route.test.ts
• 新增认证冒烟 E2E：
  • tests/e2e/smoke-auth.spec.ts
• 新增全路由回归 E2E：
  • tests/e2e/full-route-regression.spec.ts
• 新增工程脚本：
  • test、test:ci、test:integration、test:e2e、test:e2e:smoke、test:e2e:full-routes
• 更新 CI 质量门禁：
  • 增加 Playwright Chromium 安装
  • 增加集成测试执行
  • 增加 E2E 全量回归测试执行

2. 验证

• npm run lint：通过
• npm run typecheck：通过
• npm run test:integration：通过（3 文件，10 用例）
• npm run build：通过
• npm run test:e2e:smoke：通过（本地使用系统 Chrome 通道，2 用例通过）
• npm run test:e2e:full-routes：通过（38 用例通过）

2026-03-03

1. 教师加入班级学科分配逻辑修复

• 修复教师已在班级中但选择学科加入时被直接返回成功的问题。
• 班级未创建该学科映射时，先补齐映射再分配。
• 学科已被其他老师占用时，返回明确提示。
• 主要修改：
  • data-access.ts

2. 验证

• 质量检查：npm run lint、npm run typecheck 均通过。

2026-03-02

1. 班级详情访问修复（基于会话身份）

• 将数据获取中的教师 ID 来源改为会话用户，移除默认教师 ID 逻辑，修复“新加入班级无法查看班级详情”问题。
• 主要修改：
  • data-access.ts
  • page.tsx

2. 任课权限与班主任权限区分（学科可见范围）

• 班主任可查看班级下所有学科；任课老师仅可查看自己负责的学科。
• 新增并应用分配学科查询，过滤相应统计与列表。
• 主要修改：
  • data-access.ts

3. 新注册学生默认班级问题修复

• 调整示例学生获取逻辑，避免为新注册学生展示“默认班级”。
• 主要修改：
  • data-access.ts

4. 教材列表 UI 精简为纯色风格

• 将教材卡片头部背景从渐变与纹理改为简洁纯色；图标容器调整为简洁样式，视觉噪音更低。
• 主要修改：
  • textbook-card.tsx

5. 学生导航清理未实现入口

• 移除学生侧导航的“Resources”入口（页面未实现，避免死链）。
• 主要修改：
  • navigation.ts

6. 验证

• 质量检查：npm run lint、npm run typecheck 均通过。

2026-02-24

1. Credentials 登录与密码安全修复

• 密码哈希规范化：
  • 注册时统一生成标准 bcrypt 前缀（$2a/$2b/$2y），确保数据库内哈希格式一致。
  • 登录时对非标准前缀（如 $10$...）自动补全为 $2b$... 再校验，避免格式不一致导致登录失败。
• 登录一致性修复：
  • 登录校验不再对密码做 trim()，避免前后空格导致的 bcrypt 比对失败。
• 调试排障（已回收）：
  • 临时加入安全日志定位失败原因（不输出明文），定位后已移除。

2. 验证

• npm run typecheck：通过
• npm run lint：存在既有告警（未新增）

2026-01-15

1. Schedule Module Optimization

• Visual Overhaul (schedule-view.tsx):

  • Refactored the schedule grid to match the exact design of the ClassScheduleGrid widget.
  • Implemented a clean, borderless layout with no grid lines for a modern look.
  • Time-Based Positioning: Replaced grid-row logic with absolute positioning based on time (8:00 - 18:00 range) using percentage calculations (getPositionStyle).
  • Color Coding: Added getSubjectColor to auto-assign thematic colors (blue for Math, purple for Physics, etc.) based on course names.
  • Card Design: Refined course cards with vertical centering, better spacing, and removed unnecessary UI elements (like the "+" button in headers).

• Filter Bar Refinement (schedule-filters.tsx):

  • Minimalist Design: Removed borders and shadows from the class selector and buttons to integrate seamlessly with the background.
  • Center Label: Added a dynamic, absolute-centered text label that updates based on selection:
    • Shows "All Classes" when no filter is active.
    • Shows "{Class Name}" when a specific class is selected.
  • Simplified Controls: Removed the "Reset" button (X icon) entirely for a cleaner interface.
  • Ghost Buttons: Styled the "Add Event" button as a ghost variant with muted colors.

2. Architecture & Cleanup

• Insights Module Removal:
  • Deleted the entire src/app/(dashboard)/teacher/classes/insights directory as the feature was deemed redundant.
  • Removed insights-filters.tsx component.
  • Updated navigation.ts to remove the "Insights" link from the sidebar.
  • Note: Preserved getClassHomeworkInsights in data-access.ts as it's still used by the Class Detail dashboard widgets.

3. Verification

• Type Safety: Ran npm run typecheck multiple times during refactoring to ensure no regressions (Passed).
• Build: Attempted to clear build cache to resolve a chunk loading error (Windows permission issue encountered but workaround applied).

2026-01-14

1. Class Management Refactoring (Role Separation)

• Separation of Duties:

  • Moved class creation and management responsibilities from the generic Teacher view to a dedicated Management view.
  • Created Grade Management Page at src/app/(dashboard)/management/grade/classes/page.tsx for Grade Directors and Admins.
  • Teachers can now only Join Classes (via code) or view their assigned classes in "My Classes".

• New Components & Pages:

  • GradeClassesView (src/modules/classes/components/grade-classes-view.tsx): A comprehensive table view for managing classes within specific grades, supporting creation, editing, and deletion.
  • GradeClassesPage: Server Component that fetches managed grades and classes using strict RBAC (Role-Based Access Control).

• Teacher "My Classes" Update (my-classes-grid.tsx):

  • Removed the "Create Class" button/dialog.
  • Added a "Join Class" dialog that accepts a 6-digit invitation code.
  • Updated styling to use standard design system colors (bg-card, border-border) instead of hardcoded gradients.

2. Backend & Logic Updates

• Data Access (data-access.ts):

  • Implemented getGradeManagedClasses: Fetches classes for grades where the user is either a Grade Head or Teaching Head.
  • Implemented getManagedGrades: Fetches the list of grades managed by the user for the creation dropdown.
  • Updated getTeacherClasses: Now returns both owned classes (assigned by admin) and enrolled classes (joined via code).
  • Fixed a SQL syntax error in getGradeManagedClasses (unescaped backticks in template literal).

• Server Actions (actions.ts):

  • Added createGradeClassAction, updateGradeClassAction, deleteGradeClassAction: These actions enforce that the user manages the target grade before performing operations.
  • Updated joinClassByInvitationCodeAction: Expanded to allow Teachers (role teacher) to join classes, not just Students.

3. Verification

• RBAC: Verified that users can only manage classes for grades they are assigned to.
• Flow: Verified Teacher "Join Class" flow correctly redirects and updates the list.
• Syntax: Fixed TypeScript/SQL syntax errors in the new data access functions.

4. Class UI/UX Optimization

• Students Management Interface (students-table.tsx, students-filters.tsx):

  • Enhanced Table: Added student avatars, gender display, and join date.
  • Pagination: Implemented client-side pagination (10 items per page) to handle larger classes gracefully.
  • Status Filtering: Added "Active/Inactive" filter with visual status badges (Emerald for active, muted for inactive).
  • Data Access: Updated getClassStudents to fetch extended user profile data and support server-side status filtering.

• Class Detail Dashboard (/teacher/classes/my/[id]/page.tsx):

  • Dashboard Layout: Refactored into a responsive two-column layout (Main Content + Sidebar).
  • Key Metrics: Added a 4-card stats grid at the top displaying critical insights:
    • Total Students (Active/Inactive breakdown)
    • Schedule Items (Weekly sessions)
    • Active Assignments (Overdue count)
    • Class Average (Based on graded submissions)
  • Sidebar Widgets: Added "Class Schedule" and "Homework History" widgets for quick access to temporal data.
  • Visual Polish: Integrated lucide-react icons throughout for better information scanning.

2026-01-13

1. Navigation & Layout Improvements

• Dynamic Breadcrumbs (site-header.tsx):
  • Replaced hardcoded "Dashboard > Overview" breadcrumbs with a dynamic system.
  • Implemented a path-to-title lookup using NAV_CONFIG from src/modules/layout/config/navigation.ts.
  • Added logic to filter out root role segments (admin/teacher/student/parent) for cleaner paths.
  • Added fallback capitalization for segments not found in the config.
  • Refactored SiteHeader to use usePathname for real-time route updates.

2. Code Quality & Bug Fixes

• Type Safety (homework-grading-view.tsx):
  • Fixed a TypeScript error where a boolean expression was returning boolean | undefined which is not a valid React node (implicit true check added).
  • Resolved "Calling setState synchronously within an effect" React warning by initializing state lazily instead of using useEffect.
  • Fixed implicit any type errors in map functions.
• Linting:
  • Cleaned up unused imports across multiple files (exam-actions.tsx, exam-assembly.tsx, textbook-reader.tsx, etc.).
  • Fixed unescaped HTML entities in student-dashboard-header.tsx and others.
  • Removed unused variables to clear ESLint warnings.
• Refactoring:
  • Updated TextbookCard to support hideActions prop for better reuse in student views.
  • Added missing Progress component to src/shared/components/ui/progress.tsx.

3. Verification

• Ran npm run typecheck: Passed (0 errors).
• Ran npm run lint: Passed (0 errors, 28 warnings remaining for unused vars/components that may be needed later).