8.8 KiB
8.8 KiB
项目标准说明
本文档覆盖项目边界、目录结构、运行方式、输入输出和维护约定。核对代码时间：2026-07-25。
项目目标
本项目是一套中文词云生成+画布设计系统，核心能力：
- 词云生成：读取 Excel 名单，按掩膜轮廓填充人名，输出 PNG/SVG/DB/metrics。
- 画布设计：前端提供图层化画布、贴纸库、基础形状编辑、SVG 总图导出。
- 同底图换名单：画布中已有的词云底图，支持只换名单不换位置和字号（保留视觉结构）。
- 线距分析：对 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 # 顶层面向用户说明（非标准）
运行方式
一键前后端联调（推荐开发用）
./start-all.sh
- 后端：http://localhost:8000
- 前端：http://localhost:3000
- 两者通过前端 Vite 代理通信（配置见
frontend/vite.config.ts）
单独启动后端
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源码有更新时自动重新编译
单独启动前端
cd frontend
npm run dev
CLI 生成
cd backend
python wordcloud_generate_hybrid.py --config /path/to/config.json
CLI 配置优先级见 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 |
不再新增单次变更记录文档；短期变更合并进标准文档。