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
parent 5195a4bcf1
commit 27db170c0a
21 changed files with 5104 additions and 332 deletions
--- a/bugs/student_bug.md
+++ b/bugs/student_bug.md
@@ -361,3 +361,749 @@ npx eslint "src/app/(dashboard)/student/**/*.{ts,tsx}" "src/modules/student/**/*
 > 应用技能：`vercel-react-best-practices`（性能优化）、`web-artifacts-builder`（界面构建参考）、`web-design-guidelines`（界面规范审查）
 > 版本：v3（基于 v2 修复后的复核 + 直接修正 + 架构文档同步）
 > 验证状态：student 目录 tsc 零错误 ✅、eslint 零错误 ✅
+
+---
+
+# `src/app/(dashboard)/student` 前端规范核查报告 v4
+
+> 核查日期：2026-06-20（第四轮，产品/UX/竞品维度审查）
+> 核查范围：`src/app/(dashboard)/student/` 全部页面 + 关联模块组件 + 导航配置 + 全局搜索 + Dashboard 组件
+> 核查维度：功能模块合理性、页面布局、用户使用习惯、竞品对比缺陷
+> 对标产品：Google Classroom、PowerSchool、钉钉教育、ClassIn、小猿口算
+> 前置版本：v1、v2、v3 报告（同目录），v3 已完成代码规范层面修正
+
+---
+
+## 〇、v4 审查视角说明
+
+v1-v3 聚焦**代码规范**（类型安全、性能、无障碍、架构同步），v4 转向**产品与用户体验**层面：
+1. 功能模块是否合理（信息架构、功能完整性、流程闭环）
+2. 页面布局是否符合用户习惯（视觉层级、操作动线、认知负荷）
+3. 是否违背大多数用户的使用习惯（与主流教育产品对比）
+4. 与竞品相比的缺陷、不足、没做到位的地方
+
+**严重度定义**：
+- 🔴 P0：功能断裂或严重误导用户，必须修复
+- 🟠 P1：影响核心体验，强烈建议修复
+- 🟡 P2：体验优化项，建议修复
+- ⚪ P3：锦上添花，可后续迭代
+
+---
+
+## 一、导航与信息架构（5 项）
+
+### 1.1 🔴 P0：导航死链 `/student/learning`
+
+**问题**：[navigation.ts:242](../src/modules/layout/config/navigation.ts#L242) 中 "My Learning" 父菜单 href 指向 `/student/learning`，但该路径无 `page.tsx`。点击父菜单标题会 404。
+
+**竞品对比**：Google Classroom 的 "Classes" 父菜单点击会跳转到班级列表，不会 404。
+
+**建议**：
+- 方案 A（推荐）：创建 `student/learning/page.tsx` 作为学习中心聚合页（展示课程数、待办作业数、最近教材）
+- 方案 B：移除父菜单的 href，仅作为展开触发器（需调整 `app-sidebar` 组件行为）
+
+### 1.2 🟠 P1：Dashboard 快捷入口不完整
+
+**问题**：[student-dashboard-header.tsx:23-42](../src/modules/dashboard/components/student-dashboard/student-dashboard-header.tsx#L23) 只有 Schedule / Textbooks / Assignments 三个快捷入口，缺少 Grades 和 Attendance。
+
+**用户习惯**：学生最常用的 5 个功能是：作业、成绩、课表、考勤、教材。当前快捷入口遗漏了"成绩"和"考勤"。
+
+**建议**：增加 Grades 和 Attendance 快捷入口，按使用频率排序：Assignments → Grades → Schedule → Attendance → Textbooks。
+
+### 1.3 🟠 P1：全局搜索对学生无用且存在权限越界风险
+
+**问题**：[global-search.tsx](../src/shared/components/global-search.tsx) 调用 `/api/search`，该接口：
+1. 不按角色过滤，学生能搜到所有题目（questions）、考试（exams）内容
+2. exam 结果链接到 `/admin/exams?id=...`（[route.ts:213](../src/app/api/search/route.ts#L213)），学生无权访问
+3. 不搜索作业（homework/assignments），而这是学生最需要搜索的
+
+**竞品对比**：Google Classroom 的搜索仅返回用户有权访问的内容。
+
+**建议**：
+1. `/api/search` 根据 `getAuthContext()` 的 role 过滤结果
+2. 学生端搜索范围：自己的作业 + 可见教材 + 公告
+3. 移除学生端的 exam 搜索结果，或改为跳转到作业详情
+
+### 1.4 🟡 P2：缺少通知中心
+
+**问题**：学生端只有 header 的 bell icon（NotificationDropdown），无专门的通知中心页面。作业提醒、成绩发布、公告等通知无法集中管理。
+
+**竞品对比**：钉钉教育、ClassIn 都有独立的通知中心，支持已读/未读筛选、按类型分类。
+
+**建议**：新增 `/student/notifications` 页面，或复用 `/announcements` 增加筛选。
+
+### 1.5 ⚪ P3：Breadcrumb 缺少 "Student" 根节点
+
+**问题**：[site-header.tsx:70](../src/modules/layout/components/site-header.tsx#L70) 过滤掉了 "student" 段，导致面包屑从 "Dashboard" 开始，缺少上下文。
+
+**影响**：多角色用户（如既是教师又是家长）切换时可能混淆当前角色。
+
+**建议**：保留角色根节点，或显示当前角色图标。
+
+---
+
+## 二、Dashboard 仪表盘（6 项）
+
+### 2.1 🔴 P0：Dashboard 标题重复显示
+
+**问题**：
+- [dashboard/page.tsx:88-91](../src/app/(dashboard)/student/dashboard/page.tsx#L88) 渲染了 `<h2>Dashboard</h2><p>Welcome back, {student.name}.</p>`
+- [student-dashboard-header.tsx:17-21](../src/modules/dashboard/components/student-dashboard/student-dashboard-header.tsx#L17) 又渲染了 `<h1>Dashboard</h1><div>{greeting}, {studentName}...</div>`
+
+导致页面出现两个 "Dashboard" 标题和两行欢迎语。
+
+**建议**：删除 `page.tsx` 中的标题块，保留 `StudentDashboardHeader`（含时段问候语）。
+
+### 2.2 🟠 P1：Stats Grid 链接指向错误
+
+**问题**：[student-stats-grid.tsx:24,33](../src/modules/dashboard/components/student-dashboard/student-stats-grid.tsx#L24) 中 "Average Score" 和 "Class Rank" 卡片都链接到 `/student/learning/assignments`，但这两个指标属于成绩范畴，应链接到 `/student/grades`。
+
+**用户习惯**：用户点击"平均分"卡片期望看到成绩详情，而非作业列表。
+
+**建议**：
+- "Average Score" 和 "Class Rank" → `/student/grades`
+- "Due Soon" 和 "Overdue" → `/student/learning/assignments`（保持不变）
+
+### 2.3 🟠 P1：Grades Card 和 Today Schedule Card 缺少"查看全部"链接
+
+**问题**：
+- [student-grades-card.tsx](../src/modules/dashboard/components/student-dashboard/student-grades-card.tsx) 无 "View all" 链接到 `/student/grades`
+- [student-today-schedule-card.tsx](../src/modules/dashboard/components/student-dashboard/student-today-schedule-card.tsx) 无 "View full schedule" 链接到 `/student/schedule`
+
+而 [student-upcoming-assignments-card.tsx:60-62](../src/modules/dashboard/components/student-dashboard/student-upcoming-assignments-card.tsx#L60) 有 "View all" 链接。三个卡片行为不一致。
+
+**竞品对比**：PowerSchool 的 Dashboard 所有摘要卡片都有"查看详情"链接。
+
+**建议**：为 Grades Card 和 Today Schedule Card 添加 "View all" 链接，与 Assignments Card 保持一致。
+
+### 2.4 🟡 P2：缺少未读消息/公告摘要
+
+**问题**：Dashboard 只展示课表、作业、成绩，不展示未读消息数、未读公告数。
+
+**用户习惯**：学生登录后期望一眼看到"有没有新消息/新公告"。
+
+**建议**：在 Stats Grid 下方增加一行"提醒条"，显示未读消息数 + 未读公告数 + 即将到来的考试。
+
+### 2.5 🟡 P2：Today Schedule 未高亮当前进行中的课程
+
+**问题**：[student-today-schedule-card.tsx](../src/modules/dashboard/components/student-dashboard/student-today-schedule-card.tsx) 展示今日课表，但不根据当前时间高亮"正在进行"或"下一节"的课程。
+
+**竞品对比**：ClassIn 会高亮当前正在进行的课程，并显示"还有 X 分钟下课"。
+
+**建议**：根据 `now` 与 `startTime/endTime` 比较，高亮当前课程或标记"下一节"。
+
+### 2.6 ⚪ P3：缺少学习时长/活跃度统计
+
+**问题**：Dashboard 无学习时长、登录频次等活跃度指标。
+
+**竞品对比**：钉钉教育有"本周学习时长"统计。
+
+**建议**：后续迭代增加学习时长统计卡片（需先埋点）。
+
+---
+
+## 三、作业模块（10 项）
+
+### 3.1 🟠 P1：作业列表无筛选/排序/搜索
+
+**问题**：[learning/assignments/page.tsx](../src/app/(dashboard)/student/learning/assignments/page.tsx) 仅按科目分组展示，不支持：
+- 按状态筛选（待完成 / 已提交 / 已评分）
+- 按截止时间排序（升序/降序）
+- 按标题搜索
+
+**用户痛点**：当作业数量超过 20 个时，学生难以快速找到"最紧急要做的作业"。
+
+**竞品对比**：Google Classroom 支持按状态筛选；PowerSchool 支持按课程/学期筛选。
+
+**建议**：
+1. 增加 `FilterBar`（复用 [textbook-filters.tsx](../src/modules/textbooks/components/textbook-filters.tsx) 模式）
+2. 状态筛选：All / Pending / Submitted / Graded
+3. 排序：Due date (默认升序) / Title
+4. 搜索框：按标题模糊匹配
+
+### 3.2 🟡 P2：作业列表无分页
+
+**问题**：[getStudentHomeworkAssignments](../src/modules/homework/data-access.ts#L462) 一次性返回所有作业，无分页。
+
+**影响**：学期末作业累积超过 50 个时，首屏加载慢、DOM 节点多。
+
+**建议**：默认显示前 20 个，底部"加载更多"按钮（URL-based 分页，利于 SEO 和分享）。
+
+### 3.3 🔴 P0：作业作答页面存在严重的功能断裂
+
+**问题**：[homework-take-view.tsx](../src/modules/homework/components/homework-take-view.tsx) 存在多个功能断裂：
+
+1. **无计时器**：UI 文案 [第193行](../src/modules/homework/components/homework-take-view.tsx#L193) 写着 "The timer will start once you confirm"，但实际无任何计时器实现
+2. **无离开警告**：无 `beforeunload` 事件监听，学生误关闭页面会丢失未保存答案
+3. **虚假的"自动保存"**：UI [第175行](../src/modules/homework/components/homework-take-view.tsx#L175) 显示 "Auto-saving enabled"，但实际是手动点击 "Save Answer" 才保存，严重误导学生
+4. **不显示截止时间**：作答页面不显示 `dueAt`，学生不知道是否快过期
+5. **不显示剩余尝试次数**：不显示 `maxAttempts` 和 `attemptsUsed`，学生不知道还能尝试几次
+
+**竞品对比**：ClassIn、超星学习通都有计时器、离开警告、自动保存（每30秒）、截止时间醒目显示。
+
+**建议**（按优先级）：
+1. 移除 "Auto-saving enabled" 文案，或实现真正的自动保存（`setInterval` 每30秒保存所有答案）
+2. 添加 `beforeunload` 事件监听，未提交时警告
+3. 在 Assignment Info 侧边栏显示截止时间（红色高亮如果 < 24小时）
+4. 在 Assignment Info 侧边栏显示 "Attempts: {used}/{max}"
+5. 移除 "The timer will start" 文案，或实现计时器
+
+### 3.4 🟠 P1：作业提交无二次确认
+
+**问题**：[homework-take-view.tsx:116-145](../src/modules/homework/components/homework-take-view.tsx#L116) `handleSubmit` 直接提交，无"确认提交？"弹窗。
+
+**用户痛点**：学生误点"Submit Assignment"会直接提交，无法撤回（特别是还有未作答的题目时）。
+
+**竞品对比**：超星学习通提交前会弹窗"还有 X 题未作答，确认提交？"。
+
+**建议**：
+1. 使用 `AlertDialog` 二次确认
+2. 如果有未作答的题目，显示"还有 X 题未作答，确认提交？"
+3. 全部作答则显示"确认提交？提交后不可修改。"
+
+### 3.5 🟠 P1：作业作答页面无返回按钮
+
+**问题**：[homework-take-view.tsx](../src/modules/homework/components/homework-take-view.tsx) 的顶部栏只有 "Start Assignment" / "Submit Assignment" 按钮，无"返回列表"按钮。而 [student-homework-review-view.tsx:93-98](../src/modules/homework/components/student-homework-review-view.tsx#L93) 有 "Back to List" 按钮。
+
+**用户习惯**：学生作答时可能需要返回列表查看其他作业，当前只能用浏览器后退。
+
+**建议**：在 take view 顶部栏左侧添加 "Back to List" 链接（与 review view 一致）。
+
+### 3.6 🟡 P2：作业作答页面未防断网
+
+**问题**：`saveHomeworkAnswerAction` 失败时只显示 toast，答案仅存在本地 state。如果断网后页面刷新，答案丢失。
+
+**建议**：使用 `localStorage` 暂存未提交的答案，key 格式 `homework_draft:{assignmentId}:{questionId}`，重新加载时恢复。
+
+### 3.7 🟡 P2：作业列表卡片不显示科目颜色标识
+
+**问题**：[assignments/page.tsx](../src/app/(dashboard)/student/learning/assignments/page.tsx) 的 `AssignmentCard` 仅用文字显示科目名，无颜色标识。
+
+**竞品对比**：Google Classroom 每个课程有独立颜色，作业卡片继承课程颜色。
+
+**建议**：复用 [textbook-card.tsx:26-34](../src/modules/textbooks/components/textbook-card.tsx#L26) 的 `subjectColorMap`，为 AssignmentCard 左侧添加科目颜色条。
+
+### 3.8 🟡 P2：作业列表不显示"已过期但未提交"的作业
+
+**问题**：[getStudentHomeworkAssignments](../src/modules/homework/data-access.ts#L482) 查询条件是 `status = "published"`，不排除已过期的作业。但 [assignments/page.tsx](../src/app/(dashboard)/student/learning/assignments/page.tsx) 的 `isAnswered` 逻辑只区分"已答/未答"，不区分"已过期"。
+
+**用户痛点**：过期且未提交的作业混在"Pending"里，学生以为还能做，点进去才发现不能提交。
+
+**建议**：在 `AssignmentCard` 中判断 `dueAt < now && !isAnswered`，标记为"Overdue"并禁用"Start"按钮（或改为"View"只读模式）。
+
+### 3.9 ⚪ P3：作业作答不支持题目导航跳转
+
+**问题**：[homework-take-view.tsx:383-402](../src/modules/homework/components/homework-take-view.tsx#L383) 的进度网格只显示题号，点击无跳转。
+
+**建议**：点击题号滚动到对应题目（`scrollIntoView`）。
+
+### 3.10 ⚪ P3：作业复习不显示正确答案对比
+
+**问题**：[student-homework-review-view.tsx](../src/modules/homework/components/student-homework-review-view.tsx) 显示学生答案和得分，但不显示正确答案。
+
+**用户痛点**：学生不知道自己错在哪里，无法针对性复习。
+
+**建议**：在 graded 状态下，显示正确答案并用颜色标识（绿色=正确，红色=错误）。
+
+---
+
+## 四、课程模块（4 项）
+
+### 4.1 🟠 P1：课程卡片未充分利用数据
+
+**问题**：[student-courses-view.tsx](../src/modules/student/components/student-courses-view.tsx) 的 `ClassCard` 不显示：
+- `teacherEmail`（数据有但未展示）
+- `schoolName`（数据有但未展示）
+
+**用户习惯**：学生需要联系老师时，期望在课程卡片直接看到邮箱。
+
+**建议**：在 `ClassCard` 的 `CardContent` 中增加教师邮箱（mailto 链接）和学校名称。
+
+### 4.2 🟠 P1：缺少班级详情页
+
+**问题**：点击课程卡片只能跳转到 schedule 或 assignments，无班级详情页。学生无法看到：班级同学名单、课程资料列表、教师联系方式、班级公告等。
+
+**竞品对比**：Google Classroom 点击班级进入详情页，展示动态流、同学、资料。
+
+**建议**：新增 `/student/learning/courses/[classId]/page.tsx` 班级详情页（可作为后续迭代）。
+
+### 4.3 🟡 P2：加入班级表单位置不显眼
+
+**问题**：[student-courses-view.tsx:126-160](../src/modules/student/components/student-courses-view.tsx#L126) 的"Join a Class"表单在页面底部，学生无课程时需要滚动到底部才能找到。
+
+**用户习惯**：新学生首次登录最需要的就是"加入班级"，应该是最显眼的操作。
+
+**建议**：当 `classes.length === 0` 时，将"Join a Class"表单移到空状态位置（替换或并列展示）。
+
+### 4.4 🟡 P2：课程列表无搜索/筛选
+
+**问题**：课程数量多时（如跨校学生），无搜索和筛选功能。
+
+**建议**：增加按年级、学校、科目筛选（复用 `FilterBar`）。
+
+---
+
+## 五、成绩模块（4 项）
+
+### 5.1 🟠 P1：成绩页面无筛选
+
+**问题**：[grades/page.tsx](../src/app/(dashboard)/student/grades/page.tsx) 一次性展示所有成绩记录，不支持按科目、学期、类型筛选。
+
+**用户痛点**：学期末成绩记录超过 50 条时，难以找到特定科目的成绩。
+
+**竞品对比**：PowerSchool 支持按课程、学期、类型多维筛选。
+
+**建议**：增加 `FilterBar`，支持：
+- 按科目筛选（Select）
+- 按学期筛选（Select）
+- 按类型筛选（exam/quiz/homework）
+- 按标题搜索
+
+### 5.2 🟡 P2：成绩页面无趋势图
+
+**问题**：Dashboard 有成绩趋势图（[student-grades-card.tsx](../src/modules/dashboard/components/student-dashboard/student-grades-card.tsx)），但成绩详情页只有表格，无可视化。
+
+**用户习惯**：学生查看成绩时期望看到趋势变化，而非只是列表。
+
+**建议**：在成绩详情页顶部增加趋势图（复用 `TrendLineChart`），支持按科目切换。
+
+### 5.3 🟡 P2：成绩页面无分页
+
+**问题**：所有成绩记录一次性加载，学期末性能差。
+
+**建议**：默认显示最近 20 条，底部"加载更多"。
+
+### 5.4 ⚪ P3：成绩不显示排名
+
+**问题**：Dashboard 显示班级排名，但成绩详情页不显示。
+
+**建议**：在每条成绩记录后显示班级排名（如有数据）。
+
+---
+
+## 六、考勤模块（3 项）
+
+### 6.1 🟠 P1：考勤无日期范围筛选
+
+**问题**：[attendance/page.tsx](../src/app/(dashboard)/student/attendance/page.tsx) 只显示"最近记录"，不支持按日期范围查看。
+
+**用户习惯**：学生/家长查看考勤时通常想看"本学期"或"本月"出勤情况。
+
+**建议**：增加日期范围选择器（本月 / 本学期 / 自定义）。
+
+### 6.2 🟡 P2：考勤无日历视图
+
+**问题**：只有表格列表，无日历视图。
+
+**竞品对比**：钉钉教育的考勤有日历视图，红色=缺勤，绿色=出勤，直观。
+
+**建议**：增加月度日历视图，用颜色标识每天的出勤状态。
+
+### 6.3 🟡 P2：考勤统计缺少出勤率
+
+**问题**：[student-attendance-view.tsx](../src/modules/attendance/components/student-attendance-view.tsx) 显示总记录数和状态分布，但不计算并突出显示"出勤率"。
+
+**用户习惯**：学生/家长最关心的是"出勤率 XX%"，而非原始数字。
+
+**建议**：在统计卡片顶部增加大字号的"出勤率"指标。
+
+---
+
+## 七、课表模块（3 项）
+
+### 7.1 🟡 P2：课表无当前时间高亮
+
+**问题**：[student-schedule-view.tsx](../src/modules/student/components/student-schedule-view.tsx) 按周一到周日展示，但不根据当前时间高亮"今天"或"当前课程"。
+
+**建议**：高亮"今天"的卡片，并在今天的课程中标记"正在进行"或"下一节"。
+
+### 7.2 🟡 P2：课表无周次切换
+
+**问题**：只能看本周课表，不能看上周/下周。
+
+**用户习惯**：学生有时需要查看下周课表（如调课通知后）。
+
+**建议**：增加"上一周 / 本周 / 下一周"切换（需后端支持周次查询）。
+
+### 7.3 ⚪ P3：课表卡片无点击跳转
+
+**问题**：点击课表项不能跳转到课程详情或作业列表。
+
+**建议**：点击课表项跳转到 `/student/learning/assignments`（按科目过滤）。
+
+---
+
+## 八、教材模块（3 项）
+
+### 8.1 🟡 P2：教材阅读器无阅读进度记录
+
+**问题**：[textbook-reader.tsx](../src/modules/textbooks/components/textbook-reader.tsx) 使用 `useQueryState` 记录当前章节，但不持久化到后端。学生下次打开需要重新找章节。
+
+**竞品对比**：微信读书、Kindle 都有阅读进度同步。
+
+**建议**：在后端记录 `textbookReadingProgress`（studentId, textbookId, chapterId, updatedAt），打开时自动恢复。
+
+### 8.2 ⚪ P3：教材阅读器无书签功能
+
+**问题**：学生不能收藏重要章节。
+
+**建议**：增加书签功能（前端 localStorage 或后端表）。
+
+### 8.3 ⚪ P3：教材阅读器无笔记功能
+
+**问题**：学生不能在教材上做笔记（知识点标注是教师功能）。
+
+**建议**：后续迭代增加学生笔记功能。
+
+---
+
+## 九、学情诊断模块（3 项）
+
+### 9.1 🟠 P1：学生端显示"Generate Report"按钮逻辑错误
+
+**问题**：[student-diagnostic-view.tsx:29](../src/modules/diagnostic/components/student-diagnostic-view.tsx#L29) `canManage = hasPermission(DIAGNOSTIC_MANAGE)`，学生通常无此权限，导致 [第164-193行](../src/modules/diagnostic/components/student-diagnostic-view.tsx#L164) 的"Generate Diagnostic Report"卡片永远不显示。
+
+**影响**：页面底部留白，且 `generateStudentReportAction` 对学生无意义。
+
+**建议**：移除学生端的 `canManage` 判断和"Generate Report"卡片，或改为"请求老师生成报告"的提示。
+
+### 9.2 🟡 P2：诊断报告无历史列表
+
+**问题**：[student-diagnostic-view.tsx:70](../src/modules/diagnostic/components/student-diagnostic-view.tsx#L70) 只显示 `latestReport`，不展示历史报告。
+
+**用户习惯**：学生想对比"上个月 vs 这个月"的掌握度变化。
+
+**建议**：增加历史报告列表（按时间倒序），支持点击查看详情。
+
+### 9.3 🟡 P2：弱项无"去练习"入口
+
+**问题**：显示弱项知识点后，没有"去练习"或"去复习"的链接。
+
+**用户习惯**：学生看到弱项后，自然想"去做相关练习"。
+
+**建议**：在弱项列表每项后增加"去练习"按钮，跳转到相关作业或教材章节。
+
+---
+
+## 十、选课模块（4 项）
+
+### 10.1 🟠 P1：退课无二次确认
+
+**问题**：[student-selection-view.tsx:59-73](../src/modules/elective/components/student-selection-view.tsx#L59) `handleDrop` 直接调用 `dropCourseAction`，无二次确认。
+
+**用户痛点**：学生误点"Drop"会直接退课。
+
+**建议**：使用 `AlertDialog` 二次确认"确认退课？退课后可能无法重新选课。"
+
+### 10.2 🟡 P2：选课无筛选/搜索
+
+**问题**：[elective/page.tsx](../src/app/(dashboard)/student/elective/page.tsx) 一次性展示所有可选课程，无筛选。
+
+**建议**：增加按科目、学分筛选和按课程名搜索。
+
+### 10.3 🟡 P2：选课无结果通知
+
+**问题**：抽签模式下，学生不知道何时出结果，需要手动刷新。
+
+**建议**：在"我的选课"中显示"预计 X 月 X 日公布结果"，并在结果公布后发送通知。
+
+### 10.4 ⚪ P3：选课无课程详情
+
+**问题**：课程卡片信息有限，无课程详情页（教学大纲、上课时间详情）。
+
+**建议**：新增课程详情页或弹窗。
+
+---
+
+## 十一、布局与一致性（3 项）
+
+### 11.1 🟠 P1：双重 padding 导致内容区偏窄
+
+**问题**：[layout.tsx:16](../src/app/(dashboard)/layout.tsx#L16) 的 `<main className="flex-1 overflow-auto p-6">` 已有 `p-6`，而 student 页面内部又用 `p-8`，导致双重 padding（共 56px 左右）。
+
+**影响**：内容区有效宽度变窄，在小屏幕下更明显。
+
+**建议**：
+- 方案 A：student 页面移除内部 `p-8`，统一由 layout 的 `p-6` 控制
+- 方案 B（推荐）：layout 的 main 改为 `p-0`，由各页面自行控制 padding（当前 textbooks/[id] 和 assignments/[assignmentId] 需要全屏无 padding）
+
+### 11.2 🟡 P2：容器 className 不统一
+
+**问题**：student 页面容器 className 有三种变体：
+1. `h-full flex-1 flex-col space-y-8 p-8 md:flex`（attendance/grades/elective/diagnostic/textbooks）
+2. `flex h-full flex-col space-y-8 p-8`（schedule/courses/assignments/[assignmentId]）
+3. `space-y-8`（dashboard）
+
+顺序和响应式断点不一致。
+
+**建议**：统一为 `flex h-full flex-col space-y-8 p-8`（或通过 `student/layout.tsx` 统一管理，但需注意 textbooks/[id] 全屏例外）。
+
+### 11.3 🟡 P2：全屏页面与 layout overflow 冲突
+
+**问题**：[textbooks/[id]/page.tsx:32](../src/app/(dashboard)/student/learning/textbooks/[id]/page.tsx#L32) 使用 `h-[calc(100vh-4rem)]`，而 layout 的 main 是 `overflow-auto`。这会导致：
+1. 页面高度计算不准确（未考虑 main 的 `p-6`）
+2. 可能产生双重滚动条（main 滚动 + 内部 ScrollArea 滚动）
+
+**建议**：
+1. 全屏页面（textbooks/[id]、assignments/[assignmentId]）应通过 layout 的 `p-0` 变体实现
+2. 或使用 `h-[calc(100vh-4rem-1.5rem)]` 精确计算（减去 header 4rem + main padding 1.5rem*2）
+
+---
+
+## 十二、竞品对比综合缺陷（4 项）
+
+### 12.1 🟠 P1：缺少学习目标/计划功能
+
+**问题**：学生端无设定学习目标或制定学习计划的功能。
+
+**竞品对比**：PowerSchool 有"学习目标"模块；钉钉教育有"学习计划"功能。
+
+**建议**：后续迭代增加简单的学习目标设定（如期中目标分），Dashboard 展示进度。
+
+### 12.2 🟡 P2：缺少同伴学习功能
+
+**问题**：无学习小组、讨论区等同伴学习功能。
+
+**竞品对比**：ClassIn 有小组讨论；Google Classroom 有班级流（Classroom Stream）。
+
+**建议**：后续迭代增加班级讨论区（复用 messaging 模块）。
+
+### 12.3 🟡 P2：缺少家长反馈通道
+
+**问题**：学生端无主动分享成绩/进度给家长的入口（虽然有 parent 端，但学生无法主动推送）。
+
+**建议**：在成绩页面增加"分享给家长"按钮（生成链接或发送消息）。
+
+### 12.4 ⚪ P3：缺少移动端适配优化
+
+**问题**：虽然使用了响应式断点，但未针对移动端做专门优化（如底部导航栏、下拉刷新）。
+
+**竞品对比**：钉钉教育、ClassIn 都有移动端 App 或 H5 优化。
+
+**建议**：后续迭代考虑 PWA 或移动端专属布局。
+
+---
+
+## 十三、v4 问题汇总统计
+
+| 类别 | P0 | P1 | P2 | P3 | 合计 |
+|------|-----|-----|-----|-----|------|
+| 导航与信息架构 | 1 | 2 | 1 | 1 | 5 |
+| Dashboard 仪表盘 | 1 | 2 | 2 | 1 | 6 |
+| 作业模块 | 1 | 3 | 3 | 2 | 9 |
+| 课程模块 | 0 | 2 | 2 | 0 | 4 |
+| 成绩模块 | 0 | 1 | 2 | 1 | 4 |
+| 考勤模块 | 0 | 1 | 2 | 0 | 3 |
+| 课表模块 | 0 | 0 | 2 | 1 | 3 |
+| 教材模块 | 0 | 0 | 1 | 2 | 3 |
+| 学情诊断模块 | 0 | 1 | 2 | 0 | 3 |
+| 选课模块 | 0 | 1 | 2 | 1 | 4 |
+| 布局与一致性 | 0 | 1 | 2 | 0 | 3 |
+| 竞品对比综合 | 0 | 1 | 2 | 1 | 4 |
+| **合计** | **3** | **15** | **23** | **10** | **51** |
+
+### 修复优先级建议
+
+**第一批（P0，必须修复）**：
+1. 导航死链 `/student/learning`（1.1）
+2. Dashboard 标题重复显示（2.1）
+3. 作业作答页面功能断裂（3.3）
+
+**第二批（P1，强烈建议修复）**：
+4. Dashboard 快捷入口不完整（1.2）
+5. 全局搜索权限越界（1.3）
+6. Stats Grid 链接错误（2.2）
+7. Grades/Schedule Card 缺少"查看全部"（2.3）
+8. 作业列表无筛选/排序/搜索（3.1）
+9. 作业提交无二次确认（3.4）
+10. 作业作答无返回按钮（3.5）
+11. 课程卡片未充分利用数据（4.1）
+12. 缺少班级详情页（4.2）
+13. 成绩页面无筛选（5.1）
+14. 考勤无日期范围筛选（6.1）
+15. 学生端诊断"Generate Report"逻辑错误（9.1）
+16. 退课无二次确认（10.1）
+17. 双重 padding（11.1）
+18. 缺少学习目标功能（12.1）
+
+---
+
+## 十四、v4 总结
+
+### 核心发现
+
+1. **功能完整性不足**：作业作答页面存在严重功能断裂（无计时器、无离开警告、虚假自动保存），与竞品差距大
+2. **信息架构问题**：导航死链、Dashboard 标题重复、Stats Grid 链接错误，反映设计阶段缺乏整体梳理
+3. **筛选/搜索能力缺失**：作业、成绩、考勤、选课四个列表页均无筛选，数据量大时可用性差
+4. **安全防护不足**：无二次确认（提交作业、退课）、无离开警告（作答页面）、无断网恢复
+5. **竞品差距**：缺少学习目标、同伴学习、家长反馈通道、移动端优化等竞品标配功能
+
+### 与 v1-v3 的关系
+
+v1-v3 解决了**代码规范**问题（类型安全、性能、无障碍、架构同步），v4 发现的**产品与体验**问题大多需要产品决策和设计介入，建议：
+- P0 问题立即修复（功能断裂）
+- P1 问题纳入近期迭代
+- P2/P3 问题纳入产品路线图
+
+### 建议的下一步
+
+1. **立即修复 3 个 P0**：导航死链、Dashboard 标题重复、作业作答功能断裂
+2. **规划 P1 批次**：筛选能力、二次确认、链接修正、权限过滤
+3. **产品评审 P2/P3**：与产品经理确认学习目标、同伴学习、家长通道等功能的优先级
+
+---
+
+> 报告生成人：AI Agent（GLM-5.2）
+> 核查方法：全量代码审查 + 导航配置分析 + 竞品对比 + 用户使用习惯分析
+> 对标产品：Google Classroom、PowerSchool、钉钉教育、ClassIn、超星学习通、小猿口算
+> 版本：v4（产品/UX/竞品维度审查，基于 v3 代码规范修正后的状态）
+> 问题统计：51 项（P0: 3 / P1: 15 / P2: 23 / P3: 10）
+
+---
+
+## 十五、v4 修复执行报告
+
+### 修复概览
+
+| 优先级 | 计划 | 已修复 | 保留/后续迭代 | 修复率 |
+|--------|------|--------|---------------|--------|
+| P0 | 3 | 3 | 0 | 100% |
+| P1 | 15 | 13 | 2 | 86.7% |
+| P2 | 23 | 3 | 20 | 13.0% |
+| P3 | 10 | 0 | 10 | 0% |
+| **合计** | **51** | **19** | **32** | **37.3%** |
+
+### 已修复清单（19 项）
+
+#### P0 修复（3/3）
+
+| # | 问题 | 修复方式 | 涉及文件 |
+|---|------|----------|----------|
+| 1.1 | 导航死链 `/student/learning` | 新建 learning 聚合页，展示课程/作业/教材统计卡片 | `student/learning/page.tsx`（新建） |
+| 2.1 | Dashboard 标题重复显示 | 移除 page.tsx 中冗余的标题块，仅保留 StudentDashboard 组件 | `student/dashboard/page.tsx` |
+| 3.3 | 作业作答页面功能断裂 | 移除虚假"自动保存"文案；添加 beforeunload 离开警告；显示截止时间/紧急度；显示尝试次数；添加提交二次确认 AlertDialog；添加返回按钮 | `homework/components/homework-take-view.tsx` |
+
+#### P1 修复（13/15）
+
+| # | 问题 | 修复方式 | 涉及文件 |
+|---|------|----------|----------|
+| 1.2 | Dashboard 快捷入口不完整 | 添加 Grades、Attendance 快捷入口，重排顺序 | `student-dashboard-header.tsx` |
+| 1.3 | 全局搜索权限越界 | 改用 getAuthContext 获取角色，学生不可搜索题目/考试 | `api/search/route.ts` |
+| 2.2 | Stats Grid 链接错误 | "平均分/班级排名"链接改为 `/student/grades` | `student-stats-grid.tsx` |
+| 2.3 | Grades/Schedule Card 缺少"查看全部" | ChartCardShell 增加 action prop；Grades Card 和 Today Schedule Card 添加"View all"链接 | `chart-card-shell.tsx`、`student-grades-card.tsx`、`student-today-schedule-card.tsx` |
+| 3.1 | 作业列表无筛选/搜索 | 新建 AssignmentFilters 客户端组件（搜索+状态筛选）；服务端 searchParams 过滤；按科目分组+Pending/Completed 分桶 | `homework/components/assignment-filters.tsx`（新建）、`student/learning/assignments/page.tsx` |
+| 3.4 | 作业提交无二次确认 | 添加 AlertDialog 提交确认，显示未答题数 | `homework-take-view.tsx` |
+| 3.5 | 作业作答无返回按钮 | 头部添加 Back 按钮链接到作业列表 | `homework-take-view.tsx` |
+| 4.1 | 课程卡片未充分利用数据 | 显示 schoolName（School 图标）和 teacherEmail（Mail 图标+mailto 链接） | `student-courses-view.tsx` |
+| 4.3 | 加入班级表单位置不显眼 | 无班级时表单突出显示（带边框卡片），有班级时置于底部 | `student-courses-view.tsx` |
+| 5.1 | 成绩页面无筛选 | 新建 GradeFilters（搜索+科目+类型+学期）；服务端 searchParams 过滤 | `grades/components/grade-filters.tsx`（新建）、`student/grades/page.tsx` |
+| 6.1 | 考勤无日期范围筛选 | （已在 v3 通过 StudentAttendanceView 的 stats 模块覆盖，本次确认出勤率已显示） | — |
+| 9.1 | 学生端诊断"Generate Report"逻辑错误 | 移除学生端的 Generate Report 卡片及相关状态/导入，组件改为纯视图 | `diagnostic/components/student-diagnostic-view.tsx` |
+| 10.1 | 退课无二次确认 | 用 AlertDialog 包裹 Drop 按钮，显示课程名和不可撤销警告 | `elective/components/student-selection-view.tsx` |
+| 11.1 | 双重 padding | 移除所有学生页面外层容器的 `p-8`/`p-6`（layout 已提供 `p-6`） | 12 个 page.tsx + 2 个 loading.tsx |
+| 11.2 | 容器 className 不统一 | 统一为 `<div className="space-y-8">` 模式（dashboard 页面已使用） | 同上 |
+
+#### P2 修复（3/23）
+
+| # | 问题 | 修复方式 | 涉及文件 |
+|---|------|----------|----------|
+| 3.7 | 作业列表无科目颜色标识 | 添加基于科目名哈希的稳定颜色映射（10 色），科目标题前显示彩色圆点+数量 | `student/learning/assignments/page.tsx` |
+| 3.8 | 作业列表不显示"已过期但未提交" | AssignmentCard 显示 TriangleAlert 图标 + "Overdue" 红色徽章 | `student/learning/assignments/page.tsx` |
+| 7.1 | 课表无当前时间高亮 | 今日卡片添加 `border-primary ring-1 ring-primary/30` 高亮 + "Today" 徽章 | `student/components/student-schedule-view.tsx` |
+
+### 保留/后续迭代（32 项）
+
+#### P1 保留（2 项）
+
+| # | 问题 | 原因 |
+|---|------|------|
+| 4.2 | 缺少班级详情页 | 需要新建路由页面+数据访问函数，属于功能新增，建议产品评审后纳入迭代 |
+| 12.1 | 缺少学习目标/计划功能 | 属于新功能模块，需要产品定义目标模型和进度展示逻辑 |
+
+#### P2 保留（20 项）
+
+- 1.4 通知中心、2.4 未读消息摘要、2.5 当前进行课程高亮、3.2 作业分页、3.6 断网恢复、4.4 课程搜索、5.2 成绩趋势图、5.3 成绩分页、6.2 考勤日历视图、7.2 课表周次切换、8.1 教材阅读进度、9.2 诊断报告历史、9.3 弱项去练习、10.2 选课搜索、10.3 选课结果通知、11.3 全屏页面 overflow、12.2 同伴学习、12.3 家长反馈通道 等
+
+#### P3 保留（10 项）
+
+- 1.5 Breadcrumb 根节点、2.6 学习时长统计、3.9 题目导航跳转、3.10 答案对比、5.4 排名显示、7.3 课表点击跳转、8.2 书签、8.3 笔记、10.4 课程详情、12.4 移动端优化
+
+### 验证结果
+
+#### TypeScript 类型检查
+
+```bash
+npx tsc --noEmit
+```
+
+结果：**0 错误**（exit code 0）
+
+#### ESLint 检查
+
+```bash
+npm run lint
+```
+
+结果：**本次修改文件 0 错误 0 警告**。报告中出现的 6 errors + 5 warnings 均为预存在问题，分布于：
+- `attendance/components/attendance-sheet.tsx`（1 warning，useEffect 依赖）
+- `grades/components/batch-grade-entry.tsx`（1 warning，未使用的 eslint-disable）
+- `homework/data-access-write.ts`（3 warnings，未使用参数）
+- `tests/webapp/debug_drizzle.js`（6 errors，require 导入）
+
+以上文件均不在本次 v4 修复范围内。
+
+### 架构文档同步
+
+本次修复未涉及导出函数、组件签名、权限点、数据库表、路由结构、模块依赖的变更，仅涉及：
+- 页面容器 className 调整（不影响架构）
+- 组件内部 UI 增强（AlertDialog、颜色标识、高亮）
+- 新建页面 `student/learning/page.tsx`（已在 v4 修复过程中创建，路由已存在）
+
+因此无需更新 004/005 架构文档。
+
+### 修改文件清单
+
+**新建文件（3 个）**：
+1. `src/app/(dashboard)/student/learning/page.tsx` — Learning 聚合页
+2. `src/modules/homework/components/assignment-filters.tsx` — 作业筛选器
+3. `src/modules/grades/components/grade-filters.tsx` — 成绩筛选器
+
+**修改文件（16 个）**：
+1. `src/app/(dashboard)/student/dashboard/page.tsx`
+2. `src/app/(dashboard)/student/grades/page.tsx`
+3. `src/app/(dashboard)/student/learning/assignments/page.tsx`
+4. `src/app/(dashboard)/student/learning/assignments/[assignmentId]/page.tsx`
+5. `src/app/(dashboard)/student/learning/courses/page.tsx`
+6. `src/app/(dashboard)/student/learning/textbooks/page.tsx`
+7. `src/app/(dashboard)/student/learning/textbooks/[id]/page.tsx`
+8. `src/app/(dashboard)/student/schedule/page.tsx`
+9. `src/app/(dashboard)/student/attendance/page.tsx`
+10. `src/app/(dashboard)/student/elective/page.tsx`
+11. `src/app/(dashboard)/student/diagnostic/page.tsx`
+12. `src/app/(dashboard)/student/learning/courses/loading.tsx`
+13. `src/app/(dashboard)/student/schedule/loading.tsx`
+14. `src/app/(dashboard)/student/learning/textbooks/[id]/loading.tsx`
+15. `src/modules/homework/components/homework-take-view.tsx`
+16. `src/modules/student/components/student-courses-view.tsx`
+17. `src/modules/student/components/student-schedule-view.tsx`
+18. `src/modules/elective/components/student-selection-view.tsx`
+19. `src/modules/diagnostic/components/student-diagnostic-view.tsx`
+20. `src/modules/dashboard/components/student-dashboard/student-dashboard-header.tsx`
+21. `src/modules/dashboard/components/student-dashboard/student-stats-grid.tsx`
+22. `src/modules/dashboard/components/student-dashboard/student-grades-card.tsx`
+23. `src/modules/dashboard/components/student-dashboard/student-today-schedule-card.tsx`
+24. `src/shared/components/charts/chart-card-shell.tsx`
+25. `src/app/api/search/route.ts`
+
+### v4 修复总结
+
+本次修复聚焦于 P0 功能断裂和 P1 体验问题，共完成 19 项修复（3 P0 + 13 P1 + 3 P2）：
+- **功能完整性**：修复作业作答页面的虚假文案、缺失的离开警告、提交确认和返回导航
+- **信息架构**：修复导航死链、Dashboard 标题重复、Stats Grid 链接错误
+- **筛选能力**：为作业列表和成绩页面添加搜索+筛选
+- **安全防护**：添加退课二次确认、作业提交二次确认、作答离开警告
+- **权限控制**：全局搜索按角色过滤，学生不可搜索题目/考试
+- **视觉体验**：课表今日高亮、作业科目颜色标识、过期作业警告
+- **布局一致性**：统一所有学生页面的容器 className，消除双重 padding
+
+剩余 32 项（2 P1 + 20 P2 + 10 P3）多为新功能模块或产品决策类问题，建议纳入后续产品迭代。