# 🏗️ PPT 设计工程手册 v3.0

> 华平小超人 Scratch 课件 · 全流程设计系统
> 
> 融合：dom-to-pptx 实践经验 + ppt-agent-skill 设计体系 + 教研实战迭代

---

## 目录

1. [流程管线](#一流程管线)
2. [七环节课程结构](#二七环节课程结构)
3. [Bento Grid 布局系统](#三bento-grid-布局系统)
4. [卡片内容类型](#四卡片内容类型)
5. [视觉设计系统](#五视觉设计系统)
6. [风格决策矩阵](#六风格决策矩阵)
7. [排版铁律](#七排版铁律)
8. [HTML 编写规范](#八html-编写规范)
9. [技术路线](#九技术路线)
10. [质量检测清单](#十质量检测清单)
11. [交付标准](#十一交付标准)

---

## 一、流程管线

### 标准流程（适用于新课开发）

```
Step 1  需求分析    明确课程主题、学生水平、知识链位置
  ↓
Step 2  大纲策划    7环节结构 + 页数分配 + 金字塔原理
  ↓
Step 3  内容策划    每页：论点 + 卡片类型 + 布局选择 + 内容文本
  ↓                     ↑ 建议用户确认后再往下 ↑
Step 4  风格决策    根据课程主题选配色方案和视觉风格
  ↓
Step 5  逐页设计    HTML 设计稿（1920×1080），按 Part 分批
  ↓
Step 6  质量审计    自检清单 + qa_audit.py 脚本
  ↓
Step 7  转换导出    dom-to-pptx → PPTX → 文件站交付
  ↓
Step 8  预览部署    Cloudflare Pages 预览站
```

### 轻量流程（适用于课件迭代）

```
已有大纲 → 跳过 Step 1-2
已有策划稿 → 跳到 Step 5 直接设计
小修改 → 直接改 HTML + 重新导出
```

---

## 二、七环节课程结构

> 替代旧六关制。每节课 18-25 页。

### 环节总览

| # | 环节 | 英文 | 定位 | 页数 | 核心任务 |
|---|------|------|------|------|---------|
| 1 | 🎯 课前预热 | Warm-up | 激活兴趣、场景代入 | 2-3p | 封面 + 互动问答卡 |
| 2 | 🔄 温故知新 | Review | 知识衔接、唤醒记忆 | 1-2p | 上节课要点回顾 + 过渡语 |
| 3 | 📖 故事导入 | Story | 情境驱动、问题提出 | 1-2p | 小超人故事 + 关键问题 |
| 4 | 🔍 项目分析 | Analysis | 拆解目标、功能认知 | 1-2p | 角色/背景/功能表 |
| 5 | 🛠 编程实践 | Practice | 核心教学、动手操作 | 8-12p | 新积木讲解 + Step by Step + 组装 + Bug |
| 6 | 🚀 扩展练习 | Extension | 分层挑战、创意发挥 | 1-2p | 三级挑战 + 自由创作 |
| 7 | 📚 总结回顾 | Summary | 知识固化、成果展示 | 3-4p | 知识总结 + 测验 + 展示 + 下课 |

### 各环节设计详解

#### 环节1：课前预热（2-3页）

**第1页 · 封面**
- 大号课程标题 + emoji 主题图标
- 副标题含"和小超人一起…"
- 品牌标签（Lx-xx）
- 角色视觉元素（小鸡🦖扫帚等）
- 暗色渐变背景，让标题突出

**第2-3页 · 互动暖场**
- 2-3张卡片并列
- 每张卡片：emoji + 问题 + 引导说明
- 问题设计方向：生活经验 → 项目联想 → 技术工具
- 示例："你玩过保护小鸡的游戏吗？" / "翼龙怎么飞的？" / "键盘能控制角色吗？"

#### 环节2：温故知新（1-2页）

**格式**：5宫格卡片（上节课学过的知识）

```
┌─────┬─────┬─────┬─────┬─────┐
│ emoji│ emoji│ emoji│ emoji│ emoji│
│ 积木名│ 积木名│ 积木名│ 积木名│ 概念  │
│ 作用  │ 作用  │ 作用  │ 作用  │ 说明  │
└─────┴─────┴─────┴─────┴─────┘
```

底部过渡语："今天，我们要把所有本领组合起来——做一款完整的游戏！"

#### 环节3：故事导入（1-2页）

- 小超人遇到一个场景/问题
- 3-4段递进式叙事（每段1-2句）
- 右/下侧配场景示意
- 关键问题卡片："你能…？"
- 语言风格：口语化、带emoji、有代入感

#### 环节4：项目分析（1-2页）

**经典布局**：左视频框 + 右功能表

```
┌──────────────────┬──────────────────┐
│                  │ 🌊 背景：…       │
│   🎬 运行效果    │ 🐤 角色1：…      │
│   （视频占位）   │ 🦖 角色2：…      │
│                  │ 🧹 角色3：…      │
│                  │ 🎵 声音：…       │
│                  ├──────────────────┤
│                  │ 交互规则：…       │
└──────────────────┴──────────────────┘
```

#### 环节5：编程实践（8-12页）

**子结构**：

```
新装备解锁（1p）：3种新积木概览卡片 → 位置/作用/颜色/比喻
积木详解（1-2p）：每个新积木单独讲解 → 对比旧积木 → 为什么用这个
Step 1~5（5p）：每个 Step 用 💭→🧩→🛠→🤔 四步法
整体组装（1p）：三个角色脚本并列展示 + 交互关系箭头
Bug急救站（1p）：3-5个常见Bug + 排查方案
```

**💭🧩🛠🤔 讲解法**（每个Step的核心）：

```
💭 问题："小鸡怎么走来走去？"
🧩 积木："移动3步"（蓝色运动模块）→ 让角色走起来
🛠 动手：拖出「移动3步+当绿旗」→ 点绿旗试一下
🤔 发现："只走了一步就停了！" → 引出「重复执行」
    （循环到下一个积木）
```

#### 环节6：扩展练习（1-2页）

**三级挑战卡片**：

```
🌟 初级：调参数（速度/数量）
🌟🌟 中级：加元素（多一个角色）
🌟🌟🌟 高级：加系统（生命值/计分）
🎨 自由创作
```

#### 环节7：总结回顾（3-4页）

- **知识总结页**：积木全家福（6宫格表格）→ 积木名 | 模块 | 作用
- **随堂测验**：5道题，Q&A格式排列
- **展示关**：填空式脚本（8-10个空）
- **下课页**：大标题 + 鼓励泡泡 + 品牌条

---

## 三、Bento Grid 布局系统

> 所有内容页使用 1200×580px 内容区（基于1920×1080画布）

### 画布参数

```
固定画布: 1920×1080px
标题区: x=60, y=80~120
内容区: x=80, y=210, w=1760, h=780
卡片间距: gap=20px (可调至24px)
卡片圆角: 16-28px（按页面风格）
卡片内边距: 20-36px
```

### 7种布局速查

| # | 布局名 | CSS Grid | 适用场景 |
|---|--------|----------|---------|
| 1 | **单一焦点** | `1fr / 1fr` | 1个核心论点、大数据展示、大标题 |
| 2 | **50/50 对称** | `1fr / 1fr 1fr` | 对比、并列概念、"VS"比较 |
| 3 | **非对称两栏** | `1fr / 2fr 1fr` | 主次关系、图文搭配（**最常用**） |
| 4 | **三栏等宽** | `1fr / repeat(3,1fr)` | 3个并列要素、积木对比 |
| 5 | **主次结合** | `1fr 1fr / 2fr 1fr` | 1核心+2辅助、层级关系（**信息丰富时首选**） |
| 6 | **顶部英雄式** | `auto 1fr / repeat(3,1fr)` | 总分结构、综述+子项（**总分时首选**） |
| 7 | **混合网格** | `repeat(3,1fr) / 1fr 1fr` | 6个异构块、高密度信息、积木全家福 |

### 布局决策矩阵

| 内容特征 | 推荐布局 | 卡片数 |
|---------|---------|-------|
| 1个核心论点/全屏数据 | 单一焦点 | 1 |
| 2个对比/并列 | 50/50 对称 | 2 |
| 主概念 + 补充说明 | 非对称两栏 | 2 |
| 3个并列要素 | 三栏等宽 | 3 |
| 1核心 + 2辅助 | 主次结合 | 3 |
| 综述 + 3-4子项 | 顶部英雄式 | 4-5 |
| 4-6个异构块 | 混合网格 | 4-6 |

### 课件场景映射

| 课件页面 | 推荐布局 |
|---------|---------|
| 封面 | 单一焦点（居中自由排版） |
| 互动暖场 | 三栏等宽（3个问答卡） |
| 温故知新 | 混合网格（5-6格知识卡） |
| 故事导入 | 非对称两栏（文+图） |
| 项目分析 | 非对称两栏（视频框+功能表） |
| 新积木概览 | 三栏等宽（3个积木卡） |
| 积木对比 | 三栏等宽 |
| Step讲解 | 50/50 对称或顶部英雄式（问题→积木→动手→发现） |
| 整体组装 | 三栏等宽（3角色脚本） |
| Bug急救 | 混合网格（5-6个bug卡） |
| 扩展挑战 | 三栏等宽（3级挑战） |
| 知识总结 | 混合网格（6宫格） |
| 随堂测验 | 单一焦点（列表式） |
| 展示关 | 单一焦点（填空模板） |
| 下课页 | 单一焦点（居中庆祝） |

---

## 四、卡片内容类型

### 6种卡片

| 类型 | 标识 | 结构要求 | 适用 |
|------|------|---------|------|
| **text** | 文本卡 | 标题(h3 18-20px) + 正文(13-14px) × 2段 | 概念解释、知识点 |
| **data** | 数据卡 | 核心数字(36-48px, accent色) + 单位 + 趋势 + 解读 | 对比数值、统计 |
| **list** | 列表卡 | 圆点(6-8px, accent色) + 4+条(每条约20字) | 步骤、要点罗列 |
| **tag_cloud** | 标签云 | flex-wrap容器 + 5+胶囊标签 | 技能标签、概念群 |
| **process** | 流程卡 | 圆形节点(32px) + 连线(真实div) + 每步标题+描述 | 步骤流程 |
| **highlight** | 高亮区 | 超大数字(64-80px, accent色) + 副标题 + 补充行 | 封面/重点页 |

### 卡片内容密度要求

- 每个内容页至少 **3张卡片**
- 用至少 **2种不同的card_type**
- 至少包含 **1个data或list卡片**
- 标题不超过15字，正文每段30-50字

---

## 五、视觉设计系统

### 色彩系统

| Token | 色值 | 用途 |
|-------|------|------|
| `--bg-primary` | 随环节变化 | 页面主背景 |
| `--accent-1` | `#FFD23F` | 主强调色（标题高亮/标签/步骤条） |
| `--accent-2` | `#4ECDC4` | 辅助色（卡片/边框/链接） |
| `--accent-3` | `#FF6B9D` | 活泼点缀（新积木/bug/展示） |
| `--accent-4` | `#FF8C42` | 警告/扩展 |
| `--accent-5` | `#1E88FF` | 品牌蓝（回顾/复习） |
| `--text-primary` | `#fff` 或 `#1A2B4B` | 主文字（随明/暗底） |
| `--text-secondary` | `rgba(255,255,255,.5)` | 次要文字 |
| `--card-bg` | `rgba(255,255,255,.04)` | 卡片背景 |
| `--card-border` | `rgba(255,255,255,.06)` | 卡片边框 |
| `--glass` | `rgba(255,255,255,.05)` + `blur(8px)` | 毛玻璃面板 |

### 各环节配色主题

| 环节 | 背景 | 标签色 | 氛围 |
|------|------|--------|------|
| 课前预热 | 深蓝渐变 `#0a0e27→#1a1f3a` | `#FF4757` 红 | 激动/好奇 |
| 温故知新 | 深蓝 `#0d1b2a→#1b2d3d` | `#1E88FF` 蓝 | 回忆/连接 |
| 故事导入 | 海蓝渐变 `#0f2027→#2c5364` | `#FF8C42` 橙 | 冒险/代入 |
| 项目分析 | 科技蓝 `#1a1a2e→#0f3460` | `#FF6B9D` 粉 | 探索/拆解 |
| 编程实践 | 紫黑/暗色系 | `#1A2B4B` 深蓝+黄 | 专注/动手 |
| 扩展练习 | 紫红渐变 `#1a1028→#2d1a3d` | `#FF8C42` 橙 | 创造/自由 |
| 总结回顾 | 深蓝 `#1a1a2e→#0f3460` | `#FFD23F` 金 | 收获/成就 |

### 页面元素组件库

#### 章节标签 (badge)

```css
.badge {
  display: inline-block;
  padding: 5px 16px;
  border-radius: 20px;
  font-size: 12px;
  font-weight: 600;
  letter-spacing: 1px;
}
```
位置：页面左上 `top:40px; left:80px`

#### 卡片

```css
.card {
  background: rgba(255,255,255,.04);
  border: 1px solid rgba(255,255,255,.06);
  border-radius: 20px;
  padding: 24px;
}
```

#### 步骤胶囊

```css
.step-badge {
  display: inline-block;
  background: #FFD23F;
  color: #1A2B4B;
  padding: 4px 16px;
  border-radius: 20px;
  font-size: 14px;
  font-weight: 700;
}
```

#### 页脚

```
左侧: 华平小超人 · Lx-xx 课程名
右侧: 页码/总页数 · 环节名
字体: 12px, color: rgba(255,255,255,.25)
位置: 页面底部 bottom:20px
```

### 字体

| 用途 | 字体 | 备选 |
|------|------|------|
| 标题 | Noto Sans SC 700/900 | — |
| 正文 | Noto Sans SC 400 | system-ui |
| 代码/积木 | Noto Sans SC, monospace | Courier New |
| 特殊装饰 | 系统 emoji | — |

字体栈：`'Noto Sans SC', system-ui, -apple-system, sans-serif`

---

## 六、风格决策矩阵

> 根据课程主题选择视觉风格

### 5大风格板块

| 板块 | 风格ID | 特征 | 适用课程 |
|------|--------|------|---------|
| **暗色专业** | dark_tech / luxury_purple / cyberpunk_neon | 深色底+霓虹亮色 | 综合实战课、高年级 |
| **浅色高级** | blue_white / fresh_green / minimal_gray | 白/浅底+蓝色系 | 常规教学课（**推荐**） |
| **活力鲜明** | vibrant_rainbow / kindergarten_pop / candy_pastel | 彩色渐变+活泼 | 低龄/入门课 |
| **东方文化** | royal_red / sakura_wabi / ink_jade | 中国传统配色 | 文化主题课 |
| **自然复古** | botanic_forest / safari_savanna / retro_70s | 自然色+暖调 | 户外/动物主题 |

### 快速选择

| 课程类型 | 推荐风格 | 理由 |
|---------|---------|------|
| L1 入门（1-3课） | kindergarten_pop / candy_pastel | 低龄友好，彩色吸引注意力 |
| L1 进阶（4-8课） | fresh_green / blue_white | 逐渐成熟，清爽不干扰 |
| L1 综合（9-11课） | dark_tech / luxury_purple | 综合实战，有"游戏感" |
| L2+ 全部 | blue_white / minimal_gray | 成熟稳定，内容优先 |

---

## 七、排版铁律

### 字号阶梯（7级）

| 层级 | 用途 | 字号 | 字重 |
|------|------|------|------|
| H0 | 封面大标题 | 72-78px | 900 |
| H1 | 页面主标题 | 36-42px | 700 |
| H2 | 区块标题 | 22-28px | 700 |
| H3 | 卡片标题 | 18-20px | 600 |
| Body | 正文 | 15-17px | 400 |
| Caption | 辅助说明 | 13-14px | 400 |
| Fine | 页脚/标签 | 11-12px | 400 |

### 间距规则

- 标题区距顶部：80-120px
- 内容区间距标题：90-130px
- 卡片间水平间距：20-24px
- 卡片内边距：20-36px（大卡=36, 小卡=20）
- 行高：body 1.7-1.8, caption 1.5

### 视觉节奏

- **密度交替**：高密度页（4-6卡）后跟低密度页（1-2卡/章节封面），连续不超过3页高密度
- **色彩递进**：环节1-3 用冷色调，环节4-5 加深，环节6-7 暖色回归
- **封面-结尾呼应**：封面和下课页使用相同背景基调

### 审美国际线

- tabular-nums（数字等宽对齐）
- 正文行宽不超过 40em
- 卡片圆角统一（全页一致）
- emoji 作为视觉锚点，不滥用（每页 3-8 个）

---

## 八、HTML 编写规范

### 核心原则

1. **全部内联样式**：`style="..."` 内写完，不依赖外部CSS
2. **绝对定位优先**：`position:absolute; left:XXpx; top:XXpx;`
3. **1920×1080 固定画布**：`.slide` 容器固定尺寸
4. **无色值硬编码**：尽量用色值变量（当前实现中用颜色常量传递）
5. **纯静态 HTML**：无 JavaScript 逻辑
6. **禁止伪元素装饰**：`::before`/`::after` 不用于视觉元素，dom-to-pptx 转换会丢失
7. **禁止 conic-gradient**：dom-to-pptx 不支持
8. **禁止 CSS border 三角形**：用内联 SVG 替代

### 页面骨架模板

```html
<div class="slide" style="background:linear-gradient(…);width:1920px;height:1080px;overflow:hidden;position:relative">
  <!-- 光晕装饰层 -->
  <div style="position:absolute;inset:0;overflow:hidden">
    <div style="position:absolute;top:-80px;right:-120px;width:600px;height:600px;border-radius:50%;background:radial-gradient(circle,rgba(X,X,X,.12),transparent 70%)"></div>
  </div>
  
  <!-- 章节标签 -->
  <div style="position:absolute;top:40px;left:80px;z-index:10">
    <span style="…badge样式…">🎯 课前预热</span>
  </div>
  
  <!-- 标题 -->
  <h2 style="position:absolute;top:120px;left:80px;z-index:10;font-size:38px;font-weight:700;color:#fff">标题</h2>
  
  <!-- 内容区 -->
  <div style="position:absolute;top:210px;left:80px;right:80px;z-index:10;display:flex;gap:24px">
    <!-- 卡片们 -->
  </div>
  
  <!-- 页脚 -->
  <div style="position:absolute;bottom:20px;left:60px;right:60px;z-index:100;display:flex;justify-content:space-between">
    <span style="font-size:12px;color:rgba(255,255,255,.25)">华平小超人 · Lx-xx</span>
    <span style="font-size:12px;color:rgba(255,255,255,.25)">1/20 · 环节名</span>
  </div>
</div>
```

### 图片引用

- 本地占位：`<div>` + emoji 或 CSS 装饰
- 模块截图：`scratch.shenxinduo.com` 积木图片
- 小超人素材：中文名文件夹 → 映射为英文引用
- AI 配图：暂不启用（课堂不需要）

---

## 九、技术路线

### 唯一方案：HTML → dom-to-pptx → PPTX

```
HTML 设计稿 (1920×1080)
  → Playwright + Chromium 渲染
  → dom-to-pptx 转换
  → 导出 .pptx（原生形状，可编辑）
```

### 工具链

| 工具 | 用途 | 备注 |
|------|------|------|
| HTML + CSS | 设计稿 | 内联样式，固定画布 |
| dom-to-pptx (188⭐) | HTML→PPTX 转换 | 浏览器端库，需 Playwright 驱动 |
| Playwright | 渲染引擎 | Chromium headless |
| Cloudflare Pages | 预览站 + 文件站 | 自动部署 |
| PPTXjs | 在线预览 | 文件站集成 |

### 备选/补充方案

| 方案 | 适用场景 | 说明 |
|------|---------|------|
| Marp CLI | 纯文字型课件 | Markdown → PPTX，简单但缺视觉设计 |
| PptxGenJS (5.4k⭐) | JS 代码生成 | 复杂图表/数据驱动PPT时可用 |
| Slidev (46.6k⭐) | Markdown+组件 | 开发者场景，不适合儿童课件 |
| python-pptx | SVG 导入 | 可作为补充后处理步骤 |

---

## 十、质量检测清单

### 结构检查

- [ ] 7环节齐全，页数 18-25 页
- [ ] 每环节有环节标签（badge）
- [ ] 编程实践包含 💭→🧩→🛠→🤔 四步循环
- [ ] 有 Bug 急救站
- [ ] 有展示关（填空式脚本）
- [ ] 每页有页脚（课程名 + 页码）
- [ ] 封面和下课页有品牌条

### 内容检查

- [ ] 故事主角统一（小超人）
- [ ] 积木名称/模块正确
- [ ] 知识链衔接正确（上节课回顾 = 本课温故知新）
- [ ] 测验题覆盖本节课核心知识点
- [ ] 无教师备注/时间标注

### 视觉检查

- [ ] 1920×1080 画布
- [ ] 每页有光晕/渐变背景装饰
- [ ] 颜色按环节主题一致
- [ ] 卡片圆角统一（20-28px）
- [ ] emoji 用法恰当（非纯装饰）
- [ ] 文字可读（暗底白字/亮底深字）
- [ ] 字号不越级（H0→Fine 七级）

### 卡片检查

- [ ] 每页≥3张卡片（封面/下课/展示除外）
- [ ] 使用了≥2种 card_type
- [ ] 至少1张 data 或 list 卡片
- [ ] 卡片内边距≥20px

### 技术检查

- [ ] 无 `::before`/`::after` 伪元素
- [ ] 无 `conic-gradient`
- [ ] 无 CSS border 三角形
- [ ] 所有样式内联
- [ ] 无外部CSS依赖
- [ ] 绝对定位在 1920×1080 范围内

---

## 十一、交付标准

### HTML 预览站

- Cloudflare Pages 部署
- 侧边栏导航 + 键盘快捷键
- 自动缩放适配屏幕
- 返回导航主页链接

### PPTX 文件

- 通过 dom-to-pptx + Playwright 导出
- 文件站 `files-f0v.pages.dev` 交付
- 命名：`Lx-xx课程名.pptx`

### 配套产物

```
教研/L{级别}/L{级别}-{课号}{课程名}/
  ├── Lx-xx课程名PPT大纲.md      # 大纲文档
  ├── Lx-xx课程名.pptx           # 最终PPTX
  └── (可选) slides/              # HTML源文件
```

---

## 附录A：快速启动清单

开始一门新课前，回答这7个问题：

1. 课程级别 + 课号？（L1-1 / L2-3 …）
2. 在知识链中的位置？（前导课→本课→后续课）
3. 本节课的核心知识点？（3-5个积木/概念）
4. 故事主题？（小超人遇到什么场景）
5. 角色构成？（背景 + 2-4个角色 + 交互规则）
6. 视觉风格？（用风格决策矩阵选）
7. 预期页数？（标准 20p / 精简 15p / 详细 25p）

---

## 附录B：常见失败模式 & 修复

| 失败模式 | 症状 | 修复 |
|---------|------|------|
| **空泛页** | 一页只有标题+1行字 | 至少3个卡片，添加data/list |
| **风格断裂** | 突然换色/换字体 | 全课固定 style.json，按环节调色 |
| **视觉疲劳** | 连续多页同布局 | 密度交替原则，插入过渡页 |
| **卡片同质** | 全是text卡片 | 强制要求≥2种card_type |
| **emoji过载** | 每页10+个emoji | 限制3-8个/页，用做锚点 |
| **文字溢出** | 卡片内文字超出可视区 | 正文≤50字/段，行高≥1.7 |
| **转换失败** | dom-to-pptx报错 | 检查伪元素/conic-gradient/border三角形 |

---

> v3.0 · 2026-05-23 定稿
> 
> 基于：ppt-agent-skill 设计体系 + dom-to-pptx 实战经验 + McK 布局参考 + 教研11课迭代