NextEdu/bugs/others_bug.md

# `src/app/(dashboard)/{announcements,dashboard,management,messages,profile,settings}` 规范核查报告

> 核查日期：2026-06-18
> 核查范围：`src/app/(dashboard)/` 下的 announcements、dashboard、management、messages、profile、settings 子路由及其直接依赖的模块组件
> 依据文档：
> - [项目规则](../.trae/rules/project_rules.md)
> - [编码规范](../docs/standards/coding-standards.md)
> - [架构影响地图 004](../docs/architecture/004_architecture_impact_map.md)
> - [架构数据 005](../docs/architecture/005_architecture_data.json)
> 应用技能：`vercel-react-best-practices`、`web-design-guidelines`（`web-artifacts-builder` 加载失败，界面优化建议已合并至 web-design-guidelines 章节）

---

## 一、核查文件清单

| 文件 | 行数 | 类型 | 用途 |
|------|------|------|------|
| [announcements/page.tsx](../src/app/(dashboard)/announcements/page.tsx) | 20 | RSC 页面 | 公告列表（普通用户） |
| [dashboard/page.tsx](../src/app/(dashboard)/dashboard/page.tsx) | 18 | RSC 页面 | 角色路由分发 |
| [management/grade/classes/page.tsx](../src/app/(dashboard)/management/grade/classes/page.tsx) | 31 | RSC 页面 | 年级班级管理 |
| [management/grade/insights/page.tsx](../src/app/(dashboard)/management/grade/insights/page.tsx) | 243 | RSC 页面 | 年级作业洞察 |
| [messages/page.tsx](../src/app/(dashboard)/messages/page.tsx) | 31 | RSC 页面 | 消息+通知列表 |
| [messages/[id]/page.tsx](../src/app/(dashboard)/messages/[id]/page.tsx) | 30 | RSC 页面 | 消息详情 |
| [messages/compose/page.tsx](../src/app/(dashboard)/messages/compose/page.tsx) | 34 | RSC 页面 | 撰写消息 |
| [profile/page.tsx](../src/app/(dashboard)/profile/page.tsx) | 305 | RSC 页面 | 个人资料（学生/教师视图） |
| [settings/page.tsx](../src/app/(dashboard)/settings/page.tsx) | 32 | RSC 页面 | 设置入口（按角色分发） |
| [settings/security/page.tsx](../src/app/(dashboard)/settings/security/page.tsx) | 50 | RSC 页面 | 安全设置 |
| [layout.tsx](../src/app/(dashboard)/layout.tsx) | 21 | RSC 布局 | Dashboard 通用布局 |
| [error.tsx](../src/app/(dashboard)/error.tsx) | 22 | 客户端组件 | 错误边界 |
| [not-found.tsx](../src/app/(dashboard)/not-found.tsx) | 23 | RSC 组件 | 404 页面 |
| [modules/announcements/components/announcement-list.tsx](../src/modules/announcements/components/announcement-list.tsx) | 108 | 客户端组件 | 公告列表（含筛选） |
| [modules/announcements/components/announcement-card.tsx](../src/modules/announcements/components/announcement-card.tsx) | 79 | 客户端组件 | 公告卡片 |
| [modules/announcements/components/announcement-detail.tsx](../src/modules/announcements/components/announcement-detail.tsx) | 206 | 客户端组件 | 公告详情 |
| [modules/messaging/components/message-list.tsx](../src/modules/messaging/components/message-list.tsx) | 117 | 客户端组件 | 消息列表 |
| [modules/messaging/components/message-detail.tsx](../src/modules/messaging/components/message-detail.tsx) | 153 | 客户端组件 | 消息详情 |
| [modules/messaging/components/message-compose.tsx](../src/modules/messaging/components/message-compose.tsx) | 146 | 客户端组件 | 撰写消息表单 |
| [modules/messaging/components/notification-list.tsx](../src/modules/messaging/components/notification-list.tsx) | 141 | 客户端组件 | 通知列表 |
| [modules/settings/components/admin-settings-view.tsx](../src/modules/settings/components/admin-settings-view.tsx) | 129 | 客户端组件 | 管理员设置视图 |
| [modules/settings/components/teacher-settings-view.tsx](../src/modules/settings/components/teacher-settings-view.tsx) | 132 | 客户端组件 | 教师设置视图 |
| [modules/settings/components/student-settings-view.tsx](../src/modules/settings/components/student-settings-view.tsx) | 120 | 客户端组件 | 学生设置视图 |
| [modules/settings/components/password-change-form.tsx](../src/modules/settings/components/password-change-form.tsx) | 180 | 客户端组件 | 修改密码表单 |
| [modules/settings/components/profile-settings-form.tsx](../src/modules/settings/components/profile-settings-form.tsx) | 198 | 客户端组件 | 资料编辑表单 |
| [modules/settings/components/notification-preferences-form.tsx](../src/modules/settings/components/notification-preferences-form.tsx) | 260 | 客户端组件 | 通知偏好表单 |
| [modules/settings/components/theme-preferences-card.tsx](../src/modules/settings/components/theme-preferences-card.tsx) | 60 | 客户端组件 | 主题偏好 |
| [modules/settings/components/ai-provider-settings-card.tsx](../src/modules/settings/components/ai-provider-settings-card.tsx) | 405 | 客户端组件 | AI Provider 配置 |
| [modules/classes/components/grade-classes-view.tsx](../src/modules/classes/components/grade-classes-view.tsx) | 455 | 客户端组件 | 年级班级管理视图 |

---

## 二、违规问题清单

### 2.1 [announcements/page.tsx](../src/app/(dashboard)/announcements/page.tsx) — 严重度：高

#### BUG-A01：缺少权限校验（违反 Server Action 规范）
- **位置**：`src/app/(dashboard)/announcements/page.tsx:6-7`
- **问题**：页面直接调用 `getAnnouncements({ status: "published" })`，未通过 `requirePermission()` 或 `requireAuth()` 进行任何权限校验
- **规范依据**：项目规则「Server Action 必须使用 `requirePermission()` 进行权限校验」；架构文档 004 已记录此问题（P2-12）
- **影响**：未登录用户可直接访问 `/announcements` 路由获取公告数据，存在信息泄露风险
- **改进建议**：
  ```typescript
  import { requirePermission } from "@/shared/lib/auth-guard"
  import { Permissions } from "@/shared/types/permissions"

  export default async function AnnouncementsPage() {
    await requirePermission(Permissions.ANNOUNCEMENT_READ)
    const announcements = await getAnnouncements({ status: "published" })
    // ...
  }
  ```

#### BUG-A02：缺少 `metadata` 导出
- **位置**：`src/app/(dashboard)/announcements/page.tsx`
- **问题**：未导出 `metadata`，浏览器标签页无标题
- **规范依据**：Web Interface Guidelines — Metadata & SEO
- **改进建议**：补充 `export const metadata = { title: "Announcements" }`

---

### 2.2 [dashboard/page.tsx](../src/app/(dashboard)/dashboard/page.tsx) — 严重度：中

