Initial project baseline
This commit is contained in:
@@ -0,0 +1,146 @@
|
||||
# 项目标准说明
|
||||
|
||||
本文档按当前代码整理，覆盖项目边界、运行方式、输入输出和维护约定。最后核对代码时间：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)。
|
||||
- 不再新增单次变更记录文档；短期变更应合并进标准文档。
|
||||
Reference in New Issue
Block a user