NextEdu/bugs/parent_bug.md

# `src/app/(dashboard)/parent` 前端规范核查报告

> 核查日期：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`

---

## 一、核查文件清单

### 1.1 路由页面文件（`src/app/(dashboard)/parent/`）

| 文件 | 行数 | 类型 | 用途 |
|------|------|------|------|
| [dashboard/page.tsx](../src/app/(dashboard)/parent/dashboard/page.tsx) | 16 | Server Component | 家长仪表盘入口页 |
| [attendance/page.tsx](../src/app/(dashboard)/parent/attendance/page.tsx) | 61 | Server Component | 子女考勤聚合页 |
| [grades/page.tsx](../src/app/(dashboard)/parent/grades/page.tsx) | 61 | Server Component | 子女成绩聚合页 |
| [children/[studentId]/page.tsx](../src/app/(dashboard)/parent/children/[studentId]/page.tsx) | 71 | Server Component | 单个子女详情页 |

### 1.2 模块组件文件（`src/modules/parent/components/`）

| 文件 | 行数 | 类型 | 用途 |
|------|------|------|------|
| [parent-dashboard.tsx](../src/modules/parent/components/parent-dashboard.tsx) | 68 | Server Component | 仪表盘主组件 |
| [child-card.tsx](../src/modules/parent/components/child-card.tsx) | 89 | Server Component | 子女卡片 |
| [child-detail-header.tsx](../src/modules/parent/components/child-detail-header.tsx) | 49 | Server Component | 详情页头部 |
| [child-detail-panel.tsx](../src/modules/parent/components/child-detail-panel.tsx) | 27 | Server Component | 详情页面板 |
| [child-grade-summary.tsx](../src/modules/parent/components/child-grade-summary.tsx) | 163 | Client Component | 成绩趋势图 |
| [child-homework-summary.tsx](../src/modules/parent/components/child-homework-summary.tsx) | 131 | Server Component | 作业摘要 |
| [child-schedule-card.tsx](../src/modules/parent/components/child-schedule-card.tsx) | 67 | Server Component | 今日课表 |

### 1.3 数据访问与类型（`src/modules/parent/`）

| 文件 | 行数 | 类型 | 用途 |
|------|------|------|------|
| [data-access.ts](../src/modules/parent/data-access.ts) | 234 | server-only | 家长-子女数据聚合 |
| [types.ts](../src/modules/parent/types.ts) | 57 | 类型定义 | 模块类型 |

---

## 二、违规问题清单

### 2.1 `children/[studentId]/page.tsx` — 严重度：高（架构违规）

#### BUG-P001：app 层直接访问 DB，违反三层架构
- **位置**：`src/app/(dashboard)/parent/children/[studentId]/page.tsx:2-6, 24-31`
- **问题**：页面直接 `import { db }` 和 `parentStudentRelations` schema，并执行 `db.select().from(parentStudentRelations)` 查询
- **规范依据**：项目规则「架构分层规则」明确「`app/` 只能调用 `modules/` 的 Server Actions 和 data-access，不直接访问 DB」
- **现状**：
  ```tsx
  import { db } from "@/shared/db"
  import { parentStudentRelations } from "@/shared/db/schema"
  // ...
  const [relation] = await db
    .select({ id: parentStudentRelations.id, relation: parentStudentRelations.relation })
    .from(parentStudentRelations)
    .where(eq(parentStudentRelations.studentId, studentId))
    .limit(1)
  ```
- **改进建议**：在 `parent/data-access.ts` 新增 `verifyParentChildRelation(studentId, parentId)` 函数，页面调用该函数

#### BUG-P002：权限校验存在信息泄露风险
- **位置**：`src/app/(dashboard)/parent/children/[studentId]/page.tsx:24-31`
- **问题**：第一次查询 relation 时仅按 `studentId` 过滤，未加 `parentId = ctx.userId` 条件。任何登录用户都能探测任意 studentId 是否存在 parent 关系
- **影响**：信息泄露（可枚举 studentId 探测家庭关系）
- **改进建议**：查询条件加 `and(eq(parentStudentRelations.studentId, studentId), eq(parentStudentRelations.parentId, ctx.userId))`

#### BUG-P003：两个 "Access denied" 分支重复
- **位置**：`src/app/(dashboard)/parent/children/[studentId]/page.tsx:33-58`
- **问题**：relation 不存在与 dataScope 不包含两个分支返回完全相同的 UI，代码重复
- **改进建议**：合并为单一校验路径，或抽取 `AccessDenied` 组件

#### BUG-P004：`requireAuth()` 未做角色校验
- **位置**：`src/app/(dashboard)/parent/children/[studentId]/page.tsx:21`
- **问题**：使用 `requireAuth()` 而非 `requirePermission()`，未校验当前用户是否为 parent 角色。teacher/admin 也能访问该页面（虽然 dataScope 校验会拦截，但应前置失败）
- **改进建议**：使用 `requirePermission(PARENT_VIEW)` 或在 auth-guard 中增加角色校验

---

### 2.2 `attendance/page.tsx` 与 `grades/page.tsx` — 严重度：高（代码重复）

#### BUG-P005：两个页面文件几乎完全重复
- **位置**：`src/app/(dashboard)/parent/attendance/page.tsx` 与 `src/app/(dashboard)/parent/grades/page.tsx`
- **问题**：两个文件结构 95% 相同，仅模块名（attendance vs grades）、图标（CalendarCheck vs GraduationCap）、标题文案不同
- **违反规则**：DRY 原则，编码规范「工具函数 ≤ 40 行」隐含的复用精神
- **改进建议**：抽取共享组件 `ParentChildrenDataPage`，通过 props 传入 `fetcher`、`icon`、`title`、`emptyTitle`、`renderItem`

  ```tsx
  // 抽取后的共享组件
  function ParentChildrenDataPage<T>({
    title, description, icon, fetcher, renderItem, emptyTitle, emptyDescription,
  }: ParentChildrenDataPageProps<T>) { /* ... */ }
  ```

#### BUG-P006：`Promise.all` 内部异常未处理
- **位置**：`src/app/(dashboard)/parent/attendance/page.tsx:29-31`、`grades/page.tsx:29-31`
- **问题**：`ctx.dataScope.childrenIds.map((id) => getStudentAttendanceSummary(id))` 若任一查询抛错，整个页面 500。未做 try-catch 或 Promise.allSettled
- **改进建议**：使用 `Promise.allSettled` 并过滤 rejected，或对单个子女查询失败显示局部错误状态

---

### 2.3 `dashboard/page.tsx` — 严重度：中

#### BUG-P007：缺少 dataScope 空状态处理
- **位置**：`src/app/(dashboard)/parent/dashboard/page.tsx:7-15`
- **问题**：未检查 `ctx.dataScope.type === "children"` 或 `childrenIds.length === 0`，直接调用 `getParentDashboardData(ctx.userId)`。虽然 data-access 会返回空数组，但与 attendance/grades 页面的处理方式不一致
- **改进建议**：与 attendance/grades 页面统一，前置检查 dataScope

---

### 2.4 `parent-dashboard.tsx` — 严重度：中

#### BUG-P008：使用 `<a href>` 而非 `<Link>`，丢失客户端导航
- **位置**：`src/modules/parent/components/parent-dashboard.tsx:30, 36`
- **问题**：`<a href="/parent/grades">` 和 `<a href="/announcements">` 使用原生 `<a>` 标签，导致整页刷新，丢失 Next.js 客户端路由优化
- **违反规则**：Web Interface Guidelines — Navigation & State「Links use `<a>`/`<Link>` (Cmd/Ctrl+click, middle-click support)」；Next.js 最佳实践
- **改进建议**：`import Link from "next/link"`，使用 `<Link href="/parent/grades">`

#### BUG-P009：问候语使用 `new Date().getHours()` 存在时区风险
- **位置**：`src/modules/parent/components/parent-dashboard.tsx:12-16`
- **问题**：服务端渲染时使用服务器时区计算问候语，与用户实际时区可能不符（例如部署在 UTC 服务器，北京时间早 8 点用户看到 "Good afternoon"）
- **违反规则**：Web Interface Guidelines — Locale & i18n「Dates/times: use `Intl.DateTimeFormat` not hardcoded formats」
- **改进建议**：使用 `Intl.DateTimeFormat(undefined, { hour: "numeric", timeZone: ctx.timezone })` 或将问候语计算移至客户端组件

#### BUG-P010：标题层级与间距与其他页面不一致
- **位置**：`src/modules/parent/components/parent-dashboard.tsx:22` vs `attendance/page.tsx:16`、`grades/page.tsx::16`
- **问题**：dashboard 使用 `text-3xl` + `space-y-6`，attendance/grades 使用 `text-2xl` + `space-y-8`
- **违反规则**：web-artifacts-builder 设计一致性原则
- **改进建议**：统一标题字号（建议 `text-2xl`）和间距（建议 `space-y-6`）

---

### 2.5 `child-card.tsx` — 严重度：中

#### BUG-P011：`getInitials` 函数重复定义
- **位置**：`src/modules/parent/components/child-card.tsx:9-12` 与 `src/modules/parent/components/child-detail-header.tsx:9-12`
- **问题**：两个文件定义了完全相同的 `getInitials` 函数
- **违反规则**：DRY 原则
- **改进建议**：抽取到 `src/modules/parent/lib/utils.ts` 或 `src/shared/lib/utils.ts`

#### BUG-P012：使用字符串拼接动态类名，违反 Tailwind 规范
- **位置**：`src/modules/parent/components/child-card.tsx:57-60`
- **问题**：
  ```tsx
  className={`text-lg font-semibold tabular-nums ${
    homeworkSummary.overdueCount > 0 ? "text-destructive" : ""
  }`}
  ```
  使用模板字符串拼接类名，违反编码规范「Tailwind 规范：使用 `cn()` 工具函数管理条件类名」
- **对比**：同模块 `child-homework-summary.tsx:72-75` 正确使用了 `cn()`
- **改进建议**：
  ```tsx
  className={cn(
    "text-lg font-semibold tabular-nums",
    homeworkSummary.overdueCount > 0 && "text-destructive",
  )}
  ```

#### BUG-P013：手动截断标题，应使用 Tailwind `truncate`/`line-clamp`
- **位置**：`src/modules/parent/components/child-card.tsx:81-83`
- **问题**：
  ```tsx
  ({latestGrade.assignmentTitle.slice(0, 20)}
  {latestGrade.assignmentTitle.length > 20 ? "..." : ""})
  ```
  手动 slice + "..." 截断，违反 Web Interface Guidelines — Typography「`…` not `...`」
- **改进建议**：使用 `<span className="truncate inline-block max-w-[200px]">{latestGrade.assignmentTitle}</span>`

#### BUG-P014：`cursor-pointer` 在 Link 上冗余
- **位置**：`src/modules/parent/components/child-card.tsx:21`
- **问题**：`<Card className="hover:bg-muted/50 transition-colors cursor-pointer h-full">` 中 `cursor-pointer` 冗余（外层 `<Link>` 默认 pointer）
- **违反规则**：Web Interface Guidelines — Anti-patterns
- **改进建议**：移除 `cursor-pointer`

#### BUG-P015：整个 Card 作为 Link 缺少可访问性描述
- **位置**：`src/modules/parent/components/child-card.tsx:20-87`
- **问题**：`<Link>` 包裹整个 Card，屏幕阅读器会读出所有内部文本（姓名、班级、数字、最新成绩），缺少简洁的 aria-label
- **违反规则**：Web Interface Guidelines — Accessibility「Icon-only buttons need `aria-label`」延伸到卡片导航
- **改进建议**：`<Link href={...} aria-label={`查看 ${basicInfo.name ?? "子女"} 的详情`}>`

#### BUG-P016：Link 缺少 `focus-visible:ring` 样式
- **位置**：`src/modules/parent/components/child-card.tsx:20-21`
- **问题**：`<Link>` 包裹 Card，但 Card 没有 `focus-visible:ring-*` 样式，键盘导航时无可见焦点
- **违反规则**：Web Interface Guidelines — Focus States「Interactive elements need visible focus」
- **改进建议**：添加 `focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2`

---

### 2.6 `child-detail-header.tsx` — 严重度：低

#### BUG-P017：`getInitials` 重复（同 BUG-P011）
- **位置**：`src/modules/parent/components/child-detail-header.tsx:9-12`
- **改进建议**：见 BUG-P011

#### BUG-P018：邮箱直接展示未做防爬处理
- **位置**：`src/modules/parent/components/child-detail-header.tsx:43`
- **问题**：`<span>· {basicInfo.email}</span>` 直接展示子女邮箱，无防爬/掩码处理
- **改进建议**：考虑隐私场景下掩码处理（如 `j***@example.com`），或仅对家长本人可见时展示完整

---

### 2.7 `child-grade-summary.tsx` — 严重度：中

#### BUG-P019：`"use client"` 必要性可优化
- **位置**：`src/modules/parent/components/child-grade-summary.tsx:1`
- **问题**：组件标记为 `"use client"`，但实际仅 `recharts` 需要客户端。整个组件（包括数据预处理 `chartData` 计算）都被打包到客户端 bundle
- **违反规则**：`vercel-react-best-practices` — `bundle-dynamic-imports`「Use next/dynamic for heavy components」
- **改进建议**：将图表部分抽取为独立的客户端组件 `GradeTrendChart`，父组件保持服务端组件，通过 `next/dynamic` 懒加载图表

#### BUG-P020：`latestGrade` 取数组末尾，语义不明确
- **位置**：`src/modules/parent/components/child-grade-summary.tsx:32`
- **问题**：`const latestGrade = grades.trend[grades.trend.length - 1]` 假设 trend 是按时间升序排列，但类型定义 `StudentDashboardGradeProps` 未明确顺序
- **对比**：`child-card.tsx:17` 使用 `gradeTrend.recent[0]` 取最新（假设 recent 是降序）
- **改进建议**：在 `homework/types.ts` 的 `StudentDashboardGradeProps` 中补充 JSDoc 说明 `trend` 和 `recent` 的排序语义

#### BUG-P021：`chartData` 在每次渲染时重新计算
- **位置**：`src/modules/parent/components/child-grade-summary.tsx:34-41`
- **问题**：`const chartData = grades.trend.map(...)` 每次渲染都重新 map，未 memoize
- **违反规则**：`vercel-react-best-practices` — `rerender-memo`「Extract expensive work into memoized components」
- **改进建议**：`const chartData = useMemo(() => grades.trend.map(...), [grades.trend])`

#### BUG-P022：`tickFormatter` 内联函数每次渲染创建新引用
- **位置**：`src/modules/parent/components/child-grade-summary.tsx:99-101`
- **问题**：`tickFormatter={(value) => value.slice(0, 8) + (value.length > 8 ? "..." : "")}` 内联箭头函数
- **违反规则**：Web Interface Guidelines — Typography「`…` not `...`」；`vercel-react-best-practices` — `rerender-functional-setstate`
- **改进建议**：抽取为模块级纯函数 `const formatTick = (v: string) => v.slice(0, 8) + (v.length > 8 ? "…" : "")`

#### BUG-P023：使用 `"..."` 应为 `…`
- **位置**：`src/modules/parent/components/child-grade-summary.tsx:100`
- **问题**：`value.length > 8 ? "..." : ""` 使用三个英文句号，应为省略号字符 `…`
- **违反规则**：Web Interface Guidelines — Typography「`…` not `...`」

---

### 2.8 `child-homework-summary.tsx` — 严重度：低

#### BUG-P024：状态字符串硬编码，应使用枚举/常量
- **位置**：`src/modules/parent/components/child-homework-summary.tsx:10-21`
- **问题**：`getStatusVariant` 和 `getStatusLabel` 使用硬编码字符串 `"graded"`、`"submitted"`、`"in_progress"` 比较
- **改进建议**：从 `homework/types.ts` 导入状态常量或联合类型，使用 switch + exhaustive check

#### BUG-P025：`getDueUrgency` 在渲染期调用 `new Date()`
- **位置**：`src/modules/parent/components/child-homework-summary.tsx:23-31, 95`
- **问题**：每次 `map` 迭代都调用 `new Date()` 创建新日期对象，虽然性能影响小，但语义上应在外层计算一次 `now`
- **改进建议**：在组件顶部 `const now = new Date()` 一次，传入 `getDueUrgency(a.dueAt, now)`

---

### 2.9 `child-schedule-card.tsx` — 严重度：低

#### BUG-P026：空状态高度与其他组件不一致
- **位置**：`src/modules/parent/components/child-schedule-card.tsx:31`
- **问题**：`className="border-none h-60"`，而 `child-grade-summary.tsx:57` 使用 `h-60`，`child-homework-summary.tsx:87` 使用 `h-40`
- **改进建议**：统一空状态高度（建议 `h-48`）

---

### 2.10 `data-access.ts` — 严重度：中

#### BUG-P027：`toWeekday` 使用 `as` 类型断言
- **位置**：`src/modules/parent/data-access.ts:28-31`
- **问题**：
  ```ts
  const toWeekday = (d: Date): 1 | 2 | 3 | 4 | 5 | 6 | 7 => {
    const day = d.getDay()
    return (day === 0 ? 7 : day) as 1 | 2 | 3 | 4 | 5 | 6 | 7
  }
  ```
  使用 `as` 类型断言，违反编码规范「禁止 `as` 断言（除非从 `unknown` 转换）」
- **改进建议**：使用类型守卫
  ```ts
  const toWeekday = (d: Date): 1 | 2 | 3 | 4 | 5 | 6 | 7 => {
    const day = d.getDay()
    const weekday = day === 0 ? 7 : day
    if (weekday < 1 || weekday > 7) throw new Error(`Invalid weekday: ${weekday}`)
    return weekday
  }
  ```

#### BUG-P028：`getChildBasicInfo` 串行查询瀑布（架构图已标注 P2）
- **位置**：`src/modules/parent/data-access.ts:58-117`
- **问题**：4 个串行 DB 查询：users → grades → classEnrollments → classes。其中 grades 和 classEnrollments 互相独立，可并行
- **违反规则**：`vercel-react-best-practices` — `async-parallel`「Use Promise.all() for independent operations」
- **架构图标注**：004 文档 2.19 节「⚠️ P2：`getChildBasicInfo` 多次串行查询，可优化为 join」
- **改进建议**：
  ```ts
  // grades 和 classEnrollments 并行
  const [gradeRow, enrollment] = await Promise.all([
    student.gradeId
      ? db.select({ name: grades.name }).from(grades).where(eq(grades.id, student.gradeId)).limit(1)
      : Promise.resolve([]),
    db.select({ classId: classEnrollments.classId, status: classEnrollments.status })
      .from(classEnrollments)
      .where(and(eq(classEnrollments.studentId, studentId), eq(classEnrollments.status, "active")))
      .orderBy(asc(classEnrollments.createdAt))
      .limit(1),
  ])
  ```
  或重构为单次 JOIN 查询

#### BUG-P029：`getChildBasicInfo` 返回类型未显式标注
- **位置**：`src/modules/parent/data-access.ts:58`
- **问题**：`export const getChildBasicInfo = cache(async (studentId: string, relation: string | null = null) => {` 未显式标注返回类型
- **违反规则**：编码规范「函数返回值必须显式标注，特别是 `Promise<T>`」
- **改进建议**：定义 `ChildBasicInfo` 返回类型并显式标注（`types.ts` 中已有 `ChildBasicInfo` 类型，可直接使用）

#### BUG-P030：`buildHomeworkSummary` 中 `[...assignments].sort()` 不必要的拷贝
- **位置**：`src/modules/parent/data-access.ts:150-156`
- **问题**：`[...assignments].sort(...)` 创建数组副本再排序。`assignments` 来自 `getStudentHomeworkAssignments` 返回的新数组，无需再拷贝
- **改进建议**：直接 `assignments.sort(...)` 或使用 `toSorted()`（ES2023）

---

### 2.11 `types.ts` — 严重度：低

#### BUG-P031：类型缺少 JSDoc 文档注释
- **位置**：`src/modules/parent/types.ts` 全文件
- **问题**：所有类型（`ParentChildRelation`、`ChildBasicInfo`、`ChildScheduleItem`、`ChildHomeworkSummary`、`ChildDashboardData`、`ParentDashboardData`）均无 JSDoc
- **违反规则**：编码规范 5.4「必须编写 JSDoc」
- **改进建议**：为每个类型补充 JSDoc，说明用途、字段语义

#### BUG-P032：`ChildHomeworkSummary` 与组件同名类型冲突风险
- **位置**：`src/modules/parent/types.ts:37` 与 `child-homework-summary.tsx:33`
- **问题**：类型名 `ChildHomeworkSummary` 与组件名 `ChildHomeworkSummary` 完全相同，在 `child-homework-summary.tsx` 中同时 import 两者会造成命名冲突
  ```tsx
  import type { ChildHomeworkSummary } from "@/modules/parent/types"  // 类型
  export function ChildHomeworkSummary({ summary }: { summary: ChildHomeworkSummary }) // 组件
  ```
  当前依赖 TypeScript 类型与值的命名空间分离才不冲突，但可读性差
- **改进建议**：类型重命名为 `ChildHomeworkSummaryData` 或组件重命名为 `ChildHomeworkSummaryCard`

---

## 三、React 性能优化（应用 `vercel-react-best-practices` 技能）

### PERF-P01：`getChildBasicInfo` 串行查询瀑布（同 BUG-P028）
- **违反规则**：`async-parallel` — Use Promise.all() for independent operations
- **改进建议**：见 BUG-P028

### PERF-P02：`chartData` 未 memoize（同 BUG-P021）
- **违反规则**：`rerender-memo` — Extract expensive work into memoized components
- **改进建议**：见 BUG-P021

### PERF-P03：`child-grade-summary.tsx` 整体客户端化，bundle 体积大
- **位置**：`src/modules/parent/components/child-grade-summary.tsx:1`
- **问题**：`"use client"` 导致 recharts（~100KB）整体进入客户端 bundle，但组件大部分逻辑（数据预处理、布局）可在服务端完成
- **违反规则**：`bundle-dynamic-imports` — Use next/dynamic for heavy components
- **改进建议**：
  ```tsx
  // child-grade-summary.tsx (Server Component)
  import dynamic from "next/dynamic"
  const GradeTrendChart = dynamic(() => import("./grade-trend-chart").then(m => m.GradeTrendChart))
  // 仅图表部分客户端化
  ```

### PERF-P04：`getParentDashboardData` 内部 `Promise.all` 已正确并行化
- **位置**：`src/modules/parent/data-access.ts:225-227`
- **说明**：✅ 已正确使用 `Promise.all` 并行获取所有子女数据，符合 `async-parallel` 规范

### PERF-P05：`getChildDashboardData` 内部 `Promise.all` 已正确并行化
- **位置**：`src/modules/parent/data-access.ts:190-196`
- **说明**：✅ 已正确使用 `Promise.all` 并行获取 enrolledClasses/schedule/assignments/gradeTrend/gradeSummary

### PERF-P06：`cache()` 已正确包裹 data-access 函数
- **位置**：`src/modules/parent/data-access.ts:33, 58, 185, 209`
- **说明**：✅ 所有 data-access 函数均使用 React `cache()` 包裹，符合 `server-cache-react` 规范，实现单次请求内去重

### PERF-P07：`parent-dashboard.tsx` 中 `new Date()` 在服务端执行无 hydration 风险
- **位置**：`src/modules/parent/components/parent-dashboard.tsx:12`
- **说明**：✅ 组件为 Server Component，`new Date()` 仅在服务端执行一次，无 hydration mismatch 风险（但有时区问题，见 BUG-P009）

---

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

### UI-P01：`parent-dashboard.tsx`

```
src/modules/parent/components/parent-dashboard.tsx:30 - <a href> → use <Link> for client-side nav
src/modules/parent/components/parent-dashboard.tsx:36 - <a href> → use <Link> for client-side nav
src/modules/parent/components/parent-dashboard.tsx:12 - new Date() server-side, timezone mismatch risk
src/modules/parent/components/parent-dashboard.tsx:22 - title size inconsistent (text-3xl vs text-2xl in other pages)
```

### UI-P02：`child-card.tsx`

```
src/modules/parent/components/child-card.tsx:20 - Link wrapping Card lacks aria-label
src/modules/parent/components/child-card.tsx:21 - cursor-pointer redundant on Link
src/modules/parent/components/child-card.tsx:21 - missing focus-visible:ring-* for keyboard nav
src/modules/parent/components/child-card.tsx:57 - string concatenation for className → use cn()
src/modules/parent/components/child-card.tsx:82 - "..." → "…"
src/modules/parent/components/child-card.tsx:82 - manual slice truncation → use truncate/line-clamp
```

### UI-P03：`child-grade-summary.tsx`

```
src/modules/parent/components/child-grade-summary.tsx:100 - "..." → "…"
src/modules/parent/components/child-grade-summary.tsx:99 - inline tickFormatter → hoist to module scope
src/modules/parent/components/child-grade-summary.tsx:142 - Link lacks query param for tab deep-linking
```

### UI-P04：`child-homework-summary.tsx`

```
src/modules/parent/components/child-homework-summary.tsx:98 - Link lacks query param for tab deep-linking
src/modules/parent/components/child-homework-summary.tsx:25 - new Date() in each map iteration → hoist to component scope
```

### UI-P05：`child-detail-header.tsx`

```
src/modules/parent/components/child-detail-header.tsx:43 - email displayed without masking (privacy)
```

### UI-P06：`attendance/page.tsx` & `grades/page.tsx`

```
src/app/(dashboard)/parent/attendance/page.tsx:14 - h-full flex-1 flex-col space-y-8 p-8 md:flex → inconsistent with dashboard/page.tsx (p-6 md:p-8)
src/app/(dashboard)/parent/grades/page.tsx:14 - same inconsistency as above
```

### UI-P07：空状态一致性

```
src/modules/parent/components/child-schedule-card.tsx:31 - EmptyState h-60
src/modules/parent/components/child-grade-summary.tsx:57 - EmptyState h-60
src/modules/parent/components/child-homework-summary.tsx:87 - EmptyState h-40
src/app/(dashboard)/parent/attendance/page.tsx:24 - EmptyState border-none shadow-none (no height)
→ unify EmptyState height and className
```

---

## 五、界面优化建议（应用 `web-artifacts-builder` 技能）

### UIX-P01：子女卡片网格响应式断点不足
- **位置**：`src/modules/parent/components/parent-dashboard.tsx:59`
- **问题**：`grid-cols-1 md:grid-cols-2 lg:grid-cols-3` 在 sm 屏幕下强制单列，2 列布局在 sm（640px）下更合适
- **改进建议**：`grid-cols-1 sm:grid-cols-2 lg:grid-cols-3`

### UIX-P02：详情页布局中等屏幕下右侧栏过窄
- **位置**：`src/modules/parent/components/child-detail-panel.tsx:12`
- **问题**：`grid-cols-1 lg:grid-cols-3` 在 md（768-1024px）下为单列，但 `lg:col-span-2` 在 lg 下才生效，md 下左侧内容占满，右侧课表也在下方
- **改进建议**：增加 md 断点 `grid-cols-1 md:grid-cols-2 lg:grid-cols-3`，左侧 `md:col-span-1 lg:col-span-2`

### UIX-P03：卡片内嵌套卡片视觉层级混乱
- **位置**：`src/modules/parent/components/child-card.tsx:43-73`
- **问题**：Card 内部 CardContent 中又使用 `rounded-md border bg-card p-2` 创建 3 个小卡片，与外层 Card 视觉层级冲突
- **改进建议**：内部小卡片改用 `bg-muted/50` 或移除 border，弱化层级

### UIX-P04：作业摘要卡片缺少"查看全部"链接
- **位置**：`src/modules/parent/components/child-homework-summary.tsx:90-126`
- **问题**：仅展示 `recentAssignments`（最多 5 条），无"查看全部作业"入口
- **改进建议**：底部添加 `<Link href="/parent/children/{childId}?tab=homework">View all</Link>`

### UIX-P05：成绩趋势图 X 轴标签截断后信息丢失
- **位置**：`src/modules/parent/components/child-grade-summary.tsx:94-102`
- **问题**：`tickFormatter` 截断为 8 字符 + "…"，多个作业标题前 8 字符相同时无法区分
- **改进建议**：X 轴改为日期（`formatDate(submittedAt)`），标题在 tooltip 中完整展示

### UIX-P06：仪表盘快捷入口仅 2 个，可扩展
- **位置**：`src/modules/parent/components/parent-dashboard.tsx:28-41`
- **问题**：仅有 Grades 和 Announcements 两个快捷按钮，缺少 Attendance、Schedule 等常用入口
- **改进建议**：增加 Attendance 快捷入口，或改为下拉菜单

---

## 六、架构文档同步问题

### DOC-P01：004 文档 parent 模块行数记录过期
- **位置**：`docs/architecture/004_architecture_impact_map.md:924`
- **问题**：记录 `data-access.ts | 234 | 子女关系 + 仪表盘数据聚合`，实际 234 行 ✅ 一致；但 `components/* | 7 文件` 实际为 7 个组件文件 ✅ 一致
- **说明**：本节核查后无需更新（行数与文件数均一致）

### DOC-P02：004 文档未记录 `children/[studentId]/page.tsx` 的架构违规
- **位置**：`docs/architecture/004_architecture_impact_map.md` 2.19 节
- **问题**：未在 parent 模块「已知问题」中记录 `app/(dashboard)/parent/children/[studentId]/page.tsx` 直接访问 DB 的违规（BUG-P001）
- **改进建议**：在 004 文档 2.19 节「已知问题」中补充：
  ```
  - ❌ P1：`app/(dashboard)/parent/children/[studentId]/page.tsx` 直接访问 DB（违反三层架构）
  ```

### DOC-P03：005 JSON 中 parent 模块的 routes 节点需补充
- **问题**：若修复 BUG-P005（抽取共享组件），路由结构不变，但需在 005 JSON 中记录 attendance/grades 页面的 fetcher 依赖关系
- **改进建议**：在 `005_architecture_data.json` 的 `modules.parent.dependencies` 中补充 `attendance`、`grades` 模块依赖

---

## 七、问题汇总统计

| 严重度 | 数量 | 问题编号 |
|--------|------|----------|
| 高（架构违规/安全） | 6 | BUG-P001, BUG-P002, BUG-P004, BUG-P005, BUG-P006, BUG-P028 |
| 中（规范违规/性能） | 12 | BUG-P003, BUG-P007, BUG-P008, BUG-P009, BUG-P010, BUG-P011, BUG-P012, BUG-P019, BUG-P020, BUG-P021, BUG-P027, BUG-P029 |
| 低（代码质量/UX） | 13 | BUG-P013, BUG-P014, BUG-P015, BUG-P016, BUG-P017, BUG-P018, BUG-P022, BUG-P023, BUG-P024, BUG-P025, BUG-P026, BUG-P030, BUG-P031, BUG-P032 |
| 合计 | 31 | — |

### 按技能分类统计

| 技能 | 发现问题数 | 主要问题类型 |
|------|-----------|-------------|
| 项目规范核查 | 18 | 架构违规、代码重复、类型规范、Tailwind 规范 |
| vercel-react-best-practices | 7 | 串行查询瀑布、bundle 体积、memoize 缺失 |
| web-design-guidelines | 15 | 可访问性、焦点状态、排版、导航、空状态一致性 |
| web-artifacts-builder | 6 | 响应式断点、视觉层级、交互入口、图表可读性 |

---

## 八、修复优先级建议

### P0（立即修复 — 架构与安全）
1. **BUG-P001**：`children/[studentId]/page.tsx` 移除直接 DB 访问，下沉到 `parent/data-access.ts`
2. **BUG-P002**：权限校验加 `parentId` 条件，防止信息泄露
3. **BUG-P005**：抽取 `ParentChildrenDataPage` 共享组件，消除 attendance/grades 重复

### P1（短期修复 — 规范与性能）
4. **BUG-P008**：`<a href>` 改为 `<Link>`
5. **BUG-P012**：`child-card.tsx` 使用 `cn()` 替代字符串拼接
6. **BUG-P011**：抽取 `getInitials` 到共享 utils
7. **BUG-P028**：`getChildBasicInfo` 并行化查询
8. **BUG-P019**：`child-grade-summary.tsx` 拆分服务端/客户端组件
9. **BUG-P027**：`toWeekday` 移除 `as` 断言
10. **BUG-P029**：`getChildBasicInfo` 显式标注返回类型

### P2（机会修复 — UX 与代码质量）
11. **BUG-P009**：问候语时区处理
12. **BUG-P013**：使用 `truncate` 替代手动截断
13. **BUG-P015, BUG-P016**：卡片可访问性增强
14. **BUG-P023**：`...` → `…`
15. **BUG-P031**：补充类型 JSDoc
16. **UIX-P01~P06**：界面优化项

---

## 九、标杆实践（建议保留）

| 实践 | 位置 | 说明 |
|------|------|------|
| `cache()` 包裹 data-access | `data-access.ts:33, 58, 185, 209` | 符合 `server-cache-react`，单次请求去重 |
| `Promise.all` 并行获取子女数据 | `data-access.ts:190-196, 225-227` | 符合 `async-parallel`，消除瀑布 |
| Server Component 默认 | 7/8 组件为 Server Component | 仅 `child-grade-summary.tsx` 因 recharts 标记 client |
| `import type` 正确使用 | 所有类型导入均使用 `import type` | 符合编码规范 4.2.6 |
| `server-only` 标注 | `data-access.ts:1` | 防止 data-access 被客户端误引入 |
| 空状态处理完整 | 所有页面均使用 `EmptyState` 组件 | UX 一致性良好 |

---

> **说明**：本报告基于 2026-06-18 代码状态生成。修复后需同步更新 `docs/architecture/004_architecture_impact_map.md` 2.19 节与 `005_architecture_data.json` 的 parent 模块节点。