Initial project baseline

2026-07-04 02:40:45 +08:00
commit d5d8caef2f
86 changed files with 15590 additions and 0 deletions
@@ -0,0 +1,104 @@
+# 配置说明
+
+本文档只覆盖当前代码中实际可用的配置。完整键集合以 `backend/core/config.py` 的 `KNOWN_CONFIG_KEYS` 为准。
+
+## 配置来源和优先级
+
+CLI 入口 `backend/wordcloud_generate_hybrid.py` 的顺序：
+
+1. 加载 `backend/core/config.py` 默认值
+2. 如果传 `--config`，调用 `apply_json_config()`
+3. 调用 `apply_cli_overrides()`
+4. 调用 `finalize_runtime_config()` 派生路径、字体、输出路径
+5. 调用 `set_random_seed()`
+
+服务模式下，`POST /api/jobs` 会生成任务配置并写入：
+
+```text
+backend/service_workspace/{job_id}/config.json
+```
+
+之后由子进程通过 `--config` 读取。
+
+## 前端参数映射
+
+当前前端 `TestWorkbench.tsx` 提交的关键字段：
+
+| 前端字段 | 后端配置 |
+| --- | --- |
+| `dataColIndex` | `DATA_COL_INDEX` |
+| `seed` | `SEED` |
+| `weightColIndex` | `WEIGHT_COL_INDEX` |
+| `fontColor` | `FONT_COLOR` |
+| `nRepetitions` | `N_REPETITIONS` |
+| `strokeWeights=false` | `ENABLE_STROKE_WEIGHTS=false` |
+
+前端只在重复次数大于 1 时传 `N_REPETITIONS`，只在关闭笔画权重时传 `ENABLE_STROKE_WEIGHTS=false`。
+
+## 常用配置
+
+| 键 | 默认值 | 说明 |
+| --- | --- | --- |
+| `MODE` | `IMAGE` | 掩膜模式，`IMAGE` 或 `TEXT` |
+| `MASK_IMAGE_PATH` | `7887.png` | IMAGE 模式掩膜路径，服务模式会覆盖为上传文件路径 |
+| `IMAGE_CANVAS_MODE` | `WIDTH` | 图片掩膜缩放模式 |
+| `FILL_ON` | `BLACK` | `BLACK` 表示黑色可填，`WHITE` 表示白色可填 |
+| `EXCEL_PATH` | `四个方向汇总录取名单.xlsx` | Excel 路径，服务模式会覆盖为上传文件路径 |
+| `DATA_COL_INDEX` | `1` | 名单列，0-based |
+| `WEIGHT_COL_INDEX` | `None` | 权重列，0-based |
+| `WEIGHT_COL_NAME` | `None` | 权重列名，优先于列索引 |
+| `REMOVE_DUPLICATES` | `False` | 是否对名单去重 |
+| `ENABLE_STROKE_WEIGHTS` | `True` | 是否在无 Excel 权重时使用笔画复杂度权重 |
+| `N_REPETITIONS` | `1` | 名单重复倍率 |
+| `SIZE_RATIO` | `2.0` | `max_font` 相对 `min_font` 的比例 |
+| `PACKING_EFFICIENCY` | `0.85` | 面积模型中的打包效率 |
+| `MIN_ACCEPT_FILL_RATIO` | `0.75` | 填充率重试阈值 |
+| `REQUIRE_ALL_WORDS` | `True` | 搜索阶段是否优先要求达到目标词数 |
+| `USER_MIN_FONT_SIZE` | `None` | 用户覆盖最小字号 |
+| `USER_MAX_FONT_SIZE` | `None` | 用户覆盖最大字号 |
+| `FONT_SCALE_MIN` | `0.5` | 二分搜索缩放下限 |
+| `FONT_SCALE_MAX` | `1.2` | 二分搜索缩放上限 |
+| `LIMIT_LARGE_FONTS` | `True` | 是否限制大字号数量 |
+| `LARGE_FONT_LIMIT_RATIO` | `0.2` | 大字号数量上限占比 |
+| `LARGE_FONT_THRESHOLD_RATIO` | `0.8` | 超过有效最大字号该比例视为大字号 |
+| `LARGE_FONT_CAP_RATIO` | `0.6` | 超过大字号限制后的降级比例 |
+| `ENABLE_DOT_MATRIX` | `False` | 是否用点阵补偿空白区域 |
+| `CANVAS_RETRY_MAX_ROUNDS` | `1` | 画布扩大重试轮数 |
+| `FONT_COLOR` | `#000000` | 固定字体颜色；为空时使用调色板 |
+| `SEED` | `None` | 随机种子 |
+| `LAYOUT_ORDER_MODE` | `SORTED` | 展开序列排序模式 |
+| `LAYOUT_SEED` | `None` | 布局顺序种子，默认继承 `SEED` |
+
+## JSON 别名
+
+`apply_json_config()` 支持部分小写别名：
+
+| 别名 | 正式配置 |
+| --- | --- |
+| `seed` | `SEED` |
+| `layout_order_mode` | `LAYOUT_ORDER_MODE` |
+| `layout_seed` | `LAYOUT_SEED` |
+| `excel_path` | `EXCEL_PATH` |
+| `mask_image_path` | `MASK_IMAGE_PATH` |
+| `output_dir` | `OUTPUT_DIR` |
+| `output_prefix` | `OUTPUT_PREFIX` |
+| `mode` | `MODE` |
+| `work_scale` | `WORK_SCALE` |
+| `weight_col_index` | `WEIGHT_COL_INDEX` |
+| `weight_col_name` | `WEIGHT_COL_NAME` |
+| `min_font_size` | `USER_MIN_FONT_SIZE` |
+| `max_font_size` | `USER_MAX_FONT_SIZE` |
+| `font_color` | `FONT_COLOR` |
+| `stroke_weights` | `ENABLE_STROKE_WEIGHTS` |
+
+CLI 覆盖只支持 `parse_args()` 中定义的参数，不支持 `font_color` 或 `stroke_weights` CLI 参数。
+
+## 类型校验
+
+`CRITICAL_TYPE_CHECKS` 中的配置类型错误会直接退出。未知配置键只告警，不会失败。
+
+## 路径规则
+
+相对路径会以 `backend` 目录作为基准解析。输出路径会在 `finalize_runtime_config()` 中创建。
+
+字体会先尝试项目字体，再尝试 `FONT_FALLBACK_PATHS`。字体不可用会直接失败。