xiner/NextEdu
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity
Files
7e320d78c10c1c0253d3bab20693087bcb0e9f16
NextEdu/docs/architecture/audit/lesson-preparation-audit-report-v2.md
SpecialX 97e59b95a1 refactor(lesson-preparation): V2 审计深度修复 — Server Actions i18n + 错误码模式 + 类型断言清零 + a11y 深度修复 + Tracker 埋点接入 
V2-1: 12 个 Server Action 通过 getTranslations 翻译错误消息；Service/DataAccess 层抛出错误码异常（PublishServiceError/LessonPlanDataError），Actions 层通过 PUBLISH_ERROR_KEY_MAP 翻译为 i18n 消息
V2-2: SYSTEM_TEMPLATES name/title 改为 i18n 键，createLessonPlan 接受 translateTitle 函数在服务端翻译后存储到 DB
V2-3: 8 处 as unknown as 断言替换为显式类型映射函数（mapRowToLessonPlan/mapRowToListItem/mapRowToTemplate/mapRowToVersion）+ 类型守卫（isLessonPlanStatus/isTemplateType/isTemplateScope）
V2-4: MiniMap nodeColor 复用 lib/node-summary.ts 的 getNodeColor
V2-5: a11y 深度修复 — lesson-plan-filters/exercise-block/inline-question-editor 的 select 添加 label htmlFor 关联；exercise-block 题目列表改为 ul/li；node-editor 画布添加 role=application + 键盘导航配置
V2-6: Tracker 埋点接入 — 新增 useLessonPlanTrackerSafe hook，在 create/save/publish/revert/duplicate/archive 6 处调用 tracker.track

同步更新架构图 004 和 005 文档
2026-06-22 18:45:35 +08:00

