update at 2026-02-07 16:05:38

DETAIL-DESIGN.md

@@ -0,0 +1,242 @@
+# DETAIL-DESIGN
+
+更新时间：2026-02-07
+
+## 1. 文档目标
+
+本文定义 `font2svg` 的详细设计，覆盖以下范围：
+
+- Web 前端（`frontend/`）的模块职责、数据结构、处理流程
+- Python CLI（`font2svg.py` / `pic2svg.py`）的职责边界
+- 字体资源组织规范与导出策略
+- 性能、错误处理、可维护性约束
+
+## 2. 系统边界
+
+## 2.1 子系统划分
+
+1. `frontend/`：交互式预览与导出（主用户入口）
+2. `scripts/generate-font-list.py`：字体清单构建
+3. `font2svg.py`：命令行字体文本转 SVG
+4. `pic2svg.py`：命令行图片转 SVG
+
+## 2.2 非目标
+
+- 不提供后端 API
+- 不做字体版权管理系统
+- 不做云端存储与用户账号
+
+## 3. 前端架构设计
+
+## 3.1 技术选型
+
+- 框架：Vue 3 + Composition API
+- 构建：Vite + `vite-plugin-wasm`
+- 状态：Pinia
+- 样式：UnoCSS + 手写样式
+- 字体解析：`opentype.js`
+- 字形 shaping：`harfbuzzjs`（已封装，主链路暂未强依赖）
+
+## 3.2 目录与模块映射
+
+- `src/App.vue`：页面总编排、交互入口、导出触发
+- `src/stores/fontStore.ts`：字体域状态
+- `src/stores/uiStore.ts`：UI 域状态与导出选择
+- `src/components/FontSelector.vue`：字体搜索与树渲染入口
+- `src/components/FontTree.vue`：分类树、收藏、预览勾选
+- `src/components/FavoritesList.vue`：收藏列表
+- `src/components/SvgPreview.vue`：预览生成调度
+- `src/utils/svg-builder.ts`：SVG 生成核心
+- `src/utils/download.ts`：下载与打包
+- `src/utils/font-loader.ts`：字体加载（含进度）
+- `src/utils/text-layout.ts`：文本换行标准化
+
+## 3.3 状态模型
+
+## FontInfo
+
+```ts
+interface FontInfo {
+  id: string
+  name: string
+  path: string
+  category: string
+  isFavorite: boolean
+  font?: Font
+  loaded: boolean
+  progress: number
+}
+```
+
+## UI 持久化 Key
+
+- `font.favoriteFontIds`
+- `font.previewFontIds`
+- `font.expandedCategories`
+- `ui.fontSize`
+- `ui.inputText`
+- `ui.textColor`
+- `ui.selectedExportItems`
+
+## 4. 关键流程设计
+
+## 4.1 字体清单加载
+
+1. `useFontLoader()` 在 `App.vue` 初始化阶段触发。
+2. 请求 `/fonts.json`。
+3. 每条记录映射为 `FontInfo`，加入 `fontStore.fonts`。
+4. 调用 `updateFontTree()` 生成分组树。
+
+异常策略：请求失败弹窗提示，并记录控制台错误。
+
+## 4.2 字体按需加载
+
+入口：`fontStore.loadFont(fontInfo)`
+
+- 若 `loaded=true` 或无路径则直接返回
+- 同字体并发请求通过 `loadingFontTasks` 去重
+- 使用 `loadFontWithProgress` 拉取字体并实时写入 `progress`
+- 解析成功后写入 `fontInfo.font` 与 `loaded=true`
+
+设计意图：避免初始一次性加载全部字体导致内存抖动。
+
+## 4.3 预览生成调度
+
+入口：`SvgPreview.vue`
+
+1. 监听 `previewFonts/inputText/fontSize/fillColor` 变化。
+2. 采用 `240ms` 防抖触发重算。
+3. 每批最多处理 `20` 个字体，批内并发 `4`。
+4. 借助 `IntersectionObserver` 懒加载后续批次。
+5. 使用 `previewGeometryCache` 缓存几何结果，颜色切换直接替换 token。
+
+核心常量：
+
+- `PREVIEW_DEBOUNCE_MS = 240`
+- `PREVIEW_BATCH_SIZE = 20`
+- `PREVIEW_CONCURRENCY = 4`
+- `PREVIEW_GEOMETRY_CACHE_LIMIT = 600`
+
+取消策略：用 `previewGenerationToken` 判定过期任务，避免旧结果污染。
+
+## 4.4 文本布局
+
+`wrapTextByChars(text, 45)` 策略：
+
+- 统一换行符 `\r\n/\r -> \n`
+- 保留手动换行
+- 每行按字符数上限切分（默认 45）
+
+说明：该策略简单稳定，但不进行词边界或 East Asian 宽度感知换行。
+
+## 4.5 SVG 生成
+
+当前主链路：`generateSvg(options)`
+
+- 基于 `opentype.js` 的 `charToGlyph` + path 指令拼装
+- 计算 glyph 边界盒，汇总 viewBox 与 width/height
+- 输出 `<g transform="translate(... ) scale(1 -1)">` 的坐标翻转结构
+
+高级链路：`generateSvgWithHarfbuzz(options, fontBuffer)`
+
+- 已封装 HarfBuzz shaping 与定位缩放逻辑
+- 目前未接到主预览流程
+
+## 4.6 导出流程
+
+入口：`App.vue -> handleExport('svg' | 'png')`
+
+1. 先清理失效导出项（不在当前预览集合中的项）
+2. 单项导出：直接下载
+3. 多项导出：聚合后 ZIP 下载
+4. PNG 导出：先 SVG，再 `canvas` 渲染为 Blob
+
+命名规则：
+
+- SVG：`{fontPart}_{textPart}.svg`
+- PNG：`{fontPart}_{textPart}.png`
+- `textPart` 截取前 8 字符
+- 非法字符统一替换 `_`
+
+## 5. 字体资源规范
+
+## 5.1 目录约束
+
+字体唯一来源：`frontend/public/fonts/`
+
+- 支持多级目录
+- 分类名来自相对目录路径
+- 根目录字体分类记为 `未分类`
+
+## 5.2 fonts.json 结构
+
+由 `scripts/generate-font-list.py` 生成：
+
+```json
+{
+  "id": "分类/字体名",
+  "name": "字体名",
+  "filename": "字体文件名.ttf",
+  "category": "分类",
+  "path": "/fonts/分类/字体文件名.ttf"
+}
+```
+
+## 6. Python CLI 设计
+
+## 6.1 font2svg.py
+
+职责：把给定字体与文本转换为 SVG。
+
+- 使用 `uharfbuzz` 做 shaping
+- 使用 `fonttools` 读取 glyph 与路径
+- 支持单字体或目录批量转换
+- 支持字距参数 `--letter-spacing`
+
+## 6.2 pic2svg.py
+
+职责：将二值化后的图片轮廓矢量化。
+
+- OpenCV 预处理灰度与阈值
+- 可选圆拟合快速路径
+- 默认依赖 potrace 做高保真描边
+
+## 7. 性能设计
+
+- 字体元数据与字体文件解耦（先列表后按需）
+- 预览批处理 + 并发上限
+- 预览项懒加载
+- 几何缓存与颜色 token 替换，减少重复 path 生成
+
+## 8. 错误处理设计
+
+- 用户可恢复错误：`alert` 提示（如空文本、未选导出项）
+- 任务级错误：控制台 `console.error/warn`，不中断整个批次
+- 资源加载失败：单字体失败不阻断其他字体渲染
+
+## 9. 测试与质量门禁
+
+当前仓库实际情况：
+
+- 有 TypeScript 编译检查（`pnpm -C frontend run build` 中包含 `vue-tsc`）
+- 暂无标准 `lint` 脚本
+- 暂无标准单元测试脚本
+
+建议目标：
+
+1. 增加 `lint`（ESLint）
+2. 增加 `test`（Vitest）
+3. 在 CI 中强制执行 `lint + typecheck + test`
+
+## 10. 已知限制
+
+- 主预览链路尚未默认启用 HarfBuzz shaping
+- 自动换行仅按固定字符数，不考虑语义断句
+- 浏览器内批量 PNG 导出在极大尺寸时可能触发内存压力
+
+## 11. 后续演进建议
+
+1. 将 `generateSvgWithHarfbuzz` 接入主链路并提供回退机制
+2. 为预览与导出建立一致性回归样例
+3. 增加导出并发队列与失败重试（有限次数）
+4. 统一日志级别，移除生产环境调试日志

