# 可打印教学设计生成器设计方案
## 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 表格分隔符。
- `
`、`
` 和 `
`。
- 带序号或不带序号的教学环节。
- `（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。
- 全部处理在浏览器本地完成。