feat: 英文字母描红开发

2026-04-03 15:21:04 +08:00
parent 206c44cf6d
commit 1ef6770810
37 changed files with 1812 additions and 179 deletions
@@ -0,0 +1,377 @@
+# 字母描红 — 预览、配置与模板引擎设计
+
+> 配套文档：[产品设计文档](../产品设计文档.md) | [技术架构设计文档](../技术架构设计文档.md)  
+> 版本：v1.0  
+> 最后更新：2026-04-03
+
+---
+
+## 一、目标与范围
+
+本文档说明「英语字母描红」在小程序内的**预览与配置页**如何设计，以及如何对齐 [技术架构设计文档](../技术架构设计文档.md) 第五章的**模板引擎**（`tracing-writing` + `letter-tracing`）。
+
+覆盖四种练习形态：
+
+1. **单字母学习页**：选定一个字母，含书写示意、阅读句（如 *L is for Lion*）、配图，下方四线三格描红行。
+2. **整页 26 字母**：26 个字母各占一行（或等价满版排列），四线三格内描红。
+3. **上大小写下小写**：上半区展示大写 A–Z，下半区展示小写 a–z。
+4. **两列 26 字母**：一页内左列 A–M、右列 N–Z（或同构小写），每行含示范与描红格。
+
+交付形态遵循 [产品设计文档](../产品设计文档.md) §7.3：**客户端动态生成**，不预生成整页 PNG 上云存储。
+
+---
+
+## 二、四种子类型的模板引擎归类
+
+从产品视角是四种题型；从引擎视角可收敛为**同一排版模板 + 同一数据生成器**，通过 `generatorConfig.mode` 区分。
+
+
+| 用户可见类型    | 排版本质               | 模板 `template`     | 生成器 `generator`  |
+| --------- | ------------------ | ----------------- | ---------------- |
+| 单字母学习页    | 教学区 + 描红区（混合型纵向分区） | `tracing-writing` | `letter-tracing` |
+| 26 字母整页描红 | 纯描红满版（多行）          | `tracing-writing` | `letter-tracing` |
+| 上大写 / 下小写 | 纯描红双区块（展示 + 轻描红）   | `tracing-writing` | `letter-tracing` |
+| 两列 26 字母  | 纯描红双栏              | `tracing-writing` | `letter-tracing` |
+
+
+**结论**：一个 `TracingWritingRenderer`（扩展四线三格能力）+ 一个 `LetterTracingGenerator`，用 `mode` 参数驱动四种版面，无需四种独立页面类型（除非产品坚持拆入口卡片）。
+
+---
+
+## 三、Mode 定义与版面结构
+
+### 3.1 `single-letter`（单字母学习页）
+
+- **上部（约 40%～45% 内容高）**：教学区  
+  - 配图（与字母绑定的词汇插图，内置 26 组映射 + 资源 key / CDN URL）  
+  - 大写 + 小写展示  
+  - 阅读句：`*X* is for *Word`*  
+  - 书写顺序示意（可用简化箭头/步骤编号，首版可弱化）
+- **下部（约 50%）**：描红区  
+  - 至少两行四线三格：一行大写、一行小写（或按配置多行）  
+  - 每行：示范格（实线/深色）+ 若干渐淡虚线格 + 可选空白格
+
+### 3.2 `full-alphabet`（26 字母整页）
+
+- 26 行（大写或二选一为小写），每行对应一个字母。  
+- 每行：四线三格横排多个单元格——首格示范，后续为渐淡描红或空白。  
+- 行高由可用高度 / 26 自动换算，保证打印可读（需与 `fontSize`、DPI 导出策略一致）。
+
+### 3.3 `upper-lower-split`（上大写、下小写）
+
+- 上区块：标题如「大写字母」+ 两行（或紧凑网格）排完 A–Z，每字母一格四线三格，偏**展示**（描红可弱：首格实线 + 空白）。  
+- 分隔线。  
+- 下区块：标题如「小写字母」+ 同理排完 a–z。
+
+### 3.4 `two-column`（两列）
+
+- 左列 A–M（或 a–m），右列 N–Z（或 n–z）。  
+- 每行结构与 `full-alphabet` 类似：示范 + 多格描红。  
+- 中间留白或细分隔线，避免幼儿视觉混淆。
+
+---
+
+## 四、四线三格绘制约定
+
+用于英文字母书写指导（区别于汉字田字格）：
+
+- **顶线**：大写字母上沿参考。  
+- **中虚线**：小写无升部字母的上沿（x-height 概念）。  
+- **基线**：字母落笔主参考线。  
+- **底线**：降部（如 g、p、y）下沿参考。
+
+大写主体落在顶线—基线之间；小写主体多在中虚线—基线之间，降部延伸至底线。渲染器需实现 `drawFourLineGrid(cellRect)`，并与 `fontSize`、基线对齐算法统一。
+
+---
+
+## 五、预览与配置页（产品 UI）
+
+### 5.1 页面结构（与通用生成页一致）
+
+对齐产品设计中的生成/预览页：**A4 预览区（Canvas）+ 参数面板 + 底部操作**（换一批 / 保存相册 / 分享等）。
+
+### **预览/配置页面 UI 设计**
+
+所有4种类型**共用一个通用 worksheet 页面**（`pages/worksheet/worksheet`），通过 `worksheetId` 加载不同 JSON 配置。但字母描红也可以做成一个**聚合入口页** + 通用 worksheet 页的组合，体验更好：
+
+┌─────────────────────────────────────────┐
+
+│  ← 返回    英语字母描红        ❤️         │
+
+├─────────────────────────────────────────┤
+
+│                                         │
+
+│  ┌─────────────────────────────────┐    │
+
+│  │                                 │    │
+
+│  │      A4 打印效果预览区           │    │
+
+│  │      (Canvas 实时渲染)           │    │
+
+│  │                                 │    │
+
+│  └─────────────────────────────────┘    │
+
+│                                         │
+
+│  ⚙️ 参数设置                             │
+
+│  ┌─────────────────────────────────┐    │
+
+│  │                                 │    │
+
+│  │  练习类型：                      │    │
+
+│  │  ┌──────┐┌──────┐┌──────┐      │    │
+
+│  │  │ 单字母 ││ 整页  ││大小写│      │    │  ← 核心切换
+
+│  │  │ 学习页 ││ 描红  ││对照  │      │    │
+
+│  │  └──────┘└──────┘└──────┘      │    │
+
+│  │  ┌──────┐                      │    │
+
+│  │  │ 两列  │                      │    │
+
+│  │  │ 描红  │                      │    │
+
+│  │  └──────┘                      │    │
+
+│  │                                 │    │
+
+│  │  ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─     │    │
+
+│  │                                 │    │
+
+│  │  大小写：[大写 ▼]                │    │  ← mode 2/4 时显示
+
+│  │                                 │    │
+
+│  │  选择字母：A [选中] B [选中]...  │    │  ← mode 1 时显示
+
+│  │                                 │    │
+
+│  │  每行描红格数：[5 ▼]             │    │  ← mode 1/2/4 时显示
+
+│  │                                 │    │
+
+│  └─────────────────────────────────┘    │
+
+│                                         │
+
+│  ┌──────────┐  ┌──────────────┐         │
+
+│  │  🔄 换一批 │  │ 📥 保存到相册 │         │
+
+│  └──────────┘  └──────────────┘         │
+
+│                                         │
+
+└─────────────────────────────────────────┘
+
+### 5.2 参数项与 Mode 的显隐
+
+
+| 配置项        | `single-letter` | `full-alphabet` | `upper-lower-split` | `two-column` |
+| ---------- | --------------- | --------------- | ------------------- | ------------ |
+| 练习类型（mode） | 显示              | 显示              | 显示                  | 显示           |
+| 选择字母       | 显示（单选）          | 隐藏              | 隐藏                  | 隐藏           |
+| 大小写        | 隐藏（默认双写）        | 显示              | 隐藏（固定双区）            | 显示           |
+| 每行描红格数     | 显示              | 显示              | 隐藏或固定为 1            | 显示           |
+| 换一批        | 可切换下一字母         | 可不展示或禁用         | 可不展示                | 可不展示         |
+
+
+参数面板由 `WorksheetConfig.userConfigurable` 描述；前端根据当前 `mode` **过滤**不适用字段（或在 JSON 层拆成 4 条配置，每条只含本 mode 的 `userConfigurable`）。
+
+### 5.3 入口策略
+
+- **推荐**：发现页 / 英语分类下 **4 张卡片**，对应 4 个 `worksheet id`，均进入**同一通用 worksheet 页面**，仅默认 `generatorConfig` 不同。  
+- **可选**：单页内提供「练习类型」Segment，切换 `mode` 并合并默认参数后重绘（与多卡片二选一或并存）。
+
+---
+
+## 六、生成器设计：`letter-tracing`
+
+### 6.1 配置（建议字段）
+
+```typescript
+type LetterTracingMode =
+    | 'single-letter'
+    | 'full-alphabet'
+    | 'upper-lower-split'
+    | 'two-column';
+
+interface LetterTracingGeneratorConfig {
+    mode: LetterTracingMode;
+    /** full-alphabet / two-column 使用 */
+    letterCase: 'upper' | 'lower';
+    /** single-letter 使用，如 'L' */
+    selectedLetter?: string;
+    /** 每行描红单元数量（示范 + 渐淡 + 空白计在同一行内） */
+    repetitions: number;
+    /** 渐淡策略 */
+    fadePattern: 'gradient' | 'first-only';
+}
+```
+
+### 6.2 输出数据结构（示意）
+
+生成器产出**与平台无关**的数据，供 `TracingWritingRenderer` 消费：
+
+- `single-letter`：`{ teaching: { upper, lower, word, sentence, imageRef }, rows: TracingRow[] }`  
+- `full-alphabet` / `two-column`：`{ columns?: 1 | 2, rows: TracingRow[] }`  
+- `upper-lower-split`：`{ upperBlock: TracingRow[] | GlyphCell[], lowerBlock: ... }`
+
+`TracingRow` 建议包含：`displayChar`、`cells: { char, opacity, isGuide }[]`、`gridType: 'four-line'`。
+
+### 6.3 词汇与配图数据
+
+- 维护 `Record<'A'..'Z', { word: string; imageKey: string }>`（或云端下发）。  
+- 图片走内置分包资源或云存储 URL，由 [产品设计文档](../产品设计文档.md) §7.3 中「云素材」规则约束：**插图是设计资产，可 CDN；整页描红仍客户端拼版**。
+
+---
+
+## 七、渲染器设计：`tracing-writing` 扩展
+
+### 7.1 职责
+
+- 沿用现有 `BaseTemplateRenderer` 流程：背景、页眉、说明文案、内容区、页脚。  
+- 根据 `data.mode` 分支调用 `drawSingleLetterPage` / `drawFullAlphabetPage` / `drawUpperLowerSplitPage` / `drawTwoColumnPage`。  
+- 统一使用 **A4 逻辑坐标**（与技术文档 §7.1 Canvas 管线一致）。
+
+### 7.2 与汉字描红的差异
+
+
+| 维度  | 汉字练字（`character-tracing`） | 字母描红（`letter-tracing`） |
+| --- | ------------------------- | ---------------------- |
+| 格子  | 田字格                       | 四线三格                   |
+| 字形  | SVG 笔画路径                  | 优先 `fillText` + 字体轮廓   |
+| 版面  | 多字多格排布                    | 四种 mode 分区逻辑           |
+
+
+### 7.3 参考现有实现
+
+- `service/wordDrawService.ts`：布局分区、渐淡格思路可对齐。  
+- `mathPages/shared/service/numberWriteDraw.ts`：四线三格线型可参考。
+
+---
+
+## 八、WorksheetConfig 示例（四条）
+
+以下可与 `core/data/worksheets.ts` 或云端 `worksheets` 集合对齐；`id` 供路由与统计使用。
+
+**1）单字母学习页**
+
+```json
+{
+    "id": "letter-tracing-single",
+    "title": "字母学习页",
+    "category": "english",
+    "subcategory": "letter-tracing",
+    "template": "tracing-writing",
+    "generator": "letter-tracing",
+    "generatorConfig": {
+        "mode": "single-letter",
+        "selectedLetter": "A",
+        "repetitions": 5,
+        "fadePattern": "gradient"
+    },
+    "layoutConfig": {
+        "showInstruction": true,
+        "instructionText": "看一看，读一读，再描一描"
+    }
+}
+```
+
+**2）26 字母整页**
+
+```json
+{
+    "id": "letter-tracing-full",
+    "title": "26 字母描红",
+    "category": "english",
+    "subcategory": "letter-tracing",
+    "template": "tracing-writing",
+    "generator": "letter-tracing",
+    "generatorConfig": {
+        "mode": "full-alphabet",
+        "letterCase": "upper",
+        "repetitions": 8,
+        "fadePattern": "gradient"
+    }
+}
+```
+
+**3）大小写对照**
+
+```json
+{
+    "id": "letter-tracing-upper-lower",
+    "title": "大小写字母对照",
+    "category": "english",
+    "subcategory": "letter-tracing",
+    "template": "tracing-writing",
+    "generator": "letter-tracing",
+    "generatorConfig": {
+        "mode": "upper-lower-split",
+        "repetitions": 1,
+        "fadePattern": "first-only"
+    },
+    "layoutConfig": {
+        "columns": 13
+    }
+}
+```
+
+**4）两列描红**
+
+```json
+{
+    "id": "letter-tracing-two-column",
+    "title": "字母描红（两列）",
+    "category": "english",
+    "subcategory": "letter-tracing",
+    "template": "tracing-writing",
+    "generator": "letter-tracing",
+    "generatorConfig": {
+        "mode": "two-column",
+        "letterCase": "upper",
+        "repetitions": 4,
+        "fadePattern": "gradient"
+    },
+    "layoutConfig": {
+        "columns": 2
+    }
+}
+```
+
+完整 `userConfigurable` 数组可在实现阶段按 §5.2 补全，并同步云库字段定义。
+
+---
+
+## 九、实现落地清单（工程侧）
+
+
+| 项                        | 说明                                                                         |
+| ------------------------ | -------------------------------------------------------------------------- |
+| `LetterTracingGenerator` | `core/generators/` 或英语分包 `shared/generators/`，注册到 `generatorRegistry`      |
+| `TracingWritingRenderer` | 扩展四线三格 + 四种 `draw*Page`                                                    |
+| 字母词汇与配图映射                | `core/data/alphabet.ts` 或云端配置                                              |
+| 通用 worksheet 页           | `pages/worksheet/worksheet`（或过渡期 `englishPages` 专用页再迁）                     |
+| `ALL_WORKSHEETS`         | 增加 4 条 `WorksheetDefinition`，`category` 对齐英语，`legacyPage` 可指向 worksheet 路由 |
+| 分包                       | 按需新增 `englishPages`，避免主包膨胀                                                 |
+
+
+---
+
+## 十、修订记录
+
+
+| 日期         | 版本   | 说明   |
+| ---------- | ---- | ---- |
+| 2026-04-03 | v1.0 | 初稿入库 |
+
+