README.md

@@ -1,125 +1,83 @@
 # font2svg
 
-一个基于 Vue 3 + TypeScript 的本地字体预览与导出工具。
+本仓库提供两条能力链路：
 
-核心目标：从本地字体库中选择字体，实时生成文本预览，并导出为 `SVG` 或 `PNG`。
+- Web 应用（`frontend/`）：本地字体预览、多字体对比、导出 `SVG/PNG`
+- Python CLI（根目录脚本）：图片转 SVG、字体文本转 SVG
 
-## 界面快照
+## 文档导航
 
-![snapshot](frontend/src/assets/snapshot.png)
+- 项目总览：`README.md`
+- 详细设计：`DETAIL-DESIGN.md`
+- 使用说明：`USAGE.md`
+- 迭代计划：`PLAN.md`
+- 前端子项目说明：`frontend/README.md`
 
-## 当前功能
+## 核心特性
 
-- 字体库加载
-  - 从 `frontend/public/fonts.json` 读取字体清单
-  - 支持按分类展示字体树
-  - 支持收藏字体列表
-- 预览控制
-  - 勾选字体进入预览
-  - 多字体并行预览
-  - 预览项可单独勾选用于导出
-- 文本输入
-  - 输入框支持手动回车换行
-  - 自动按每行 45 字换行（保留手动换行）
-- 样式控制
-  - 字号滑块（10 ~ 500）
-  - 文字颜色选择
-- 导出
-  - 支持导出 `SVG`
-  - 支持导出 `PNG`（由 SVG 转换）
-  - 多项导出自动打包 zip
-  - 导出文件名规则：`字体名_内容前8字.扩展名`
+- 字体树 + 分类折叠 + 搜索 + 收藏
+- 预览勾选与导出勾选分离，支持全选/全不选
+- 文本自动按每行 45 字换行（保留手动换行）
+- 预览采用分批加载与并发渲染，降低大字体库卡顿
+- 导出 `SVG` 或 `PNG`，多项自动打包 ZIP
+- 字体来源统一为 `frontend/public/fonts/`
 