#### BUG-D01：使用权限反推角色（硬编码反模式）
- **位置**：`src/app/(dashboard)/dashboard/page.tsx:14-16`
- **问题**：使用 `permissions.includes(HOMEWORK_SUBMIT) && !permissions.includes(EXAM_CREATE)` 反推学生身份，应使用 `hasRole("student")`
- **规范依据**：项目规则「前端组件禁止使用 `role === "xxx"` 硬编码，统一使用 `usePermission().hasPermission()`」；架构文档 004 已标记此为 P2 问题
- **影响**：当学生被授予 `EXAM_CREATE` 权限（如助教）时会被错误路由到教师页面
- **改进建议**：服务端应使用 `session.user.roles` 判断
  ```typescript
  const roles = session.user.roles ?? []
  if (roles.includes("admin")) redirect("/admin/dashboard")
  if (roles.includes("student")) redirect("/student/dashboard")
  if (roles.includes("parent")) redirect("/parent/dashboard")
  redirect("/teacher/dashboard")
  ```

#### BUG-D02：多重 `redirect` 调用难以维护
- **位置**：`src/app/(dashboard)/dashboard/page.tsx:14-17`
- **问题**：4 个连续 `if + redirect` 缺乏优先级文档说明，新增角色时易遗漏
- **改进建议**：抽取为 `resolveDefaultPath(roles)` 单一函数（`proxy.ts` 已有类似实现），保持单一职责

---

### 2.3 [management/grade/classes/page.tsx](../src/app/(dashboard)/management/grade/classes/page.tsx) — 严重度：高

#### BUG-M01：缺少权限校验
- **位置**：`src/app/(dashboard)/management/grade/classes/page.tsx:7-15`
- **问题**：仅调用 `auth()` 获取 session，未调用 `requirePermission()` 校验 `CLASS_MANAGE` 权限
- **规范依据**：项目规则「Server Action 必须使用 `requirePermission()` 进行权限校验」
- **影响**：无 `CLASS_MANAGE` 权限的用户可访问页面并获取教师列表、年级数据
- **改进建议**：
  ```typescript
  import { requirePermission } from "@/shared/lib/auth-guard"
  import { Permissions } from "@/shared/types/permissions"

  export default async function GradeClassesPage() {
    const ctx = await requirePermission(Permissions.CLASS_MANAGE)
    const userId = ctx.userId
    // ...
  }
  ```

#### BUG-M02：`userId` 兜底为空字符串存在隐患
- **位置**：`src/app/(dashboard)/management/grade/classes/page.tsx:9`
- **问题**：`const userId = session?.user?.id ?? ""` 在未登录时返回空字符串，下游 `getGradeManagedClasses("")` 会查询无意义数据
- **改进建议**：未登录应直接 `redirect("/login")`，不应继续执行

---

### 2.4 [management/grade/insights/page.tsx](../src/app/(dashboard)/management/grade/insights/page.tsx) — 严重度：高

#### BUG-MI01：缺少权限校验
- **位置**：`src/app/(dashboard)/management/grade/insights/page.tsx:25-34`
- **问题**：页面直接调用 `getTeacherIdForMutations()` 和 `getGradesForStaff()`，未调用 `requirePermission()`
- **规范依据**：项目规则「Server Action 必须使用 `requirePermission()` 进行权限校验」
- **改进建议**：增加 `requirePermission(Permissions.HOMEWORK_READ)` 或对应年级负责人权限校验

#### BUG-MI02：使用原生 `<select>` 而非 shadcn Select 组件
- **位置**：`src/app/(dashboard)/management/grade/insights/page.tsx:70-81`
- **问题**：使用原生 `<select>` 元素，与项目其他页面使用的 shadcn `Select` 组件风格不一致
- **规范依据**：Web Interface Guidelines — Consistency；项目组件规范
- **影响**：视觉风格不统一，无障碍特性差异，主题切换时原生 select 样式无法跟随
- **改进建议**：替换为 shadcn `Select` 组件

#### BUG-MI03：`<label>` 缺少 `htmlFor` 关联
- **位置**：`src/app/(dashboard)/management/grade/insights/page.tsx:69`
- **问题**：`<label className="text-sm font-medium">Grade</label>` 未关联到 `select` 元素，点击 label 无法聚焦
- **规范依据**：Web Interface Guidelines — Forms「Labels properly associated」
- **改进建议**：`<label htmlFor="gradeId" className="...">Grade</label>`

#### BUG-MI04：表单提交触发整页刷新
- **位置**：`src/app/(dashboard)/management/grade/insights/page.tsx:68`
- **问题**：`<form action="/management/grade/insights" method="get">` 使用原生 GET 提交，导致整页刷新
- **违反规则**：`rerender-use-deferred-value`、Next.js 客户端导航最佳实践
- **改进建议**：改为客户端组件 + `useRouter().push()` 或使用 `useSearchParams` 实现无刷新筛选

#### BUG-MI05：`fmt` 工具函数命名过于简短
- **位置**：`src/app/(dashboard)/management/grade/insights/page.tsx:23`
- **问题**：`const fmt = (v: number | null, digits = 1) => ...` 命名过于简短，不符合可读性要求
- **改进建议**：重命名为 `formatScore` 或 `formatNumber`

---

### 2.5 [messages/page.tsx](../src/app/(dashboard)/messages/page.tsx) — 严重度：低

#### BUG-MSG01：缺少 `metadata` 导出
- **位置**：`src/app/(dashboard)/messages/page.tsx`
- **问题**：未导出 `metadata`
- **改进建议**：`export const metadata = { title: "Messages" }`

---

### 2.6 [messages/[id]/page.tsx](../src/app/(dashboard)/messages/[id]/page.tsx) — 严重度：中

#### BUG-MSG02：渲染期间执行写操作（标记已读）
- **位置**：`src/app/(dashboard)/messages/[id]/page.tsx:20-23`
- **问题**：在 RSC 渲染期间调用 `markMessageAsRead(id, ctx.userId)` 执行写操作
- **违反规则**：React Server Components 规范 — 渲染函数应为纯函数，不应有副作用
- **影响**：
  1. React 18+ 严格模式下渲染函数可能被调用两次，导致重复写入
  2. 流式渲染时若渲染被中断，写操作可能已执行但 UI 未更新
  3. 错误边界捕获错误后重试渲染会再次执行写操作
- **改进建议**：使用 `after()` API 延迟执行非阻塞写操作
  ```typescript
  import { after } from "next/server"

  if (!message.isRead && message.receiverId === ctx.userId) {
    after(() => markMessageAsRead(id, ctx.userId))
  }
  ```
- **规范依据**：`vercel-react-best-practices` — `server-after-nonblocking`

---

### 2.7 [messages/compose/page.tsx](../src/app/(dashboard)/messages/compose/page.tsx) — 严重度：低

#### BUG-MSG03：缺少 `metadata` 导出
- **改进建议**：`export const metadata = { title: "Compose Message" }`

---

### 2.8 [profile/page.tsx](../src/app/(dashboard)/profile/page.tsx) — 严重度：高

