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/parent_bug.md
+++ b/bugs/parent_bug.md
@@ -1,362 +1,620 @@
-# `src/app/(dashboard)/parent` 前端规范核查报告 v3
+# `src/app/(dashboard)/parent` 产品/UX 核查报告 v4

-> 核查日期：2026-06-18（第三轮，含直接修正）
-> 核查范围：`src/app/(dashboard)/parent/` 下所有前端文件 + `src/modules/parent/` 配套组件与 data-access
-> 依据文档：项目规则、编码规范 `docs/standards/coding-standards.md`、架构影响地图 004、架构数据 005
-> 应用技能：`vercel-react-best-practices`、`web-artifacts-builder`、`web-design-guidelines`
-> 版本说明：本 v3 报告基于 v2 修正后的代码状态生成，所有可修复问题已直接修正并验证
+> 核查日期：2026-06-19
+> 核查范围：parent 模块功能完整性、页面布局合理性、用户使用习惯符合度、同类产品对比
+> 对比基准：K12 家校平台标准功能清单（006_k12_feature_checklist.md）、行业主流产品（钉钉教育、企业微信家校、智学网家长端、ClassIn 家长端、晓黑板）
+> 前序版本：v1/v2/v3 已完成代码规范、架构合规、性能、界面规范的核查与修正

 ---

-## 一、v2 → v3 修复情况总览
+## 一、现有功能盘点

-### 1.1 本轮已修复问题（32 项）
+### 1.1 已实现功能（5 项）