-## 技术栈
+## 目录结构
 
-- `Vue 3`
-- `TypeScript`
-- `Vite`
-- `Pinia`
-- `UnoCSS`
-- `opentype.js`
-- `harfbuzzjs`
-- `jszip`
-
-## 目录说明
-
-- `frontend/`: 前端应用源码
-- `frontend/public/fonts/`: 字体目录（唯一字体来源，支持分类子目录）
-- `frontend/public/fonts.json`: 字体清单（由脚本重建）
-- `scripts/generate-font-list.py`: 扫描 `frontend/public/fonts` 并生成 `fonts.json`
+```text
+font2svg/
+├── frontend/                    # Vue3 + TS Web 应用
+│   ├── public/
+│   │   ├── fonts/               # 字体唯一来源目录
+│   │   └── fonts.json           # 字体清单（脚本生成）
+│   └── src/
+├── scripts/
+│   └── generate-font-list.py    # 生成 frontend/public/fonts.json
+├── font2svg.py                  # 字体文本转 SVG（Python CLI）
+├── pic2svg.py                   # 图片转 SVG（Python CLI）
+└── DETAIL-DESIGN.md             # 详细设计
+```
 
 ## 环境要求
 
-- Node.js 18+
-- pnpm 8+
-- Python 3（用于字体准备脚本）
+- Node.js `>=18`
+- pnpm `>=8`
+- Python `>=3.9`
+- （可选）potrace：`pic2svg.py` 需要
 
