feat(admin): 补全 admin 模块核心功能与产品体验优化

修复 v4 报告中的 13 个产品体验问题：新增用户管理列表页和系统设置页，重组导航菜单并补充缺失入口，增加角色切换机制，Dashboard 增加快捷操作和 recharts 趋势图表，考勤增加统计概览，排课增加课表网格视图，统一 Toast 操作反馈，同步更新架构文档

docs/architecture/004_architecture_impact_map.md

@@ -60,7 +60,7 @@
 │                   change-logger · login-logger · password-policy ·  │
 │                   rate-limit · excel · file-storage · ...           │
 │  hooks/           use-permission · use-aria-live · ...              │
-│  components/      ui/ (shadcn) · a11y/ · onboarding-gate · ...      │
+│  components/      ui/ (shadcn) · a11y/ · global-search · ...        │
 │  types/           permissions · action-state                        │
 └─────────────────────────────────────────────────────────────────────┘
                                ▲
@@ -372,6 +372,38 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
    ✅ P0-4 已修复：dashboard 改为并行调用各模块 dashboard stats 函数，不再直查跨模块表
 ```
 
+### 1.4.4 调用链路：admin 路由组统一权限守卫
+
+```
+[Layout]  app/(dashboard)/admin/layout.tsx (Server Component)
+   │
+   ▼
+[AuthGuard] shared/lib/auth-guard.getAuthContext()
+   │
+   └─▶ getSession() → 校验已登录（未登录抛 PermissionDeniedError）
+   │
+   ▼
+[Children] 各 admin/* 页面（page.tsx）在函数体首行调用 requirePermission(XXX)
+   │
+   ├─▶ /admin/school/schools         → requirePermission(SCHOOL_MANAGE)
+   ├─▶ /admin/school/academic-year   → requirePermission(SCHOOL_MANAGE)
+   ├─▶ /admin/school/classes         → requirePermission(SCHOOL_MANAGE)
+   ├─▶ /admin/school/departments     → requirePermission(SCHOOL_MANAGE)
+   ├─▶ /admin/school/grades          → requirePermission(SCHOOL_MANAGE)
+   ├─▶ /admin/school/grades/insights → requirePermission(SCHOOL_MANAGE)
+   ├─▶ /admin/users/import           → requirePermission(USER_MANAGE)
+   ├─▶ /admin/users                  → requirePermission(USER_MANAGE)
+   ├─▶ /admin/scheduling/auto        → requirePermission(SCHEDULE_AUTO)
+   ├─▶ /admin/scheduling/changes     → requirePermission(SCHEDULE_ADJUST)
+   ├─▶ /admin/scheduling/rules       → requirePermission(SCHEDULE_ADJUST)
+   ├─▶ /admin/announcements          → requirePermission(ANNOUNCEMENT_MANAGE)
+   ├─▶ /admin/announcements/[id]     → requirePermission(ANNOUNCEMENT_MANAGE)
+   └─▶ /admin/audit-logs             → requirePermission(AUDIT_LOG_READ)
+
+   ✅ P0 安全修复：admin/layout.tsx 提供登录态统一守卫，
+      各页面 requirePermission() 提供细粒度权限校验
+```
+
 ---
 
 # 第二部分：模块清单
@@ -393,7 +425,7 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
 - `getInitials(name)` / `formatDateForFile(d?)` — 通用工具（P1-c / P1-a 重构新增：从 parent/lib/utils.ts、grades/export-button.tsx 等多处重复实现抽取）
 - `downloadBase64File(base64, filename, mimeType?)` / `downloadBlob(blob, filename)` — 客户端文件下载（P1-c 重构新增：从 grades/export-button、users/user-import-dialog、audit/audit-log-export-button 三处重复实现抽取，位于 `lib/download.ts`）
 
-**共享组件导出**（P0-b / P1-a / P1-b / P1-c / P2-a / P2-b / P3-a / P3-b / P3-c / P3-d 重构新增，按类别组织）：
+**共享组件导出**（P0-b / P1-a / P1-b / P1-c / P2-a / P2-b / P3-a / P3-b / P3-c / P3-d / 第二轮 P0-1/P0-2/P0-3/P1-1/P1-2/P1-3/P1-4 重构新增，按类别组织）：
 
 | 类别 | 组件 | 文件 | 用途 | 消费方数量 |
 |------|------|------|------|-----------|
@@ -402,13 +434,34 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
 | **UI 组件** | `ChipNav` | `components/ui/chip-nav.tsx` | 芯片导航组（通过 URL search params 切换筛选维度，Link 跳转） | 3 个（P1-b） |
 | **UI 组件** | `PageHeader` | `components/ui/page-header.tsx` | 页面头部（标题+描述+icon+actions，响应式布局） | 2 个（P2-b: profile/page.tsx, settings/security/page.tsx） |
 | **UI 组件** | `FilterBar` / `FilterSearchInput` / `FilterResetButton` | `components/ui/filter-bar.tsx` | 筛选栏容器+搜索框+重置按钮（统一布局壳，URL 状态由各模块处理） | 5 个（P3-b: exam/textbook/question/audit-log/login-log filters） |
+| **UI 组件** | `ConfirmDeleteDialog` | `components/ui/confirm-delete-dialog.tsx` | 通用删除确认对话框（AlertDialog 包装，支持自定义 confirmText/cancelText） | 5 个（P0-1: announcement-detail, message-detail, course-plan-detail, grade-classes-view, students-table） |
+| **UI 组件** | `Pagination` | `components/ui/pagination.tsx` | 通用分页 UI（Showing X-Y of Z + Page X of Y + 上一页/下一页按钮） | 3 个（P0-2: audit-log-table, login-log-table, data-change-log-table） |
+| **UI 组件** | `EmptyTableRow` | `components/ui/empty-table-row.tsx` | 表格空状态行（TableRow + TableCell 居中显示空状态文案） | 3 个（P0-3: audit-log-table, login-log-table, data-change-log-table） |
+| **UI 组件** | `StatusBadge` | `components/ui/status-badge.tsx` | 通用状态徽章（Badge + 状态→variant/label/className 映射表，修复 in_progress 颜色不一致 bug） | 9+ 个（P1-1: audit 3 文件, grades 2 文件, student/learning/assignments, parent/child-homework-summary, student-upcoming-assignments-card, question-columns） |
+| **表单字段** | `TextField` | `components/form-fields/text-field.tsx` | 通用文本字段（FormField + Input 包装，支持 text/number/password/datetime-local 类型 + value 转换器） | 3 个文件 16 处（P1-2: profile-settings-form 6, exam-basic-info-form 4, ai-provider-settings-card 4） |
+| **表单字段** | `SelectField` | `components/form-fields/select-field.tsx` | 通用选择字段（FormField + Select 包装，支持 toSelectValue/fromSelectValue 处理 number↔string） | 4 个文件 8 处（P1-2: exam-basic-info-form 3, ai-provider-settings-card 1, create-question-dialog 2, profile-settings-form 1） |
+| **表单字段** | `TextareaField` | `components/form-fields/textarea-field.tsx` | 通用多行文本字段（FormField + Textarea 包装） | 1 个（P1-2: create-question-dialog） |
 | **图表组件** | `ChartCardShell` | `components/charts/chart-card-shell.tsx` | 图表卡片外壳（Card+Header+EmptyState+Content 统一结构） | 8 个（P3-c） |
 | **图表组件** | `TrendLineChart` | `components/charts/trend-line-chart.tsx` | 趋势折线图（LineChart 统一配置，支持单/多系列） | 8 个（P3-c: grade-trend-chart 等） |
 | **图表组件** | `SimpleBarChart` | `components/charts/simple-bar-chart.tsx` | 柱状图（BarChart 统一配置，支持单/多 Bar + Cell 分桶着色） | 8 个（P3-c: grade-distribution-chart 等） |
 | **图表组件** | `ComparisonRadarChart` | `components/charts/comparison-radar-chart.tsx` | 对比雷达图（RadarChart 统一配置，支持双 Radar 对比） | 8 个（P3-c: subject-comparison-chart, mastery-radar-chart 等） |
 | **课表组件** | `ScheduleList` / `ScheduleListItem` | `components/schedule/schedule-list.tsx` | 课表列表+列表项（课程+时间+地点+班级徽章，separator/card 两种变体） | 3 个（P3-a: student-today-schedule-card, child-schedule-card, student-schedule-view） |
 | **题库组件** | `QuestionBankFilters` | `components/question/question-bank-filters.tsx` | 题库筛选栏（搜索+题型+难度，default/compact 两种布局） | 2 个（P3-d: exam-assembly, question-bank-picker） |
-| **设置组件** | `SettingsView` | `modules/settings/components/settings-view.tsx` | 统一设置页布局（4 标签页：General/Notifications/Appearance/Security，角色差异通过 props 注入） | 3 个（P2-a: admin/teacher/student 设置页） |
+| **设置组件** | `SettingsView` | `modules/settings/components/settings-view.tsx` | 统一设置页布局（5 标签页：General/Notifications/Appearance/Security/AI，角色差异通过 props 注入，Tab URL 持久化，登出二次确认） | 4 个（P2-a: admin/teacher/student/parent 设置页） |
+
+**共享 Hooks 导出**（第二轮 P1-4 重构新增）：
+
+| Hook | 文件 | 签名 | 用途 | 消费方 |
+|------|------|------|------|--------|
+| `useActionMutation` | `hooks/use-action-mutation.ts` | `useActionMutation<T>(options?): { isWorking, mutate }` | 通用 Server Action mutation Hook，替代 50+ 文件中重复的 setIsWorking + try/catch/finally + toast 模式 | 1 个示范（P1-4: schools-view），潜在影响 50+ 文件 |
+| `useActionQuery` | `hooks/use-action-query.ts` | `useActionQuery<T>(action, options?): { data, loading, error, refetch }` | 通用 Server Action 查询 Hook，替代 11 个文件中重复的 useEffect + useState(loading) + Action().then().catch().finally() 模式，内置竞态防护 | 1 个示范（P1-4: create-question-dialog），潜在影响 11 个文件 |
+
+**共享工具函数导出**（第二轮 P1-3 重构新增）：
+
+| 函数 | 文件 | 签名 | 用途 | 消费方 |
+|------|------|------|------|--------|
+| `formatDateTime` | `lib/utils.ts` | `formatDateTime(date, locale?): string` | 国际化日期+时间格式化（含小时、分钟） | 4 个（P1-3: lesson-plan-card, version-history-drawer, proctoring-dashboard, exam-ai-generator） |
+| `formatLongDate` | `lib/utils.ts` | `formatLongDate(date, locale?): string` | 国际化长日期格式化（含星期、完整月份名） | 1 个（P1-3: teacher-dashboard-header） |
 
 > 注：`SettingsView` 位于 `modules/settings/components/`（非 shared 层），因仅被 settings 模块消费，未下沉到 shared。此处列出以完整反映本次重构的组件抽取范围。
 
@@ -421,7 +474,8 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
 - ⚠️ P1：`schema.ts` 1111 行（54 张表混合，超 1000 硬上限）
 - ✅ P1：~~`auth.ts` 293 行混合 5 类职责~~ 已拆分（4 个辅助函数组迁移至 `shared/lib/{role-utils,bcrypt-utils,http-utils,password-security-service}`，auth.ts 仅保留 NextAuth 配置）
 - ✅ P2-2 已修复：~~`ai.ts` 218 行混合 5 类职责~~ 已拆分为 `ai/` 目录（payload-parser.ts/api-key-crypto.ts/provider-config.ts/client.ts/errors.ts/index.ts），原 `ai.ts` 保留为向后兼容的重导出文件（9 行）
-- ⚠️ P2：`onboarding-gate.tsx` 业务逻辑泄漏到 shared
+- ✅ P2-4 已修复：~~`onboarding-gate.tsx` 业务逻辑泄漏到 shared~~ 已迁移至 `modules/onboarding/`（actions/data-access/schema/types/components），引导流程改为独立路由 `/onboarding` + middleware 重定向 + Server Action
+- ✅ P0-2/P0-3/P0-4/P0-5/P1-1/P1-2/P1-4/P1-5 已修复（v3 对标 PowerSchool/Veracross/Auth0）：家长绑定三因子验证（邮箱+生日+手机号后4位）、教师多科目循环绑定、审计日志、服务端幂等、URL query 持久化步骤、局部错误收集、家长多子女动态行、跳过机制明确化
 
 **文件清单**：
 | 文件 | 行数 | 职责 |
@@ -465,7 +519,7 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
 | `components/question/question-bank-filters.tsx` | 137 | QuestionBankFilters 题库筛选栏（P3-d 新增） |
 | `lib/download.ts` | 47 | downloadBase64File + downloadBlob 客户端下载工具（P1-c 新增） |
 | `lib/utils.ts` | - | 通用工具（P1-a/P1-c 新增 getInitials + formatDateForFile） |
-| `components/onboarding-gate.tsx` | 312 | 引导流程（业务泄漏） |
+| `components/onboarding-gate.tsx` | 312 | ~~引导流程（业务泄漏）~~ 已废弃，逻辑迁移至 `modules/onboarding/`（P2-4 已修复） |
 | `components/global-search.tsx` | 221 | 全局搜索（业务泄漏） |
 | `types/permissions.ts` | 157 | 61 个权限点常量 + Role/DataScope/AuthContext 类型 |
 
@@ -735,7 +789,8 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
 
 **导出函数**：
 - Actions：`getAttendanceRecordsAction` / `createAttendanceRecordAction` / `updateAttendanceRecordAction` / `deleteAttendanceRecordAction` / `getStudentAttendanceAction` / `getAttendanceStatsAction`
-- Data-access：`getAttendanceRecords` / `createAttendanceRecord` / `updateAttendanceRecord` / `deleteAttendanceRecord` / `getClassStudentsForAttendance` / `getAttendanceStats`
+- Data-access：`getAttendanceRecords` / `createAttendanceRecord` / `updateAttendanceRecord` / `deleteAttendanceRecord` / `getClassStudentsForAttendance` / `getAttendanceStats`（管理员考勤总览页统计概览，基于 `getAttendanceRecords` 聚合）
+- Components：`AttendanceStatsCards`（管理员考勤总览页 6 卡片统计概览）
 
 **依赖关系**：
 - 依赖：`shared/*`、`@/auth`、`classes`（✅ P1-1 已修复：通过 classes data-access.getTeacherClasses/getAdminClasses）
@@ -751,7 +806,7 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
 | 文件 | 行数 | 职责 |
 |------|------|------|
 | `actions.ts` | 271 | 6 个 Server Action |
-| `data-access.ts` | 271 | 考勤 CRUD |
+| `data-access.ts` | 309 | 考勤 CRUD + 管理员统计概览 |
 | `data-access-stats.ts` | 145 | 统计逻辑（拆分范例） |
 | `schema.ts` | - | Zod 校验 |
 | `types.ts` | - | 类型定义 |
@@ -760,14 +815,15 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
 
 ## 2.11 users（用户模块）
 
-**职责**：用户资料管理 + 批量导入导出。
+**职责**：用户资料管理 + 批量导入导出 + 管理员用户列表管理。
 
 **导出函数**：
-- Actions：`getUserProfileAction` / `updateUserProfileAction` / `importUsersAction` / `exportUsersAction` / `downloadUserTemplateAction`
-- Data-access：`getUserProfile` / `getCurrentStudentUser`（✅ P2-20 已修复：从 homework 模块迁移而来，6 个 student 页面通过此函数获取学生身份，不再依赖 homework 模块）
+- Actions：`getUserProfileAction` / `updateUserProfileAction` / `importUsersAction` / `exportUsersAction` / `downloadUserTemplateAction` / `updateUserRoleAction` / `deleteUserAction`
+- Data-access：`getUserProfile` / `getCurrentStudentUser`（✅ P2-20 已修复：从 homework 模块迁移而来，6 个 student 页面通过此函数获取学生身份，不再依赖 homework 模块）/ `getAdminUsers`（管理员用户列表分页查询，支持搜索+角色聚合）/ `getAdminUserRoles`（角色名列表，用于筛选下拉框）
 - Import-export：`generateUserImportTemplate` / `parseUserImportData` / `exportUsersToExcel`（+ re-export `batchImportUsers` / `UserImportResult` 保持向后兼容）
 - User-service：`batchImportUsers`（用户创建 + 密码哈希 + 角色分配）
 - Class-registration：`registerStudentByInvitationCode`（委托 classes/data-access 完成班级注册）
+- Components：`UserImportDialog`（批量导入对话框）/ `AdminUsersView`（管理员用户列表客户端组件，搜索+筛选+分页+删除）
 
 **依赖关系**：
 - 依赖：`shared/*`（含 `shared/lib/role-utils`，✅ P2 已修复：删除本地 `normalizeRoleName`/`resolvePrimaryRole`/`rolePriority`，统一复用 `shared/lib/role-utils.resolvePrimaryRole`）、`@/auth`、`classes`（✅ P1-4 已修复：通过 `class-registration.ts` 调用 `classes/data-access.enrollStudentByInvitationCode`，不再直写 classEnrollments）
@@ -780,6 +836,7 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
 - ✅ P1-1 已修复：~~`updateUserProfile` 绕过 data-access 直接 DB 写~~ 已下沉到 data-access
 - ✅ P2-20 已修复：新增 `getCurrentStudentUser` 函数（从 homework 模块迁移），6 个 student 页面通过此函数获取学生身份，不再依赖 homework 模块
 - ✅ P2 已解决：`data-access.ts` 已扩充写操作（updateUserProfile 已下沉）
+- ⚠️ 已知限制：`AdminUsersView` 客户端组件的删除操作通过 `fetch("/api/admin/users/:id")` 调用，对应 API 路由尚未实现（`deleteUserAction` Server Action 已就绪，可作为后续 API 路由的实现基础）
 
 **文件清单**：
 | 文件 | 行数 | 职责 |
@@ -787,32 +844,37 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
 | `import-export.ts` | 157 | 文件解析/生成（模板生成 + 解析校验 + Excel 导出）+ re-export 向后兼容 |
 | `user-service.ts` | 82 | 用户创建（批量导入 + 密码哈希 + 角色分配） |
 | `class-registration.ts` | 21 | 班级注册（委托 classes/data-access） |
-| `actions.ts` | 131 | 5 个 Server Action |
-| `data-access.ts` | 133 | getUserProfile + 用户查询 |
+| `actions.ts` | 218 | 7 个 Server Action（profile 更新 + 模板下载/导入/导出 + 角色更新 + 删除） |
+| `data-access.ts` | 394 | getUserProfile + 用户查询 + 管理员用户列表分页查询（getAdminUsers/getAdminUserRoles） |
+| `components/admin-users-view.tsx` | 290 | 管理员用户列表客户端组件（搜索+筛选+表格+分页+删除对话框） |
 
 ---
 
 ## 2.12 dashboard（仪表盘模块）
 
-**职责**：管理员/教师/学生仪表盘数据聚合。
+**职责**：管理员/教师/学生仪表盘数据聚合 + 管理员趋势图表。
 
 **导出函数**：
 - Data-access：`getAdminDashboardData` / `getTeacherDashboardData` / `getStudentDashboardData`
+- Components：`AdminDashboardView` / `UserGrowthChart`（recharts 折线图，复用于用户增长趋势与作业提交趋势）
 
 **依赖关系**：
-- 依赖：`shared/*`、`@/auth`、`classes`（通过 data-access，合理）、`homework`（通过 data-access，合理）、`grades`（合理）、`users`/`textbooks`/`questions`/`exams`（通过各模块 dashboard stats 函数，P0-4 已修复）
+- 依赖：`shared/*`、`@/auth`、`classes`（通过 data-access，合理）、`homework`（通过 data-access，合理）、`grades`（合理）、`users`/`textbooks`/`questions`/`exams`（通过各模块 dashboard stats 函数，P0-4 已修复）、`recharts`（UserGrowthChart）
 - 被依赖：无
 
 **已知问题**：
 - ✅ P0-4 已修复：`getAdminDashboardData` 改为并行调用各模块 dashboard stats 函数（`getUsersDashboardStats`/`getClassesDashboardStats`/`getTextbooksDashboardStats`/`getQuestionsDashboardStats`/`getExamsDashboardStats`/`getHomeworkDashboardStats`），不再直查跨模块表
 - ✅ P1-1 已修复：~~教师仪表盘直查 `users` 表获取教师姓名~~ 改为通过 users data-access 获取
 - ✅ 学生/教师仪表盘正确通过各模块 data-access 获取数据
+- ℹ️ V1 新增：`AdminDashboardData` 类型新增 `userGrowth`/`homeworkTrend` 字段（`Array<{ date: string; count: number }>`），`data-access.ts` 当前返回空数组占位，待后续接入真实统计
 
 **文件清单**：
 | 文件 | 行数 | 职责 |
 |------|------|------|
-| `data-access.ts` | - | 仪表盘数据聚合（P0-4 已修复，通过各模块 data-access 获取数据） |
-| `types.ts` | - | 类型定义 |
+| `data-access.ts` | - | 仪表盘数据聚合（P0-4 已修复，通过各模块 data-access 获取数据；V1 新增 userGrowth/homeworkTrend 占位字段） |
+| `types.ts` | - | 类型定义（V1 新增 userGrowth/homeworkTrend 字段） |
+| `components/admin-dashboard/admin-dashboard.tsx` | - | 管理员仪表盘视图（V1 新增趋势图表区域：用户增长趋势 + 作业提交趋势） |
+| `components/admin-dashboard/user-growth-chart.tsx` | - | recharts 折线图组件（V1 新增，复用于两个趋势卡片） |
 | `components/*` | 14 文件 | 三种角色仪表盘组件 |
 
 ---
@@ -915,29 +977,32 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
 
 ## 2.16 announcements（公告模块）
 
-**职责**：公告 CRUD + 发布/归档。
+**职责**：公告 CRUD + 发布/归档 + 发布通知。
 
 **导出函数**：
-- Actions：`getAnnouncementsAction` / `createAnnouncementAction` / `updateAnnouncementAction` / `deleteAnnouncementAction` / `publishAnnouncementAction` / `archiveAnnouncementAction`（✅ P1-2 已修复：actions 层不再直接访问 DB，全部下沉到 data-access）
-- Data-access：`getAnnouncements` / `getAnnouncementById` / `insertAnnouncement` / `updateAnnouncementById` / `deleteAnnouncementById` / `publishAnnouncementById` / `archiveAnnouncementById`（后 5 个为 P1-2 新增）
+- Actions：`getAnnouncementsAction` / `createAnnouncementAction` / `updateAnnouncementAction` / `deleteAnnouncementAction` / `publishAnnouncementAction` / `archiveAnnouncementAction`（✅ P1-2 已修复：actions 层不再直接访问 DB，全部下沉到 data-access；✅ 发布公告时触发通知模块 `sendBatchNotifications`）
+- Data-access：`getAnnouncements`（支持 `audience` 受众过滤）/ `getAnnouncementById` / `insertAnnouncement` / `updateAnnouncementById` / `deleteAnnouncementById` / `publishAnnouncementById` / `archiveAnnouncementById`（后 5 个为 P1-2 新增）
 
 **依赖关系**：
-- 依赖：`shared/*`、`@/auth`、`school`（合理，获取年级列表）
+- 依赖：`shared/*`、`@/auth`、`school`（获取年级列表）、`classes`（获取班级列表 + 解析受众）、`users`（获取目标用户 ID 列表）、`notifications`（发布公告时发送通知）
 - 被依赖：无
 
 **已知问题**：
 - ✅ P1-2 已修复：~~所有写操作直接在 actions 层 `db.insert/update/delete`，未下沉到 data-access~~ 写操作已下沉到 data-access（5 个新函数）
-- ⚠️ P2：死代码 `void wasPublished`
 - ✅ P2 已修复：~~`getAnnouncementsAction` 使用 `requireAuth()` 而非 `requirePermission(ANNOUNCEMENT_READ)`~~ 改为 `requirePermission(Permissions.ANNOUNCEMENT_READ)`
-- ✅ P2 已修复：`data-access.ts` 中 2 处 catch 块添加 `console.error` 输出错误上下文（getAnnouncements/getAnnouncementById）
+- ✅ 已修复：用户端列表页传入 `audience` 受众过滤（school/grade/class），管理端返回所有公告
+- ✅ 已修复：用户端新增公告详情页 `/announcements/[id]`（只读模式）
+- ✅ 已修复：管理端列表页传递 `classes` 数据给 `AdminAnnouncementsView`
+- ✅ 已修复：发布公告时（`publishAnnouncementAction` / `createAnnouncementAction` 直接发布 / `updateAnnouncementAction` 状态变为 published）触发通知模块 `sendBatchNotifications`
+- ✅ 已修复：新增 `loading.tsx` 骨架屏（用户端 + 管理端）
 
 **文件清单**：
 | 文件 | 行数 | 职责 |
 |------|------|------|
-| `actions.ts` | 197 | 6 个 Server Action（P1-2 已修复，无直接 DB 操作） |
-| `data-access.ts` | 171 | 公告 CRUD + 发布/归档（含 P1-2 新增 5 个写函数） |
+| `actions.ts` | ~270 | 6 个 Server Action + 通知触发逻辑（P1-2 已修复，无直接 DB 操作） |
+| `data-access.ts` | ~190 | 公告 CRUD + 发布/归档 + 受众过滤（含 P1-2 新增 5 个写函数） |
 | `schema.ts` | - | Zod 校验 |
-| `types.ts` | - | 类型定义 |
+| `types.ts` | - | 类型定义（`GetAnnouncementsParams` 新增 `audience` 字段） |
 
 ---
 
@@ -1000,10 +1065,39 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
 **职责**：家长视角的子女数据聚合与展示。
 
 **导出函数**：
-- Data-access：`getChildren` / `getChildBasicInfo` / `getChildDashboardData` / `getParentDashboardData` / `verifyParentChildRelation`（✅ P2 已修复：`getChildBasicInfo` 使用 `Promise.all` 并行化 gradeName 与 activeClass 查询；新增 `verifyParentChildRelation` 同时按 parentId + studentId 过滤，防止跨家庭信息泄露；新增 `getStudentActiveClass` 一次 JOIN 返回 classId + className；新增 `getGradeNameById` 替代全量 `getGradeOptions`）
+- Data-access：`getChildren` / `getChildBasicInfo` / `getChildDashboardData` / `getParentDashboardData` / `verifyParentChildRelation` / `getChildNameList`（✅ v4 新增：用于详情页头部多子女切换器，一次批量查询避免 N+1）
+- Components：`ParentDashboard` / `ChildCard` / `ChildDetailHeader` / `ChildDetailPanel` / `SiblingSwitcher` / `ChildHomeworkSummary` / `ChildGradeSummary` / `ChildScheduleCard` / `ParentChildrenDataPage` / `ParentNoChildrenPage` / `ParentAttentionBanner`（v4 新增）/ `ParentAttendanceWarning`（v4 新增）/ `ParentExportButton`（v4 新增）
+
+**v4 修复（产品/UX 维度）**：
+- ✅ FEAT-G01：新增 `/parent/leave` 请假申请占位页（含 loading.tsx）
+- ✅ FEAT-G02：详情页 Schedule Tab 支持完整周课表（新增 `weeklySchedule` 字段 + `ChildWeeklyScheduleItem` 类型 + `buildWeeklySchedule` 函数）
+- ✅ FEAT-G05：考勤页新增 `ParentAttendanceWarning` 异常预警横幅（聚合缺勤/迟到/低出勤率）
+- ✅ FEAT-G06：详情页底部新增"Contact Teacher"快捷入口
+- ✅ FEAT-G07：详情页头部新增 `SiblingSwitcher` 多子女切换器
+- ✅ LAYOUT-P01：仪表盘新增 `ParentAttentionBanner` 待办事项横幅
+- ✅ LAYOUT-P02：`ChildCard` 突出 Overdue 异常（红色边框 + AlertTriangle 图标）
+- ✅ LAYOUT-P03：仪表盘快捷入口改为 4 宫格大图标卡片
+- ✅ LAYOUT-P04：详情页改为 Tab 布局（Overview/Homework/Grades/Schedule/Attendance/Diagnostic）
+- ✅ LAYOUT-P05：详情页新增面包屑导航
+- ✅ LAYOUT-P07：成绩趋势图 X 轴改用序号，避免日期重叠
+- ✅ LAYOUT-P08：成绩页新增 `ParentExportButton` 导出按钮（占位）
+- ✅ NAV-P03：详情页实现 `?tab=` 参数支持
+- ✅ NAV-P04：所有 parent 路由新增 `loading.tsx` 骨架屏 + `error.tsx` 错误边界
+- ✅ DATA-P02：成绩卡片新增 TrendIcon 进步/退步/持平标识
+- ✅ DATA-P03：排名展示新增"Top X%"百分比
+- ✅ DATA-P04：作业列表新增科目标识 Badge
+- ✅ HABIT-P01：仪表盘"一眼定位异常"能力（AttentionBanner 聚合）
+- ✅ HABIT-P03：多子女切换无需返回仪表盘
+- ✅ HABIT-P06：仪表盘展示未读/待办数量
+- ✅ A11Y-P02：Overdue 状态增加 AlertTriangle 图标辅助
+- ✅ A11Y-P04：成绩图表容器新增 aria-label
+- ✅ PERF-P01/P02：骨架屏 + 错误边界
+- ✅ PERF-P03：空状态新增"Contact support"引导按钮
+- ✅ PERF-P04：`ChildCard` Link 添加 `prefetch`
+- ✅ MOBILE-P04：作业/成绩列表项 `min-h-[44px]` 触摸区域
 
 **依赖关系**：
-- 依赖：`shared/*`、`@/auth`、`classes`（合理）、`homework`（合理）、`grades`（合理）、`users`（合理）、`school`（合理）
+- 依赖：`shared/*`、`@/auth`、`classes`（合理）、`homework`（合理）、`grades`（合理）、`users`（合理）、`school`（合理）、`attendance`（v4 新增：考勤页复用 `StudentAttendanceView`）
 - 被依赖：无
 
 **已知问题**：
@@ -1013,15 +1107,37 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
 - ✅ P2 已修复：~~`getGradeOptions` 全量查询效率低~~ 改为 `getGradeNameById` 按 ID 查询
 - ✅ P2 已修复：~~`buildHomeworkSummary` 中 `[...assignments].sort()` 不必要拷贝~~ 改为 `toSorted()`
 - ✅ P2 已修复：~~`in7Days` 死代码~~ 已删除
+- ⚠️ v4 保留：`/parent/leave` 为占位页，待后端实现请假审批流后接入
+- ⚠️ v4 保留：`ParentExportButton` 为占位，待后端实现成绩导出 Server Action 后接入
+- ⚠️ v4 保留：详情页 Attendance/Diagnostic Tab 为占位提示，待对应功能实现后填充
 - ✅ 职责单一，正确复用其他模块 data-access
 
 **文件清单**：
 | 文件 | 行数 | 职责 |
 |------|------|------|
-| `data-access.ts` | 227 | 子女关系 + 仪表盘数据聚合 + 关系校验 |
-| `types.ts` | 67 | 类型定义（含 JSDoc） |
-| `lib/utils.ts` | 7 | 模块共享工具函数（getInitials） |
-| `components/*` | 8 文件 | 子女卡片/详情/仪表盘/共享数据页 |
+| `data-access.ts` | 243 | 子女关系 + 仪表盘数据聚合 + 关系校验 + 子女姓名列表（v4 新增 `getChildNameList` + `buildWeeklySchedule`） |
+| `types.ts` | 79 | 类型定义（含 JSDoc，v4 新增 `ChildWeeklyScheduleItem`） |
+| `components/parent-dashboard.tsx` | 97 | 仪表盘（v4 重构：待办横幅 + 宫格快捷入口） |
+| `components/parent-attention-banner.tsx` | 116 | v4 新增：待办事项/异常聚合横幅 |
+| `components/parent-attendance-warning.tsx` | 89 | v4 新增：考勤异常预警 |
+| `components/parent-export-button.tsx` | 50 | v4 新增：成绩导出按钮（占位） |
+| `components/child-card.tsx` | 148 | 子女卡片（v4 增强：异常突出 + 趋势图标） |
+| `components/child-detail-header.tsx` | 78 | 详情页头部（v4 增强：面包屑） |
+| `components/child-detail-panel.tsx` | 187 | 详情页 Tab 面板 + SiblingSwitcher（v4 重写） |
+| `components/child-homework-summary.tsx` | 147 | 作业摘要（v4 增强：科目标识 + 触摸区域） |
+| `components/child-grade-summary.tsx` | 159 | 成绩趋势（v4 增强：趋势图标 + aria-label） |
+| `components/child-schedule-card.tsx` | 119 | 课表卡片（v4 增强：周课表视图） |
+| `components/parent-children-data-page.tsx` | 92 | 共享数据页（v4 增强：headerExtra） |
+
+**路由清单**：
+| 路由 | 文件 | 说明 |
+|------|------|------|
+| `/parent/dashboard` | `dashboard/page.tsx` + `loading.tsx` | 家长仪表盘 |
+| `/parent/grades` | `grades/page.tsx` + `loading.tsx` | 多子女成绩聚合 |
+| `/parent/attendance` | `attendance/page.tsx` + `loading.tsx` | 多子女考勤聚合（v4 新增预警横幅） |
+| `/parent/leave` | `leave/page.tsx` + `loading.tsx` | v4 新增：请假申请（占位） |
+| `/parent/children/[studentId]` | `children/[studentId]/page.tsx` + `loading.tsx` | 子女详情页（v4 重构：Tab 布局 + 多子女切换） |
+| `error.tsx` | `error.tsx` | v4 新增：错误边界 |
 
 ---
 
@@ -1128,13 +1244,13 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
 
 ## 2.23 settings（设置模块）
 
-**职责**：AI Provider 管理 + 密码修改 + 个人资料 + 主题偏好 + 通知偏好。
+**职责**：系统设置（学校信息/安全策略/文件上传/通知配置）+ AI Provider 管理 + 密码修改 + 个人资料 + 主题偏好 + 通知偏好。
 
 **导出函数**：
 - Actions：`getAiProvidersAction` / `createAiProviderAction` / `updateAiProviderAction` / `deleteAiProviderAction` / `testAiProviderAction`
 - Actions-password：`changePasswordAction`（✅ P1 已修复：使用 `requirePermission(USER_PROFILE_UPDATE)` + Zod 校验 + DB 操作下沉到 data-access）
 - Data-access：`getAiProviderSummaries` / `countDefaultAiProviders` / `getAiProviderForUpdate` / `updateAiProvider` / `createAiProvider` / `getUserPasswordHash` / `getPasswordSecurityByUserId` / `updateUserPassword` / `upsertPasswordSecurityOnPasswordChange`（P1 新增，从 actions 下沉）
-- Components：`SettingsView`（P2-a 新增：统一设置页布局，消除 admin/teacher/student 三个设置视图的重复布局；4 标签页 General/Notifications/Appearance/Security，角色差异通过 `description` / `backHref` / `generalExtra` 三个 props 注入；3 个消费方：admin/teacher/student 设置页）
+- Components：`SettingsView`（P2-a 新增：统一设置页布局，消除 admin/teacher/student/parent 四个设置视图的重复布局；5 标签页 General/Notifications/Appearance/Security/AI，角色差异通过 `description` / `backHref` / `generalExtra` 三个 props 注入；Tab 通过 URL `?tab=` 参数持久化；AI 标签页条件渲染需 `AI_CONFIGURE` 权限；登出按钮使用 AlertDialog 二次确认；4 个消费方：admin/teacher/student/parent 设置页）、`ParentSettingsView`（家长设置视图，backHref 指向 `/parent/dashboard`，含家长专属快捷链接）、`AdminSettingsView`（系统设置视图，4 个 Card：学校信息/安全策略/文件上传/通知配置；消费方：`/admin/settings` 页面，权限 `SETTINGS_ADMIN`）
 - Types：`AiProviderSummary` / `AiProviderName` / `AiProviderExisting`（P1 新增，从 actions.ts 迁出）
 
 **依赖关系**：
@@ -1146,7 +1262,12 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
 - ✅ P1 已修复：~~无 `data-access.ts`，`actions.ts` 直接使用 `db`~~ 新建 `data-access.ts`，所有 DB 操作已下沉
 - ✅ P1 已修复：~~`changePasswordAction` 使用 `requireAuth()` 无 Zod 校验~~ 改为 `requirePermission(USER_PROFILE_UPDATE)` + `ChangePasswordSchema` Zod 校验 + 并行查询优化
 - ✅ P2 已修复：`actions-password.ts` 删除本地 `normalizeBcryptHash`，统一复用 `shared/lib/bcrypt-utils.normalizeBcryptHash`，消除重复代码
-- ✅ P2-a 已修复：~~admin/teacher/student 三个设置视图重复布局~~ 新增 `SettingsView` 统一设置页布局（4 标签页 + 角色差异通过 props 注入），3 个设置页改为消费 `SettingsView`
+- ✅ P2-a 已修复：~~admin/teacher/student 三个设置视图重复布局~~ 新增 `SettingsView` 统一设置页布局（5 标签页 + 角色差异通过 props 注入），4 个设置页改为消费 `SettingsView`
+- ✅ parent 角色路由已修复：~~parent 用户被错误渲染为 TeacherSettingsView~~ 新增 `ParentSettingsView`，`/settings` 页面增加 parent 角色分支
+- ✅ Tab URL 持久化已修复：`SettingsView` 改为受控模式，通过 `useSearchParams` 读取 `tab` 参数，`router.push` 更新 URL
+- ✅ 登出二次确认已修复：`SettingsView` 的 Log out 按钮使用 `AlertDialog` 包裹，点击时弹出确认对话框
+- ✅ AiProviderSettingsCard 已集成：`SettingsView` 新增 AI 标签页，条件渲染需 `AI_CONFIGURE` 权限
+- ✅ password-change-form 任意值 Tailwind 类已修复：~~`[&>div]:bg-red-500` 等任意值类~~ Progress 组件新增 `indicatorClassName` prop，使用标准颜色类
 - ⚠️ P2：`notification-preferences-form.tsx` 跨模块 UI 依赖
 - ✅ 密码修改有速率限制
 - ✅ AI Provider 操作有 `AI_CONFIGURE` 权限校验
@@ -1158,8 +1279,10 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
 | `actions-password.ts` | 107 | 修改密码（P1 已修复：requirePermission + Zod + data-access） |
 | `data-access.ts` | 175 | AI Provider CRUD + 密码修改 DB 操作（P1 新增） |
 | `types.ts` | 16 | 类型定义（P1 新增，AiProviderSummary 等） |
-| `components/settings-view.tsx` | 117 | SettingsView 统一设置页布局（P2-a 新增，4 标签页 + props 注入角色差异） |
-| `components/*` | 8 文件 | 通用设置 + AI 配置 + 密码 + 主题 + 通知偏好 |
+| `components/settings-view.tsx` | 196 | SettingsView 统一设置页布局（P2-a 新增，5 标签页 + props 注入角色差异 + Tab URL 持久化 + 登出二次确认 + AI 标签页） |
+| `components/admin-settings-view.tsx` | 195 | AdminSettingsView 系统设置视图（4 个 Card：学校信息/安全策略/文件上传/通知配置，模拟保存） |
+| `components/parent-settings-view.tsx` | 70 | ParentSettingsView 家长设置视图（新增，复用 SettingsView 布局） |
+| `components/*` | 9 文件 | 通用设置 + AI 配置 + 密码 + 主题 + 通知偏好 + 4 角色设置视图 |
 
 ---
 
@@ -1188,23 +1311,23 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
 
 ## 2.25 layout（布局模块）
 
-**职责**：应用骨架（侧边栏 + 顶部导航 + 导航配置）。
+**职责**：应用骨架（侧边栏 + 顶部导航 + 导航配置 + 多角色切换）。
 
 **导出函数**：`AppSidebar` / `SidebarProvider` / `SiteHeader` + `navigation` 配置
 
 **依赖关系**：
-- 依赖：`shared/hooks/use-permission`、`@/auth`（useSession）、`messaging`（通知下拉）
+- 依赖：`shared/hooks/use-permission`、`@/auth`（useSession）、`messaging`（通知下拉）、`shared/components/ui/select`（角色切换下拉）
 - 被依赖：`app/(dashboard)/layout.tsx`
 
 **已知问题**：
-- ⚠️ P2：用权限反推角色（`permissions.includes(HOMEWORK_SUBMIT) && !permissions.includes(EXAM_CREATE)`），应改用 `hasRole("student")`
+- ✅ P2 已修复：~~用权限反推角色~~ `app-sidebar.tsx` 改用 `hasRole()` 判断角色，并新增多角色切换机制（`SidebarContext.currentRole`/`setCurrentRole`，null 表示自动检测；当用户拥有多个角色时在侧边栏底部显示 `Select` 下拉切换）
 - ✅ navigation.ts 无幽灵路由（13 个已修复）
 
 **文件清单**：
 | 文件 | 职责 |
 |------|------|
-| `components/app-sidebar.tsx` | 侧边栏（根据权限渲染） |
-| `components/sidebar-provider.tsx` | 侧边栏状态 Context |
+| `components/app-sidebar.tsx` | 侧边栏（根据权限渲染 + 多角色切换下拉） |
+| `components/sidebar-provider.tsx` | 侧边栏状态 Context（含 `currentRole`/`setCurrentRole`） |
 | `components/site-header.tsx` | 顶部导航（含通知下拉） |
 | `config/navigation.ts` | 导航配置（4 个角色） |
 
@@ -1494,7 +1617,7 @@ shared/lib/{audit-logger, change-logger, auth-guard} → @/auth → shared/lib/*
 | P2-1 | `exams/ai-pipeline.ts` 857 行，混合 4 类职责 | exams |
 | ~~P2-2~~ | ~~`exams/actions.ts` 832 行（超 800 建议）~~ ✅ 已修复（P1-2 后降至 691 行） | exams |
 | ~~P2-3~~ | ~~`shared/lib/ai.ts` 218 行，混合 5 类职责~~ ✅ 已修复（P2-2 已拆分为 `ai/` 目录） | shared |
-| P2-4 | `onboarding-gate.tsx` 业务逻辑泄漏到 shared | shared |
+| ~~P2-4~~ | ~~`onboarding-gate.tsx` 业务逻辑泄漏到 shared~~ ✅ 已修复（迁移至 `modules/onboarding/`，改用独立路由 + Server Action + middleware 重定向） | shared/onboarding |
 | P2-5 | `global-search.tsx` 业务类型硬编码在 shared | shared |
 | ~~P2-6~~ | ~~`proxy.ts` 硬编码权限字符串，未复用 Permissions 常量~~ ✅ 已修复（改用 `Permissions` 常量） | proxy |
 | ~~P2-7~~ | ~~`useA11yId` Hook 错放在 lib/ 而非 hooks/~~ ✅ 已修复（文件已不存在；`use-aria-live.ts` 已在 `hooks/` 目录） | shared |
@@ -1507,7 +1630,7 @@ shared/lib/{audit-logger, change-logger, auth-guard} → @/auth → shared/lib/*
 | ~~P2-14~~ | ~~`elective` runLottery 使用 Math.random~~ ✅ 已修复（改为 Fisher-Yates 无偏洗牌） | elective |
 | ~~P2-15~~ | ~~`elective` selectCourse FCFS 并发超卖风险~~ ✅ 已修复（db.transaction + FOR UPDATE 行锁） | elective |
 | P2-16 | `diagnostic` 班级报告 studentId 字段复用 | diagnostic |
-| ~~P2-17~~ | ~~`layout` 用权限反推角色~~ ✅ 已修复（`app-sidebar.tsx` 改用 `hasRole()` 判断角色） | layout |
+| ~~P2-17~~ | ~~`layout` 用权限反推角色~~ ✅ 已修复（`app-sidebar.tsx` 改用 `hasRole()` 判断角色；N3 新增多角色切换机制：`SidebarContext.currentRole`/`setCurrentRole` + 侧边栏底部 Select 下拉） | layout |
 | ~~P2-18~~ | ~~`scheduling/actions.ts` 末尾 re-export data-access~~ ✅ 已修复（移除 re-export，4 个页面改为从 `data-access` 导入） | scheduling |
 | P2-19 | `ExamAssembly` / `ExamPreviewQuestionEditor` 10 个 props | exams |
 | P2-20 | ~~`homework/data-access.getDemoStudentUser` 使用 `auth()` 而非 auth-guard~~ ✅ 已修复（已迁移至 `users/data-access.getCurrentStudentUser`，6 个 student 页面改用 users 模块；`elective` 页面改用 `getAuthContext()`；homework 保留 re-export 向后兼容） | homework |