#### BUG-P01：使用权限反推角色（硬编码反模式）
- **位置**：`src/app/(dashboard)/profile/page.tsx:47-48`
- **问题**：`isStudent = permissions.includes(HOMEWORK_SUBMIT) && !permissions.includes(EXAM_CREATE)`，`isTeacher = permissions.includes(EXAM_CREATE)`
- **规范依据**：项目规则禁止硬编码角色判断；架构文档 004 已标记
- **改进建议**：使用 `session.user.roles` 判断
  ```typescript
  const roles = session.user.roles ?? []
  const isStudent = roles.includes("student")
  const isTeacher = roles.includes("teacher")
  ```

#### BUG-P02：在 RSC 中使用 IIFE 异步块（可读性差）
- **位置**：`src/app/(dashboard)/profile/page.tsx:50-118`
- **问题**：使用 `await (async () => { ... })()` 立即执行异步函数，将学生数据加载逻辑内联在组件中
- **影响**：
  1. 函数体过长（60+ 行），难以测试
  2. 无法被 React `cache()` 缓存
  3. 违反单一职责原则
- **改进建议**：抽取为 `data-access.ts` 中的 `getStudentProfileData(userId)` 函数
  ```typescript
  // modules/users/data-access.ts
  export const getStudentProfileData = cache(async (userId: string) => {
    const [classes, schedule, assignmentsAll, grades] = await Promise.all([...])
    // ... 计算逻辑
    return { enrolledClassCount, dueSoonCount, ... }
  })
  ```

#### BUG-P03：本地 `formatDate` 函数与全局工具重复
- **位置**：`src/app/(dashboard)/profile/page.tsx:26-33`
- **问题**：定义了本地 `formatDate` 函数，与 `@/shared/lib/utils.formatDate` 重复
- **影响**：日期格式不一致（本地使用 `en-US`，全局使用 `zh-CN`），维护成本增加
- **改进建议**：删除本地函数，使用全局 `formatDate`，或为全局函数增加 `locale` 参数

#### BUG-P04：`toWeekday` 类型断言不必要
- **位置**：`src/app/(dashboard)/profile/page.tsx:21-24`
- **问题**：`(day === 0 ? 7 : day) as 1 | 2 | 3 | 4 | 5 | 6 | 7` 使用 `as` 断言
- **规范依据**：编码规范 4.2.3「禁止 `as` 断言（除非从 `unknown` 转换）」
- **改进建议**：使用类型守卫
  ```typescript
  const toWeekday = (d: Date): 1 | 2 | 3 | 4 | 5 | 6 | 7 => {
    const day = d.getDay()
    const result = day === 0 ? 7 : day
    if (result < 1 || result > 7) throw new Error("Invalid weekday")
    return result
  }
  ```

#### BUG-P05：缩进不一致
- **位置**：`src/app/(dashboard)/profile/page.tsx:157,167,185,205-207`
- **问题**：多处缩进不一致（如 157 行 `               <div` 比 156 行多一个空格）
- **规范依据**：`.prettierrc` 配置 `tabWidth: 2`
- **改进建议**：运行 `npx prettier --write` 统一格式

#### BUG-P06：缺少 `metadata` 导出
- **改进建议**：`export const metadata = { title: "Profile" }`

---

### 2.9 [settings/page.tsx](../src/app/(dashboard)/settings/page.tsx) — 严重度：中

#### BUG-S01：使用权限反推角色
- **位置**：`src/app/(dashboard)/settings/page.tsx:25-30`
- **问题**：同 BUG-P01，使用 `permissions.includes(HOMEWORK_SUBMIT) && !permissions.includes(EXAM_CREATE)` 判断学生
- **改进建议**：使用 `session.user.roles` 判断

#### BUG-S02：缺少 `metadata` 导出
- **改进建议**：`export const metadata = { title: "Settings" }`

---

### 2.10 [settings/security/page.tsx](../src/app/(dashboard)/settings/security/page.tsx) — 严重度：低

#### BUG-SS01：缺少权限校验
- **位置**：`src/app/(dashboard)/settings/security/page.tsx:14-16`
- **问题**：仅检查 `session?.user`，未调用 `requirePermission()`
- **改进建议**：至少调用 `requireAuth()` 确保登录状态

---

### 2.11 [layout.tsx](../src/app/(dashboard)/layout.tsx) — 严重度：中

#### BUG-L01：跳过链接样式使用任意值
- **位置**：`src/app/(dashboard)/layout.tsx:12`
- **问题**：`focus:absolute focus:z-50 focus:p-4 focus:bg-background focus:text-foreground focus:border focus:border-border focus:rounded-md focus:m-2` 类名过长且重复
- **规范依据**：项目规则「禁止使用任意值（`w-[137px]`）」
- **改进建议**：抽取为 `skip-link` 类名或独立组件

#### BUG-L02：`<main>` 元素缺少 `role="main"`（虽隐式但建议显式）
- **位置**：`src/app/(dashboard)/layout.tsx:16`
- **问题**：`<main id="main-content">` 已有 `id`，但部分屏幕阅读器需要显式 `role="main"`
- **改进建议**：添加 `role="main"`（虽然 HTML5 规范中 `<main>` 隐式 `role="main"`，但为兼容性建议显式）

---

### 2.12 [error.tsx](../src/app/(dashboard)/error.tsx) — 严重度：低

#### BUG-E01：未使用 `error.digest` 信息
- **位置**：`src/app/(dashboard)/error.tsx:7`
- **问题**：`error` 参数包含 `digest` 字段（用于错误追踪），但未展示给用户或上报
- **改进建议**：在描述中包含 `digest` 或提供「复制错误码」按钮

---

### 2.13 [not-found.tsx](../src/app/(dashboard)/not-found.tsx) — 严重度：低

#### BUG-NF01：使用原生 `<a>` 样式而非 Button 组件
- **位置**：`src/app/(dashboard)/not-found.tsx:15-20`
- **问题**：`<Link className="bg-primary text-primary-foreground hover:bg-primary/90 inline-flex h-9 ...">` 手动拼接 Button 样式
- **规范依据**：项目组件规范「使用 `cn()` 工具函数管理条件类名」
- **改进建议**：使用 `<Button asChild><Link href="/dashboard">...</Link></Button>`

---

### 2.14 [announcement-list.tsx](../src/modules/announcements/components/announcement-list.tsx) — 严重度：中

#### BUG-AL01：使用 `<a href>` 而非 `<Link>`（全页刷新）
- **位置**：`src/modules/announcements/components/announcement-list.tsx:76`
- **问题**：`<a href={createHref}>` 使用原生 `<a>` 标签，导致全页刷新
- **违反规则**：`vercel-react-best-practices` — Next.js 客户端导航最佳实践
- **改进建议**：使用 `next/link` 的 `<Link>` 组件
  ```typescript
  import Link from "next/link"
  <Button asChild>
    <Link href={createHref ?? "#"}>
      <Plus className="mr-2 h-4 w-4" />
      New Announcement
    </Link>
  </Button>
  ```

