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](file:///e:/Desktop/CICD/src/proxy.ts)

### 2. MySQL 端口切换 + 数据库创建脚本
- `.env` 中 MySQL 端口从 13002 改为 14013
- 新增 `scripts/create-db.ts`：连接 MySQL（不指定库）后执行 `CREATE DATABASE IF NOT EXISTS next_edu`，字符集 utf8mb4_unicode_ci
- 主要修改：[.env](file:///e:/Desktop/CICD/.env)、[create-db.ts](file:///e:/Desktop/CICD/scripts/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](file:///e:/Desktop/CICD/scripts/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](file:///e:/Desktop/CICD/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](file:///e:/Desktop/CICD/src/modules/classes/data-access.ts)

### 2. 验证
- 质量检查：`npm run lint`、`npm run typecheck` 均通过。

## 2026-03-02

### 1. 班级详情访问修复（基于会话身份）
- 将数据获取中的教师 ID 来源改为会话用户，移除默认教师 ID 逻辑，修复“新加入班级无法查看班级详情”问题。
- 主要修改：
  - [data-access.ts](file:///e:/Desktop/CICD/src/modules/classes/data-access.ts)
  - [page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/classes/my/%5Bid%5D/page.tsx)

### 2. 任课权限与班主任权限区分（学科可见范围）
- 班主任可查看班级下所有学科；任课老师仅可查看自己负责的学科。
- 新增并应用分配学科查询，过滤相应统计与列表。
- 主要修改：
  - [data-access.ts](file:///e:/Desktop/CICD/src/modules/classes/data-access.ts)

### 3. 新注册学生默认班级问题修复
- 调整示例学生获取逻辑，避免为新注册学生展示“默认班级”。
- 主要修改：
  - [data-access.ts](file:///e:/Desktop/CICD/src/modules/homework/data-access.ts)

### 4. 教材列表 UI 精简为纯色风格
- 将教材卡片头部背景从渐变与纹理改为简洁纯色；图标容器调整为简洁样式，视觉噪音更低。
- 主要修改：
  - [textbook-card.tsx](file:///e:/Desktop/CICD/src/modules/textbooks/components/textbook-card.tsx)

### 5. 学生导航清理未实现入口
- 移除学生侧导航的“Resources”入口（页面未实现，避免死链）。
- 主要修改：
  - [navigation.ts](file:///e:/Desktop/CICD/src/modules/layout/config/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).