-## 快速开始
-
-### 1. 安装依赖
+## 快速开始（Web）
 
 ```bash
 pnpm -C frontend install
-```
-
-### 2. 准备字体
-
-将字体放入如下结构：
-
-```text
-frontend/public/fonts/
-  手写/
-    字体A.ttf
-  黑体/
-    字体B.otf
-```
-
-然后执行：
-
-```bash
 pnpm run prepare-fonts
-```
-
-该命令会扫描 `frontend/public/fonts/` 并重新生成 `frontend/public/fonts.json`。
-
-### 3. 启动开发环境
-
-```bash
 pnpm run dev
 ```
 
-默认由 Vite 启动前端开发服务。
+默认访问地址：`http://localhost:5174`
 
 ## 常用命令
 
 ```bash
-# 启动开发
+# 根目录
 pnpm run dev
-
-# 构建（调用 frontend build）
 pnpm run build
-
-# 本地预览构建产物
 pnpm run preview
-
-# 重新生成字体清单
 pnpm run prepare-fonts
+
+# 前端子项目
+pnpm -C frontend run dev
+pnpm -C frontend run build
+pnpm -C frontend run preview
 ```
 
-## 导出行为说明
+## Python CLI 概览
 
-- 单个选中项：直接下载对应文件（`svg` 或 `png`）
-- 多个选中项：打包 zip 下载
-  - SVG: `font2svg-svg-export.zip`
-  - PNG: `font2svg-png-export.zip`
-- 导出前会自动清理失效选中项，避免导出已不在当前预览列表中的字体
+```bash
+# 字体转 SVG
+python font2svg.py --font path/to/font.ttf --text "你好"
 
-## 文本布局说明
+# 图片转 SVG
+python pic2svg.py images/your_image.png --outdir output
+```
 
-- 输入文本会先做换行标准化（`\r\n` -> `\n`）
-- 每行超过 45 字会自动分行
-- SVG 高度按字形真实边界计算，不额外添加内置 padding
-
-## 旧脚本说明
-
-仓库仍保留 `pic2svg.py` / `font2svg.py` 等 Python 脚本，用于历史流程或离线转换；当前主交互流程以上述 `frontend/` Web 应用为准。
+详细参数请看 `USAGE.md`。

USAGE.md

@@ -1,44 +1,77 @@
-# 使用示例与说明
+# 使用说明
 
-## 🚀 快速开始
+本文覆盖两类使用方式：
 
-### 1. 安装依赖
+- Web 应用（推荐）：`frontend/` 图形界面
+- Python CLI：`font2svg.py` / `pic2svg.py`
+
+## 1. Web 应用
+
+### 1.1 安装依赖
+
+```bash
+pnpm -C frontend install
+```
+
+### 1.2 准备字体
+
+将字体放入：`frontend/public/fonts/`，支持多级目录，例如：
+
+```text
+frontend/public/fonts/
+  书法/
+    字体A.ttf
+  黑体/
+    字体B.otf
+```
+
+执行清单生成：
+
+```bash
+pnpm run prepare-fonts
+```
+
+该命令会重建：`frontend/public/fonts.json`
+
+### 1.3 启动与构建
+
+```bash
+pnpm run dev
+pnpm run build
+pnpm run preview
+```
+
+默认开发端口：`5174`。
+
+### 1.4 页面操作
+
+1. 左侧字体区搜索/勾选字体进入预览。
+2. 可点击收藏按钮加入“已收藏字体”。
+3. 顶部设置字号、颜色、输入内容。
+4. 右侧预览区点击条目可切换导出选择。
+5. 点击导出 `SVG` 或 `PNG`。
+
+导出规则：
+
+- 单个条目：直接下载
+- 多个条目：自动打包 ZIP
+- 文件名：`字体名_文本前8字符.扩展名`
+
+## 2. Python CLI
+
+### 2.1 安装依赖
 
 ```bash
 pip install -r requirements.txt
 ```
 