#### BUG-AL02：`handleFilterChange` 未使用 `useCallback`
- **位置**：`src/modules/announcements/components/announcement-list.tsx:51-57`
- **问题**：`handleFilterChange` 每次渲染创建新引用，传递给 `Select` 的 `onValueChange` 导致不必要重渲染
- **违反规则**：`rerender-functional-setstate`、`rerender-memo`
- **改进建议**：使用 `useCallback` 包裹

---

### 2.15 [announcement-card.tsx](../src/modules/announcements/components/announcement-card.tsx) — 严重度：低

#### BUG-AC01：`useMemo` 包裹整个 JSX（过度优化）
- **位置**：`src/modules/announcements/components/announcement-card.tsx:38-68`
- **问题**：使用 `useMemo` 包裹整个卡片 JSX，依赖项为 `[announcement]`（对象）
- **违反规则**：`rerender-simple-expression-in-memo` — 简单表达式不需要 memo
- **影响**：`announcement` 是对象，每次父组件传入新引用时 memo 失效，无实际优化效果
- **改进建议**：移除 `useMemo`，直接渲染 JSX；如需优化应使用 `React.memo` 包裹组件
  ```typescript
  export const AnnouncementCard = React.memo(function AnnouncementCard({...}) {
    return <Card>...</Card>
  })
  ```

---

### 2.16 [announcement-detail.tsx](../src/modules/announcements/components/announcement-detail.tsx) — 严重度：中

#### BUG-AD01：使用 `<a href>` 而非 `<Link>`
- **位置**：`src/modules/announcements/components/announcement-detail.tsx:123,146`
- **问题**：`backHref` 和 `editHref` 使用原生 `<a>` 标签
- **改进建议**：替换为 `next/link`

#### BUG-AD02：三个处理函数未 `useCallback`
- **位置**：`src/modules/announcements/components/announcement-detail.tsx:64-115`
- **问题**：`handlePublish`、`handleArchive`、`handleDelete` 每次渲染创建新引用
- **违反规则**：`rerender-functional-setstate`
- **改进建议**：使用 `useCallback` 包裹

---

### 2.17 [message-list.tsx](../src/modules/messaging/components/message-list.tsx) — 严重度：中

#### BUG-ML01：使用字符串拼接动态类名
- **位置**：`src/modules/messaging/components/message-list.tsx:82,91`
- **问题**：`` className={`transition-colors hover:bg-accent/50 ${unread ? "border-primary/40" : ""}`} `` 使用模板字符串拼接类名
- **规范依据**：项目规则「使用 `cn()` 工具函数管理条件类名」
- **改进建议**：
  ```typescript
  className={cn(
    "transition-colors hover:bg-accent/50",
    unread && "border-primary/40"
  )}
  ```

#### BUG-ML02：`usePermission` 在客户端组件中导致 hydration 风险
- **位置**：`src/modules/messaging/components/message-list.tsx:30-31`
- **问题**：`usePermission()` 依赖 `useSession()`，服务端渲染时返回空权限，客户端首次渲染后才有权限，导致「Compose」按钮在 hydration 后闪烁
- **违反规则**：Web Interface Guidelines — Hydration Safety
- **改进建议**：将 `canSend` 作为 prop 从 RSC 父组件传入

---

### 2.18 [message-detail.tsx](../src/modules/messaging/components/message-detail.tsx) — 严重度：中

#### BUG-MD01：使用 `<a href>` 而非 `<Link>`
- **位置**：`src/modules/messaging/components/message-detail.tsx:79`
- **问题**：`<a href={backHref}>` 使用原生 `<a>`
- **改进建议**：替换为 `next/link`

#### BUG-MD02：`replyHref` 为 `undefined` 时仍渲染 Link
- **位置**：`src/modules/messaging/components/message-detail.tsx:68,87-92`
- **问题**：当 `canSend` 为 false 时 `replyHref` 为 `undefined`，但代码使用 `<Link href={replyHref ?? "#"}>` 仍渲染可点击链接，点击后跳转到 `#`
- **影响**：用户体验差，点击无效链接
- **改进建议**：`canSend` 为 false 时不渲染 Reply 按钮（当前已有 `{canSend ? ... : null}` 包裹，但内部仍用 `?? "#"` 兜底，应直接使用 `replyHref!` 或移除兜底）

#### BUG-MD03：URL 参数未编码
- **位置**：`src/modules/messaging/components/message-detail.tsx:69-71`
- **问题**：`subject=${encodeURIComponent(...)}` 已编码 subject，但 `parentId` 和 `receiverId` 未编码（虽然 UUID 不含特殊字符，但不严谨）
- **改进建议**：使用 `URLSearchParams` 构建查询字符串
  ```typescript
  const params = new URLSearchParams({
    parentId: message.id,
    receiverId: isReceived ? message.senderId : message.receiverId,
    subject: message.subject?.startsWith("Re:") ? message.subject : `Re: ${message.subject ?? ""}`,
  })
  const replyHref = canSend ? `/messages/compose?${params.toString()}` : undefined
  ```

---

### 2.19 [message-compose.tsx](../src/modules/messaging/components/message-compose.tsx) — 严重度：中

#### BUG-MC01：使用 `<a href>` 而非 `<Link>`
- **位置**：`src/modules/messaging/components/message-compose.tsx:73`
- **问题**：返回按钮使用原生 `<a>`
- **改进建议**：替换为 `next/link`

#### BUG-MC02：隐藏 input 与 `formData.set` 重复
- **位置**：`src/modules/messaging/components/message-compose.tsx:46,97`
- **问题**：`handleSubmit` 中 `formData.set("receiverId", receiverId)`，同时 JSX 中又有 `<input type="hidden" name="receiverId" value={receiverId} />`，两者重复
- **改进建议**：移除隐藏 input，仅使用 `formData.set`

#### BUG-MC03：`handleSubmit` 未 `useCallback`
- **位置**：`src/modules/messaging/components/message-compose.tsx:41-66`
- **改进建议**：使用 `useCallback` 包裹

---

### 2.20 [notification-list.tsx](../src/modules/messaging/components/notification-list.tsx) — 严重度：中

#### BUG-NL01：使用字符串拼接动态类名
- **位置**：`src/modules/messaging/components/notification-list.tsx:94,102`
- **问题**：`` className={`transition-colors ${!n.isRead ? "border-primary/40 bg-primary/5" : ""}`} ``
- **规范依据**：项目规则「使用 `cn()` 工具函数管理条件类名」
- **改进建议**：使用 `cn()`

#### BUG-NL02：`handleMarkRead` 未 `useCallback`
- **位置**：`src/modules/messaging/components/notification-list.tsx:54-63`
- **改进建议**：使用 `useCallback`

#### BUG-NL03：`<button>` 元素缺少 `type` 属性
- **位置**：`src/modules/messaging/components/notification-list.tsx:118-124`
- **问题**：`<button onClick={...}>` 未指定 `type="button"`，默认为 `submit`，若被表单包裹会触发提交
- **规范依据**：Web Interface Guidelines — Forms
- **改进建议**：添加 `type="button"`

---

### 2.21 [password-change-form.tsx](../src/modules/settings/components/password-change-form.tsx) — 严重度：高

