feat: 新增认识时钟绘制

2026-06-25 12:46:43 +08:00
parent b802709517
commit 783ebfb936
15 changed files with 1119 additions and 1 deletions
@@ -0,0 +1,183 @@
+# 认识钟表 — 预览、出题与绘制设计
+
+> 配套文档：[产品设计文档](../产品设计文档.md) | [技术架构设计文档](../技术架构设计文档.md)  
+> 版本：v1.0  
+> 最后更新：2026-06-25
+
+---
+
+## 一、目标与范围
+
+为幼儿园中班至小学一年级（约 4–7 岁）提供 **「看模拟钟表，填写数字时间」** 的可打印练习纸。
+
+- 每页 **4 行 × 3 列**，共 12 题
+- 每组：上方模拟钟表 + 下方带冒号的数字填写框
+- 小程序内预览、换题、下载打印
+- 排版归类为技术架构文档 **模式 H：时钟/特殊图形型**
+
+**实现路径**：独立绘制页 `mathPages/clockReading/`，不并入 `mathDraw` 聚合页（时钟绘制逻辑特殊，独立维护更清晰）。
+
+---
+
+## 二、页面结构
+
+```
+mathPages/clockReading/
+├── clockReading.ts
+├── clockReading.wxml
+├── clockReading.less
+├── clockReading.json
+├── clockReading.config.ts
+├── generators/
+│   └── clock-generator.ts      # 纯数据出题
+└── draw/
+    ├── clockReadingDraw.ts     # 整页编排
+    └── drawAnalogClock.ts      # 模拟钟表（可复用）
+```
+
+**交互区（预览卡片下方）**
+
+| 区域 | 说明 |
+|------|------|
+| 预览卡片 | Canvas 实时预览 A4 效果，支持换一换 |
+| 时刻类型 chips | 随机（默认）/ 整点 / 半点 / 刻钟 |
+| 底部操作 | 分享、下载打印（复用 `pageMixin`） |
+
+---
+
+## 三、练习纸版面
+
+### 3.1 网格布局
+
+```
+┌──────────────────────────────────────────┐
+│  [统一页眉] 认识钟表                      │
+│  姓名:___  日期:___  得分:___             │
+├──────────────────────────────────────────┤
+│   [钟1]      [钟2]      [钟3]            │
+│   [__:__]    [__:__]    [__:__]          │
+│   [钟4]      [钟5]      [钟6]            │
+│   ...                                    │
+│              （4 行 × 3 列 = 12 题）      │
+└──────────────────────────────────────────┘
+```
+
+### 3.2 单题单元
+
+1. **模拟钟表**：绿色外圈、1–12 数字、红色时针、黑色分针
+2. **填写框**：绿色圆角描边，中间固定冒号 `:`，左右留白供手写
+
+### 3.3 A4 尺寸参数（逻辑像素 595×842）
+
+| 参数 | 值 |
+|------|-----|
+| 内容区起始 Y | 页眉后 ~110px |
+| 左右边距 | 28px |
+| 行数 / 列数 | 4 / 3 |
+| 钟表半径 | ~58px |
+| 钟表与填写框间距 | 10px |
+| 填写框 | 宽 88px，高 30px，圆角 6px |
+| 行高 | ~168px |
+
+---
+
+## 四、钟表视觉规范
+
+| 元素 | 颜色 | 色值 |
+|------|------|------|
+| 外圈 | 绿色 | `#3D9E47` |
+| 刻度 / 数字 | 黑色 | `#333333` |
+| 时针 | 红色 | `#E53935` |
+| 分针 / 中心点 | 黑色 | `#333333` |
+| 填写框描边 | 绿色 | `#3D9E47` |
+| 冒号 | 黑色 | `#333333` |
+
+**指针角度**（12 点方向为 0°，顺时针）：
+
+```ts
+const minuteAngle = minute * 6;
+const hourAngle = (hour % 12) * 30 + minute * 0.5;
+// Canvas 绘制时减去 90° 偏移（0° 在 3 点方向）
+```
+
+---
+
+## 五、时刻类型
+
+| 模式 ID | 显示名称 | 分针位置 | 示例 | 难度 |
+|---------|----------|----------|------|------|
+| `random` | 随机 | 0–59 分均可 | 如 4:07、11:23 | ★★ |
+| `whole-hour` | 整点 | 12 点（0 分） | 3:00, 9:00 | ★ |
+| `half-hour` | 半点 | 6 点（30 分） | 6:30, 10:30 | ★★ |
+| `quarter-hour` | 刻钟 | 3 或 9 点（15/45 分） | 2:15, 7:45 | ★★★ |
+
+> **命名说明**：「刻钟」对应传统「一刻」「三刻」，比「一刻时」更符合小学钟表教学用语，且与「整点」「半点」形成清晰三元组。
+
+**随机模式**：分钟在 0–59 之间均匀随机，不限制为整点/半点/刻钟。
+
+---
+
+## 六、出题规则（`clock-generator.ts`）
+
+```ts
+interface ClockProblem {
+  hour: number;    // 1–12
+  minute: number;  // 随机模式 0–59；其他模式见时刻类型表
+}
+
+interface ClockReadingData {
+  problems: ClockProblem[];  // 固定 12 个
+  timeMode: ClockReadingTimeMode;
+}
+```
+
+1. 每页固定 12 题
+2. 同一页内 `(hour, minute)` 不重复
+3. 小时 1–12 均匀随机
+4. 按所选时刻类型约束 `minute`
+5. 纯函数输出 JSON，不依赖 Canvas
+
+---
+
+## 七、绘制服务拆分
+
+```
+clockReadingDraw.draw(data)
+  ├── prepareDraw() / drawHeaderAndDivider({ title: '认识钟表' })
+  └── drawGrid(problems)
+        └── for each:
+              ├── drawAnalogClock(cx, cy, radius, hour, minute)
+              └── drawTimeInputBox(x, y, w, h)
+```
+
+`drawAnalogClock.ts` 独立封装，便于后续「画指针」题型复用。
+
+---
+
+## 八、配置与注册
+
+- Worksheet ID：`clock-reading`
+- 分类：`math` / `clock-reading`
+- 路径：`/mathPages/clockReading/clockReading?id=clock-reading`
+- 注册：`app.json` 分包、`config/worksheets/clockReading.ts`、`category.data.ts`
+
+---
+
+## 九、验收标准
+
+- [ ] 预览区 4×3 共 12 组「钟表 + 填写框」
+- [ ] 绿圈、红时针、黑分针、1–12 数字
+- [ ] 填写框中间有冒号
+- [ ] 默认随机；切换整点/半点/刻钟后分针位置正确
+- [ ] 换一换生成新题且不重复
+- [ ] A4 下载打印清晰
+- [ ] 分享、收藏、打印解锁链路正常
+
+---
+
+## 十、后续演进（非 MVP）
+
+1. 定制页眉（日期/姓名/用时 + 装饰边框，更贴近教辅纸）
+2. 对答案页 / 画指针题型
+3. 5 分钟间隔、逐分钟进阶模式
+4. AI 出题 tool：`generate_clock_reading({ timeMode, count: 12 })`