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

## 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 布局优化**: 实现多字排版和打印优化。