#### BUG-PC01：使用字符串拼接动态类名（严重违规）
- **位置**：`src/modules/settings/components/password-change-form.tsx:133`
- **问题**：`` className={`h-2 [&>div]:${meta.color}`} `` 动态拼接 Tailwind 类名
- **规范依据**：项目规则「**禁止**字符串拼接动态类名（`bg-${color}-500`）」
- **影响**：Tailwind JIT 无法识别动态拼接的类名，`bg-red-500`、`bg-yellow-500`、`bg-green-500` 可能被 tree-shaking 移除，导致生产环境进度条无颜色
- **改进建议**：使用映射对象 + `cn()`
  ```typescript
  const STRENGTH_BAR_CLASS: Record<PasswordStrength, string> = {
    weak: "h-2 [&>div]:bg-red-500",
    medium: "h-2 [&>div]:bg-yellow-500",
    strong: "h-2 [&>div]:bg-green-500",
  }

  <Progress value={meta.value} className={STRENGTH_BAR_CLASS[strength]} />
  ```

#### BUG-PC02：使用 `document.getElementById` 操作 DOM（反 React 模式）
- **位置**：`src/modules/settings/components/password-change-form.tsx:62-63`
- **问题**：`const form = document.getElementById("password-change-form") as HTMLFormElement | null` 直接操作 DOM
- **规范依据**：React 最佳实践 — 避免直接 DOM 操作
- **改进建议**：使用 `useRef<HTMLFormElement>` 或受控组件重置表单
  ```typescript
  const formRef = useRef<HTMLFormElement>(null)
  // ...
  formRef.current?.reset()
  ```

#### BUG-PC03：`as` 断言使用
- **位置**：`src/modules/settings/components/password-change-form.tsx:62`
- **问题**：`as HTMLFormElement | null` 使用类型断言
- **规范依据**：编码规范 4.2.3「禁止 `as` 断言」
- **改进建议**：使用 `useRef` 后通过 ref.current 的类型推导

---

### 2.22 [profile-settings-form.tsx](../src/modules/settings/components/profile-settings-form.tsx) — 严重度：高

#### BUG-PS01：使用 `as any` 类型断言（严重违规）
- **位置**：`src/modules/settings/components/profile-settings-form.tsx:35`
- **问题**：`resolver: zodResolver(profileFormSchema) as any` 使用 `as any`
- **规范依据**：项目规则「**禁止 `any`**」「**禁止 `as` 断言**」
- **改进建议**：修复 `zodResolver` 类型不匹配问题
  ```typescript
  // 方案 1：使用 react-hook-form 的 Resolver 类型
  import type { Resolver } from "react-hook-form"
  const resolver: Resolver<ProfileFormValues> = zodResolver(profileFormSchema)
  
  // 方案 2：修正 schema 类型定义
  const profileFormSchema = z.object({...}) satisfies z.ZodType<ProfileFormValues>
  ```

#### BUG-PS02：`console.error` 残留
- **位置**：`src/modules/settings/components/profile-settings-form.tsx:60`
- **问题**：`console.error(error)` 在生产代码中残留
- **规范依据**：编码规范 — 生产代码不应包含 `console.*`
- **改进建议**：移除或替换为日志服务

#### BUG-PS03：`onSubmit` 未 `useCallback`
- **位置**：`src/modules/settings/components/profile-settings-form.tsx:47-63`
- **改进建议**：使用 `useCallback`

#### BUG-PS04：`age` 字段使用 `z.coerce.number()` 但未处理 NaN
- **位置**：`src/modules/settings/components/profile-settings-form.tsx:25`
- **问题**：`age: z.coerce.number().min(0).optional()` 当输入为空字符串时会转换为 `0`，而非 `undefined`
- **改进建议**：使用 `z.preprocess` 处理空值
  ```typescript
  age: z.preprocess(
    (v) => (v === "" || v === null || v === undefined ? undefined : Number(v)),
    z.number().min(0).optional()
  )
  ```

---

### 2.23 [notification-preferences-form.tsx](../src/modules/settings/components/notification-preferences-form.tsx) — 严重度：中

#### BUG-NPF01：Switch 与隐藏 checkbox 状态同步问题
- **位置**：`src/modules/settings/components/notification-preferences-form.tsx:186-201,233-248`
- **问题**：同时使用隐藏 `<input type="checkbox">` 和 `<Switch>`，两者都调用 `toggleChannel`/`toggleCategory`，可能导致双重切换
- **影响**：用户点击 Switch 时，`onCheckedChange` 触发；同时隐藏 checkbox 的 `onChange` 也触发，导致状态切换两次回到原点
- **改进建议**：移除隐藏 checkbox，仅使用 Switch + 隐藏 input（`type="hidden"`）提交表单
  ```typescript
  <input type="hidden" name={item.key} value={checked ? "true" : "false"} />
  <Switch
    checked={checked}
    onCheckedChange={() => toggleChannel(item.key)}
    aria-label={item.label}
  />
  ```

#### BUG-NPF02：本地状态与服务器状态可能不同步
- **位置**：`src/modules/settings/components/notification-preferences-form.tsx:122-133`
- **问题**：`useState` 初始化自 `preferences` prop，但 prop 变化时状态不更新
- **违反规则**：`rerender-derived-state-no-effect` — 不应使用 effect 同步派生状态
- **改进建议**：使用 `key` prop 重置组件，或使用受控组件

#### BUG-NPF03：中文注释混合英文代码
- **位置**：`src/modules/settings/components/notification-preferences-form.tsx:121,161,209`
- **问题**：`// 本地状态用于即时反馈 Switch 切换`、`{/* 通知渠道 */}`、`{/* 通知类别 */}` 中文注释
- **规范依据**：项目代码一致性（其他文件使用英文注释）
- **改进建议**：统一为英文注释

---

### 2.24 [theme-preferences-card.tsx](../src/modules/settings/components/theme-preferences-card.tsx) — 严重度：低

#### BUG-TP01：`"use client"` 后缺少空行
- **位置**：`src/modules/settings/components/theme-preferences-card.tsx:1-2`
- **问题**：`"use client"` 紧跟 `import` 无空行
- **规范依据**：`.prettierrc` 格式规范
- **改进建议**：运行 `npx prettier --write`

#### BUG-TP02：`setTheme` 参数类型不安全
- **位置**：`src/modules/settings/components/theme-preferences-card.tsx:31`
- **问题**：`onValueChange={(v) => setTheme(v)}` 中 `v` 为 `string`，但 `setTheme` 期望特定类型
- **改进建议**：`onValueChange={(v) => setTheme(v as ThemeChoice)}`（虽然违反 as 规范，但 next-themes 类型定义如此；或使用类型守卫）

---

### 2.25 [ai-provider-settings-card.tsx](../src/modules/settings/components/ai-provider-settings-card.tsx) — 严重度：高

