213 lines
8.8 KiB
Markdown
213 lines
8.8 KiB
Markdown
# 项目标准说明
|
||
|
||
本文档覆盖项目边界、目录结构、运行方式、输入输出和维护约定。核对代码时间：2026-07-25。
|
||
|
||
## 项目目标
|
||
|
||
本项目是一套中文词云生成+画布设计系统，核心能力：
|
||
|
||
1. **词云生成**：读取 Excel 名单，按掩膜轮廓填充人名，输出 PNG/SVG/DB/metrics。
|
||
2. **画布设计**：前端提供图层化画布、贴纸库、基础形状编辑、SVG 总图导出。
|
||
3. **同底图换名单**：画布中已有的词云底图，支持只换名单不换位置和字号（保留视觉结构）。
|
||
4. **线距分析**：对 SVG 路径进行线距采样，辅助激光加工参数设定。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
wordcloud/
|
||
├── docs/ # 标准文档
|
||
│ ├── README.md
|
||
│ ├── PROJECT_STANDARD.md
|
||
│ ├── ALGORITHM.md
|
||
│ ├── CONFIG.md
|
||
│ ├── API.md
|
||
│ ├── CANVAS_STUDIO.md
|
||
│ ├── TESTING.md
|
||
│ └── DEPLOYMENT.md
|
||
├── backend/
|
||
│ ├── core/ # 词云核心引擎
|
||
│ │ ├── config.py # 配置默认值、别名、类型校验
|
||
│ │ ├── pipeline.py # 主流程：数据→掩膜→权重→布局→渲染→导出
|
||
│ │ ├── layout.py # Python 布局调度、SVG 路径导出
|
||
│ │ ├── weights.py # 笔画权重、Excel 权重、面积字号模型
|
||
│ │ ├── mask.py # 掩膜生成、归一化、自动画幅
|
||
│ │ ├── render.py # 高清精修、填充率计算、重叠检测
|
||
│ │ ├── fonts.py # 字体缓存
|
||
│ │ └── ewc.py # 兼容层（基类+Python 稀疏网格）
|
||
│ ├── EfficientWordCloud/ # C++ 扩展（integral grid + 精确字形碰撞）
|
||
│ │ ├── efficient_wordcloud/
|
||
│ │ │ ├── wordcloud.py # Python 包装
|
||
│ │ │ └── src/ewc_core.cpp # Cython 扩展
|
||
│ │ └── setup.py # C++ 编译入口
|
||
│ ├── service/ # FastAPI 服务
|
||
│ │ ├── app.py # HTTP 路由
|
||
│ │ ├── schemas.py # Pydantic 模型
|
||
│ │ ├── runner.py # 子进程任务执行
|
||
│ │ ├── job_manager.py # 内存任务状态管理
|
||
│ │ ├── storage.py # 任务文件目录管理
|
||
│ │ ├── line_spacing.py # SVG 线距分析
|
||
│ │ └── log_config.py # 服务日志配置
|
||
│ ├── tests/ # 单元测试
|
||
│ │ └── test_layout_constraints.py
|
||
│ ├── tools/ # 基准工具
|
||
│ │ └── benchmark_layout.py
|
||
│ ├── service_workspace/ # 运行时任务产物（.gitignore）
|
||
│ ├── service_assets/ # 后端素材库（.gitignore）
|
||
│ ├── service_projects/ # 后端工程项目（.gitignore）
|
||
│ ├── service_design_templates/ # 设计模板（.gitignore）
|
||
│ └── start-dev.sh # 本地后端启动脚本
|
||
├── frontend/
|
||
│ ├── src/
|
||
│ │ ├── App.tsx # 页面路由：home → canvas / wordcloud / orders / find / help
|
||
│ │ ├── main.tsx
|
||
│ │ ├── types.ts # 全项目 TypeScript 类型
|
||
│ │ ├── styles.css
|
||
│ │ ├── pages/ # 页面级组件
|
||
│ │ │ ├── TemplateHome.tsx # 首页：模板选择
|
||
│ │ │ ├── CanvasStudio.tsx # 画布设计页
|
||
│ │ │ ├── TestWorkbench.tsx # 词云生成页
|
||
│ │ │ ├── OrdersPage.tsx # 生产订单页（登录保护）
|
||
│ │ │ ├── FindPage.tsx # 查找名字页（登录保护，跨任务单任务内查找）
|
||
│ │ │ └── HelpPage.tsx # 帮助页
|
||
│ │ ├── components/ # 可复用组件
|
||
│ │ │ ├── AdvancedPanel.tsx
|
||
│ │ │ ├── CanvasArea.tsx
|
||
│ │ │ ├── DockTabBar.tsx
|
||
│ │ │ ├── EditPanel.tsx
|
||
│ │ │ ├── ExportPanel.tsx
|
||
│ │ │ ├── FindPanel.tsx
|
||
│ │ │ ├── FloatingPanel.tsx
|
||
│ │ │ ├── ImportPanel.tsx
|
||
│ │ │ ├── ProgressPanel.tsx
|
||
│ │ │ ├── ViewControls.tsx
|
||
│ │ │ └── AppSettingsWindow.tsx
|
||
│ │ ├── hooks/
|
||
│ │ ├── lib/
|
||
│ │ │ ├── api.ts # API 工具函数
|
||
│ │ │ ├── canvasDocument.ts # 画布模型操作
|
||
│ │ │ ├── stickerLibrary.ts # 贴纸库存取
|
||
│ │ │ ├── svgExport.ts # SVG/Zip 序列化
|
||
│ │ │ └── templateLibrary.ts # 模板库
|
||
│ │ └── vite-env.d.ts
|
||
│ ├── vite.config.ts
|
||
│ ├── package.json
|
||
│ └── tsconfig.json
|
||
├── start-all.sh # 一键前后端联调
|
||
├── install-ubuntu.sh # Ubuntu Docker 一键部署
|
||
├── release/
|
||
│ └── install-ubuntu.sh
|
||
├── scripts/
|
||
│ └── pack-release.sh
|
||
└── README.md / README_zh.md # 顶层面向用户说明（非标准）
|
||
```
|
||
|
||
## 运行方式
|
||
|
||
### 一键前后端联调（推荐开发用）
|
||
|
||
```bash
|
||
./start-all.sh
|
||
```
|
||
|
||
- 后端：http://localhost:8000
|
||
- 前端：http://localhost:3000
|
||
- 两者通过前端 Vite 代理通信（配置见 `frontend/vite.config.ts`）
|
||
|
||
### 单独启动后端
|
||
|
||
```bash
|
||
cd backend
|
||
./start-dev.sh
|
||
```
|
||
|
||
脚本会自动：
|
||
- 探测 Python 3.9+（优先系统 Python，否则创建 `.venv`）
|
||
- 检查并安装 `fastapi uvicorn python-multipart pydantic pandas openpyxl pillow numpy matplotlib`
|
||
- 在外部 Python 中复用 `scipy`（ABI 匹配时），避免网络安装
|
||
- C++ 扩展 `ewc_core` 源码有更新时自动重新编译
|
||
|
||
### 单独启动前端
|
||
|
||
```bash
|
||
cd frontend
|
||
npm run dev
|
||
```
|
||
|
||
### CLI 生成
|
||
|
||
```bash
|
||
cd backend
|
||
python wordcloud_generate_hybrid.py --config /path/to/config.json
|
||
```
|
||
|
||
CLI 配置优先级见 [CONFIG.md](CONFIG.md)。
|
||
|
||
## 输入要求
|
||
|
||
### Excel 名单
|
||
|
||
- 服务接口仅接受 `.xlsx`
|
||
- `DATA_COL_INDEX` 默认 `1`（第2列，0-based）
|
||
- `REMOVE_DUPLICATES` 默认 `False`，前端也默认保留重复
|
||
- 权重列：优先 `WEIGHT_COL_NAME`，次选 `WEIGHT_COL_INDEX`
|
||
- 有效权重必须为正数
|
||
|
||
### 权重来源
|
||
|
||
| 场景 | 行为 |
|
||
|------|------|
|
||
| 有 Excel 权重，笔画权重开启 | Excel 值作为基础 × 笔画复杂度归一化乘数 |
|
||
| 有 Excel 权重，笔画权重关闭 | 仅 Excel 权重 |
|
||
| 无 Excel 权重，笔画权重开启 | 仅笔画复杂度权重 |
|
||
| 两者均无 | 全部默认权重 `10` |
|
||
|
||
### 掩膜
|
||
|
||
- `MODE=IMAGE` 时必须上传 PNG/JPG/JPEG 掩膜文件
|
||
- 后端转灰度后按阈值 `200` 二值化
|
||
- `FILL_ON=BLACK`：黑色区域可填充；`FILL_ON=WHITE`：白色区域可填充
|
||
- `MODE=TEXT`：用指定文字生成文本掩膜
|
||
|
||
## 输出产物
|
||
|
||
服务任务产物位置：
|
||
|
||
```
|
||
backend/service_workspace/{job_id}/
|
||
input/
|
||
mask.png
|
||
names.xlsx
|
||
output/
|
||
Efficient_Result_HD_AutoResize.png # 最终位图
|
||
Efficient_Result_HD_AutoResize.svg # 填充 SVG
|
||
Efficient_Result_HD_AutoResize_stroke.svg # 描边 SVG（激光雕刻适用）
|
||
wordcloud_hd.db # SQLite：word_locations 表
|
||
metrics.json # 运行指标
|
||
debug/ # 调试图（受 SAVE_DEBUG_IMAGES 控制）
|
||
config.json
|
||
```
|
||
|
||
## 当前限制
|
||
|
||
- **名单完整性是不可关闭的硬约束。** 放不下的情况下只会整批缩放字号或扩大画布，不会漏词。
|
||
- 不存在逐词缩字号、gap filling 或大字号自动压缩路径。
|
||
- `USER_MIN_FONT_SIZE` 和 `USER_MAX_FONT_SIZE` 是不可越过的边界；冲突时直接报错。
|
||
- `SIZE_RATIO=1` 时所有同权重词语保持完全相同字号，面积估算和重试阶段都维持单一字号。
|
||
- C++ 中保留旧矩形查询 API 供底层兼容性，正式流水线使用 `place_glyph_exact()` 真实字形主路径。
|
||
- 前端贴纸库和画布文档只保存在当前浏览器 `localStorage`，不跨设备同步。
|
||
- Jobs 状态存在内存中，服务重启后历史任务状态丢失；文件仍保留在 `service_workspace`。
|
||
- 当前 Projects、Assets、Templates 接口主要服务当前工作台原型和素材管理，不代表完整生产级工程系统。
|
||
|
||
## 维护约定
|
||
|
||
| 变更范围 | 同步更新 |
|
||
|----------|----------|
|
||
| 算法行为 | ALGORITHM.md |
|
||
| 配置项增删 | CONFIG.md |
|
||
| HTTP 接口/响应模型 | API.md |
|
||
| 前端画布功能 | CANVAS_STUDIO.md |
|
||
| 测试/基准 | TESTING.md |
|
||
| 部署方式 | DEPLOYMENT.md |
|
||
|
||
不再新增单次变更记录文档；短期变更合并进标准文档。
|