From d8c19d9187744a09bafd450ece6fd53e965bfc13 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=8B=E5=BE=B7=E5=AE=87?= Date: Wed, 23 Sep 2026 11:46:31 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=B0=E5=A2=9E=20UI=20=E7=BC=96=E8=BE=91?= =?UTF-8?q?=E5=99=A8=E4=BB=A3=E7=A0=81=E5=9C=B0=E5=9B=BE=E4=B8=8E=E6=A8=A1?= =?UTF-8?q?=E5=9D=97=E8=81=8C=E8=B4=A3=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 定义 `Rust` 权威层、`React` 会话层与视图层的职责边界 - 描述数据流、关键模块设计与核心命令 - 补充扩展指引与关联文档链接 - 更新 `docs/README.md` 引用路径 --- docs/README.md | 1 + ...案】UI编辑器代码地图与模块职责-2026-09-23.md | 73 +++++++++++++++++++ 2 files changed, 74 insertions(+) create mode 100644 docs/technical/【技术方案】UI编辑器代码地图与模块职责-2026-09-23.md diff --git a/docs/README.md b/docs/README.md index d1af5b3c0..8aca10866 100644 --- a/docs/README.md +++ b/docs/README.md @@ -62,6 +62,7 @@ - [AGC 聊天素材引用](./【功能说明】AGC聊天素材引用-2026-09-08.md)：聊天输入框 @ 引用项目素材的入口、引用模型与「当前版本素材」口径。 - [AGC 聊天 AI 润色与发送前提醒](./【功能说明】AGC聊天AI润色与发送前提醒-2026-09-10.md)：提示词润色与发送前提醒的交互、失败与取消口径。 - [UI 工作流资源桥接与 Runtime 执行](./【技术方案】UI工作流资源桥接与Runtime执行-2026-08-24.md) +- [UI 编辑器代码地图与模块职责](./technical/【技术方案】UI编辑器代码地图与模块职责-2026-09-23.md)：Rust `ui_editor` 模块、`features/ui-editor` 语义层与 `view/ui-editor` 视图层的职责划分与扩展指引。 - [UI 编辑器 Godot 容器布局](./technical/【技术方案】UI编辑器Godot容器布局模型-2026-08-18.md) - [UI 编辑器变换角点偏移编辑器](./technical/【设计】UI编辑器变换角点偏移编辑器-2026-09-03.md) - [UI 编辑器子节点显示规则](./technical/【技术方案】UI编辑器子节点显示规则-2026-08-18.md) diff --git a/docs/technical/【技术方案】UI编辑器代码地图与模块职责-2026-09-23.md b/docs/technical/【技术方案】UI编辑器代码地图与模块职责-2026-09-23.md new file mode 100644 index 000000000..1af293291 --- /dev/null +++ b/docs/technical/【技术方案】UI编辑器代码地图与模块职责-2026-09-23.md @@ -0,0 +1,73 @@ +# UI 编辑器代码地图与模块职责 + +更新时间：`2026-09-23` + +一句话定位：`apps/ai-game-creator-shell` 的 UI 编辑器由「Rust/Tauri 权威层 + React 会话层 + 视图层」三段组成；Rust 持有可持久化 State、校验、LLM 工具链、预览渲染与代码生成，前端只负责语义编辑、会话编排和表现。 + +## 分层与数据流 + +```text +view/ui-editor (页面/组件) + └─ useUiEditorSession ← features/ui-editor (语义 + adapter) + ├─ useUiEditorState / stateTransition / nodeTransformGeometry + ├─ uiDesignStateStore → Tauri command + └─ invoke: recognize_ui / merge_ui / ... + └─ src-tauri/src/ui_editor (权威 State、校验、持久化、工作流) +``` + +- 唯一事实来源是项目内的 `ui_design` JSON 文档（含 `revision`），前端 State 只是它的编辑副本。 +- 所有跨进程类型由 Rust 经 `ts_rs` 生成到 `features/ui-editor/types/`（当前 59 个文件），前端不得手改。 + +## Rust 侧：`src-tauri/src/ui_editor` + +| 模块 | 职责 | +| --- | --- | +| `state/mod.rs` | 权威 State 根类型：`State`（`ui_trees` + 界面图/sprite/字体三张资源表）、`UITree`；ts-rs 导出源 | +| `layout/` | 节点模型：`Node`、`NodeMetadata`/`StageStatus`、`ControlLayout`、`Container`、`NodeOffset`、`transform`、`ChildrenDisplayMode`（`Stack`/`Exclusive`） | +| `component/` | 组件枚举 `Component::{Image, Text}`、`NodeComponent`（LLM 工具载荷的 `PureNode`/`WithComponent` 判别式） | +| `resource/` | 界面图、sprite（含 `SpriteBorder` 九宫格）、字体（格式/媒体类型/CSS format）资源描述 | +| `persistence.rs` | 文档读写、`revision` 乐观并发保存、领域校验（重复 ID、环检测、组件状态）、代码生成写盘 | +| `resource_bridge.rs` | 原型图 → `ui_design` 资源的桥接建项（持项目写锁，装 revision 0，仅首个设计图） | +| `html_renderer/` | 由 State 生成 HTML 片段与 JS（maud + 布局/组件 CSS 映射），供预览与 `ui/generated-*.js` | +| `commands/` | LLM 工具链：`recognition`（结构识别）、`binding`（组件绑定）、`merge`（多树合并）、`ui_design_suggestion`（参考图语义）、`separation/`（自动切分素材）、`utils.rs`（LLM 请求、重试、`required_tool_arguments`） | +| `workflow.rs` | 游戏页级工作流：发现 `game/ui-pages.json`、准备/识别/装状态/落阶段（`reference-ready → completed`）、`@genarrative-ui-page` 标记与 receipt 校验、生成最终路由 | +| `commands/separation/` | 切分批处理、截图/预切、sidecar 恢复（inspect / finalize / discard）、patch 回写 | + +关键命令（`main.rs` 注册）：`load_ui_design_state`、`save_ui_design_state`、`generate_ui_design_code`、`ensure_ui_design_resource_for_prototype`、`suggest_ui_design_semantic`、`recognize_ui`、`bind_components`、`merge_ui`、`separate_ui`、`inspect_separation_recovery`、`finalize_separation`、`discard_separation_recovery`。 + +保存语义（`save_ui_design_state_at`）：`Saved` / `Unchanged` / `Conflict`（返回当前快照）三态；先 `validate_state` 再持锁重读比对 `expected_revision`，成功后推进项目 revision。代码生成只接受已保存的 revision，产物路径为 `ui/generated--.js`。 + +## 前端：`src/features/ui-editor`（无视图依赖的语义层） + +- `useUiEditorState.ts`：State reducer + 撤销/重做（`undo/redo/resetHistory`）、`isLocked` 与 `runWithStateLocked`、节点/资源/树偏移的语义写操作、`createTree`（新树横向排布 + `UI_TREE_PADDING`）、删除影响 projection。 +- `stateTransition.ts`：React-free 的命令 → State 语义 transition（`set-tree-offset`、`set-node-metadata`、`set-node-component`）。 +- `nodeTransformGeometry.ts`：State 级节点几何（页面矩形、父矩形、resize 手柄反演），预览/Inspector 共用。 +- `stateInvariants.ts`：保存前不变量 projection，给视图稳定的中文失败信息；Rust 仍是权威校验。 +- `uiDesignStateStore.ts`：`IUiDesignStateStore`（`load`/`save`/`generateCode`）+ Tauri 实现 + 内存替身。 +- 结果应用 seam：`recognition.ts`、`merge.ts`、`uiDesignSuggestions.ts`、`separationStatus.ts`（问题节点 → `NeedReview`）。 +- 概览 projection：`stageStatusOverview.ts`、`separationOverview.ts`。 +- 前置校验：`requisites.ts` 在发起 LLM 操作前检查必需资源与结果完整性。 +- 适配器：`importAdapter.ts`（图片解码、批量导入、字体准备）、`uiDesignResourceBridge.ts`（原型桥接）、`useUiEditorFontFaces.ts`（私有字体族加载）、`spriteBorder.ts`。 +- `utils/`：State → CSS 映射（`componentToCss`、`controlLayoutToCss`、`textStyleToCss`、`transform/tf2css`）、`treeUtils`。 + +## 前端：`src/view/ui-editor`（表现与编排） + +- `useUiEditorPage.ts`：`useUiEditorSession` 是视图与 adapter 的唯一协调边界，产出 `input` / `canvas` / `inspector` / `workflow` / `dialogs` / `save` 六个小 projection；视图不接收完整 controller。 +- `index.tsx`：页面骨架（输入侧栏、预览、Inspector、工具栏、保存/生成结果弹窗、键盘快捷键绑定），由 `view/project-development` 挂载。 +- `model.ts`：三步工作流（分析参考图 / 识别界面结构 / 自动切分素材）、导入种类、界面图 role、操作失败文案。 +- `operationLifecycle.ts`：suggestion/recognition/merge/separation 共用的异步操作 adapter。 +- `components/`：`InputSidebar`、`UiTreePanel`、`Inspector/*`（Transform、Components Text/Image、SpriteBorder）、`preview/*`（`PreviewWorkspace`、`UiTreeRenderer`、组件视图、排他子节点 tab、缩放/平移/拖拽手势）、工作流与结果弹窗。 +- 已退役的 render mode 由会话级开关 `showFrame` / `showOriginImage` / `showComponent` 取代。 + +## 扩展指引 + +- 新增节点/组件字段：先改 `layout/`（或 `component/`）并让 ts-rs 重新导出，再补 `stateTransition`、`stateInvariants`、`persistence::validate_node`、Inspector 与预览映射。 +- 新增 LLM 步骤：在 `commands/` 内自成 command（prompt + schema + 领域校验 + materializer），共用 `commands::utils` 的请求、重试与 tool-call 解析 seam。 +- 新增界面图 role 或状态值：改 Rust 枚举并同步 `view/ui-editor/model.ts` 的中文标签表。 + +## 关联文档 + +- [UI 编辑会话模块边界](./【前端架构】UI编辑会话模块边界-2026-08-19.md) +- [UI 编辑器 Godot 容器布局模型](./【技术方案】UI编辑器Godot容器布局模型-2026-08-18.md) +- [UI 编辑器子节点显示规则](./【技术方案】UI编辑器子节点显示规则-2026-08-18.md) +- [UI 编辑器自动切分素材工作流](./【技术方案】UI编辑器自动切分素材工作流-2026-09-08.md)