#### BUG-AI01：中英文混合 UI（严重一致性违规）
- **位置**：`src/modules/settings/components/ai-provider-settings-card.tsx:298,325,352,367`
- **问题**：FormLabel 使用中文「品牌方」「设为默认」，FormDescription 使用中文「填写基础地址，不要包含 /chat/completions。」「不会回显历史 Key，留空表示不更新。」
- **规范依据**：Web Interface Guidelines — Consistency；项目其他 UI 均为英文
- **影响**：用户在英文界面中突然看到中文，体验割裂
- **改进建议**：统一为英文
  ```typescript
  <FormLabel>Provider</FormLabel>
  <FormDescription>Enter base URL without /chat/completions suffix.</FormDescription>
  <FormLabel>Set as default</FormLabel>
  <FormDescription>Existing key won't be displayed. Leave blank to keep current.</FormDescription>
  ```

#### BUG-AI02：`useEffect` 依赖项过多导致重复执行
- **位置**：`src/modules/settings/components/ai-provider-settings-card.tsx:108-136`
- **问题**：`useEffect` 依赖 `[form, selectedId, onProvidersChanged, initialMode, resetToNew]`，但使用 `loadedRef` 防止重复执行
- **违反规则**：`rerender-dependencies` — 应使用原始依赖
- **改进建议**：将初始化逻辑移至 `useEffect` 内部，依赖项仅为 `[]`（仅执行一次）
  ```typescript
  useEffect(() => {
    let cancelled = false
    startTransition(async () => {
      const rows = await getAiProviderSummaries()
      if (cancelled) return
      // ...
    })
    return () => { cancelled = true }
  }, []) // 仅挂载时执行
  ```

#### BUG-AI03：`handleSelectChange` 未 `useCallback`
- **位置**：`src/modules/settings/components/ai-provider-settings-card.tsx:138-156`
- **改进建议**：使用 `useCallback`

#### BUG-AI04：文件行数 405 行，接近上限
- **位置**：`src/modules/settings/components/ai-provider-settings-card.tsx`
- **问题**：文件 405 行，项目规则建议 React 组件 ≤ 500 行，但复杂度较高
- **改进建议**：考虑拆分为 `AiProviderSelect`、`AiProviderForm`、`AiProviderTestButton` 子组件

---

### 2.26 [admin-settings-view.tsx](../src/modules/settings/components/admin-settings-view.tsx) — 严重度：低

#### BUG-AS01：Tab 图标语义错误
- **位置**：`src/modules/settings/components/admin-settings-view.tsx:50-53`
- **问题**：`appearance` Tab 使用 `<Shield />` 图标（盾牌通常表示安全），应使用 `<Palette />` 或 `<Monitor />`
- **规范依据**：Web Interface Guidelines — Iconography
- **改进建议**：`<TabsTrigger value="appearance"><Palette /></TabsTrigger>`

#### BUG-AS02：`signOut` 直接调用未确认
- **位置**：`src/modules/settings/components/admin-settings-view.tsx:120`
- **问题**：`onClick={() => signOut({ callbackUrl: "/login" })}` 直接登出，无确认对话框
- **规范依据**：Web Interface Guidelines — Destructive Actions
- **改进建议**：增加确认对话框（虽然登出非破坏性，但意外登出影响体验）

---

### 2.27 [teacher-settings-view.tsx](../src/modules/settings/components/teacher-settings-view.tsx) — 严重度：低

#### BUG-TS01：与 admin-settings-view.tsx 大量重复代码
- **位置**：`src/modules/settings/components/teacher-settings-view.tsx`
- **问题**：与 `admin-settings-view.tsx`、`student-settings-view.tsx` 90% 代码重复，仅「Back to dashboard」链接和「Quick links」不同
- **规范依据**：DRY 原则
- **改进建议**：抽取为 `SettingsLayout` 共享组件，通过 props 传入 `backHref` 和 `quickLinks`
  ```typescript
  export function SettingsLayout({ title, description, backHref, quickLinks, children }: {...}) {
    return <div>...</div>
  }
  ```

---

### 2.28 [student-settings-view.tsx](../src/modules/settings/components/student-settings-view.tsx) — 严重度：低

#### BUG-ST01：同 BUG-TS01，代码重复
- **改进建议**：同 BUG-TS01

---

### 2.29 [grade-classes-view.tsx](../src/modules/classes/components/grade-classes-view.tsx) — 严重度：高

#### BUG-GC01：文件 455 行，超过 500 行建议上限的 91%
- **位置**：`src/modules/classes/components/grade-classes-view.tsx`
- **问题**：单文件 455 行，包含列表、创建对话框、编辑对话框、删除确认对话框
- **规范依据**：项目规则「React 组件：建议 ≤ 500 行」
- **改进建议**：拆分为：
  - `grade-classes-view.tsx`（主视图，< 100 行）
  - `grade-class-create-dialog.tsx`
  - `grade-class-edit-dialog.tsx`
  - `grade-class-delete-dialog.tsx`

#### BUG-GC02：`useEffect` 依赖项导致不必要重渲染
- **位置**：`src/modules/classes/components/grade-classes-view.tsx:62-78`
- **问题**：两个 `useEffect` 依赖 `managedGrades` 数组引用，父组件每次传入新数组都会触发
- **违反规则**：`rerender-dependencies`
- **改进建议**：依赖 `managedGrades[0]?.id` 而非整个数组

#### BUG-GC03：中英文混合 UI
- **位置**：`src/modules/classes/components/grade-classes-view.tsx:183-184,283,370,389`
- **问题**：表头「班主任」「任课老师」使用中文，其他列使用英文
- **规范依据**：Web Interface Guidelines — Consistency
- **改进建议**：统一为英文 `Homeroom Teacher`、`Subject Teachers`

#### BUG-GC04：`formatSubjectTeachers` 在每次渲染时重新创建
- **位置**：`src/modules/classes/components/grade-classes-view.tsx:140-146`
- **问题**：函数在组件内定义，每次渲染创建新引用
- **改进建议**：移至模块级别（不依赖组件状态）

---

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

### 3.1 重渲染优化

#### PERF-01：`usePermission` 返回的回调未 memoize
- **位置**：`src/shared/hooks/use-permission.ts:11-25`
- **问题**：`hasPermission`、`hasAnyPermission`、`hasAllPermissions`、`hasRole` 每次渲染创建新函数引用
- **违反规则**：`rerender-functional-setstate`、`rerender-memo`
- **影响**：`message-list.tsx`、`message-detail.tsx` 中使用 `usePermission()` 的组件每次渲染都创建新 `canSend`/`canDelete` 值
- **改进建议**：使用 `useCallback` 包裹所有回调（详见 `student_bug.md` PERF-01）

#### PERF-02：`AnnouncementCard` 的 `useMemo` 无效
- **位置**：`src/modules/announcements/components/announcement-card.tsx:38-68`
- **问题**：`useMemo` 依赖 `[announcement]`（对象），父组件每次渲染传入新引用，memo 失效
- **违反规则**：`rerender-simple-expression-in-memo`
- **改进建议**：移除 `useMemo`，使用 `React.memo` 包裹组件

