feat: 新增备课模块并修复全模块 P0/P1/P2 缺陷

主要变更:

- 新增 lesson-preparation 模块: 备课编辑器、节点编辑、AI 建议、知识点选择、版本历史、作业发布

- 新增 shared 通用组件: charts/question-bank-filters/schedule-list/ui (chip-nav/filter-bar/page-header/stat-card/stat-item)

- 新增 student/admin 端 loading.tsx 与 error.tsx, 优化加载与错误态体验

- 新增 teacher/lesson-plans 页面 (列表/新建/编辑)

- 新增 drizzle 迁移 0002_tiny_lionheart 及 snapshot

- 新增 textbooks/schema.ts 与 exams/utils/normalize-structure.ts

- 修复 Tiptap v3 SSR hydration 崩溃 (rich-text-block immediatelyRender: false)

- 重构多模块 data-access/actions/组件, 修复权限校验与类型规范

- 同步架构文档 004/005 反映新增模块、导出、依赖关系

- 归档 bugs/* 测试报告与 e2e 测试脚本 (admin/parent/student/teacher web_test)

src/shared/hooks/use-permission.ts

@@ -1,28 +1,53 @@
 "use client"
 
+import { useCallback, useMemo } from "react"
 import { useSession } from "next-auth/react"
-import type { Permission } from "@/shared/types/permissions"
+import type { Permission, Role } from "@/shared/types/permissions"
 
+/**
+ * Client-side permission hook.
+ *
+ * Hydration safety: `useSession()` returns `null`/`loading` on the server and
+ * during the first client render. Callers should gate permission-dependent UI
+ * behind `status === "authenticated"` (returned by `useSession`) or render a
+ * skeleton/placeholder while loading to avoid hydration mismatches.
+ */
 export function usePermission() {
-  const { data: session } = useSession()
-  const permissions = (session?.user?.permissions ?? []) as Permission[]
-  const roles = (session?.user?.roles ?? []) as string[]
+  const { data: session, status } = useSession()
 
-  const hasPermission = (permission: Permission): boolean => {
-    return permissions.includes(permission)
+  const permissions = useMemo<Permission[]>(
+    () => session?.user?.permissions ?? [],
+    [session?.user?.permissions]
+  )
+  const roles = useMemo<Role[]>(
+    () => session?.user?.roles ?? [],
+    [session?.user?.roles]
+  )
+
+  const hasPermission = useCallback(
+    (permission: Permission): boolean => permissions.includes(permission),
+    [permissions]
+  )
+  const hasAnyPermission = useCallback(
+    (...perms: Permission[]): boolean => perms.some((p) => permissions.includes(p)),
+    [permissions]
+  )
+  const hasAllPermissions = useCallback(
+    (...perms: Permission[]): boolean => perms.every((p) => permissions.includes(p)),
+    [permissions]
+  )
+  const hasRole = useCallback(
+    (role: Role): boolean => roles.includes(role),
+    [roles]
+  )
+
+  return {
+    permissions,
+    roles,
+    status,
+    hasPermission,
+    hasAnyPermission,
+    hasAllPermissions,
+    hasRole,
   }
-
-  const hasAnyPermission = (...perms: Permission[]): boolean => {
-    return perms.some((p) => permissions.includes(p))
-  }
-
-  const hasAllPermissions = (...perms: Permission[]): boolean => {
-    return perms.every((p) => permissions.includes(p))
-  }
-
-  const hasRole = (role: string): boolean => {
-    return roles.includes(role)
-  }
-
-  return { permissions, roles, hasPermission, hasAnyPermission, hasAllPermissions, hasRole }
 }