Rework layout engine around exact-glyph collision, add tests and docs sync

Replace the old bbox/heuristic placement (scale search rounds, large-font
capping, stratified sampling, fill-retry ladders) with an area-model font
sizing pass feeding a C++ exact-glyph collision engine (centroid-biased
spiral + random probing, HD clearance refinement, density/hole
optimization). Simplify the frontend advanced-params panel and JobParams
type to match the surviving config surface, add a layout-constraints test
suite and a repeatable benchmark tool, and bring docs/*.md back in sync
with current code (plus new TESTING.md and DEPLOYMENT.md).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
2026-07-26 18:32:25 +08:00
co-authored by Claude Sonnet 5
parent bf2b138007
commit 1d17b5e20d
24 changed files with 2600 additions and 1283 deletions
+17 -16
View File
@@ -1,27 +1,22 @@
# WordCloud 项目文档入口
# WordCloud 项目文档
本文档目录是当前项目的标准文档入口。除非某个历史文档被明确标注为“标准文档”,否则以这里列出的文档为准
## 文档准则
- 以代码为准。文档只描述当前代码实际行为,不提前承诺未实现能力。
-`backend/core/config.py``backend/core/pipeline.py``backend/core/layout.py``backend/EfficientWordCloud/efficient_wordcloud/src/ewc_core.cpp` 为算法事实来源。
-`backend/service/app.py``backend/service/schemas.py` 为 HTTP API 事实来源。
- 变更记录只记录历史,不作为使用说明。
本文档目录是标准文档入口。标准文档直接对应代码实现;历史/规划文档不作为行为依据
## 标准文档
| 文档 | 用途 |
| --- | --- |
| [PROJECT_STANDARD.md](PROJECT_STANDARD.md) | 项目结构、运行方式、输入输出、工程约定 |
| [ALGORITHM.md](ALGORITHM.md) | 词云生成算法、重复填充、权重、C++ 碰撞搜索 |
| [CONFIG.md](CONFIG.md) | 配置项优先级、前端参数到后端配置的映射 |
| [API.md](API.md) | FastAPI 接口、请求格式、响应结构、产物下载 |
|------|------|
| [PROJECT_STANDARD.md](PROJECT_STANDARD.md) | 项目目标、目录结构、运行方式、输入输出、工程约定 |
| [ALGORITHM.md](ALGORITHM.md) | 词云生成算法:面积模型、权重、布局、C++ 碰撞搜索、高清精修 |
| [CONFIG.md](CONFIG.md) | 配置项清单、来源优先级、前端参数映射、类型校验 |
| [API.md](API.md) | FastAPI HTTP 接口、请求格式、响应结构、产物下载 |
| [CANVAS_STUDIO.md](CANVAS_STUDIO.md) | 画布设计、贴纸库、词云作为贴纸、总图 SVG 导出 |
| [TESTING.md](TESTING.md) | 单元测试、基准测试、质量门禁 |
| [DEPLOYMENT.md](DEPLOYMENT.md) | 本地开发、Docker、Ubuntu 服务器部署 |
## 非标准/历史文档
以下文档可能包含历史规划阶段性设想或已经过期的实现描述,不再作为行为依据:
以下文档可能包含过期规划阶段性描述,不再作为行为依据:
- `docs/PPT-EfficientWordCloud-详细大纲-v1.0.md`
- `docs/stroke-weights-optional.md`
@@ -29,4 +24,10 @@
- `backend/README.md`
- `backend/README_zh.md`
需要确认行为时,优先查标准文档;标准文档仍不清楚时,直接查代码。
## 工程约定
- **以代码为准。** 文档描述当前代码的实际行为,不提前承诺未实现能力。
- 算法事实来源:`backend/core/pipeline.py``backend/core/layout.py``backend/EfficientWordCloud/efficient_wordcloud/src/ewc_core.cpp`
- HTTP API 事实来源:`backend/service/app.py``backend/service/schemas.py`
- 前端事实来源:`frontend/src/App.tsx``frontend/src/pages/TestWorkbench.tsx``frontend/src/components/AdvancedPanel.tsx``frontend/src/types.ts`
- 变更不单独记文档;短期变更直接合并进标准文档。