-### 2. 安装 potrace（必需）
+`pic2svg.py` 还需要 `potrace`：
 
 ```bash
 brew install potrace
 ```
 
-### 2.1 字体转SVG依赖
-
-```bash
-pip install fonttools uharfbuzz
-```
-
-### 3. 转换单个文件
-
-```bash
-python pic2svg.py images/your_image.png
-```
-
-### 3.1 指定输出目录
-
-```bash
-python pic2svg.py images/your_image.png --outdir output/
-```
-
-### 4. 批量转换
-
-```bash
-python pic2svg.py --indir images --outdir output
-```
-
-### 5. 字体转SVG
+### 2.2 字体转 SVG（font2svg.py）
 
 ```bash
 python font2svg.py --font path/to/font.ttf --text "Hello"
@@ -47,56 +80,53 @@ python font2svg.py --font path/to/font.ttf --text "Hello" --letter-spacing 20
 python font2svg.py --fontdir font --text "星程紫微" --outdir svg
 ```
 
-说明：单字体输出文件名根据 `--text` 自动生成；使用 `--fontdir` 时会加上字体名作为前缀。
+参数：
 
-## ⚙️ 参数说明
+- `--font`：单个字体文件（ttf/otf）
+- `--fontdir`：字体目录（批量处理）
+- `--text`：必填，渲染文字
+- `--outdir`：输出目录，不传则输出到当前目录
+- `--letter-spacing`：字距（字体单位）
 
-- `--threshold`：固定阈值（0-255），默认使用 Otsu 自动阈值。
-- `--indir`：输入目录（批量转换）。
-- `--outdir`：输出目录（自动创建，使用输入文件名.svg）。
-- `--turdsize`：抑制噪点面积阈值，越小保留细节越多。
-- `--opttolerance`：曲线优化容差，越大文件越小但可能失真。
-- `--unit`：坐标量化单位，`1` 表示不量化。
-- `--optimize-curves`：开启曲线优化（更小但可能略失真）。
-- `--circle-fit`：圆拟合误差阈值（相对半径），>0 启用圆替代。
-- `--font`：字体文件路径（ttf/otf）。
-- `--fontdir`：字体目录（遍历ttf/otf）。
-- `--text`：文字内容。
-- `--letter-spacing`：字距（字体单位），默认 0。
-
-## 🧩 常用配置示例
+### 2.3 图片转 SVG（pic2svg.py）
 
 ```bash
-# 保真优先（默认参数）
-python pic2svg.py images/your_image.png --turdsize 0 --opttolerance 0 --unit 1
-
-# 文件更小（可能略失真）
-python pic2svg.py images/your_image.png --optimize-curves --opttolerance 0.2
-
-# 需要固定阈值时
-python pic2svg.py images/your_image.png --threshold 128
-
-# 圆拟合简化（仅当轮廓接近圆时生效）
-python pic2svg.py images/your_image.png --circle-fit 0.02
-
-# 批量转换
+python pic2svg.py images/your_image.png
+python pic2svg.py images/your_image.png --outdir output/
 python pic2svg.py --indir images --outdir output
 ```
 
-## 🐛 常见问题
+常用参数：
 
-**Q: 细节丢失或断裂？**  
-A: 降低 `--turdsize`，关闭 `--optimize-curves`，必要时指定 `--threshold`。
+- `--threshold`：固定阈值（0-255），默认 Otsu
+- `--turdsize`：噪点抑制阈值
+- `--opttolerance`：曲线优化容差
+- `--unit`：坐标量化单位
+- `--optimize-curves`：启用曲线优化
+- `--circle-fit`：圆拟合误差阈值
 
