# 项目标准说明

本文档按当前代码整理，覆盖项目边界、运行方式、输入输出和维护约定。最后核对代码时间：2026-06-09。

## 项目目标

本项目生成基于名单和掩膜的词云图。后端负责读取 Excel 名单、处理掩膜、计算权重、布局、渲染和导出；前端提供参数面板、任务提交、结果查看、查找和导出入口。

当前项目不是通用设计平台。`Projects`、`Assets`、`Templates` 接口存在，但主要服务于当前工作台原型和素材管理，不代表完整生产级工程系统。

## 目录结构

| 路径 | 职责 |
| --- | --- |
| `backend/wordcloud_generate_hybrid.py` | CLI 入口，加载配置后调用生成管线 |
| `backend/core/config.py` | 默认配置、JSON 配置合并、CLI 覆盖、路径和字体解析 |
| `backend/core/pipeline.py` | 生成主流程：读数据、画布、掩膜、权重、布局、渲染、DB、metrics |
| `backend/core/layout.py` | Python 布局调度、字号打分、逐词放置、SVG 导出 |
| `backend/core/weights.py` | 笔画复杂度权重、Excel 权重、面积字号模型 |
| `backend/core/mask.py` | 掩膜归一化、自动画布、边界安全 padding |
| `backend/core/render.py` | 填充率计算和点阵补偿 |
| `backend/EfficientWordCloud/` | C++ 扩展及其 Python 包装 |
| `backend/service/` | FastAPI 服务、任务管理、文件存储 |
| `frontend/src/` | React 工作台 |
| `docs/` | 标准文档入口 |

## 运行方式

### 一键前后端联调

在项目根目录运行：

```bash
./start-all.sh
```

它会：

- 启动 `backend/start-dev.sh`
- 启动前端 `npm run dev`
- 默认后端端口为 `8000`
- 前端 Vite 端口为 `3000`

### 单独启动后端

```bash
cd backend
./start-dev.sh
```

`start-dev.sh` 会检查 Python 依赖、必要时创建 `.venv`，并在 C++ 源码更新后重新编译 `ewc_core`。

### 单独启动前端

```bash
cd frontend
npm run dev
```

前端通过 Vite 代理访问后端。代理配置见 `frontend/vite.config.ts`。

### CLI 生成

```bash
cd backend
python wordcloud_generate_hybrid.py --config /path/to/config.json
```

CLI 配置优先级：

1. `backend/core/config.py` 默认值
2. JSON 配置文件
3. CLI 参数覆盖

## 输入要求

### Excel 名单

服务接口只接受 `.xlsx`。默认名单列为 `DATA_COL_INDEX = 1`，也就是第 2 列，索引从 0 开始。

当 `REMOVE_DUPLICATES = False` 时，Excel 中重复姓名会保留。当前前端默认保留重复。

### 权重

权重来源按优先级合并：

1. Excel 权重列：`WEIGHT_COL_NAME` 优先于 `WEIGHT_COL_INDEX`
2. 笔画复杂度权重：受 `ENABLE_STROKE_WEIGHTS` 控制
3. 默认权重：没有权重时使用 `10`

关闭 `ENABLE_STROKE_WEIGHTS` 且不传 Excel 权重列时，所有姓名进入均等权重。

### 掩膜

`MODE = IMAGE` 时必须提供 PNG/JPG/JPEG 掩膜。后端会将图片转灰度并以阈值 `200` 二值化。

`FILL_ON = BLACK` 时，黑色区域可填充；`FILL_ON = WHITE` 时，白色区域可填充。

## 输出产物

每次服务任务会创建：

```text
backend/service_workspace/{job_id}/
  input/
    mask.png
    names.xlsx
  output/
    Efficient_Result_HD_AutoResize.png
    Efficient_Result_HD_AutoResize.svg
    Efficient_Result_HD_AutoResize_stroke.svg
    wordcloud_hd.db
    metrics.json
    debug/
      mask_src.png
      mask_hd.png
      mask_small.png
      occ_fast.png
  config.json
```

产物说明：

| 文件 | 含义 |
| --- | --- |
| PNG | 最终位图结果 |
| SVG | 填充路径 SVG |
| `_stroke.svg` | 描边 SVG，适合继续加工 |
| SQLite DB | `word_locations` 表，记录词语位置、字号、颜色、方向、包围盒 |
| metrics | 运行指标、画布尺寸、填充率、配置快照 |
| debug | 调试图，受 `SAVE_DEBUG_IMAGES` 控制 |

## 当前限制

- 重复填充当前按名单轮次展开，但单个词在放置失败时会独立降字号；这会导致后几轮整体字号小于前几轮。
- `reorder_stratified()` 当前对主路径 `query_direct()` 没有实际影响，因为 `query_direct()` 不使用 `valid_coords`。
- C++ `Grid_query_direct` 的 GIL 释放包装没有包住实际扫描调用，性能并发上还有优化空间。
- API 中的 Jobs 存储在进程内存，服务重启后历史任务状态会丢失；文件仍保留在 `service_workspace`。
- 旧文档中的市场分析、路线图和性能宣传不作为当前能力承诺。

## 维护约定

- 修改算法行为时，同步更新 [ALGORITHM.md](ALGORITHM.md)。
- 新增或删除配置项时，同步更新 [CONFIG.md](CONFIG.md)。
- 改 HTTP 接口或响应模型时，同步更新 [API.md](API.md)。
- 不再新增单次变更记录文档；短期变更应合并进标准文档。