138 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 备课模块审计报告 V2（第二轮深度检查）
> 审查日期：2026-06-22（第二轮）
> 审查范围：基于 V1 审计报告的修复成果，对全模块进行深度复查
> 前置状态：V1 审计报告中的 P0-1/P0-2/P0-3/P1-2/P1-3/P1-4/P1-5/P1-6/P1-7/P1-8/P2-1（部分）/P2-4（接口）已完成
> 本次目的：识别 V1 修复中遗留的未完成项，继续全量完整完成
---
## 一、V1 修复成果确认
| 项 | 状态 | 证据 |
|----|------|------|
| P0-1 跨模块直查 | ✅ 已完成 | publish-service.ts 使用 `addExamQuestions`/`getStudentIdsByClassIds` 跨模块接口 |
| P0-2 i18n 接入 | ⚠️ 部分完成 | 消息文件、request.ts、组件 useTranslations 已接入；但 actions 错误消息、constants SYSTEM_TEMPLATES 仍硬编码 |
| P0-3 DataScope | ✅ 已完成 | buildScopeCondition 按 scope 类型精确过滤 |
| P1-1 类型安全 | ⚠️ 部分完成 | `as never` 已修复；但 8 处 `as unknown as` 断言未修复 |
| P1-2 错误边界 | ✅ 已完成 | LessonPlanErrorBoundary 包裹 NodeEditPanel |
| P1-3 骨架屏 | ✅ 已完成 | 4 个 Skeleton 组件已创建 |
| P1-4 阻塞式 UI | ✅ 已完成 | alert/confirm/window.location.reload 全部替换 |
| P1-5 多实例 | ✅ 已完成 | LessonPlanProvider + Context 注入 |
| P1-6 纯函数抽取 | ⚠️ 部分完成 | lib/ 三个文件已抽取；但 node-editor.tsx MiniMap nodeColor 仍内联颜色映射 |
| P1-7 角色配置 | ✅ 已完成 | 4 个角色配置 + ROLE_CONFIGS 注册表 |
| P1-8 Block 注册表 | ✅ 已完成 | BLOCK_REGISTRY 配置驱动渲染 |
| P2-1 a11y | ⚠️ 部分完成 | 5 个对话框 role/aria-label 已添加；但 select 无 label、题目列表非 ul/li、画布无键盘导航 |
| P2-4 监控埋点 | ⚠️ 部分完成 | LessonPlanTracker 接口已定义；但未在关键操作处调用 |
---
## 二、V2 新发现的问题
### V2-1：actions 错误消息仍硬编码中文（P0-2 遗留）
| 位置 | 问题 | 违反规则 |
|------|------|----------|
| [actions.ts:53](file:///e:/Desktop/CICD/src/modules/lesson-preparation/actions.ts#L53) | `"获取课案列表失败"` | i18n 规范 |
| [actions.ts:66](file:///e:/Desktop/CICD/src/modules/lesson-preparation/actions.ts#L66) | `"课案不存在或无权访问"` | 同上 |
| [actions.ts:71](file:///e:/Desktop/CICD/src/modules/lesson-preparation/actions.ts#L71) | `"获取课案失败"` | 同上 |
| [actions.ts:102](file:///e:/Desktop/CICD/src/modules/lesson-preparation/actions.ts#L102) | `"创建课案失败"` | 同上 |
| [actions.ts:125](file:///e:/Desktop/CICD/src/modules/lesson-preparation/actions.ts#L125) | `"保存失败"` | 同上 |
| [actions.ts:152](file:///e:/Desktop/CICD/src/modules/lesson-preparation/actions.ts#L152) | `"保存版本失败"` | 同上 |
| [actions.ts:171](file:///e:/Desktop/CICD/src/modules/lesson-preparation/actions.ts#L171) | `"获取版本失败"` | 同上 |
| [actions.ts:190](file:///e:/Desktop/CICD/src/modules/lesson-preparation/actions.ts#L190) | `"版本不存在或无权操作"` | 同上 |
| [actions.ts:196](file:///e:/Desktop/CICD/src/modules/lesson-preparation/actions.ts#L196) | `"回退失败"` | 同上 |
| [actions.ts:212](file:///e:/Desktop/CICD/src/modules/lesson-preparation/actions.ts#L212) | `"删除失败"` | 同上 |
| [actions.ts:228](file:///e:/Desktop/CICD/src/modules/lesson-preparation/actions.ts#L228) | `"复制失败"` | 同上 |
| [actions.ts:245](file:///e:/Desktop/CICD/src/modules/lesson-preparation/actions.ts#L245) | `"获取模板失败"` | 同上 |
| [actions.ts:267](file:///e:/Desktop/CICD/src/modules/lesson-preparation/actions.ts#L267) | `"保存模板失败"` | 同上 |
| [actions.ts:282](file:///e:/Desktop/CICD/src/modules/lesson-preparation/actions.ts#L282) | `"删除模板失败"` | 同上 |
| [actions-ai.ts:29](file:///e:/Desktop/CICD/src/modules/lesson-preparation/actions-ai.ts#L29) | `"AI 推荐失败，请检查 AI Provider 配置"` | 同上 |
| [actions-kp.ts:37](file:///e:/Desktop/CICD/src/modules/lesson-preparation/actions-kp.ts#L37) | `"加载知识点失败"` | 同上 |
| [actions-publish.ts:48](file:///e:/Desktop/CICD/src/modules/lesson-preparation/actions-publish.ts#L48) | `"发布失败"` | 同上 |
| [publish-service.ts:39,55,60,62,64,70,103,128](file:///e:/Desktop/CICD/src/modules/lesson-preparation/publish-service.ts) | 8 处 `throw new Error("中文")` | 同上 |
| [data-access.ts:183,243](file:///e:/Desktop/CICD/src/modules/lesson-preparation/data-access.ts) | `"模板不存在"`/`"课案不存在或无权访问"` | 同上 |
| [data-access-templates.ts:61](file:///e:/Desktop/CICD/src/modules/lesson-preparation/data-access-templates.ts#L61) | `"课案不存在或无权访问"` | 同上 |
**修复方案**：Server Actions 使用 `getTranslations("lessonPreparation")` 获取翻译；publish-service/data-access 的 `throw new Error` 改为抛出错误码（如 `LESSON_PLAN_NOT_FOUND`），由 actions 层捕获并翻译。
### V2-2：constants.ts SYSTEM_TEMPLATES 仍硬编码中文（P0-2 遗留）
| 位置 | 问题 |
|------|------|
| [constants.ts:46-106](file:///e:/Desktop/CICD/src/modules/lesson-preparation/constants.ts#L46-L106) | SYSTEM_TEMPLATES 的 `name`/`title`/`hint` 字段硬编码中文（"常规课"/"教学目标"/"明确本课的知识、能力、情感目标"等） |
**修复方案**：将 SYSTEM_TEMPLATES 的 `name`/`title`/`hint` 改为 i18n 键（如 `template.names.tpl_regular`/`blockType.objective`/`template.hints.tpl_regular.objective`），在 buildInitialContent 调用时由 actions 层传入翻译后的标题。
### V2-3：8 处 `as unknown as` 断言未修复（P1-1 遗留）
| 位置 | 代码 |
|------|------|
| [data-access.ts:146](file:///e:/Desktop/CICD/src/modules/lesson-preparation/data-access.ts#L146) | `rows as unknown as LessonPlanListItem[]` |
| [data-access.ts:166](file:///e:/Desktop/CICD/src/modules/lesson-preparation/data-access.ts#L166) | `row as unknown as LessonPlan` |
| [data-access.ts:288](file:///e:/Desktop/CICD/src/modules/lesson-preparation/data-access.ts#L288) | `rows[0] as unknown as LessonPlanTemplate` |
| [data-access-versions.ts:30](file:///e:/Desktop/CICD/src/modules/lesson-preparation/data-access-versions.ts#L30) | `rows as unknown as LessonPlanVersion[]` |
| [data-access-knowledge.ts:25](file:///e:/Desktop/CICD/src/modules/lesson-preparation/data-access-knowledge.ts#L25) | `rows.filter(...) as unknown as LessonPlanListItem[]` |
| [data-access-knowledge.ts:43](file:///e:/Desktop/CICD/src/modules/lesson-preparation/data-access-knowledge.ts#L43) | 同上 |
| [data-access-templates.ts:40](file:///e:/Desktop/CICD/src/modules/lesson-preparation/data-access-templates.ts#L40) | `personalRows as unknown as LessonPlanTemplate[]` |
| [publish-service.ts:40](file:///e:/Desktop/CICD/src/modules/lesson-preparation/publish-service.ts#L40) | `rows[0] as unknown as {...}` |
**修复方案**：使用 Drizzle 的 `inferSelect` 类型推导，或定义显式类型映射函数替代断言。
### V2-4：node-editor.tsx MiniMap nodeColor 仍内联颜色映射（P1-6 遗留）
| 位置 | 问题 |
|------|------|
| [node-editor.tsx:126-144](file:///e:/Desktop/CICD/src/modules/lesson-preparation/components/node-editor.tsx#L126-L144) | MiniMap nodeColor 内联 colors 对象，未使用 lib/node-summary.ts 的 NODE_COLORS/getNodeColor |
**修复方案**：改为 `import { getNodeColor } from "../lib/node-summary"` 并在 nodeColor 回调中调用。
### V2-5：a11y 遗留问题（P2-1 遗留）
| 位置 | 问题 | 违反规则 |
|------|------|----------|
| [lesson-plan-filters.tsx:40-51](file:///e:/Desktop/CICD/src/modules/lesson-preparation/components/lesson-plan-filters.tsx#L40-L51) | 2 个 `<select>` 无 `<label>` 关联 | "语义化标签、ARIA 属性" |
| [exercise-block.tsx:56-65](file:///e:/Desktop/CICD/src/modules/lesson-preparation/components/blocks/exercise-block.tsx#L56-L65) | purpose `<select>` 无 `<label>` | 同上 |
| [exercise-block.tsx:72-92](file:///e:/Desktop/CICD/src/modules/lesson-preparation/components/blocks/exercise-block.tsx#L72-L92) | 题目列表用 `<div>` 而非 `<ul>/<li>` | 语义化标签 |
| [node-editor.tsx](file:///e:/Desktop/CICD/src/modules/lesson-preparation/components/node-editor.tsx) | React Flow 画布无键盘导航支持（Tab/方向键无法聚焦/移动节点） | 键盘导航 |
| [inline-question-editor.tsx:83-95](file:///e:/Desktop/CICD/src/modules/lesson-preparation/components/inline-question-editor.tsx#L83-L95) | type `<select>` 有 `<label>` 但未通过 htmlFor/id 关联 | label 关联 |
**修复方案**：为所有 `<select>` 添加 `id` 和 `<label htmlFor>`；题目列表改为 `<ul>/<li>`；node-editor 添加键盘事件处理（方向键移动节点）。
### V2-6：LessonPlanTracker 未在关键操作处调用（P2-4 遗留）
| 位置 | 问题 |
|------|------|
| [providers/lesson-plan-provider.tsx](file:///e:/Desktop/CICD/src/modules/lesson-preparation/providers/lesson-plan-provider.tsx) | LessonPlanTracker 接口已定义，但全模块无 `tracker.track()` 调用 |
**修复方案**：在以下关键操作处调用 tracker：
- createLessonPlanAction（create）
- updateLessonPlanAction（save）
- publishLessonPlanHomeworkAction（publish）
- revertLessonPlanVersionAction（revert）
- duplicateLessonPlanAction（duplicate）
- deleteLessonPlanAction（archive）
由于 actions 是 server-side，tracker 应在客户端组件中调用（如 lesson-plan-editor 的 handleManualSave、lesson-plan-card 的 handleArchive/handleDuplicate、publish-homework-dialog 的 handlePublish、version-history-drawer 的 handleRevert）。
---
## 三、V2 改进优先级
| # | 问题 | 优先级 | 改进方向 |
|---|------|--------|----------|
| V2-1 | actions 错误消息硬编码 | P0 | Server Actions 使用 getTranslations；publish-service/data-access 抛错误码 |
| V2-2 | SYSTEM_TEMPLATES 硬编码 | P0 | 改为 i18n 键，actions 层传入翻译后标题 |
| V2-3 | 8 处 `as unknown as` 断言 | P1 | 使用 Drizzle inferSelect 或显式映射函数 |
| V2-4 | MiniMap nodeColor 内联 | P1 | 使用 lib/node-summary.getNodeColor |
| V2-5 | a11y 遗留 | P2 | select 加 label、题目列表改 ul/li、画布键盘导航 |
| V2-6 | Tracker 未调用 | P2 | 6 个关键操作处调用 tracker.track |
---
## 四、架构图同步说明
本次 V2 修复完成后需同步更新：
- `docs/architecture/004_architecture_impact_map.md` §2.27（标注 V2 修复完成）
- `docs/architecture/005_architecture_data.json` modules.lesson_preparation.auditFixes（新增 V2-1~V2-6）
Reference in New Issue View Git Blame Copy Permalink