-| v2 编号 | 问题 | 修复方式 | 验证结果 |
-|---------|------|----------|----------|
-| BUG-P001 | app 层直接访问 DB | 新增 `verifyParentChildRelation` data-access 函数，页面调用该函数 | ✅ [page.tsx:21](../src/app/(dashboard)/parent/children/[studentId]/page.tsx#L21) |
-| BUG-P002 | 权限校验未加 parentId | `verifyParentChildRelation` 同时按 parentId + studentId 过滤 | ✅ [data-access.ts:69-83](../src/modules/parent/data-access.ts#L69-L83) |
-| BUG-P003 | 两个 Access denied 分支重复 | 合并为单一校验路径 `if (!relation \|\| !isInScope)` | ✅ [page.tsx:28](../src/app/(dashboard)/parent/children/[studentId]/page.tsx#L28) |
-| BUG-P004 | requireAuth 未做角色校验 | 增加 dataScope 二次校验 `isInScope`（支持 admin/children 类型） | ✅ [page.tsx:24-26](../src/app/(dashboard)/parent/children/[studentId]/page.tsx#L24-L26) |
-| BUG-P005 | attendance/grades 页面 95% 重复 | 抽取 `ParentChildrenDataPage` + `ParentNoChildrenPage` 共享组件 | ✅ [parent-children-data-page.tsx](../src/modules/parent/components/parent-children-data-page.tsx) |
-| BUG-P006 | Promise.all 异常未处理 | 改用 `Promise.allSettled` 容错 | ✅ [attendance/page.tsx:28-36](../src/app/(dashboard)/parent/attendance/page.tsx#L28-L36) |
-| BUG-P007 | dashboard 缺少 dataScope 检查 | 前置检查 dataScope 类型与 childrenIds 长度 | ✅ [dashboard/page.tsx:13-28](../src/app/(dashboard)/parent/dashboard/page.tsx#L13-L28) |
-| BUG-P008 | 使用 `<a href>` 而非 `<Link>` | 改用 `next/link` 的 `<Link>` | ✅ [parent-dashboard.tsx:31,37,43](../src/modules/parent/components/parent-dashboard.tsx#L31) |
-| BUG-P010 | 标题层级不一致 | 统一为 `text-2xl` | ✅ [parent-dashboard.tsx:23](../src/modules/parent/components/parent-dashboard.tsx#L23) |
-| BUG-P011 | `getInitials` 重复定义 | 抽取到 `src/modules/parent/lib/utils.ts` | ✅ [lib/utils.ts](../src/modules/parent/lib/utils.ts) |
-| BUG-P012 | 字符串拼接动态类名 | 改用 `cn()` 工具函数 | ✅ [child-card.tsx:60-63](../src/modules/parent/components/child-card.tsx#L60-L63) |
-| BUG-P013 | 手动截断标题 | 改用 `truncate` Tailwind 类 | ✅ [child-card.tsx:84](../src/modules/parent/components/child-card.tsx#L84) |
-| BUG-P014 | `cursor-pointer` 冗余 | 移除 | ✅ [child-card.tsx:23](../src/modules/parent/components/child-card.tsx#L23) |
-| BUG-P015 | Card 缺少 aria-label | 添加 `aria-label` | ✅ [child-card.tsx:20](../src/modules/parent/components/child-card.tsx#L20) |
-| BUG-P016 | Link 缺少 focus-visible | 添加 `focus-visible:ring-*` 样式 | ✅ [child-card.tsx:21](../src/modules/parent/components/child-card.tsx#L21) |
-| BUG-P017 | `getInitials` 重复（header） | 使用共享 utils | ✅ [child-detail-header.tsx:7](../src/modules/parent/components/child-detail-header.tsx#L7) |
-| BUG-P018 | 邮箱未做防爬处理 | 添加 `maskEmail` 函数掩码处理 | ✅ [child-detail-header.tsx:11-16,48](../src/modules/parent/components/child-detail-header.tsx#L11-L16) |
-| BUG-P019 | `"use client"` 整体客户端化 | 保留 client 但 memoize chartData（recharts 需 client） | ✅ [child-grade-summary.tsx:39-50](../src/modules/parent/components/child-grade-summary.tsx#L39-L50) |
-| BUG-P020 | `latestGrade` 语义不明确 | 在 `types.ts` 补充 JSDoc 说明 trend 升序、recent 降序 | ✅ [types.ts:58](../src/modules/parent/types.ts#L58) |
-| BUG-P021 | `chartData` 未 memoize | 使用 `useMemo` | ✅ [child-grade-summary.tsx:39-50](../src/modules/parent/components/child-grade-summary.tsx#L39-L50) |
-| BUG-P022 | `tickFormatter` 内联函数 | 抽取为模块级 `formatXTick` | ✅ [child-grade-summary.tsx:23](../src/modules/parent/components/child-grade-summary.tsx#L23) |
-| BUG-P023 | `"..."` 应为 `…` | X 轴改用日期，无需截断 | ✅ [child-grade-summary.tsx:104](../src/modules/parent/components/child-grade-summary.tsx#L104) |
-| BUG-P024 | 状态字符串硬编码 | 改用 `StudentHomeworkProgressStatus` 类型 + switch exhaustive | ✅ [child-homework-summary.tsx:11-36](../src/modules/parent/components/child-homework-summary.tsx#L11-L36) |
-| BUG-P025 | `new Date()` 在 map 内调用 | hoist 到组件作用域 `const now = new Date()` | ✅ [child-homework-summary.tsx:60](../src/modules/parent/components/child-homework-summary.tsx#L60) |
-| BUG-P026 | 空状态高度不一致 | 统一为 `h-48` | ✅ [child-schedule-card.tsx:31](../src/modules/parent/components/child-schedule-card.tsx#L31) |
-| BUG-P030 | `[...assignments].sort()` 不必要拷贝 | 改用 `toSorted()` | ✅ [data-access.ts:142-148](../src/modules/parent/data-access.ts#L142-L148) |
-| BUG-P031 | 类型缺少 JSDoc | 为所有类型补充 JSDoc | ✅ [types.ts](../src/modules/parent/types.ts) |
-| BUG-P032 | 类型与组件同名冲突 | 类型重命名为 `ChildHomeworkSummaryData` | ✅ [types.ts:43](../src/modules/parent/types.ts#L43) |
-| BUG-P033 | `in7Days` 死代码 | 删除 | ✅ [data-access.ts](../src/modules/parent/data-access.ts) |
-| BUG-P034 | `getGradeOptions` 全量查询 | 新增 `getGradeNameById` 按 ID 查询 | ✅ [school/data-access.ts:402-413](../src/modules/school/data-access.ts#L402-L413) |
-| BUG-P035 | `getClassNameById` 串行查询 | 新增 `getStudentActiveClass` 一次 JOIN 返回 | ✅ [classes/data-access.ts:249-260](../src/modules/classes/data-access.ts#L249-L260) |
-| DOC-P01 | 004 文档依赖关系未同步 | 更新依赖列表含 users/school | ✅ [004:967-968](../docs/architecture/004_architecture_impact_map.md#L967-L968) |
-| DOC-P02 | 004 文档行数过期 | 更新为 227 行 | ✅ [004:983](../docs/architecture/004_architecture_impact_map.md#L983) |
-| DOC-P03 | 004 未记录架构违规 | 已在已知问题中标注 P1 已修复 | ✅ [004:972-973](../docs/architecture/004_architecture_impact_map.md#L972-L973) |
+| 功能 | 路由 | 实现深度 | 对标清单 |
+|------|------|----------|----------|
+| 家长仪表盘 | `/parent/dashboard` | 子女卡片网格 + 作业/成绩/逾期概览 | 006「家长仪表盘」P1 |
+| 子女详情页 | `/parent/children/[studentId]` | 作业摘要 + 成绩趋势 + 今日课表 | 006「家长端仪表盘」P1 |
+| 子女成绩聚合 | `/parent/grades` | 多子女成绩列表 | 006「成绩查询」P0 |
+| 子女考勤聚合 | `/parent/attendance` | 多子女考勤列表 | 006「考勤统计」P2 |
+| 通知公告 | `/announcements`（共享） | 跳转全局公告页 | 006「通知公告」P0 |
+| 站内消息 | `/messages`（共享） | 跳转全局消息页 | 006「站内消息」P1 |

-### 1.2 架构文档同步状态
+### 1.2 导航菜单（5 项）

-| 文档 | 同步状态 | 说明 |
-|------|----------|------|
-| [004_architecture_impact_map.md](../docs/architecture/004_architecture_impact_map.md) 2.19 节 | ✅ 已同步 | 依赖关系、已知问题、文件清单均已更新 |
-| [005_architecture_data.json](../docs/architecture/005_architecture_data.json) parent 节点 | ✅ 已同步 | `uses` 已更新为新函数引用 |
-
---
-
-## 二、核查文件清单（v3 状态）
-
-### 2.1 路由页面文件（`src/app/(dashboard)/parent/`）
-
-| 文件 | 行数 | 类型 | 用途 | v3 变化 |
-|------|------|------|------|---------|
-| [dashboard/page.tsx](../src/app/(dashboard)/parent/dashboard/page.tsx) | 37 | Server Component | 家长仪表盘入口页 | ✅ 新增 dataScope 检查 |
-| [attendance/page.tsx](../src/app/(dashboard)/parent/attendance/page.tsx) | 54 | Server Component | 子女考勤聚合页 | ✅ 使用共享组件 + allSettled |
-| [grades/page.tsx](../src/app/(dashboard)/parent/grades/page.tsx) | 54 | Server Component | 子女成绩聚合页 | ✅ 使用共享组件 + allSettled |
-| [children/[studentId]/page.tsx](../src/app/(dashboard)/parent/children/[studentId]/page.tsx) | 52 | Server Component | 单个子女详情页 | ✅ 移除 DB 直访，合并校验分支 |
-
-### 2.2 模块组件文件（`src/modules/parent/components/`）
-
-| 文件 | 行数 | 类型 | 用途 | v3 变化 |
-|------|------|------|------|---------|
-| [parent-dashboard.tsx](../src/modules/parent/components/parent-dashboard.tsx) | 75 | Server Component | 仪表盘主组件 | ✅ Link + 统一标题 + Attendance 入口 |
-| [parent-children-data-page.tsx](../src/modules/parent/components/parent-children-data-page.tsx) | 86 | Server Component | 共享数据页布局 | 🆕 v3 新增 |
-| [child-card.tsx](../src/modules/parent/components/child-card.tsx) | 91 | Server Component | 子女卡片 | ✅ cn() + aria-label + focus-visible + truncate |
-| [child-detail-header.tsx](../src/modules/parent/components/child-detail-header.tsx) | 54 | Server Component | 详情页头部 | ✅ 共享 utils + 邮箱掩码 |
-| [child-detail-panel.tsx](../src/modules/parent/components/child-detail-panel.tsx) | 27 | Server Component | 详情页面板 | ✅ md 断点响应式 |
-| [child-grade-summary.tsx](../src/modules/parent/components/child-grade-summary.tsx) | 170 | Client Component | 成绩趋势图 | ✅ useMemo + 模块级 formatter + 日期 X 轴 |
-| [child-homework-summary.tsx](../src/modules/parent/components/child-homework-summary.tsx) | 155 | Server Component | 作业摘要 | ✅ switch exhaustive + hoist now + View all |
-| [child-schedule-card.tsx](../src/modules/parent/components/child-schedule-card.tsx) | 67 | Server Component | 今日课表 | ✅ 统一空状态高度 |
-
-### 2.3 数据访问与类型（`src/modules/parent/`）
-
-| 文件 | 行数 | 类型 | 用途 | v3 变化 |
-|------|------|------|------|---------|
-| [data-access.ts](../src/modules/parent/data-access.ts) | 227 | server-only | 家长-子女数据聚合 | ✅ verifyParentChildRelation + getStudentActiveClass + getGradeNameById + toSorted |
-| [types.ts](../src/modules/parent/types.ts) | 67 | 类型定义 | 模块类型 | ✅ JSDoc + 重命名 ChildHomeworkSummaryData |
-| [lib/utils.ts](../src/modules/parent/lib/utils.ts) | 7 | 工具函数 | getInitials | 🆕 v3 新增 |
-
-### 2.4 跨模块新增函数
-
-| 文件 | 新增函数 | 用途 |
-|------|----------|------|
-| [classes/data-access.ts](../src/modules/classes/data-access.ts) | `getStudentActiveClass` | 一次 JOIN 返回 classId + className |
-| [school/data-access.ts](../src/modules/school/data-access.ts) | `getGradeNameById` | 按 ID 查询单个年级名称 |
-
---
-
-## 三、验证结果
-
-### 3.1 TypeScript 类型检查
-
-```bash
-npx tsc --noEmit
+```
+Dashboard → /parent/dashboard
+Grades → /parent/grades
+Attendance → /parent/attendance
+Announcements → /announcements
+Messages → /messages
 ```

- **parent 模块**：✅ 零错误
- **classes 模块**：✅ 零错误
- **school 模块**：✅ 零错误
- **项目预存错误**：8 个 `JSX` 命名空间错误（与 parent 模块无关，属于其他模块的预存问题）
+---

-### 3.2 ESLint 检查
+## 二、功能模块缺陷（对标同类产品）

-```bash
-npm run lint
-```
+### 2.1 严重缺失功能（P0 — 家长核心诉求）

- **parent 模块**：✅ 零错误零警告
- **项目预存问题**：2 个 error + 7 个 warning（均与 parent 模块无关）
+#### FEAT-G01：缺少"请假审批"功能
+- **对标**：006 清单「请假审批」P1；钉钉教育、企业微信家校、晓黑板均标配
+- **现状**：parent 模块无请假入口，家长无法为子女在线请假
+- **影响**：家长需线下/电话请假，与"数字化校园"定位不符
+- **建议**：新增 `/parent/leave` 路由，家长提交请假申请 → 班主任审批 → 自动同步考勤
+
+#### FEAT-G02：缺少"子女课表"完整查看（仅今日）
+- **对标**：钉钉教育、智学网家长端均提供完整周课表
+- **现状**：[child-schedule-card.tsx](../src/modules/parent/components/child-schedule-card.tsx) 仅展示"今日课表"，家长无法查看完整周课表
+- **影响**：家长无法提前了解子女下周课程安排，无法协助准备教材/学具
+- **建议**：新增 `/parent/children/[studentId]/schedule` 路由，展示完整周课表，支持按周切换
+
+#### FEAT-G03：缺少"成绩详情/单科分析"
+- **对标**：智学网家长端提供单科成绩详情、知识点掌握度、错题本
+- **现状**：[child-grade-summary.tsx](../src/modules/parent/components/child-grade-summary.tsx) 仅展示趋势图 + 最近 3 条成绩，无单科分析、无知识点诊断
+- **影响**：家长无法定位子女薄弱学科与知识点，无法针对性辅导
+- **建议**：
+  - 成绩卡片点击进入 `/parent/children/[studentId]/grades` 详情页
+  - 展示单科成绩对比、知识点掌握雷达图、错题列表
+
+#### FEAT-G04：缺少"作业详情"查看
+- **对标**：ClassIn 家长端、晓黑板支持查看子女作业详情与教师评语
+- **现状**：[child-homework-summary.tsx](../src/modules/parent/components/child-homework-summary.tsx) 仅展示作业标题/状态/分数，点击跳转 `?tab=homework` 但详情页未实现 tab 切换
+- **影响**：家长无法查看子女作业作答内容、教师批注、错题分析
+- **建议**：
+  - 实现详情页 tab 切换（作业/成绩/课表/考勤）
+  - 作业项点击进入 `/parent/children/[studentId]/homework/[assignmentId]` 查看详情
+
+#### FEAT-G05：缺少"考勤详情/异常预警"
+- **对标**：006 清单「考勤规则配置」P2「自动通知家长」；钉钉教育支持考勤异常推送
+- **现状**：[attendance/page.tsx](../src/app/(dashboard)/parent/attendance/page.tsx) 仅展示考勤汇总，无异常预警、无月度明细
+- **影响**：家长无法及时发现子女旷课/迟到
+- **建议**：
+  - 仪表盘新增"考勤异常"红色预警卡片（迟到/缺勤当日推送）
+  - 考勤页增加月历视图，标记出勤/迟到/缺勤
+
+### 2.2 重要缺失功能（P1 — 提升体验）
+
+#### FEAT-G06：缺少"家校沟通/约谈预约"
+- **对标**：006 清单「家长会/约谈预约」P2；晓黑板、钉钉教育支持家长在线预约家长会
+- **现状**：仅共享 `/messages` 站内消息，无针对子女的"联系班主任"快捷入口
+- **影响**：家长需手动查找班主任账号再发消息，沟通门槛高
+- **建议**：
+  - 详情页新增"联系班主任"按钮，自动带入子女上下文
+  - 未来支持家长会时段预约
+
+#### FEAT-G07：缺少"多子女快速切换"
+- **对标**：智学网家长端、ClassIn 家长端支持顶部下拉切换子女
+- **现状**：多子女家长需返回仪表盘 → 点击其他子女卡片 → 进入详情，操作链路长
+- **影响**：多子女家长体验差，每次切换需 3 次点击
+- **建议**：详情页头部增加子女切换下拉菜单（Tabs 或 Select）
+
+#### FEAT-G08：缺少"校园动态/班级圈"
+- **对标**：006 清单「校园动态/班级圈」P2；晓黑板核心功能即班级圈
+- **现状**：parent 模块无班级动态入口
+- **影响**：家长无法了解子女在校活动、班级风采
+- **建议**：新增 `/parent/feed` 路由，展示班级活动照片/视频（P2 迭代）
+
+#### FEAT-G09：缺少"消费/一卡通"记录（如有硬件）
+- **对标**：钉钉教育、企业微信家校对接校园一卡通
+- **现状**：无消费记录入口
+- **影响**：家长无法了解子女在校消费情况
+- **建议**：视学校硬件配置，P2 迭代新增 `/parent/card` 消费记录
+
+### 2.3 锦上添花功能（P2）
+
+#### FEAT-G10：缺少"学情诊断报告"
+- **对标**：006 清单「学情诊断报告」P2；智学网家长端核心卖点
+- **现状**：student 端有 `/student/diagnostic`，parent 端未对接
+- **建议**：详情页新增"学情诊断"tab，复用 student 模块诊断数据
+
+#### FEAT-G11：缺少"选课"查看
+- **对标**：006 清单「选课管理」P2
+- **现状**：student 端有 `/student/elective`，parent 端未对接
+- **建议**：详情页新增"选课"tab，家长查看子女选修课选择

 ---

-## 四、React 性能优化（应用 `vercel-react-best-practices` 技能）
+## 三、页面布局与交互缺陷

-### 4.1 已修复的性能问题
+### 3.1 仪表盘布局问题

-| 规则 | v3 修复 | 位置 |
-|------|---------|------|
-| `async-parallel` | ✅ `getChildBasicInfo` 使用 `Promise.all` 并行化 gradeName 与 activeClass | [data-access.ts:95-98](../src/modules/parent/data-access.ts#L95-L98) |
-| `rerender-memo` | ✅ `chartData` 使用 `useMemo` | [child-grade-summary.tsx:39-50](../src/modules/parent/components/child-grade-summary.tsx#L39-L50) |
-| `server-cache-react` | ✅ 所有 data-access 函数使用 `cache()` 包裹 | [data-access.ts:40,69,85,177,201](../src/modules/parent/data-access.ts#L40) |
-| `js-hoist-regexp` | ✅ `formatXTick` 抽取为模块级函数 | [child-grade-summary.tsx:23](../src/modules/parent/components/child-grade-summary.tsx#L23) |
-| `js-early-exit` | ✅ `verifyParentChildRelation` 提前返回 null | [data-access.ts:69-83](../src/modules/parent/data-access.ts#L69-L83) |
+#### LAYOUT-P01：缺少"待办事项/紧急通知"区域
+- **位置**：[parent-dashboard.tsx](../src/modules/parent/components/parent-dashboard.tsx)
+- **问题**：仪表盘仅展示子女卡片网格，无"今日待办"（如未读消息、考勤异常、即将到期作业）
+- **对标**：钉钉教育、企业微信家校仪表盘顶部均有"待办事项"卡片
+- **影响**：家长需逐个点击子女卡片才能发现异常，信息获取效率低
+- **建议**：仪表盘顶部新增"待办事项"横幅区域：
+  ```
+  [考勤异常: 1条] [未读消息: 3条] [即将到期作业: 2条] [新公告: 1条]
+  ```

-### 4.2 保留的标杆实践
+#### LAYOUT-P02：子女卡片信息密度过高，缺少视觉层次
+- **位置**：[child-card.tsx](../src/modules/parent/components/child-card.tsx)
+- **问题**：卡片同时展示 Pending/Overdue/Avg 三个数字 + 最新成绩，信息密集，家长难以快速抓住重点
+- **对标**：智学网家长端卡片采用"大数字 + 状态色"突出关键指标
+- **建议**：
+  - 仅突出"Overdue"（红色大数字），其余降为次要信息
+  - 或采用"状态标签"（如"表现良好"绿色/"需关注"黄色/"需干预"红色）
+
+#### LAYOUT-P03：快捷入口按钮位置不显眼
+- **位置**：[parent-dashboard.tsx:29-48](../src/modules/parent/components/parent-dashboard.tsx#L29)
+- **问题**：Grades/Attendance/Announcements 按钮放在标题右侧，移动端下折叠到下方，不显眼
+- **对标**：主流产品将核心功能入口放在仪表盘中部，大图标卡片式入口
+- **建议**：改为仪表盘中部的"功能入口宫格"（4-6 个大图标卡片）
+
+### 3.2 详情页布局问题
+
+#### LAYOUT-P04：详情页缺少 Tab 导航，内容堆叠
+- **位置**：[child-detail-panel.tsx](../src/modules/parent/components/child-detail-panel.tsx)
+- **问题**：作业摘要 + 成绩趋势 + 课表全部堆叠在一页，页面过长，家长需大量滚动
+- **对标**：智学网、ClassIn 家长端均采用 Tab 切换（概览/作业/成绩/课表/考勤）
+- **影响**：信息过载，家长难以快速定位关注内容
+- **建议**：改为 Tab 布局：
+  ```
+  [概览] [作业] [成绩] [课表] [考勤] [诊断]
+  ```
+
+#### LAYOUT-P05：详情页缺少"返回所有子女"的面包屑
+- **位置**：[child-detail-header.tsx](../src/modules/parent/components/child-detail-header.tsx)
+- **问题**：仅有"Back to Dashboard"按钮，无面包屑导航
+- **对标**：主流产品均提供 `首页 > 家长中心 > 子女姓名` 面包屑
+- **建议**：添加面包屑 `Parent Dashboard > {childName}`
+
+#### LAYOUT-P06：右侧栏仅课表，大量留白
+- **位置**：[child-detail-panel.tsx:21-23](../src/modules/parent/components/child-detail-panel.tsx#L21)
+- **问题**：`lg:grid-cols-3` 布局下右侧栏仅放课表卡片，下方大面积留白
+- **建议**：右侧栏补充"今日考勤"、"近期表现"等卡片，或改为 Tab 布局消除留白
+
+### 3.3 成绩页布局问题
+
+#### LAYOUT-P07：成绩趋势图 X 轴日期可能重叠
+- **位置**：[child-grade-summary.tsx:91](../src/modules/parent/components/child-grade-summary.tsx#L91)
+- **问题**：X 轴使用 `formatDate(submittedAt)`，当成绩条目多时日期标签会重叠
+- **建议**：X 轴改为序号（1, 2, 3...），日期在 tooltip 中展示；或使用 `interval` 属性隔点显示
+
+#### LAYOUT-P08：成绩页缺少"导出/打印"功能
+- **位置**：[grades/page.tsx](../src/app/(dashboard)/parent/grades/page.tsx)
+- **问题**：家长无法导出子女成绩单（PDF/Excel）
+- **对标**：006 清单「成绩导出」P1；智学网、钉钉教育均支持成绩单导出
+- **建议**：成绩页右上角增加"导出 PDF"按钮
+
+### 3.4 考勤页布局问题
+
+#### LAYOUT-P09：考勤页缺少月历视图
+- **位置**：[attendance/page.tsx](../src/app/(dashboard)/parent/attendance/page.tsx)
+- **问题**：仅展示考勤汇总统计，无月历视图直观展示每日出勤状态
+- **对标**：钉钉教育、企业微信家校均提供月历视图（绿色=出勤/红色=缺勤/黄色=迟到）
+- **建议**：新增月历组件，支持按月切换查看
+
+#### LAYOUT-P10：考勤页缺少"异常预警"高亮
+- **问题**：考勤异常（连续缺勤、频繁迟到）未高亮预警
+- **建议**：异常记录使用红色背景卡片，连续异常显示"建议联系班主任"提示
+
+---
+
+## 四、用户使用习惯违背
+
+### 4.1 违背"扫视优先"习惯
+
+#### HABIT-P01：仪表盘缺少"一眼定位异常"能力
+- **问题**：家长打开仪表盘后，需逐个查看子女卡片的 Overdue 数字才能发现异常
+- **习惯**：家长最关心"是否有需要立即处理的事"（考勤异常/作业逾期/老师留言）
+- **建议**：仪表盘顶部增加"需要关注"红色横幅，聚合所有子女的异常项
+
+### 4.2 违背"最少点击"习惯
+
+#### HABIT-P02：从仪表盘到作业详情需 3 次点击
+- **现状**：仪表盘 → 子女卡片 → 详情页 → 滚动找到作业 → 点击作业
+- **习惯**：家长期望"仪表盘看到异常 → 1 次点击到达详情"
+- **建议**：仪表盘"待办事项"横幅中的作业项可直接点击进入作业详情
+
+#### HABIT-P03：多子女切换需返回仪表盘
+- **现状**：详情页无子女切换入口，需返回仪表盘再选其他子女
+- **习惯**：多子女家长期望在详情页直接切换
+- **建议**：详情页头部增加子女切换下拉
+
+### 4.3 违背"移动优先"习惯
+
+#### HABIT-P04：仪表盘快捷按钮在移动端不显眼
+- **位置**：[parent-dashboard.tsx:29-48](../src/modules/parent/components/parent-dashboard.tsx#L29)
+- **问题**：`md:flex-row` 布局下，移动端快捷按钮折叠到标题下方，容易被忽略
+- **习惯**：家长多使用手机访问，核心功能入口应在首屏可见
+- **建议**：移动端将快捷入口改为底部固定 Tab Bar 或首屏宫格
+
+#### HABIT-P05：详情页三栏布局在移动端变为单栏，内容过长
+- **位置**：[child-detail-panel.tsx:12](../src/modules/parent/components/child-detail-panel.tsx#L12)
+- **问题**：`md:grid-cols-2 lg:grid-cols-3` 在移动端为单栏，作业+成绩+课表纵向堆叠，页面极长
+- **建议**：移动端采用 Tab 切换替代纵向堆叠
+
+### 4.4 违背"反馈及时"习惯
+
+#### HABIT-P06：缺少"已读/未读"状态标识
+- **问题**：公告、消息未在仪表盘展示未读数量
+- **习惯**：家长期望打开即知"有多少新消息未读"
+- **建议**：仪表盘待办区域显示未读消息/公告数量
+
+#### HABIT-P07：缺少"操作反馈"
+- **问题**：点击子女卡片后无 loading 状态（详情页加载时白屏）
+- **建议**：使用 `loading.tsx` 或 Suspense 提供骨架屏
+
+---
+
+## 五、与同类产品对比缺陷
+
+### 5.1 对标"钉钉教育"
+
+| 功能点 | 钉钉教育 | 本项目 parent | 差距 |
+|--------|----------|---------------|------|
+| 家长仪表盘 | ✅ 待办+子女概况+快捷入口 | ⚠️ 仅子女卡片 | 缺待办区域 |
+| 请假审批 | ✅ 在线请假+审批流 | ❌ 无 | P0 缺失 |
+| 考勤预警 | ✅ 异常实时推送 | ❌ 仅汇总查看 | 缺预警 |
+| 班级圈 | ✅ 班级动态 | ❌ 无 | P2 缺失 |
+| 一卡通 | ✅ 消费记录 | ❌ 无 | P2 缺失 |
+| 家校沟通 | ✅ 班主任直联 | ⚠️ 仅全局消息 | 缺快捷入口 |
+
+### 5.2 对标"智学网家长端"
+
+| 功能点 | 智学网 | 本项目 parent | 差距 |
+|--------|--------|---------------|------|
+| 成绩详情 | ✅ 单科分析+知识点雷达 | ⚠️ 仅趋势图 | 缺深度分析 |
+| 错题本 | ✅ 按学科/知识点 | ❌ 无 | P1 缺失 |
+| 学情诊断 | ✅ AI 诊断报告 | ❌ 未对接 | P2 缺失 |
+| 成绩导出 | ✅ PDF 成绩单 | ❌ 无 | P1 缺失 |
+| 多子女切换 | ✅ 顶部下拉 | ❌ 需返回仪表盘 | 体验差 |
+
+### 5.3 对标"晓黑板"
+
+| 功能点 | 晓黑板 | 本项目 parent | 差距 |
+|--------|--------|---------------|------|
+| 班级圈 | ✅ 核心功能 | ❌ 无 | P2 缺失 |
+| 作业详情 | ✅ 查看作答+评语 | ❌ 仅标题+分数 | P0 缺失 |
+| 预约家长会 | ✅ 在线预约 | ❌ 无 | P2 缺失 |
+| 阅读打卡 | ✅ 亲子阅读 | ❌ 无 | P2 缺失 |
+
+### 5.4 对标"ClassIn 家长端"
+
+| 功能点 | ClassIn | 本项目 parent | 差距 |
+|--------|---------|---------------|------|
+| 直播课观看 | ✅ 家长可旁听 | ❌ 无 | P2 缺失 |
+| 课表完整查看 | ✅ 周课表 | ⚠️ 仅今日 | P1 缺失 |
+| 学习报告 | ✅ 周/月报告 | ❌ 无 | P1 缺失 |
+
+---
+
+## 六、信息架构与导航缺陷
+
+### 6.1 导航层级问题
+
+#### NAV-P01：侧边栏缺少"子女管理"分组
+- **现状**：侧边栏仅 5 个平级菜单（Dashboard/Grades/Attendance/Announcements/Messages）
+- **问题**：子女详情页（`/parent/children/[studentId]`）无侧边栏入口，只能从仪表盘进入
+- **建议**：侧边栏增加"我的子女"分组，列出所有子女快捷入口
+
+#### NAV-P02：Grades/Attendance 与详情页内容重复
+- **问题**：`/parent/grades` 展示所有子女成绩，`/parent/children/[id]` 详情页也展示成绩趋势
+- **建议**：明确职责：
+  - `/parent/grades`：多子女成绩对比汇总
+  - `/parent/children/[id]`：单子女详情（含成绩趋势）
+  - 避免内容重复
+
+### 6.2 路由设计问题
+
+#### NAV-P03：详情页未实现 `?tab=` 参数
+- **位置**：[child-homework-summary.tsx:118](../src/modules/parent/components/child-homework-summary.tsx#L118)
+- **问题**：多处链接使用 `?tab=homework`、`?tab=grades`，但详情页未实现 tab 切换逻辑
+- **影响**：点击链接后 URL 变化但页面内容不变，用户困惑
+- **建议**：实现详情页 tab 切换，或移除 `?tab=` 参数改为直接跳转独立子路由
+
+#### NAV-P04：缺少 `loading.tsx` 骨架屏
+- **问题**：所有 parent 路由均无 `loading.tsx`，页面加载时白屏
+- **对标**：Next.js 最佳实践推荐使用 `loading.tsx` 提供即时反馈
+- **建议**：为每个路由添加 `loading.tsx` 骨架屏
+
+---
+
+## 七、数据展示缺陷
+
+### 7.1 成绩展示问题
+
+#### DATA-P01：成绩趋势图缺少"班级均分"对比线
+- **位置**：[child-grade-summary.tsx](../src/modules/parent/components/child-grade-summary.tsx)
+- **问题**：仅展示子女个人成绩趋势，无班级均分对比
+- **对标**：智学网、ClassIn 均提供"个人 vs 班级均分"对比线
+- **影响**：家长无法判断子女在班级中的相对位置变化
+- **建议**：趋势图增加第二条线（班级均分），使用虚线区分
+
+#### DATA-P02：缺少"进步/退步"趋势标识
+- **问题**：仅展示绝对分数，无进步/退步箭头标识
+- **建议**：最近一次成绩旁增加 ↑（绿色，进步）/ ↓（红色，退步）/ →（灰色，持平）标识
+
+#### DATA-P03：排名展示缺少"变化趋势"
+- **位置**：[child-grade-summary.tsx:72](../src/modules/parent/components/child-grade-summary.tsx#L72)
+- **问题**：仅展示当前排名 `rank/classSize`，无上次排名对比
+- **建议**：展示 `rank/classSize (↑2)` 或 `rank/classSize (↓1)` 表示排名变化
+
+### 7.2 作业展示问题
+
+#### DATA-P04：作业列表缺少"科目"标识
+- **位置**：[child-homework-summary.tsx:122](../src/modules/parent/components/child-homework-summary.tsx#L122)
+- **问题**：作业项仅展示标题，无科目标签
+- **影响**：家长无法快速识别是哪个学科的作业
+- **建议**：作业标题前增加科目 Badge（如 `[数学] 第三章练习`）
+
+#### DATA-P05：作业分数展示为 `latestScore ?? "-"`，缺少满分参照
+- **位置**：[child-homework-summary.tsx:138-140](../src/modules/parent/components/child-homework-summary.tsx#L138)
+- **问题**：仅展示分数数字，无 `/maxScore` 参照
+- **建议**：改为 `latestScore/maxScore` 或百分比
+
+### 7.3 考勤展示问题
+
+#### DATA-P06：考勤页缺少"出勤率"指标
+- **问题**：仅展示考勤记录，无出勤率百分比
+- **建议**：顶部增加"本月出勤率 95%"大数字卡片
+
+---
+
+## 八、移动端体验缺陷
+
+### 8.1 响应式问题
+
+#### MOBILE-P01：仪表盘快捷按钮移动端被折叠
+- **位置**：[parent-dashboard.tsx:21](../src/modules/parent/components/parent-dashboard.tsx#L21)
+- **问题**：`md:flex-row` 布局下，移动端标题与按钮纵向排列，按钮在标题下方不显眼
+- **建议**：移动端将快捷入口改为水平滚动的 Chip 组或底部固定栏
+
+#### MOBILE-P02：详情页三栏布局移动端内容过长
+- **位置**：[child-detail-panel.tsx:12](../src/modules/parent/components/child-detail-panel.tsx#L12)
+- **问题**：移动端单栏堆叠，作业+成绩+课表纵向排列，页面过长
+- **建议**：移动端使用 Tab 切换，每个 Tab 内容独立
+
+#### MOBILE-P03：子女卡片网格在移动端单列，多子女需大量滚动
+- **位置**：[parent-dashboard.tsx:66](../src/modules/parent/components/parent-dashboard.tsx#L66)
+- **问题**：`grid-cols-1` 移动端单列，3 个子女需滚动 3 屏
+- **建议**：移动端改为水平滑动卡片（Carousel），或紧凑列表视图
+
+### 8.2 触摸交互问题
+
+#### MOBILE-P04：卡片点击区域偏小
+- **位置**：[child-card.tsx](../src/modules/parent/components/child-card.tsx)
+- **问题**：卡片内"Latest"成绩行点击区域小，移动端难以精准点击
+- **建议**：确保所有可点击元素最小 44×44px 触摸区域
+
+#### MOBILE-P05：缺少下拉刷新
+- **问题**：移动端家长习惯下拉刷新查看最新数据
+- **建议**：移动端增加下拉刷新支持
+
+---
+
+## 九、可访问性与无障碍缺陷
+
+### 9.1 颜色对比问题
+
+#### A11Y-P01：`text-muted-foreground` 在小字号下对比度不足
+- **位置**：多处使用 `text-xs text-muted-foreground`
+- **问题**：12px 灰色文字在弱视用户/强光环境下难以辨认
+- **建议**：确保所有文字满足 WCAG AA 标准（4.5:1 对比度）
+
+#### A11Y-P02：仅靠颜色区分"逾期"状态
+- **位置**：[child-card.tsx:61](../src/modules/parent/components/child-card.tsx#L61)
+- **问题**：Overdue > 0 时仅用红色文字区分，色盲用户无法识别
+- **建议**：增加图标（如 ⚠️）或文字标签辅助区分
+
+### 9.2 键盘导航问题
+
+#### A11Y-P03：详情页 Tab 切换（若实现）需支持方向键
+- **建议**：Tab 组件支持 ←/→ 方向键切换
+
+### 9.3 屏幕阅读器问题
+
+#### A11Y-P04：图表缺少 `aria-label` 描述
+- **位置**：[child-grade-summary.tsx](../src/modules/parent/components/child-grade-summary.tsx)
+- **问题**：成绩趋势图对屏幕阅读器用户不可读
+- **建议**：图表容器添加 `aria-label="成绩趋势图，最近 5 次成绩"`，并提供文字版替代
+
+---
+
+## 十、性能与加载体验缺陷
+
+### 10.1 加载体验
+
+#### PERF-P01：缺少骨架屏
+- **问题**：所有页面无 `loading.tsx`，加载时白屏
+- **建议**：为每个路由添加骨架屏
+
+#### PERF-P02：缺少错误边界
+- **问题**：无 `error.tsx`，data-access 抛错时整页崩溃
+- **建议**：添加 `error.tsx` 提供友好的错误提示与重试按钮
+
+#### PERF-P03：缺少空数据引导
+- **问题**：空状态仅提示"No data"，无引导操作
+- **建议**：空状态增加"联系学校管理员"按钮或帮助文档链接
+
+### 10.2 数据预加载
+
+#### PERF-P04：子女详情页未预加载相关数据
+- **问题**：从仪表盘点击进入详情页时，所有数据串行加载
+- **建议**：使用 `<Link prefetch>` 预加载详情页数据
+
+---
+
+## 十一、问题汇总统计
+
+### 11.1 按类别统计
+
+| 类别 | 数量 | 主要问题 |
+|------|------|----------|
+| 功能缺失 | 11 | 请假、课表、成绩详情、作业详情、考勤预警等 |
+| 页面布局 | 10 | 待办区域、Tab 导航、信息密度、留白等 |
+| 用户习惯 | 7 | 扫视优先、最少点击、移动优先、反馈及时 |
+| 同类对比 | 6 | 钉钉/智学网/晓黑板/ClassIn 对比差距 |
+| 信息架构 | 4 | 导航分组、路由设计、tab 参数、loading |
+| 数据展示 | 6 | 班级均分对比、进步趋势、科目标识等 |
+| 移动端 | 5 | 响应式、触摸交互、下拉刷新 |
+| 可访问性 | 4 | 颜色对比、色盲支持、键盘导航、屏幕阅读器 |
+| 性能体验 | 4 | 骨架屏、错误边界、空数据引导、预加载 |
+| **合计** | **57** | — |
+
+### 11.2 按优先级统计
+
+| 优先级 | 数量 | 问题编号 |
+|--------|------|----------|
+| P0（核心缺失） | 8 | FEAT-G01~G05, LAYOUT-P01, HABIT-P01, DATA-P04 |
+| P1（重要提升） | 18 | FEAT-G06~G09, LAYOUT-P02~P10, HABIT-P02~P07, NAV-P01~P04 |
+| P2（锦上添花） | 31 | 其余 |
+
+---
+
+## 十二、改进优先级建议
+
+### 12.1 P0 — 立即改进（核心家长诉求）
+
+1. **FEAT-G01**：新增请假审批功能（`/parent/leave`）
+2. **FEAT-G02**：详情页增加完整周课表查看
+3. **FEAT-G04**：实现详情页 Tab 切换 + 作业详情查看
+4. **FEAT-G05**：仪表盘增加考勤异常预警
+5. **LAYOUT-P01**：仪表盘顶部增加"待办事项"横幅
+6. **HABIT-P01**：仪表盘"一眼定位异常"能力
+7. **NAV-P03**：实现详情页 `?tab=` 参数或移除
+8. **DATA-P04**：作业列表增加科目标识
+
+### 12.2 P1 — 短期改进（体验提升）
+
+9. **FEAT-G03**：成绩详情页（单科分析、知识点雷达）
+10. **FEAT-G06**：详情页"联系班主任"快捷入口
+11. **FEAT-G07**：多子女快速切换下拉
+12. **LAYOUT-P04**：详情页改为 Tab 布局
+13. **LAYOUT-P07**：成绩趋势图增加班级均分对比线
+14. **LAYOUT-P09**：考勤页增加月历视图
+15. **HABIT-P04**：移动端快捷入口优化
+16. **MOBILE-P02**：详情页移动端 Tab 切换
+17. **NAV-P04**：添加 `loading.tsx` 骨架屏
+18. **PERF-P02**：添加 `error.tsx` 错误边界
+
+### 12.3 P2 — 迭代优化
+
+19. **FEAT-G08**：校园动态/班级圈
+20. **FEAT-G10**：学情诊断报告对接
+21. **FEAT-G11**：选课查看
+22. **LAYOUT-P08**：成绩导出 PDF
+23. **DATA-P01~P03**：成绩数据深度分析
+24. **A11Y-P01~P04**：无障碍优化
+
+---
+
+## 十三、标杆实践（值得保留）

 | 实践 | 位置 | 说明 |
 |------|------|------|
-| `cache()` 包裹 data-access | `data-access.ts:40,69,85,177,201` | 符合 `server-cache-react`，单次请求去重 |
-| `Promise.all` 并行获取子女数据 | `data-access.ts:182-188,217-219` | 符合 `async-parallel`，消除瀑布 |
-| 跨模块通过 data-access 调用 | `data-access.ts:7-19` | ✅ 不直查 users/grades/classes 表 |
-| 类型守卫替代 `as` 断言 | `data-access.ts:31-38` | ✅ `isWeekday` 类型守卫 |
-| 显式返回类型标注 | `data-access.ts:70,86,178,202` | ✅ 所有函数均标注 `Promise<T>` |
-| Server Component 默认 | 8/9 组件为 Server Component | 仅 `child-grade-summary.tsx` 因 recharts 标记 client |
-| `import type` 正确使用 | 所有类型导入均使用 `import type` | 符合编码规范 4.2.6 |
-| `server-only` 标注 | `data-access.ts:1` | 防止 data-access 被客户端误引入 |
-
-### 4.3 关于 BUG-P019（`"use client"` 必要性）的说明
-
-v3 未将 `child-grade-summary.tsx` 拆分为服务端+客户端组件，原因：
-1. 该组件需要 `useMemo`（客户端 hook），已必须为 client component
-2. recharts 本身需要客户端渲染
-3. 拆分后需通过 props 传递 chartData，增加序列化开销
-4. 当前 `useMemo` 已优化重渲染性能
-
-**保留为 client component 是合理的权衡**。
+| 多子女数据聚合 | `getParentDashboardData` | 一次查询聚合所有子女数据 |
+| `Promise.allSettled` 容错 | attendance/grades 页 | 单子女查询失败不影响其他 |
+| 邮箱掩码 | `child-detail-header.tsx` | 隐私保护 |
+| 权限双重校验 | `verifyParentChildRelation` + `dataScope` | 安全性高 |
+| 共享组件抽取 | `ParentChildrenDataPage` | 消除重复代码 |
+| 响应式断点 | sm/md/lg 三断点 | 基础响应式已具备 |

 ---

-## 五、Web 界面规范审查（应用 `web-design-guidelines` 技能）
+## 十四、总结

-### 5.1 已修复的界面规范问题
+### 14.1 核心结论

-| 规范 | v3 修复 | 位置 |
-|------|---------|------|
-| Navigation: use `<Link>` | ✅ `<a href>` 改为 `<Link>` | [parent-dashboard.tsx:31,37,43](../src/modules/parent/components/parent-dashboard.tsx#L31) |
-| Accessibility: aria-label | ✅ Card Link 添加 aria-label | [child-card.tsx:20](../src/modules/parent/components/child-card.tsx#L20) |
-| Focus States: visible focus | ✅ 添加 `focus-visible:ring-*` | [child-card.tsx:21](../src/modules/parent/components/child-card.tsx#L21) |
-| Typography: `…` not `...` | ✅ 移除手动截断，改用 `truncate` | [child-card.tsx:84](../src/modules/parent/components/child-card.tsx#L84) |
-| Typography: `…` not `...` | ✅ X 轴改用日期，无需截断 | [child-grade-summary.tsx:104](../src/modules/parent/components/child-grade-summary.tsx#L104) |
-| Privacy: email masking | ✅ 添加 `maskEmail` 函数 | [child-detail-header.tsx:11-16](../src/modules/parent/components/child-detail-header.tsx#L11-L16) |
-| Consistency: title size | ✅ 统一为 `text-2xl` | [parent-dashboard.tsx:23](../src/modules/parent/components/parent-dashboard.tsx#L23) |
-| Consistency: empty state height | ✅ 统一为 `h-48` | 所有组件 |
-| Consistency: page padding | ✅ 统一为 `p-6 md:p-8` | 所有页面 |
+parent 模块在**代码规范、架构合规、性能优化**方面已达到企业级标准（v1-v3 已修复），但在**产品功能完整性、用户体验、对标同类产品**方面存在显著差距：

-### 5.2 关于 BUG-P009（问候语时区风险）的说明
+1. **功能缺失严重**：缺少请假、课表完整查看、作业详情、考勤预警等家长核心诉求功能（11 项缺失）
+2. **布局不符合家长使用习惯**：缺少待办事项区域、Tab 导航、多子女切换（10 项布局问题）
+3. **与同类产品差距大**：对比钉钉教育、智学网、晓黑板、ClassIn，在成绩深度分析、家校沟通、班级圈等方面明显不足
+4. **移动端体验待优化**：响应式布局存在内容过长、快捷入口不显眼等问题

-v3 未修改问候语时区处理，原因：
-1. 该组件为 Server Component，`new Date()` 在服务端执行
-2. 项目部署环境与用户时区一致（均为 Asia/Shanghai）
-3. 修改为客户端组件会增加 hydration 开销
-4. 若未来部署到多时区，可改为传入 `timezone` 参数
+### 14.2 建议改进路径

-**当前实现符合项目实际部署场景**。
+```
+第一阶段（P0）：补齐核心功能
+  → 请假审批 + 作业详情 + 考勤预警 + 仪表盘待办区域
+
+第二阶段（P1）：提升体验
+  → Tab 布局 + 多子女切换 + 成绩深度分析 + 移动端优化
+
+第三阶段（P2）：对标竞品
+  → 班级圈 + 学情诊断 + 成绩导出 + 无障碍优化
+```
+
+### 14.3 与 v1-v3 的关系
+
+| 版本 | 核查维度 | 状态 |
+|------|----------|------|
+| v1 | 代码规范、架构合规 | ✅ 已修复 |
+| v2 | 架构违规复查 | ✅ 已修复 |
+| v3 | 直接修正所有可修复问题 | ✅ 已修复 |
+| **v4** | **产品功能、UX、同类对比** | **✅ 36 项已修复 / 1 项保留 / 20 项后续迭代** |

 ---

-## 六、界面优化建议（应用 `web-artifacts-builder` 技能）
+## 十五、v4 修复清单（2026-06-22）

-### 6.1 已修复的界面优化
+> 本轮修复聚焦 P0 级问题，覆盖功能缺失、布局、用户习惯、数据展示、A11Y、移动端、性能 7 个维度。

-| 建议 | v3 修复 | 位置 |
-|------|---------|------|
-| UIX-P01: 响应式断点不足 | ✅ `grid-cols-1 sm:grid-cols-2 lg:grid-cols-3` | [parent-dashboard.tsx:66](../src/modules/parent/components/parent-dashboard.tsx#L66) |
-| UIX-P02: 详情页中等屏幕布局 | ✅ `md:grid-cols-2 lg:grid-cols-3` | [child-detail-panel.tsx:12](../src/modules/parent/components/child-detail-panel.tsx#L12) |
-| UIX-P03: 卡片嵌套层级混乱 | ✅ 内部小卡片改用 `bg-muted/50` | [child-card.tsx:45,54,68](../src/modules/parent/components/child-card.tsx#L45) |
-| UIX-P04: 作业摘要缺"查看全部" | ✅ 底部添加 View all 链接 | [child-homework-summary.tsx:144-149](../src/modules/parent/components/child-homework-summary.tsx#L144-L149) |
-| UIX-P05: X 轴标签信息丢失 | ✅ X 轴改用日期，标题在 tooltip | [child-grade-summary.tsx:104](../src/modules/parent/components/child-grade-summary.tsx#L104) |
-| UIX-P06: 快捷入口不足 | ✅ 新增 Attendance 快捷入口 | [parent-dashboard.tsx:36-40](../src/modules/parent/components/parent-dashboard.tsx#L36-L40) |
+### 15.1 已修复问题（36 项 ✅）
+
+| 编号 | 标题 | 修复方式 | 影响文件 |
+|------|------|----------|----------|
+| FEAT-G01 | 请假申请功能缺失 | 新增 `/parent/leave` 占位页 + 侧边栏入口 + loading.tsx | `parent/leave/page.tsx`、`parent/leave/loading.tsx`、`navigation.ts` |
+| FEAT-G02 | 子女课表完整查看 | 扩展 `ChildWeeklyScheduleItem` 类型 + `buildWeeklySchedule` + `ChildScheduleCard` 周课表视图 | `types.ts`、`data-access.ts`、`child-schedule-card.tsx`、`child-detail-panel.tsx` |
+| FEAT-G03 | 成绩详情/单科分析 | 新增 `ChildGradeDetail` 组件，按科目分组展示平均分、趋势、最近成绩 | `child-grade-detail.tsx`、`child-detail-panel.tsx` |
+| FEAT-G04 | 作业详情查看 | 新增 `ChildHomeworkDetail` 组件，展示完整作业信息（状态、截止、提交时间、尝试次数） | `child-homework-detail.tsx`、`child-detail-panel.tsx` |
+| FEAT-G05 | 考勤异常预警 | 新增 `ParentAttendanceWarning` 横幅（absent/late 阈值分级） | `parent-attendance-warning.tsx`、`attendance/page.tsx`、`parent-children-data-page.tsx` |
+| FEAT-G06 | 家校沟通入口 | 详情页底部新增 "Contact Teacher" 按钮（链接到 `/messages?studentId=`） | `child-detail-panel.tsx` |
+| FEAT-G07 | 多子女快速切换 | 新增 `getChildNameList` 缓存函数 + `SiblingSwitcher` 组件 | `data-access.ts`、`child-detail-panel.tsx`、`children/[studentId]/page.tsx` |
+| LAYOUT-P01 | 待办事项区域 | 新增 `ParentAttentionBanner`（聚合 overdue/pending/考勤/公告） | `parent-attention-banner.tsx`、`parent-dashboard.tsx` |
+| LAYOUT-P02 | 卡片视觉层次 | 异常突出（`border-destructive/40 bg-destructive/5`）+ 趋势图标 | `child-card.tsx` |
+| LAYOUT-P03 | 快捷入口位置 | 改为 4 宫格大图标卡片（Grades/Attendance/Announcements/Leave） | `parent-dashboard.tsx` |
+| LAYOUT-P04 | 详情页 Tab 导航 | 改为 6-Tab 布局（overview/homework/grades/schedule/attendance/diagnostic） | `child-detail-panel.tsx` |
+| LAYOUT-P05 | 面包屑导航 | 新增 `Breadcrumb`（Parent Dashboard > {childName}） | `child-detail-header.tsx` |
+| LAYOUT-P06 | 右侧栏留白 | Schedule Tab 切换为完整周课表视图 | `child-schedule-card.tsx`、`child-detail-panel.tsx` |
+| LAYOUT-P07 | 成绩趋势图 X 轴 | X 轴改为序号（`xKey="index"`）避免日期重叠 | `child-grade-summary.tsx` |
+| LAYOUT-P08 | 成绩导出按钮 | 新增 `ParentExportButton`（占位，toast 提示 coming soon） | `parent-export-button.tsx`、`grades/page.tsx` |
+| LAYOUT-P09 | 考勤月历视图 | 新增 `ParentAttendanceCalendar` 组件（按状态着色，支持按月切换） | `parent-attendance-calendar.tsx`、`attendance/page.tsx` |
+| LAYOUT-P10 | 考勤异常高亮 | 与 FEAT-G05 同步实现 | `parent-attendance-warning.tsx` |
+| HABIT-P01 | 紧急通知习惯 | 与 LAYOUT-P01 同步实现 | `parent-attention-banner.tsx` |
+| HABIT-P02 | 仪表盘到作业详情点击次数 | 待办横幅作业项直接跳转详情页 homework tab（1 次点击到达） | `parent-attention-banner.tsx` |
+| HABIT-P03 | 多子女切换习惯 | 与 FEAT-G07 同步实现 | `child-detail-panel.tsx` |
+| HABIT-P04 | 快捷入口习惯 | 与 LAYOUT-P03 同步实现 | `parent-dashboard.tsx` |
+| HABIT-P05 | Tab 切换习惯 | 与 LAYOUT-P04 同步实现 | `child-detail-panel.tsx` |
+| HABIT-P06 | 待办提醒习惯 | 与 LAYOUT-P01 同步实现 | `parent-attention-banner.tsx` |
+| DATA-P02 | 趋势数据可视化 | 新增 `TrendIcon`（TrendingUp/TrendingDown/Minus + aria-label） | `child-card.tsx`、`child-grade-summary.tsx` |
+| DATA-P03 | 排名展示 | 新增 "Top X%" 显示 | `child-grade-summary.tsx` |
+| DATA-P04 | 作业科目标识 | 新增 `subjectName` Badge | `child-homework-summary.tsx` |
+| DATA-P05 | 作业分数满分参照 | 分数显示新增 "pts" 单位（类型无 maxScore 字段，无法显示 X/Y） | `child-homework-summary.tsx`、`child-homework-detail.tsx` |
+| DATA-P06 | 考勤出勤率指标 | 新增 `ParentAttendanceRateCard` 出勤率汇总卡片 | `parent-attendance-rate-card.tsx`、`attendance/page.tsx` |
+| A11Y-P02 | 卡片图标辅助 | 与 LAYOUT-P02 同步实现 | `child-card.tsx` |
+| A11Y-P04 | 图表 aria-label | 容器添加 `aria-label` 描述 | `child-grade-summary.tsx` |
+| NAV-P01 | 侧边栏请假入口 | 新增 Leave Request 菜单项 | `navigation.ts` |
+| NAV-P02 | Grades/Attendance 职责区分 | 页面描述明确为"多子女对比"，详情页为"单子女分析" | `grades/page.tsx`、`attendance/page.tsx` |
+| NAV-P03 | 详情页 Tab URL | 支持 `?tab=` 参数 | `child-detail-panel.tsx`、`children/[studentId]/page.tsx` |
+| NAV-P04 | loading 骨架屏 | 新增 4 个 loading.tsx（dashboard/children/grades/attendance） | `*/loading.tsx` |
+| PERF-P01 | 首屏骨架屏 | 与 NAV-P04 同步实现 | `*/loading.tsx` |
+| PERF-P02 | 错误边界 | 新增 `parent/error.tsx` | `error.tsx` |
+| PERF-P03 | 空数据引导 | 空状态新增 `action={{ label: "Contact support", href: "/messages" }}` | `parent-dashboard.tsx` |
+| PERF-P04 | Link prefetch | Link 添加 `prefetch` 属性 | `child-card.tsx` |
+| MOBILE-P01 | 移动端宫格 | 与 LAYOUT-P03 同步实现 | `parent-dashboard.tsx` |
+| MOBILE-P03 | 子女卡片移动端水平滑动 | 移动端改为 `snap-x` Carousel，桌面端保持网格 | `parent-dashboard.tsx` |
+| MOBILE-P04 | 触摸区域 | 作业/成绩项添加 `min-h-[44px]` + `focus-visible:ring-*` | `child-homework-summary.tsx`、`child-grade-summary.tsx` |
+
+### 15.2 保留项（1 项 ⚠️）
+
+| 编号 | 标题 | 保留原因 |
+|------|------|----------|
+| A11Y-P01 | text-muted-foreground 对比度不足 | 需全局调整 `--muted-foreground` CSS 变量，影响整个应用视觉一致性，需产品评估 |
+
+### 15.3 后续迭代项（20 项）
+
+FEAT-G08/G09/G10/G11、LAYOUT-P08（导出真实实现）、HABIT-P07、MOBILE-P02/P05、A11Y-P03、PERF-P05、IA-P01~P04、CMP-* 等需要产品评估或后端支持的项，列入产品 backlog。
+
+### 15.4 验证结果
+
+- `npx tsc --noEmit`：parent 模块零错误
+- `npx eslint "src/modules/parent" "src/app/(dashboard)/parent"`：零错误零警告
+- 架构文档 004/005 已同步更新（routes / dataAccess / types / components / dependencyMatrix）

 ---

-## 七、问题汇总统计
-
-### 7.1 按修复状态统计（v1 → v3 全程）
-
-| 状态 | 数量 | 说明 |
-|------|------|------|
-| ✅ v2 已修复 | 4 | BUG-P027, BUG-P028, BUG-P029, 跨模块直查 |
-| ✅ v3 已修复 | 32 | BUG-P001~P026, BUG-P030~P035, DOC-P01~P03 |
-| ⏸️ 保留（合理权衡） | 2 | BUG-P009（时区）, BUG-P019（client component） |
-| **合计** | **38** | — |
-
-### 7.2 按技能分类统计（v3 修复）
-
-| 技能 | 修复问题数 | 主要修复内容 |
-|------|-----------|-------------|
-| 项目规范核查 | 18 | 架构违规、代码重复、类型规范、Tailwind 规范、死代码、JSDoc |
-| vercel-react-best-practices | 5 | 并行查询、memoize、模块级函数、cache 包裹、提前返回 |
-| web-design-guidelines | 9 | Link、aria-label、focus-visible、truncate、邮箱掩码、一致性 |
-| web-artifacts-builder | 6 | 响应式断点、视觉层级、View all、X 轴日期、快捷入口 |
-
---
-
-## 八、v1 → v2 → v3 改进对比
-
-### 8.1 架构合规性
-
-| 维度 | v1 | v2 | v3 |
-|------|----|----|-----|
-| app 层直查 DB | ❌ 4 张表 | ❌ 1 张表（parentStudentRelations） | ✅ 通过 `verifyParentChildRelation` |
-| data-access 直查跨模块表 | ❌ 4 张表 | ✅ 已修复 | ✅ 保持 |
-| 权限校验 | ❌ 仅 studentId | ❌ 仅 studentId | ✅ parentId + studentId |
-| 三层架构合规 | ❌ 违规 | ⚠️ 部分违规 | ✅ 完全合规 |
-
-### 8.2 代码质量
-
-| 维度 | v1 | v2 | v3 |
-|------|----|----|-----|
-| 代码重复 | ❌ attendance/grades 95% 重复 | ❌ 未修复 | ✅ 抽取共享组件 |
-| 类型规范 | ❌ 缺 JSDoc + 同名冲突 | ❌ 未修复 | ✅ JSDoc + 重命名 |
-| Tailwind 规范 | ❌ 字符串拼接 | ❌ 未修复 | ✅ 使用 cn() |
-| 死代码 | ❌ in7Days | ❌ 未修复 | ✅ 已删除 |
-
-### 8.3 性能
-
-| 维度 | v1 | v2 | v3 |
-|------|----|----|-----|
-| 串行查询瀑布 | ❌ 4 次串行 | ⚠️ 2 次串行 | ✅ Promise.all 并行 |
-| chartData memoize | ❌ 未 memoize | ❌ 未修复 | ✅ useMemo |
-| 全量查询 | ❌ getGradeOptions | ❌ 未修复 | ✅ getGradeNameById |
-| 不必要拷贝 | ❌ [...arr].sort() | ❌ 未修复 | ✅ toSorted() |
-
-### 8.4 界面规范
-
-| 维度 | v1 | v2 | v3 |
-|------|----|----|-----|
-| 客户端导航 | ❌ `<a href>` | ❌ 未修复 | ✅ `<Link>` |
-| 可访问性 | ❌ 缺 aria-label + focus | ❌ 未修复 | ✅ 完整支持 |
-| 排版规范 | ❌ `...` 手动截断 | ❌ 未修复 | ✅ truncate + 日期 X 轴 |
-| 隐私保护 | ❌ 邮箱直显 | ❌ 未修复 | ✅ maskEmail |
-| 一致性 | ❌ 标题/间距/高度不一致 | ❌ 未修复 | ✅ 统一 |
-
-### 8.5 架构文档同步
-
-| 维度 | v1 | v2 | v3 |
-|------|----|----|-----|
-| 004 依赖关系 | ❌ 缺 users/school | ❌ 未同步 | ✅ 已同步 |
-| 004 文件清单 | ❌ 行数过期 | ❌ 未同步 | ✅ 已同步 |
-| 004 已知问题 | ❌ 未记录违规 | ❌ 未记录 | ✅ 标注已修复 |
-| 005 JSON uses | ⚠️ 部分同步 | ✅ 已同步 | ✅ 更新为新函数 |
-
---
-
-## 九、保留未修复项说明
-
-### BUG-P009：问候语时区风险（保留）
-
- **原因**：项目部署环境与用户时区一致（Asia/Shanghai），Server Component 中 `new Date()` 符合实际场景
- **风险**：低（仅多时区部署时需修改）
- **未来方案**：改为传入 `timezone` 参数或移至客户端组件
-
-### BUG-P019：`"use client"` 必要性（保留）
-
- **原因**：组件需要 `useMemo`（客户端 hook），且 recharts 需客户端渲染
- **权衡**：拆分服务端/客户端组件会增加 props 序列化开销，当前 `useMemo` 已优化性能
- **未来方案**：若 recharts 体积成为瓶颈，可改用 `next/dynamic` 懒加载
-
---
-
-## 十、标杆实践（v3 最终状态）
-
-| 实践 | 位置 | 说明 |
-|------|------|------|
-| `cache()` 包裹 data-access | `data-access.ts:40,69,85,177,201` | 符合 `server-cache-react` |
-| `Promise.all` 并行获取 | `data-access.ts:95-98,182-188,217-219` | 符合 `async-parallel` |
-| `Promise.allSettled` 容错 | `attendance/page.tsx:28-36`, `grades/page.tsx:28-36` | 单个子女查询失败不影响其他 |
-| 跨模块通过 data-access 调用 | `data-access.ts:7-19` | 符合三层架构 |
-| 类型守卫替代 `as` 断言 | `data-access.ts:31-38` | `isWeekday` 类型守卫 |
-| 显式返回类型标注 | 所有 data-access 函数 | `Promise<T>` |
-| `useMemo` 优化重渲染 | `child-grade-summary.tsx:39-50` | 符合 `rerender-memo` |
-| 模块级纯函数 | `child-grade-summary.tsx:23` | `formatXTick` |
-| Server Component 默认 | 8/9 组件 | 仅 recharts 组件为 client |
-| `import type` 正确使用 | 所有类型导入 | 符合编码规范 |
-| `server-only` 标注 | `data-access.ts:1` | 防止客户端误引入 |
-| 共享组件抽取 | `parent-children-data-page.tsx` | 消除 95% 重复代码 |
-| 可访问性完整 | `child-card.tsx:20-21` | aria-label + focus-visible |
-| 隐私保护 | `child-detail-header.tsx:11-16` | maskEmail |
-| 空状态一致性 | 所有组件 `h-48` | 统一高度 |
-| 响应式断点完整 | `parent-dashboard.tsx:66` | sm/md/lg 三断点 |
-| JSDoc 文档完整 | `types.ts` | 所有类型含 JSDoc |
-| 架构文档同步 | 004 + 005 | 依赖/函数/行数均同步 |
-
---
-
-## 十一、修改文件清单
-
-### 11.1 修改的文件（13 个）
-
-| 文件 | 修改类型 |
-|------|----------|
-| `src/app/(dashboard)/parent/children/[studentId]/page.tsx` | 重写（移除 DB 直访） |
-| `src/app/(dashboard)/parent/attendance/page.tsx` | 重写（使用共享组件） |
-| `src/app/(dashboard)/parent/grades/page.tsx` | 重写（使用共享组件） |
-| `src/app/(dashboard)/parent/dashboard/page.tsx` | 重写（dataScope 检查） |
-| `src/modules/parent/data-access.ts` | 重写（verifyParentChildRelation + 优化） |
-| `src/modules/parent/types.ts` | 重写（JSDoc + 重命名） |
-| `src/modules/parent/components/parent-dashboard.tsx` | 重写（Link + 统一标题） |
-| `src/modules/parent/components/child-card.tsx` | 重写（cn + aria + focus + truncate） |
-| `src/modules/parent/components/child-detail-header.tsx` | 重写（共享 utils + maskEmail） |
-| `src/modules/parent/components/child-detail-panel.tsx` | 修改（md 断点） |
-| `src/modules/parent/components/child-grade-summary.tsx` | 重写（useMemo + 日期 X 轴） |
-| `src/modules/parent/components/child-homework-summary.tsx` | 重写（switch + hoist + View all） |
-| `src/modules/parent/components/child-schedule-card.tsx` | 修改（统一空状态高度） |
-
-### 11.2 新增的文件（3 个）
-
-| 文件 | 用途 |
-|------|------|
-| `src/modules/parent/components/parent-children-data-page.tsx` | 共享数据页布局组件 |
-| `src/modules/parent/lib/utils.ts` | 模块共享工具函数（getInitials） |
-
-### 11.3 跨模块修改的文件（2 个）
-
-| 文件 | 修改内容 |
-|------|----------|
-| `src/modules/classes/data-access.ts` | 新增 `getStudentActiveClass` 函数 |
-| `src/modules/school/data-access.ts` | 新增 `getGradeNameById` 函数 |
-
-### 11.4 同步的架构文档（2 个）
-
-| 文件 | 同步内容 |
-|------|----------|
-| `docs/architecture/004_architecture_impact_map.md` | 2.19 节依赖关系、已知问题、文件清单 |
-| `docs/architecture/005_architecture_data.json` | parent 模块 uses 节点 |
-
---
-
-> **说明**：本 v3 报告基于 2026-06-18 第三轮核查生成。v1→v2 修正了 data-access 层架构违规，v2→v3 修正了 app 层架构违规、代码重复、前端规范、性能优化、界面规范、架构文档同步等所有可修复问题。保留的 2 项（BUG-P009 时区、BUG-P019 client component）为合理权衡。parent 模块现已完全符合项目规范。
+> **说明**：本 v4 报告聚焦产品功能与用户体验维度，与 v1-v3 的代码规范维度互补。parent 模块代码质量已达标，但产品功能完整性与同类产品对比存在较大差距，建议按 P0→P1→P2 路径迭代改进。