300 lines
8.4 KiB
Markdown
300 lines
8.4 KiB
Markdown
# 可打印教学设计生成器设计方案
|
||
|
||
## 1. 建设目标
|
||
|
||
在现有 Vue 3 + TypeScript + Vite 项目中建设一个纯前端教学设计生成网站。用户一次上传多份 Markdown 教案后，网站将其解析为一整册可编辑、可打印的 A4 教学设计，并支持调整课次顺序、自动暂存和分别导出修改后的 Markdown 文件。
|
||
|
||
所有文件均在浏览器本地处理，不上传到服务器。
|
||
|
||
## 2. 输入材料与兼容范围
|
||
|
||
主要输入为 `data` 目录下的编号 Markdown 教案：
|
||
|
||
- `data/Web/1.md` 至 `data/Web/18.md`
|
||
- `data/Python/1.md` 至 `data/Python/18.md`
|
||
- `data/C#/1.md` 至 `data/C#/19.md`
|
||
|
||
标准教案通常包含：
|
||
|
||
1. 一级标题
|
||
2. 基本信息表
|
||
3. `## 教学过程`
|
||
4. 教学过程五列表格
|
||
5. `## 板书设计`
|
||
6. `## 教学成效与反思`
|
||
7. 教学成效与反思表
|
||
|
||
部分 C# 教案缺少板书、教学过程或反思章节。系统必须尽量解析这些文件，不因局部缺失拒绝整批导入。
|
||
|
||
## 3. 核心产品决策
|
||
|
||
- 采用左侧课次导航、右侧 A4 页面直接编辑的工作区。
|
||
- 上传后按文件名中的数字自然排序。
|
||
- 左侧列表支持拖拽调整课次顺序。
|
||
- 整册包含一张封面，不生成目录。
|
||
- 封面可编辑课程名称和教师姓名。
|
||
- 每份教案在打印时独立起页。
|
||
- 板书设计保留在教案中并参与打印。
|
||
- 编辑结果自动暂存在浏览器本地。
|
||
- 修改后的 Markdown 按原文件分别生成，并打包为 ZIP 下载。
|
||
- 格式不完整的文件仍然导入，缺失区域留空并显示警告。
|
||
|
||
## 4. 技术方案
|
||
|
||
采用结构化解析器和统一教案数据模型，而不是直接编辑 Markdown DOM。
|
||
|
||
技术栈：
|
||
|
||
- Vue 3
|
||
- TypeScript
|
||
- Vite
|
||
- 浏览器 File API
|
||
- 浏览器打印 API
|
||
- `localStorage` 或等价浏览器本地存储
|
||
- 用于生成 ZIP 的轻量前端库
|
||
|
||
系统不依赖后端、数据库或外部文件服务。
|
||
|
||
## 5. 系统架构
|
||
|
||
### 5.1 MarkdownParser
|
||
|
||
负责把单个 Markdown 文件解析为统一的 `TeachingDesign` 对象。
|
||
|
||
职责：
|
||
|
||
- 识别一级标题及课题名称。
|
||
- 解析基本信息表。
|
||
- 拆分知识目标、技能目标和素养目标。
|
||
- 拆分重点和难点。
|
||
- 解析教学过程表及每个教学环节的时间。
|
||
- 提取板书设计代码块或正文。
|
||
- 解析教学成效和教学反思。
|
||
- 保存无法归类的附加内容。
|
||
- 生成不阻断导入的解析警告。
|
||
|
||
### 5.2 TeachingDesign 数据模型
|
||
|
||
每个教案包含：
|
||
|
||
- 唯一标识
|
||
- 原文件名
|
||
- 当前排序位置
|
||
- 标题
|
||
- 课题
|
||
- 课时
|
||
- 知识目标
|
||
- 技能目标
|
||
- 素养目标
|
||
- 教学重点
|
||
- 教学难点
|
||
- 教学资源准备
|
||
- 教学过程环节数组
|
||
- 板书设计
|
||
- 教学成效
|
||
- 教学反思
|
||
- 附加内容
|
||
- 解析警告数组
|
||
|
||
每个教学环节包含：
|
||
|
||
- 教学环节名称
|
||
- 时间
|
||
- 教学内容
|
||
- 教师活动
|
||
- 学生活动
|
||
- 设计意图
|
||
|
||
### 5.3 Workspace
|
||
|
||
工作区由固定工具栏、课次侧栏和 A4 编辑区组成。
|
||
|
||
工具栏提供：
|
||
|
||
- 上传或追加 Markdown
|
||
- 打印整册
|
||
- 导出 Markdown ZIP
|
||
- 清空当前整册
|
||
|
||
课次侧栏提供：
|
||
|
||
- 封面入口
|
||
- 课次编号和课题摘要
|
||
- 拖拽排序
|
||
- 当前选中状态
|
||
- 每课解析警告状态
|
||
|
||
### 5.4 A4Editor
|
||
|
||
右侧仅展示封面或当前选中的一份教案。
|
||
|
||
编辑方式：
|
||
|
||
- 表格字段在 A4 页面内直接编辑。
|
||
- 教学过程支持增删环节。
|
||
- 板书设计使用适合多行文本的编辑区域。
|
||
- 缺失字段显示空白可编辑区域。
|
||
- 编辑状态只在屏幕上可见，打印时隐藏。
|
||
|
||
页面宽度按 A4 比例显示，并允许根据浏览器宽度缩放预览。
|
||
|
||
### 5.5 PrintBook
|
||
|
||
打印时渲染完整整册，而不是只打印当前选中教案。
|
||
|
||
规则：
|
||
|
||
- 第一页为封面。
|
||
- 每份教案从新页开始。
|
||
- 隐藏工具栏、侧栏、按钮、拖拽控件、警告和编辑边框。
|
||
- A4 页面使用统一页边距和中文字体栈。
|
||
- 教学过程表允许跨页。
|
||
- 跨页后重复教学过程表头。
|
||
- 单个教学环节行尽量避免拆分。
|
||
- 板书和反思标题避免与正文分离。
|
||
|
||
### 5.6 Storage
|
||
|
||
系统在内容、顺序或封面信息变化后自动暂存。
|
||
|
||
暂存内容包括：
|
||
|
||
- 封面课程名称
|
||
- 教师姓名
|
||
- 全部教案结构化数据
|
||
- 当前课次顺序
|
||
- 当前选中页面
|
||
|
||
重新打开页面时提示恢复最近一次未清空的整册。存储失败不得中断编辑。
|
||
|
||
### 5.7 MarkdownExporter
|
||
|
||
导出器把当前结构化数据重新生成规范 Markdown。
|
||
|
||
导出规则：
|
||
|
||
- 每份教案保留原文件名。
|
||
- ZIP 内文件顺序通过文件名和当前排序清单体现。
|
||
- 输出统一使用标准标题、基本信息表、教学过程表、板书设计和反思表结构。
|
||
- 保留加粗、行内代码、列表、换行和代码块等 Markdown 内容。
|
||
- 附加内容放在明确的附加章节，避免导入时无法识别的正文丢失。
|
||
- 不保证原文件空格、换行和表格对齐符完全不变。
|
||
|
||
## 6. 解析兼容规则
|
||
|
||
解析器需要兼容：
|
||
|
||
- LF 和 CRLF 换行。
|
||
- 全角和半角冒号。
|
||
- `1课时（40分钟）` 与 `1课时(40分钟)`。
|
||
- 不同长度的 Markdown 表格分隔符。
|
||
- `<br>`、`<br/>` 和 `<br />`。
|
||
- 带序号或不带序号的教学环节。
|
||
- `（6分钟）`、`(6分钟)` 等时间写法。
|
||
- 板书使用围栏代码块或普通段落。
|
||
- 缺失章节、空单元格和额外正文。
|
||
|
||
解析失败分为字段级警告，不将单个字段问题升级为整份文件失败。只有无法读取文件文本时，才把该文件标记为导入失败。
|
||
|
||
## 7. 用户流程
|
||
|
||
1. 用户在初始页拖入或选择多份 `.md` 文件。
|
||
2. 系统自然排序并批量解析文件。
|
||
3. 系统显示工作区及解析结果摘要。
|
||
4. 用户编辑封面课程名称和教师姓名。
|
||
5. 用户在左侧切换课次，直接编辑右侧 A4 页面。
|
||
6. 用户通过拖拽调整课次顺序。
|
||
7. 系统在每次修改后自动暂存。
|
||
8. 用户点击打印整册，浏览器打开打印界面。
|
||
9. 用户点击导出 Markdown，下载包含所有修改后文件的 ZIP。
|
||
|
||
用户可以追加文件。文件名冲突时必须提示用户选择替换或保留两份，不能静默覆盖。
|
||
|
||
## 8. 错误与状态反馈
|
||
|
||
系统应提供以下反馈：
|
||
|
||
- 文件格式不支持。
|
||
- 文件读取失败。
|
||
- 单份教案缺少章节或字段。
|
||
- 教学过程表列数异常。
|
||
- 暂存失败或空间不足。
|
||
- ZIP 生成失败。
|
||
- 当前没有可打印或可导出的教案。
|
||
|
||
错误提示不得清除已经成功解析或编辑的内容。
|
||
|
||
## 9. 视觉设计
|
||
|
||
整体采用克制的教学文档工具风格：
|
||
|
||
- 页面背景使用浅灰色，A4 纸张使用白色和轻阴影。
|
||
- 主色使用稳重的绿色，用于当前课次、按钮和章节标识。
|
||
- 正文优先使用系统中文无衬线字体。
|
||
- A4 标题可使用中文宋体类字体栈增强正式文档感。
|
||
- 编辑边框、警告和辅助提示只在屏幕模式显示。
|
||
- 移动端允许浏览和轻量编辑，但主要使用场景为桌面浏览器。
|
||
|
||
## 10. 测试策略
|
||
|
||
### 10.1 单元测试
|
||
|
||
覆盖：
|
||
|
||
- 数字文件名自然排序。
|
||
- 标准 Web 教案完整解析。
|
||
- Python 教案的半角标点和 CRLF 解析。
|
||
- C# 教案缺失章节时的容错处理。
|
||
- 教学目标和重难点拆分。
|
||
- 教学环节时间提取。
|
||
- Markdown 重新生成。
|
||
- 暂存序列化和恢复。
|
||
|
||
### 10.2 组件测试
|
||
|
||
覆盖：
|
||
|
||
- 批量上传。
|
||
- 课次切换。
|
||
- 页面内字段编辑。
|
||
- 教学环节增删。
|
||
- 拖拽排序。
|
||
- 警告展示。
|
||
- 封面编辑。
|
||
- ZIP 导出触发。
|
||
|
||
### 10.3 打印验证
|
||
|
||
使用浏览器打印预览人工检查：
|
||
|
||
- 封面独立一页。
|
||
- 每份教案独立起页。
|
||
- 控件全部隐藏。
|
||
- 长教学过程表跨页正常。
|
||
- 表头重复。
|
||
- 中文、代码和板书不溢出。
|
||
|
||
### 10.4 语料回归
|
||
|
||
批量导入仓库内全部编号教案，确认：
|
||
|
||
- Web 18 份均可解析。
|
||
- Python 18 份均可解析。
|
||
- C# 19 份均不会导致整批中断。
|
||
- 缺失章节会产生警告和空白编辑区。
|
||
- 导出后文件可再次导入。
|
||
|
||
## 11. 验收标准
|
||
|
||
- 可一次上传至少 20 份 Markdown 文件。
|
||
- 文件按数字自然排序，并可拖拽调整。
|
||
- 每份教案可在 A4 页面中直接编辑。
|
||
- 标准教案主要字段均能正确解析。
|
||
- 不完整教案可容错导入并显示警告。
|
||
- 板书设计可编辑且参与打印。
|
||
- 封面包含可编辑的课程名称和教师姓名。
|
||
- 自动暂存可恢复。
|
||
- 打印整册包含封面，且每份教案独立起页。
|
||
- 可下载包含全部修改后 Markdown 的 ZIP。
|
||
- 全部处理在浏览器本地完成。
|