#### PERF-03：`profile/page.tsx` 串行 await 未并行化
- **位置**：`src/app/(dashboard)/profile/page.tsx:53-58`
- **问题**：学生数据加载使用 `Promise.all` ✅，但 `userProfile` 和 `studentData` 是串行执行
- **违反规则**：`async-parallel`
- **改进建议**：`userProfile` 和角色判断后，并行加载学生/教师数据（当前已是此模式，但 `userProfile` 必须先获取才能判断角色，无法并行）

#### PERF-04：`messages/page.tsx` 已正确使用 `Promise.all`
- **位置**：`src/app/(dashboard)/messages/page.tsx:12-15`
- **现状**：✅ 已使用 `Promise.all` 并行加载 messages 和 notifications

#### PERF-05：`management/grade/classes/page.tsx` 已正确使用 `Promise.all`
- **位置**：`src/app/(dashboard)/management/grade/classes/page.tsx:11-15`
- **现状**：✅ 已并行加载 classes、teachers、managedGrades

#### PERF-06：`ai-provider-settings-card.tsx` 使用 `loadedRef` 防止重复加载
- **位置**：`src/modules/settings/components/ai-provider-settings-card.tsx:66,109-110`
- **问题**：使用 `loadedRef` 而非空依赖 `useEffect`
- **违反规则**：`rerender-dependencies`
- **改进建议**：使用空依赖数组 `[]` + 清理函数

### 3.2 Bundle Size 优化

#### PERF-07：`lucide-react` 导入方式
- **位置**：多处，如 `src/app/(dashboard)/profile/page.tsx:17`
- **问题**：`import { User, Mail, Phone, MapPin, Calendar, Clock, Shield } from "lucide-react"` 从 barrel 文件导入
- **违反规则**：`bundle-barrel-imports`
- **现状**：Next.js 13+ 自动 tree-shaking `lucide-react`，影响较小
- **改进建议**：保持现状，但确保 `next.config.js` 启用了 `optimizePackageImports`

### 3.3 服务端性能

#### PERF-08：`profile/page.tsx` 数据加载未使用 `cache()`
- **位置**：`src/app/(dashboard)/profile/page.tsx:50-118`
- **问题**：学生数据加载逻辑内联在组件中，无法被 React `cache()` 去重
- **违反规则**：`server-cache-react`
- **改进建议**：抽取为 `data-access.ts` 中的 `cache()` 包裹函数

#### PERF-09：`messages/[id]/page.tsx` 渲染期间写操作
- **位置**：`src/app/(dashboard)/messages/[id]/page.tsx:20-23`
- **问题**：渲染期间调用 `markMessageAsRead` 执行写操作
- **违反规则**：`server-after-nonblocking`
- **改进建议**：使用 `after()` API

---

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

### 4.1 Hydration Safety

#### UI-01：`usePermission` 导致 hydration 闪烁
- **位置**：`src/modules/messaging/components/message-list.tsx:30-31`、`src/modules/messaging/components/message-detail.tsx:41-43`
- **问题**：`usePermission()` 依赖 `useSession()`，服务端渲染时无权限，客户端 hydration 后权限相关 UI（Compose、Reply、Delete 按钮）闪烁出现
- **违反规则**：Web Interface Guidelines — Hydration Safety
- **改进建议**：将权限判断结果作为 prop 从 RSC 父组件传入
  ```typescript
  // RSC 父组件
  const canSend = ctx.permissions.includes(Permissions.MESSAGE_SEND)
  <MessageList messages={...} canSend={canSend} />
  ```

#### UI-02：`theme-preferences-card.tsx` 已使用 `suppressHydrationWarning`
- **位置**：`src/modules/settings/components/theme-preferences-card.tsx:32`
- **现状**：✅ 已正确处理主题切换的 hydration 问题

### 4.2 Navigation & State

#### UI-03：使用 `<a href>` 导致全页刷新
- **位置**：多处（BUG-AL01、BUG-AD01、BUG-MD01、BUG-MC01）
- **问题**：使用原生 `<a>` 而非 `<Link>`，破坏 SPA 导航
- **违反规则**：Web Interface Guidelines — Navigation
- **改进建议**：全部替换为 `next/link`

#### UI-04：`announcement-list.tsx` 筛选状态未反映在 URL
- **位置**：`src/modules/announcements/components/announcement-list.tsx:51-57`
- **问题**：`handleFilterChange` 使用 `router.replace(qs ? ?${qs} : ?)` 更新 URL ✅，但初始 `filter` 状态来自 `initialStatus` prop 而非 URL
- **改进建议**：使用 `useSearchParams` 读取 URL 状态

#### UI-05：`message-detail.tsx` 回复链接 URL 参数构建不严谨
- **位置**：`src/modules/messaging/components/message-detail.tsx:69-71`
- **问题**：手动拼接 URL 参数，未使用 `URLSearchParams`
- **改进建议**：见 BUG-MD03

### 4.3 Forms

#### UI-06：`management/grade/insights/page.tsx` label 未关联 select
- **位置**：`src/app/(dashboard)/management/grade/insights/page.tsx:69`
- **问题**：`<label>` 缺少 `htmlFor`
- **违反规则**：Web Interface Guidelines — Forms
- **改进建议**：见 BUG-MI03

#### UI-07：`notification-list.tsx` button 缺少 `type` 属性
- **位置**：`src/modules/messaging/components/notification-list.tsx:118`
- **问题**：`<button>` 未指定 `type="button"`
- **违反规则**：Web Interface Guidelines — Forms
- **改进建议**：见 BUG-NL03

#### UI-08：`message-compose.tsx` 表单提交使用 `formData.set` 而非受控组件
- **位置**：`src/modules/messaging/components/message-compose.tsx:46-49`
- **问题**：混合使用受控（`receiverId` state）和非受控（FormData）模式
- **改进建议**：统一使用受控组件或完全使用 FormData

### 4.4 Content & Copy

#### UI-09：中英文混合 UI
- **位置**：
  - `ai-provider-settings-card.tsx`：BUG-AI01
  - `grade-classes-view.tsx`：BUG-GC03
  - `notification-preferences-form.tsx`：BUG-NPF03（注释）
- **违反规则**：Web Interface Guidelines — Consistency
- **改进建议**：统一为英文

#### UI-10：错误消息缺少修复步骤
- **位置**：`src/app/(dashboard)/error.tsx:13`
- **问题**：`"We apologize for the inconvenience. An unexpected error occurred."` 未提供下一步操作
- **违反规则**：Web Interface Guidelines — Content & Copy
- **改进建议**：增加「联系管理员」链接或错误码展示

#### UI-11：`admin-settings-view.tsx` Tab 图标语义错误
- **位置**：`src/modules/settings/components/admin-settings-view.tsx:50-53`
- **问题**：Appearance Tab 使用 Shield 图标
- **违反规则**：Web Interface Guidelines — Iconography
- **改进建议**：见 BUG-AS01

### 4.5 Accessibility

#### UI-12：`notification-list.tsx` icon 按钮缺少 `aria-label`
- **位置**：`src/modules/messaging/components/notification-list.tsx:118-124`
- **问题**：「Mark as read」按钮文本存在，但图标按钮模式未统一
- **改进建议**：确保所有图标按钮有 `aria-label`

