own-tools/design/detailed_design.md

个人工具箱 - 汉字字帖生成器详细设计

1. 项目目标

构建一个基于 Python 的 Web 工具箱，首期功能为生成两种类型的汉字书写字帖：

1. 步进式字帖：展示汉字书写的每一笔过程。
2. 教学式大方格：带笔顺序号、方向箭头和灰色临摹底样的 2x3 大格。

2. 技术栈选择

• 核心语言: Python 3.10+
• Web 框架: Streamlit (用于快速构建交互式 UI) 或 FastAPI (如果后续需要更复杂的前后端分离)。初版建议使用 Streamlit 以减少 JS 代码量。
• 绘图引擎: Pillow (PIL) (生成图片) 或 ReportLab / fpdf2 (直接生成可打印的 PDF)。
• 数据源: 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 布局优化: 实现多字排版和打印优化。