-**Q: SVG 太大？**  
-A: 开启 `--optimize-curves`，或适当增大 `--opttolerance`。
+## 3. 常见问题
 
-**Q: 能否处理彩色图？**  
-A: 当前流程会转为灰度并二值化，只保留黑色区域。
+### Q1：前端看不到字体？
 
-**Q: 圆拟合过于粗糙？**  
-A: 减小 `--circle-fit` 或关闭圆拟合。
+按顺序检查：
 
-## 📄 License
+1. 字体是否放在 `frontend/public/fonts/`
+2. 是否执行了 `pnpm run prepare-fonts`
+3. `frontend/public/fonts.json` 是否包含对应条目
 
-MIT License - 自由使用和修改
+### Q2：导出 PNG 失败？
+
+通常是浏览器内存或 SVG 内容异常导致，建议：
+
+1. 降低字号后重试
+2. 先导出 SVG 验证生成是否正常
+3. 分批导出而不是一次全选过多字体
+
+### Q3：`pic2svg.py` 提示找不到 potrace？
+
+安装后确认：
+
+```bash
+which potrace
+```

frontend/README.md

@@ -1,5 +1,74 @@
-# Vue 3 + TypeScript + Vite
+# frontend
 
-This template should help get you started developing with Vue 3 and TypeScript in Vite. The template uses Vue 3 `<script setup>` SFCs, check out the [script setup docs](https://v3.vuejs.org/api/sfc-script-setup.html#sfc-script-setup) to learn more.
+`frontend/` 是 `font2svg` 的 Vue 3 + TypeScript 前端应用，负责字体浏览、文本预览与 SVG/PNG 导出。
 
-Learn more about the recommended Project Setup and IDE Support in the [Vue Docs TypeScript Guide](https://vuejs.org/guide/typescript/overview.html#project-setup).
+## 技术栈
+
+- Vue 3 + `<script setup>`
+- TypeScript
+- Vite
+- Pinia
+- UnoCSS
+- opentype.js
+- harfbuzzjs（当前仅在高级接口中可用）
+
+## 本地开发
+
+```bash
+pnpm install
+pnpm run dev
+```
+
+默认地址：`http://localhost:5174`
+
+## 构建与预览
+
+```bash
+pnpm run build
+pnpm run preview
+```
+
+`build` 已包含 `vue-tsc -b` 类型检查。
+
+## 目录说明
+
+```text
+frontend/
+├── public/
+│   ├── fonts/              # 字体文件（由根目录统一维护）
+│   └── fonts.json          # 字体清单（根目录脚本生成）
+├── src/
+│   ├── components/         # 页面组件
+│   ├── composables/        # 组合式逻辑
+│   ├── stores/             # Pinia 状态管理
+│   ├── utils/              # 字体加载/排版/导出工具
+│   ├── types/              # 类型声明
+│   ├── App.vue             # 主界面
+│   └── main.ts             # 应用入口
+├── vite.config.ts
+└── uno.config.ts
+```
+
+## 关键实现
+
+- `src/stores/fontStore.ts`
+  - 字体、收藏、预览、分类展开状态
+  - localStorage 持久化
+  - 字体按需加载与进度回传
+- `src/components/SvgPreview.vue`
+  - 预览防抖
+  - 批量并发生成
+  - 交叉观察器懒加载
+  - 预览几何缓存（LRU）
+- `src/utils/svg-builder.ts`
+  - 字体文本转 SVG
+  - 自动按 45 字换行
+- `src/utils/download.ts`
+  - SVG/PNG 下载
+  - ZIP 打包导出
+
+## 注意事项
+
+- 字体目录唯一来源是 `frontend/public/fonts/`
+- 更新字体后需要在仓库根目录执行 `pnpm run prepare-fonts`
+- 当前仓库尚未配置前端 lint/test 脚本，后续应在计划中补齐