feat: 英文字母描红开发
This commit is contained in:
R524809
+60
-2
@@ -697,7 +697,65 @@ interface WeekPlan {
|
||||
| 热点响应 | 随时 | 追节日/热点快速上线应景内容 |
|
||||
| 版本迭代 | 每 2-4 周 | 新排版模板、新生成算法、UI 改进等需发版内容 |
|
||||
|
||||
### 7.3 分包优化
|
||||
### 7.3 内容交付形态决策框架（客户端生成 vs 云存储）
|
||||
|
||||
> 与 [技术架构设计文档](./技术架构设计文档.md) 第七章 §7.4（涂色卡/迷宫等素材型内容方案中的类型 A/B/C）一致，本节从产品视角给出**可执行的判断标准**，避免「像字母描红这种看似固定的内容是否该预生成图放云存储」这类决策反复讨论。
|
||||
|
||||
#### 7.3.1 决策树（产品侧）
|
||||
|
||||
规划新题型或新资料时，按顺序回答下列问题：
|
||||
|
||||
```
|
||||
新内容 / 新题型
|
||||
│
|
||||
├─ 能否通过算法 + 参数（含字库/字母表/随机种子）在客户端产出整页可打印结果？
|
||||
│ ├─ 能 → 【客户端动态生成】
|
||||
│ │ 例：加减法、迷宫路径、字母/拼音/数字描红、识字卡选字组合、控笔虚线…
|
||||
│ │
|
||||
│ └─ 否 → 是否依赖设计师绘制的线稿、展开图、贴纸图等「不可替代的美术素材」？
|
||||
│ ├─ 是 → 【云存储素材 + 客户端排版导出】
|
||||
│ │ 例：主题涂色卡、折纸展开图、手工模板、装饰贴纸…
|
||||
│ │
|
||||
│ └─ 否 → 【混合型】
|
||||
│ 算法生成结构 + 云存储皮肤/底图
|
||||
│ 例：迷宫（路径算法 + 主题边框）、闪卡（版式 + 配图 URL）…
|
||||
```
|
||||
|
||||
**一句话原则**：能算出来的不要囤成静态图；只有「画出来才有价值」的才上云存储。
|
||||
|
||||
#### 7.3.2 典型内容对照表
|
||||
|
||||
| 内容类型 | 推荐交付形态 | 简要理由 |
|
||||
| ------------------ | ---------------- | ------------------------------------------------------------------------ |
|
||||
| 字母 / 拼音描红 | 客户端生成 | 字形规则、参数多（每页字数、重复次数、大小写组合）；预生成图组合爆炸 |
|
||||
| 数字描红 | 客户端生成 | 同上；与现有数学/练字能力一致 |
|
||||
| 汉字描红（练字） | 客户端生成 | 依赖笔画数据 + 田字格排版；用户自选字表 |
|
||||
| 运算类、规律类题型 | 客户端生成 | 需随机「换一批」；零边际服务器成本 |
|
||||
| 主题涂色卡线稿 | 云存储 + 排版 | 美术品质依赖设计稿，无法靠通用算法还原 |
|
||||
| 折纸 / 手工模板 | 云存储 + 排版 | 展开图与步骤图为设计资产 |
|
||||
| 贴纸、装饰素材 | 云存储 | 纯素材分发 |
|
||||
| 迷宫、找不同等 | 混合型 | 结构或差异点可算法生成，主题视觉可素材化 |
|
||||
|
||||
#### 7.3.3 与模板引擎的对应关系
|
||||
|
||||
| 交付形态 | 常见模板类型（技术文档用语） | 产品侧理解 |
|
||||
| ------------ | ---------------------------- | ------------------------------ |
|
||||
| 客户端生成 | `grid-exercise`、`tracing-writing`、`sequence-pattern` 等 | 选模板 + 生成器 + 用户可调参数 |
|
||||
| 云存储素材 | `full-page-asset` + `static-asset` | 配置素材 URL，按需下载后套 A4 |
|
||||
| 混合型 | 自定义生成器 + 素材字段 | 产品需拆清「哪部分算、哪部分画」 |
|
||||
|
||||
#### 7.3.4 决策时需同步考虑的约束
|
||||
|
||||
| 约束 | 说明 |
|
||||
| ------------ | -------------------------------------------------------------------- |
|
||||
| 成本与规模 | 客户端生成主路径不增加下载带宽；大量预生成高清 PNG 会放大存储与流量成本 |
|
||||
| 离线体验 | 纯客户端生成可在弱网或无网下完成预览（依赖已内置/已缓存的数据与字体） |
|
||||
| 运营迭代 | JSON 配置 + 素材上架即可扩展客户端生成题型变体；云素材适合快速换主题 |
|
||||
| 视觉统一 | 描红类建议统一字体与格线规范；云素材需建立插画/线稿风格指南 |
|
||||
|
||||
产品评审新需求时，建议在需求单中**显式勾选**交付形态（客户端生成 / 云素材 / 混合），并与设计、研发对齐模板类型与是否需要新增生成器。
|
||||
|
||||
### 7.4 分包优化
|
||||
|
||||
```
|
||||
当前分包结构： 建议优化后：
|
||||
@@ -713,7 +771,7 @@ interface WeekPlan {
|
||||
└── craftPages (创意手工)
|
||||
```
|
||||
|
||||
### 7.4 数据模型扩展
|
||||
### 7.5 数据模型扩展
|
||||
|
||||
```typescript
|
||||
interface WorksheetConfig {
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 26 KiB |
@@ -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 | 初稿入库 |
|
||||
|
||||
|
||||
Reference in New Issue
Block a user