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)
2026-06-22 01:06:16 +08:00
parent d8962aba96
commit 978d9a8309
327 changed files with 34070 additions and 5642 deletions
--- a/bugs/shared_bug_v2.md
+++ b/bugs/shared_bug_v2.md
@@ -0,0 +1,332 @@
+# `src/shared/types` 规范核查报告 v2
+
+> 核查日期：2026-06-18（第二轮）
+> 核查范围：`src/shared/types/` 目录下所有前后端文件 + 关联使用方
+> 依据文档：项目规则、编码规范、架构影响地图 004、架构数据 005
+> 应用技能：`vercel-react-best-practices`、`web-artifacts-builder`、`web-design-guidelines`
+> 前置版本：[student_bug.md](./student_bug.md)（v1）
+
+---
+
+## 〇、修正进度总览
+
+| 类别 | v1 问题数 | 已修正 | 未修正 | 新发现 | v2 合计 |
+|------|-----------|--------|--------|--------|---------|
+| 高危违规 | 8 | 5 | 3 | 2 | 5 |
+| 中危违规 | 6 | 2 | 4 | 1 | 5 |
+| 低危违规 | 3 | 0 | 3 | 0 | 3 |
+| React 性能 | 3 | 0 | 3 | 0 | 3 |
+| Web 界面 | 3 | 0 | 3 | 0 | 3 |
+| 文档同步 | 3 | 0 | 3 | 1 | 4 |
+| **合计** | **23** | **7** | **16** | **4** | **20** |
+
+**修正率**：7/23 = 30.4%
+
+---
+
+## 一、已修正问题（7 项 ✅）
+
+### ✅ BUG-A01：Prettier 分号违规 — 已修正
+- **文件**：[action-state.ts](../src/shared/types/action-state.ts)
+- **v1 状态**：使用分号结尾，违反 `.prettierrc` 的 `"semi": false`
+- **v2 验证**：第 9-14 行已移除所有分号，符合规范
+
+### ✅ BUG-A02：缺少 JSDoc 文档注释 — 已修正
+- **文件**：[action-state.ts](../src/shared/types/action-state.ts)
+- **v1 状态**：`ActionState<T>` 无 JSDoc
+- **v2 验证**：第 1-8 行已补充 JSDoc，说明 `success`/`message`/`errors`/`data` 各字段语义
+
+### ✅ BUG-P01：权限点命名不一致 — 已修正
+- **文件**：[permissions.ts](../src/shared/types/permissions.ts)
+- **v1 状态**：`EXAM_PROCTOR_READ: "exam:proctor_read"` 使用下划线
+- **v2 验证**：第 94 行已改为 `"exam:proctor:read"`，统一冒号分隔
+
+### ✅ BUG-P04：`DataScope` 缺少 JSDoc — 已修正
+- **文件**：[permissions.ts](../src/shared/types/permissions.ts)
+- **v2 验证**：第 110-120 行已补充 JSDoc，说明 6 种 type 的适用角色
+
+### ✅ BUG-P05：`AuthContext` 缺少 JSDoc — 已修正
+- **文件**：[permissions.ts](../src/shared/types/permissions.ts)
+- **v2 验证**：第 129-136 行已补充 JSDoc，说明各字段语义
+
+### ✅ BUG-X01：`exams/actions.ts` 类型导入违规 — 已修正
+- **文件**：[exams/actions.ts](../src/modules/exams/actions.ts)
+- **v2 验证**：第 4 行已改为 `import type { ActionState } from "@/shared/types/action-state"`
+
+### ✅ BUG-X02：`questions/actions.ts` 类型导入违规 — 已修正
+- **文件**：[questions/actions.ts](../src/modules/questions/actions.ts)
+- **v2 验证**：第 7 行已改为 `import type { ActionState } from "@/shared/types/action-state"`
+
+---
+
+## 二、未修正问题（16 项 ❌）
+
+### 2.1 permissions.ts — 严重度：高
+
+#### ❌ BUG-P02：`Permissions` 常量缺少 `satisfies` 类型约束（未修正）
+- **位置**：[permissions.ts:106](../src/shared/types/permissions.ts)
+- **问题**：仍为 `as const`，未用 `satisfies` 验证所有值均为字符串
+- **规范依据**：编码规范 4.2.3
+- **改进建议**：
+  ```typescript
+  } as const satisfies Record<string, string>
+  ```
+
+#### ❌ BUG-P03：`AuthContext.roles` 类型过于宽松（未修正）
+- **位置**：[permissions.ts:139](../src/shared/types/permissions.ts)
+- **问题**：`roles: string[]` 允许任意字符串，但项目角色是有限集合
+- **改进建议**：定义 `Role` 联合类型，`AuthContext.roles` 改为 `Role[]`
+
+#### ❌ BUG-P06：`DataScope.class_members` 缺少关联数据（未修正）
+- **位置**：[permissions.ts:124](../src/shared/types/permissions.ts)
+- **问题**：`{ type: "class_members" }` 不携带 classIds，data-access 层需重复查询
+- **改进建议**：`{ type: "class_members"; classIds: string[] }`
+
+---
+
+### 2.2 action-state.test.ts — 严重度：中
+
+#### ❌ BUG-T01：测试覆盖率不足（未修正）
+- **位置**：[action-state.test.ts:4-33](../src/shared/types/action-state.test.ts)
+- **问题**：仅测试 3 种基本状态，缺少多字段错误、falsy data、空 message 等边界用例
+- **规范依据**：编码规范十「工具函数覆盖率目标 100%」
+
+#### ❌ BUG-T02：测试描述缺少行为意图（未修正）
+- **位置**：[action-state.test.ts:4](../src/shared/types/action-state.test.ts)
+- **问题**：`describe("ActionState")` 过于宽泛
+- **改进建议**：`describe("ActionState 类型构造")`
+
+---
+
+### 2.3 tsconfig.json — 严重度：中
+
+#### ❌ BUG-C01：`target` 低于规范要求（未修正）
+- **位置**：[tsconfig.json:3](../tsconfig.json)
+- **问题**：`"target": "ES2017"`，编码规范 4.1 要求 `"ES2022"`
+
+#### ❌ BUG-C02：缺少 `noUncheckedIndexedAccess`（未修正）
+- **位置**：[tsconfig.json](../tsconfig.json)
+- **问题**：未启用，`ROLE_PERMISSIONS[name]` 在 name 不存在时返回 `Permission[]` 而非 `Permission[] | undefined`
+
+#### ❌ BUG-C03：缺少 `noImplicitReturns` 等（未修正）
+- **位置**：[tsconfig.json](../tsconfig.json)
+- **问题**：未启用 `noImplicitReturns`、`noFallthroughCasesInSwitch`、`forceConsistentCasingInFileNames`
+
+---
+
+### 2.4 React 性能（应用 `vercel-react-best-practices`）
+
+#### ❌ PERF-01：`use-permission.ts` 回调函数未 memoize（未修正）
+- **位置**：[use-permission.ts:11-25](../src/shared/hooks/use-permission.ts)
+- **问题**：`hasPermission`/`hasAnyPermission`/`hasAllPermissions`/`hasRole` 每次渲染创建新引用
+- **违反规则**：`rerender-functional-setstate`、`rerender-memo`
+- **改进建议**：使用 `useCallback` 包裹
+
+#### ❌ PERF-02：`permissions`/`roles` 数组未 memoize（未修正）
+- **位置**：[use-permission.ts:8-9](../src/shared/hooks/use-permission.ts)
+- **问题**：`?? []` 每次创建新数组引用，导致下游依赖项失效
+- **违反规则**：`rerender-derived-state`
+- **改进建议**：使用 `useMemo` 包裹
+
+#### ❌ PERF-03：`as` 断言使用（未修正）
+- **位置**：[use-permission.ts:8-9](../src/shared/hooks/use-permission.ts)
+- **问题**：`as Permission[]`、`as string[]` 违反编码规范 4.2.3
+- **改进建议**：依赖 `next-auth.d.ts` 类型增强，移除断言
+
+#### `use-permission.ts` 完整改进示例
+
+```typescript
+import { useCallback, useMemo } from "react"
+import { useSession } from "next-auth/react"
+import type { Permission } from "@/shared/types/permissions"
+
+export function usePermission() {
+  const { data: session } = useSession()
+
+  const permissions = useMemo(
+    () => (session?.user?.permissions ?? []) as Permission[],
+    [session?.user?.permissions]
+  )
+  const roles = useMemo(
+    () => (session?.user?.roles ?? []) as string[],
+    [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: string): boolean => roles.includes(role),
+    [roles]
+  )
+
+  return { permissions, roles, hasPermission, hasAnyPermission, hasAllPermissions, hasRole }
+}
+```
+
+---
+
+### 2.5 Web 界面规范（应用 `web-design-guidelines`）
+
+#### ❌ UI-01：权限状态可能导致 hydration mismatch（未修正）
+- **位置**：[use-permission.ts:7](../src/shared/hooks/use-permission.ts)
+- **问题**：`useSession()` 服务端返回 `null`/`loading`，客户端 hydration 后权限 UI 闪烁
+- **违反规则**：Hydration Safety
+
+#### ❌ UI-02：权限不足重定向未反映在 URL（未修正）
+- **位置**：[proxy.ts:75-76](../src/proxy.ts)
+- **问题**：重定向到默认页时未携带原始路径，用户不知「为何被重定向」
+- **违反规则**：Navigation & State「URL reflects state」
+- **改进建议**：携带 `?from=originalPath&reason=forbidden`
+
+#### ❌ UI-03：错误消息缺少修复步骤（未修正）
+- **位置**：[auth-guard.ts:13](../src/shared/lib/auth-guard.ts)
+- **问题**：`Permission denied: ${permission}` 仅描述问题，未提供下一步
+- **违反规则**：Content & Copy「Error messages include fix/next step」
+
+---
+
+## 三、v2 新发现问题（4 项 🆕）
+
+### 🆕 NEW-01：`USER_PROFILE_UPDATE` 权限点语义分组不当 — 严重度：中
+- **位置**：[permissions.ts:41-45](../src/shared/types/permissions.ts)
+- **问题**：`USER_PROFILE_UPDATE` 放在 `// School management` 分组下（第 40 行注释），与 `SCHOOL_MANAGE`/`GRADE_MANAGE`/`USER_MANAGE` 同组，但语义上它是「用户自助更新个人资料」，不属于学校管理
+- **改进建议**：独立为 `// User` 分组
+  ```typescript
+  // User (用户自助)
+  USER_PROFILE_UPDATE: "user:profile_update",
+  ```
+
+### 🆕 NEW-02：`questions/actions.ts` 全文件使用分号 — 严重度：中
+- **位置**：[questions/actions.ts](../src/modules/questions/actions.ts)
+- **问题**：全文件 62 处使用分号结尾，违反 `.prettierrc` 的 `"semi": false`，且与 `exams/actions.ts`（无分号）风格冲突
+- **规范依据**：编码规范十五、统一工具配置
+- **改进建议**：运行 `npx prettier --write src/modules/questions/actions.ts` 自动修复
+
+### 🆕 NEW-03：`ROLE_PERMISSIONS` 键类型未约束 — 严重度：中
+- **位置**：[permissions.ts:5](../src/shared/lib/permissions.ts)（lib 层）
+- **问题**：`ROLE_PERMISSIONS: Record<string, Permission[]>` 键类型为 `string`，允许任意字符串作为角色名，与 BUG-P03 同源问题
+- **改进建议**：配合 BUG-P03 新增 `Role` 类型后，改为 `Record<Role, Permission[]>`
+
+### 🆕 NEW-04：权限点数量与文档记录严重不符 — 严重度：低
+- **位置**：[permissions.ts](../src/shared/types/permissions.ts) vs [004 文档](../docs/architecture/004_architecture_impact_map.md)
+- **问题**：permissions.ts 现有 **61 个权限点**（v1 时 54 个，新增 7 个：`EXAM_SUBMIT`、`USER_PROFILE_UPDATE`、`LESSON_PLAN_CREATE/READ/UPDATE/DELETE/PUBLISH`），但 004 文档第 436 行仍记录「54 个权限点常量」，第 1541 行仍记录「54 个权限点」
+- **改进建议**：更新 004 文档为「61 个权限点」
+
+---
+
+## 四、架构文档同步问题（4 项）
+
+### ❌ DOC-01：004 文件行数与权限点数记录过期（未修正 + 数量变化）
+- **位置**：[004_architecture_impact_map.md:436](../docs/architecture/004_architecture_impact_map.md)
+- **v1 问题**：记录 92 行，实际 114 行
+- **v2 现状**：记录仍为 `92 | 54 个权限点常量`，实际 **142 行 | 61 个权限点 + DataScope + AuthContext**
+- **改进建议**：更新为 `142 行 | 61 个权限点 + DataScope + AuthContext`
+
+### ❌ DOC-02：005 JSON 中 `DataScope` 字段顺序与代码不一致（未修正）
+- **位置**：[005_architecture_data.json:1035](../docs/architecture/005_architecture_data.json)
+- **问题**：JSON 中顺序为 `all, owned, class_taught, grade_managed, class_members, children`，代码中为 `all, owned, class_members, grade_managed, class_taught, children`
+
+### ❌ DOC-03：缺少 `Role` 类型定义记录（未修正）
+- **问题**：若按 BUG-P03 新增 `Role` 类型，需在 005 JSON 补充记录
+
+### 🆕 DOC-04：005 JSON 权限点数量未同步（新发现）
+- **位置**：[005_architecture_data.json:63-125](../docs/architecture/005_architecture_data.json)
+- **问题**：JSON 中 `permissions` 节点已包含新增的 `EXAM_SUBMIT`、`USER_PROFILE_UPDATE`、`LESSON_PLAN_*`（共 61 个），但 004 文档仍记录 54 个，两文档不一致
+- **改进建议**：以 005 JSON 为准，更新 004 文档的权限点数量
+
+---
+
+## 五、问题汇总统计（v2）
+
+| 严重度 | 数量 | 问题编号 |
+|--------|------|----------|
+| 高 | 3 | BUG-P02, BUG-P03, BUG-P06 |
+| 中 | 5 | BUG-T01, BUG-T02, BUG-C01, BUG-C02, NEW-01 |
+| 低 | 3 | BUG-C03, DOC-02, DOC-03 |
+| 性能 | 3 | PERF-01, PERF-02, PERF-03 |
+| 界面 | 3 | UI-01, UI-02, UI-03 |
+| 文档 | 3 | DOC-01, DOC-04, NEW-03 |
+| **合计** | **20** | |
+
+---
+
+## 六、修复优先级建议（v2 调整）
+
+### P0（立即修复 — 影响类型安全与一致性）
+1. BUG-C01、BUG-C02、BUG-C03：升级 `tsconfig.json`（**v1 未修复，升级为 P0**）
+2. NEW-02：`questions/actions.ts` 分号违规（Prettier 一致性）
+3. BUG-P02：`Permissions` 添加 `satisfies`
+
+### P1（本迭代修复 — 影响可维护性）
+4. BUG-P03 + NEW-03：新增 `Role` 类型，`ROLE_PERMISSIONS` 改为 `Record<Role, Permission[]>`
+5. PERF-01、PERF-02、PERF-03：`use-permission.ts` 性能优化
+6. NEW-01：`USER_PROFILE_UPDATE` 语义分组调整
+
+### P2（下迭代修复 — 增强健壮性）
+7. BUG-T01、BUG-T02：补充测试用例
+8. BUG-P06：`DataScope.class_members` 携带 classIds
+9. UI-01、UI-02、UI-03：界面规范改进
+
+### P3（文档同步）
+10. DOC-01、DOC-04：更新 004 文档权限点数量（54 → 61）和行数（92 → 142）
+11. DOC-02、DOC-03：同步 005 JSON 字段顺序，补充 `Role` 类型记录
+
+---
+
+## 七、v1 → v2 修正对比
+
+| v1 编号 | 问题 | v1 严重度 | v2 状态 | 备注 |
+|---------|------|-----------|---------|------|
+| BUG-A01 | action-state.ts 分号 | 高 | ✅ 已修正 | 移除分号 |
+| BUG-A02 | action-state.ts JSDoc | 高 | ✅ 已修正 | 补充 JSDoc |
+| BUG-P01 | 权限点命名 | 高 | ✅ 已修正 | `exam:proctor:read` |
+| BUG-P02 | Permissions satisfies | 高 | ❌ 未修正 | — |
+| BUG-P03 | Role 类型 | 高 | ❌ 未修正 | — |
+| BUG-P04 | DataScope JSDoc | 高 | ✅ 已修正 | 补充 JSDoc |
+| BUG-P05 | AuthContext JSDoc | 高 | ✅ 已修正 | 补充 JSDoc |
+| BUG-P06 | class_members classIds | 高 | ❌ 未修正 | — |
+| BUG-T01 | 测试覆盖率 | 中 | ❌ 未修正 | — |
+| BUG-T02 | 测试描述 | 中 | ❌ 未修正 | — |
+| BUG-X01 | exams import type | 中 | ✅ 已修正 | — |
+| BUG-X02 | questions import type | 中 | ✅ 已修正 | — |
+| BUG-C01 | tsconfig target | 中 | ❌ 未修正 | — |
+| BUG-C02 | noUncheckedIndexedAccess | 中 | ❌ 未修正 | — |
+| BUG-C03 | noImplicitReturns | 低 | ❌ 未修正 | — |
+| PERF-01 | useCallback | 性能 | ❌ 未修正 | — |
+| PERF-02 | useMemo | 性能 | ❌ 未修正 | — |
+| PERF-03 | as 断言 | 性能 | ❌ 未修正 | — |
+| UI-01 | hydration mismatch | 界面 | ❌ 未修正 | — |
+| UI-02 | URL 状态 | 界面 | ❌ 未修正 | — |
+| UI-03 | 错误消息 | 界面 | ❌ 未修正 | — |
+| DOC-01 | 004 行数记录 | 低 | ❌ 未修正 | 行数从 114→142，差距更大 |
+| DOC-02 | 005 字段顺序 | 低 | ❌ 未修正 | — |
+| DOC-03 | Role 记录 | 低 | ❌ 未修正 | — |
+
+---
+
+## 八、验证命令
+
+修复完成后应运行以下命令确保零错误：
+
+```bash
+npm run lint
+npx tsc --noEmit
+npm run test:unit -- action-state
+npx prettier --check "src/shared/types/**/*.ts" "src/modules/questions/actions.ts"
+```
+
+---
+
+> 报告生成人：AI Agent（GLM-5.2）
+> 核查方法：v1 对比审查 + 架构图比对 + 技能规则匹配
+> 版本：v2.0