#### UI-13：`layout.tsx` 跳过链接样式冗长
- **位置**：`src/app/(dashboard)/layout.tsx:12`
- **问题**：跳过链接使用大量 `focus:` 前缀类名，难以维护
- **改进建议**：抽取为独立样式或组件

### 4.6 Performance

#### UI-14：`management/grade/insights/page.tsx` 表单提交整页刷新
- **位置**：`src/app/(dashboard)/management/grade/insights/page.tsx:68`
- **问题**：原生 form GET 提交导致整页刷新
- **违反规则**：Web Interface Guidelines — Performance
- **改进建议**：见 BUG-MI04

#### UI-15：`profile/page.tsx` 内联数据处理逻辑
- **位置**：`src/app/(dashboard)/profile/page.tsx:60-108`
- **问题**：在组件内执行数组排序、过滤等耗时操作
- **改进建议**：移至 data-access 层

---

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

### 5.1 [004_architecture_impact_map.md](../docs/architecture/004_architecture_impact_map.md)

#### DOC-01：announcements 模块未记录页面缺少权限校验
- **位置**：004 文档 2.16 节
- **问题**：已记录 `getAnnouncementsAction` 使用 `requireAuth()` 而非 `requirePermission()`，但未记录 `app/(dashboard)/announcements/page.tsx` 完全缺少权限校验
- **改进建议**：补充已知问题「⚠️ P2：`app/(dashboard)/announcements/page.tsx` 完全缺少权限校验」

#### DOC-02：management 模块未在架构文档中独立记录
- **位置**：004 文档
- **问题**：`app/(dashboard)/management/grade/` 路由未在架构文档中记录其依赖关系
- **改进建议**：补充 management 路由的模块依赖（classes、school）

#### DOC-03：settings 模块文件清单过期
- **位置**：004 文档 2.23 节
- **问题**：记录 `components/* | 8 文件`，但实际有 8 个文件 ✅，需核对行数
- **改进建议**：核对并更新各文件行数

### 5.2 [005_architecture_data.json](../docs/architecture/005_architecture_data.json)

#### DOC-04：缺少 management 路由记录
- **改进建议**：在 `routes` 数组中补充 management 路由

---

## 六、问题汇总统计

| 严重度 | 数量 | 问题编号 |
|--------|------|----------|
| 高 | 9 | BUG-A01, BUG-M01, BUG-MI01, BUG-P01, BUG-P02, BUG-PC01, BUG-PS01, BUG-AI01, BUG-GC01 |
| 中 | 14 | BUG-D01, BUG-MI02, BUG-MI03, BUG-MI04, BUG-MSG02, BUG-S01, BUG-L01, BUG-AL01, BUG-AD01, BUG-ML01, BUG-ML02, BUG-MD01, BUG-MD02, BUG-MC01, BUG-NL01, BUG-NPF01, BUG-AI02 |
| 低 | 13 | BUG-A02, BUG-D02, BUG-MI05, BUG-MSG01, BUG-MSG03, BUG-P03, BUG-P04, BUG-P05, BUG-P06, BUG-S02, BUG-SS01, BUG-L02, BUG-E01, BUG-NF01, BUG-AC01, BUG-AD02, BUG-MC02, BUG-MC03, BUG-NL02, BUG-NL03, BUG-PC02, BUG-PC03, BUG-PS02, BUG-PS03, BUG-PS04, BUG-NPF02, BUG-NPF03, BUG-TP01, BUG-TP02, BUG-AI03, BUG-AI04, BUG-AS01, BUG-AS02, BUG-TS01, BUG-ST01, BUG-GC02, BUG-GC03, BUG-GC04 |
| 性能 | 9 | PERF-01, PERF-02, PERF-03, PERF-04, PERF-05, PERF-06, PERF-07, PERF-08, PERF-09 |
| 界面 | 15 | UI-01 ~ UI-15 |
| 文档 | 4 | DOC-01, DOC-02, DOC-03, DOC-04 |
| **合计** | **64** | |

---

## 七、修复优先级建议

### P0（立即修复 — 影响安全与正确性）
1. **BUG-A01**：`announcements/page.tsx` 增加权限校验
2. **BUG-M01**：`management/grade/classes/page.tsx` 增加权限校验
3. **BUG-MI01**：`management/grade/insights/page.tsx` 增加权限校验
4. **BUG-PC01**：`password-change-form.tsx` 修复动态类名拼接（生产环境进度条无颜色）
5. **BUG-PS01**：`profile-settings-form.tsx` 移除 `as any`
6. **BUG-AI01**：`ai-provider-settings-card.tsx` 统一 UI 语言为英文

### P1（本迭代修复 — 影响可维护性与性能）
7. **BUG-P01、BUG-S01、BUG-D01**：使用 `roles` 判断角色，移除权限反推
8. **BUG-P02**：`profile/page.tsx` 抽取数据加载逻辑到 data-access
9. **BUG-MSG02**：`messages/[id]/page.tsx` 使用 `after()` 延迟写操作
10. **BUG-AL01、BUG-AD01、BUG-MD01、BUG-MC01**：替换 `<a>` 为 `<Link>`
11. **BUG-ML01、BUG-NL01**：使用 `cn()` 替换字符串拼接
12. **PERF-01**：`usePermission` 回调 memoize
13. **UI-01**：权限相关 UI 改为 RSC prop 传入

### P2（下迭代修复 — 增强健壮性）
14. **BUG-GC01**：`grade-classes-view.tsx` 拆分组件
15. **BUG-NPF01**：`notification-preferences-form.tsx` 修复 Switch/checkbox 双重切换
16. **BUG-MI02、BUG-MI03、BUG-MI04**：`management/grade/insights` 改用 shadcn Select
17. **BUG-PC02**：`password-change-form.tsx` 使用 `useRef` 替代 `document.getElementById`
18. **BUG-TS01、BUG-ST01**：抽取 `SettingsLayout` 共享组件
19. **BUG-AS01**：修复 Tab 图标语义
20. **UI-10**：错误页增加修复步骤

### P3（文档同步）
21. **DOC-01 ~ DOC-04**：同步架构文档

---

## 八、验证命令

修复完成后应运行以下命令确保零错误：

```bash
npm run lint
npx tsc --noEmit
npm run test:unit
```

针对特定模块的端到端验证：

```bash
# 验证权限校验
curl -I http://localhost:3000/announcements  # 应返回 302 重定向到 /login
curl -I http://localhost:3000/management/grade/classes  # 应返回 302
curl -I http://localhost:3000/management/grade/insights  # 应返回 302

# 验证 hydration
# 在浏览器控制台检查无 hydration warning
```

---

> 报告生成人：AI Agent（GLM-5.2）
> 核查方法：人工逐行审查 + 架构图比对 + 技能规则匹配
> 应用技能：`vercel-react-best-practices`（65 条规则）、`web-design-guidelines`（Web Interface Guidelines）
> 注：`web-artifacts-builder` 技能加载失败，界面优化建议已合并至第四章