# 项目标准说明

本文档覆盖项目边界、目录结构、运行方式、输入输出和维护约定。核对代码时间：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 |

不再新增单次变更记录文档；短期变更合并进标准文档。