# workflow_ui.rs 拆分(8 子模块)设计

日期:2026-06-18
分支:`feat/comfy-cloud-adapter`
状态:已通过 brainstorming,待用户复审

## 背景

`src/routes/workflow_ui.rs` 单文件 6181 行,是项目最大文件,难维护/难测/edit 易错。
按职责拆成 `src/routes/workflow_ui/` 模块目录(8 子模块)。纯机械移动、零逻辑改动,
靠 Rust 编译器 + 现有 5 个测试验证。

## 已确认决策

1. 第一个优化目标:拆 workflow_ui.rs(项目最大文件)。
2. 拆成 8 子模块(见下表)。
3. 纯机械移动:函数体一字不改,只调可见性 + use 路径。零逻辑改动。
4. 安全策略:每抽一个子模块即 cargo build -j 2 验证;5 个测试全程保持通过;末尾冒烟。

## 子模块划分

| 子模块 | 职责 | 现有行号(约) |
|--------|------|--------------|
| `mod.rs` | routes() 装配 + 共享类型(WorkflowCaller、Query/Payload structs)+ 子模块声明 | 56-124 |
| `assets.rs` | UI 静态资源服务、嵌入目录解析、index/static/serve_file/官方模板资源 | 211-305, 1533-1814 |
| `auth.rs` | caller 解析(caller_from_headers/auth_caller/caller_user_id/caller_is_admin) | 313-363, 1875 |
| `node_defs.rs` | 节点定义 + 工作流模板(core_node_definitions、*_workflow_graph、node_type_def_to_comfy) | 429-932 |
| `models.rs` | 模型分类 + folder 模型(is_*_workflow_model、workflow_folder_*、native_folder_models) | 939-1530 |
| `comfy_proxy.rs` | ComfyUI API 代理 handler(settings/userdata/object_info/system_stats/extensions 等) | 1883-2200 |
| `validate.rs` | 工作流校验(validate_workflow* 三个) | 2206-2586 |
| `queue.rs` | 队列/历史/prompt(queue/history/queue_prompt/repair_native_prompt_payload/queue_boosapi_prompt/view) | 2586-3679 |

> 注:行号是当前快照,实现时以函数名定位为准(文件会随抽取缩短)。各子模块的辅助小函数
> 随其主要消费者走;跨多模块共用的(如 guess_mime_from_path、parse_boolish、safe_view_path)
> 放 mod.rs 或新建 util.rs(实现时按实际依赖定,优先放 mod.rs 顶部 pub(super))。

## 安全策略(核心)

1. **纯移动**:剪切函数到子模块,函数体一字不改。仅:
   - 可见性:跨模块调用的改 `pub(super)` / `pub(crate)`;
   - `use`:子模块顶部补齐它用到的依赖路径(crate::、super::、外部 crate)。
2. **逐模块验证**:每抽一个子模块就 `cargo build -j 2`。Rust 编译器对未解析引用/类型不符
   直接报错——这是纯移动重构的强安全网。
3. **测试保持**:现有 5 个测试(在文件尾 `#[cfg(test)] mod tests`)迁到相关子模块(多与
   models/node_defs 相关),全程保持通过:`cargo test -p boosapi --lib routes::workflow_ui`。
4. **末尾冒烟**:全部完成后,工作流 UI 打开 + 跑一个 prompt,确认行为不变。

## 数据流

不变。`routes/mod.rs` 仍 `.merge(workflow_ui::routes())`,对外接口零变化。仅文件内部
组织从 1 文件变 8 文件,所有路由路径、handler 行为、类型签名完全一致。

## 测试

- 编译器:每步 cargo build -j 2(主验证手段)。
- 单测:迁移后 5 个测试保持通过。
- 冒烟:手动开工作流 UI + 跑 prompt。
- 不新增功能测试(本任务是重构,非加功能;但若迁移中发现某函数明显缺测且易加,可顺手补)。

## 非目标

- 不改任何逻辑、不改路由路径、不改 handler 行为。
- 不拆其他巨文件(oauth.rs/digital_human.rs/user/mod.rs 各自独立后续循环)。
- 不顺手重构/优化函数实现(纯搬运)。

## 提交约定

分支 `feat/comfy-cloud-adapter`。**按子模块分多次提交**(每抽 1-2 个子模块 + 编译通过即提交),
便于回溯;不一锅烩。中文 commit。