Initial commit: Modular personal toolbox with high-fidelity Chinese stroke order tool and CI/CD

design/detailed_design.md

@@ -0,0 +1,56 @@
+# 个人工具箱 - 汉字字帖生成器详细设计
+
+## 1. 项目目标
+构建一个基于 Python 的 Web 工具箱，首期功能为生成两种类型的汉字书写字帖：
+1. **步进式字帖**：展示汉字书写的每一笔过程。
+2. **教学式大方格**：带笔顺序号、方向箭头和灰色临摹底样的 2x3 大格。
+
+## 2. 技术栈选择
+- **核心语言**: Python 3.10+
+- **Web 框架**: **Streamlit** (用于快速构建交互式 UI) 或 **FastAPI** (如果后续需要更复杂的前后端分离)。初版建议使用 Streamlit 以减少 JS 代码量。
+- **绘图引擎**: **Pillow (PIL)** (生成图片) 或 **ReportLab / fpdf2** (直接生成可打印的 PDF)。
+- **数据源**: [Hanzi Writer Data](https://github.com/chanind/hanzi-writer-data) (提供汉字笔画的 SVG Path 数据和中轴线坐标)。
+
+## 3. 核心功能设计
+
+### 3.1 数据层 (Data Provider)
+- **职责**: 加载和缓存汉字笔画 JSON 数据。
+- **实现**:
+    - 下载常用汉字的 JSON 文件并存储在本地。
+    - 结构化解析 `strokes` (SVG 路径字符串) 和 `medians` (笔画中轴线坐标序列)。
+
+### 3.2 渲染引擎 (Character Renderer)
+- **SVG 解析**: 使用 `svgpath2lines` 或类似库将 SVG Path 转换为坐标点。
+- **步进逻辑 (Step-by-Step)**:
+    - 输入：汉字，方格大小。
+    - 循环：对于第 $i$ 个笔画，在第 $i$ 个格子中绘制 `strokes[0...i]`。
+    - 样式：当前笔画（第 $i$ 笔）用黑色，之前的笔画用浅灰色或同样黑色。
+- **标注逻辑 (Annotated Square)**:
+    - **底样**: 绘制所有笔画，颜色设为浅灰 (e.g., `#D3D3D3`)。
+    - **序号**: 在每一笔 `medians[i]` 的第一个坐标点附近标注数字 $i+1$。
+    - **箭头**: 
+        - 取 `medians[i]` 的前两个点 $P_1(x_1, y_1)$ 和 $P_2(x_2, y_2)$。
+        - 计算向量 $\vec{V} = P_2 - P_1$。
+        - 在 $P_1$ 处绘制指向 $P_2$ 方向的箭头。
+
+### 3.3 导出模块 (Exporter)
+- **PDF 导出**: 使用 `fpdf2` 布局页面（A4 纸张），将生成的图片或绘制指令排列在页面上。
+- **预览**: 在 Web 界面实时展示生成的 PNG 图片。
+
+## 4. 界面设计 (Web UI)
+- **侧边栏**: 选择字帖类型（步进式/教学式）、字体大小、纸张方向。
+- **输入区**: 文本框输入目标汉字（支持多个字）。
+- **展示区**: 实时生成字帖预览。
+- **下载区**: 点击按钮下载 PDF 打印版。
+
+## 5. 待解决的技术细节
+- **SVG 坐标对齐**: 汉字数据通常基于 1024x1024 的坐标系，需要缩放到 PDF 或图片的分辨率。
+- **箭头绘制逻辑**: 处理极短笔画（如“点”）时的箭头方向问题。
+- **田字格背景**: 需要在渲染汉字前绘制标准的“田”字虚线格。
+
+## 6. 实施步骤
+1. **环境准备**: 安装 `streamlit`, `pillow`, `fpdf2`, `requests`。
+2. **数据爬取/获取**: 编写脚本从 Hanzi Writer CDN 获取指定汉字的 JSON 数据。
+3. **原型开发**: 先在本地用 Pillow 生成一张带箭头和数字的单个汉字图片。
+4. **Web 包装**: 使用 Streamlit 搭建界面。
+5. **PDF 布局优化**: 实现多字排版和打印优化。