tianshu-engine/docs/EDITOR_ROADMAP.md

编辑器 Roadmap — 与引擎功能同步

P3 完成的编辑器支持基本的场景节点编辑。以下是与引擎 P4~P31 同步所需的编辑器功能迭代。

---

已完成（P3）

功能	完成
场景节点图（Vue Flow）	✅
场景属性编辑（videoUrl, choices, nextScene, onEnter）	✅
QTE 参数编辑	✅
JSON 导入/导出	✅
视频预览	✅

---

E1: 图片/视频热点编辑（对标 P4）

• NodeEditor 新增 type 切换（video / image）
• imageUrl 字段
• 热区列表编辑：id / label / targetScene / x / y / w / h
• 时间轴参数：showAt / hideAt
• conditions / effects 编辑
• timeLimit 字段

E2: 循环等待参数（对标 P5）

• loopStart / loopEnd 两个数字字段

E3: BGM 字段编辑（对标 P6）

• bgmUrl / bgmVolume / bgmCrossFade
• bgmDuckLevel / bgmDuckFade
• videoMuted

E4: i18n Key 编辑（对标 P11/P31）

• SceneNode: subtitleUrl → subtitles map（按语言编辑）
• Choice: textKey / promptKey
• Hotspot: labelKey
• ChapterInfo: labelKey
• AchievementDef: titleKey / descKey
• EndingDef: labelKey
• QTEDefinition: promptKey
• BattleHUD / BattleResult: labelKey / titleKey

E5: Choice 增强（对标 P13）

• prompt 字段编辑

E6: 顶级字段编辑（对标 P8/P14/P15/P20/P24）

• chapters 列表编辑（id / label / startScene / thumbnail / defaultVariables）
• achievements 列表编辑（id / title / description / icon / hidden / condition）
• endings 列表编辑（id / label / sceneId / chapterId / thumbnail）
• introVideo / menuVideo
• streamingUrl map（三档画质 key-value）
• assetBase 字段

E7: 条件路由编辑（对标 P25）

• nextScene 类型切换（字符串 / 数组）
• 数组模式：逐条编辑 conditions + targetScene

E8: 关键节点编辑（对标 P26）

• keyMoment 字段（三态：自动 / 强制 true / 强制 false）

E9: 战斗系统编辑（对标 P31）

• battleHUD 列表编辑：每项含 label / portrait / stats 数组
• battleHUD stats 编辑：variable / label / max / style
• battleResult 编辑：title / stats 数组

E10: 内嵌快速测试

• 节点右键菜单 → "从此场景开始测试"
• PreviewPanel 切换为 iframe 内嵌游戏播放器（加载 /?scene=<id>）
• Engine 支持 ?scene= URL 参数指定起始场景

E11: 场景列表 + 搜索

• 左侧可折叠场景列表面板（SceneList.vue）
• 按名称搜索/筛选场景节点
• 点击列表项 → 画布跳转到对应节点并选中

E12: JSON 校验器

• 导出/保存前实时检查
• 引用完整性：targetScene 指向不存在的场景 ID
• 死路检测：无 choices / 无 nextScene / 无 qte / 无 hotspots 的场景
• 变量引用：conditions 中的 variable 未在 variables 声明

E13: 撤销/重做

• 操作历史栈（add/delete/update/move node & edge）
• Ctrl+Z 撤销 / Ctrl+Shift+Z 重做
• useGraphEditor 中维护 history[] + historyIndex

E14: 面板可折叠 + 标签页

• NodeEditor 和 PreviewPanel 加折叠/展开按钮
• NodeEditor 按类别分标签页：基本（id/type/videoUrl）/ 音频（bgmUrl 等）/ 战斗（battleHUD/battleResult）/ 高级（loopStart/keyMoment）
• 标签页间切换不丢失编辑状态

---

优先级建议

优先级	编号	说明
P0	E4	i18n key 编辑——覆盖最广，P11/P31 都依赖
P0	E10	内嵌快速测试——最直接的创作者效率提升
P1	E1	热点编辑——P4 是核心交互功能
P1	E6	顶级字段——chapters/achievements/endings 创作者需求最大
P1	E12	JSON 校验——防止导出后游戏崩溃
P2	E7/E8/E9	条件路由/关键节点/战斗——新增功能，但依赖前置
P2	E11	场景列表搜索——场景多了才有真实需求
P2	E14	面板标签页——属性字段达到 20+ 后优势明显
P3	E2/E3/E5	单字段编辑——BGM/loop/prompt，改动小
P3	E13	撤销/重做——重要但改动不小

---

E15: 编辑器架构重构 — 三层分离

目标：为应对状态增多和功能复杂化，确保扩展性和可维护性。编辑器重构为三层分离架构，与引擎分层一致。

当前问题： App.vue 310 行 god 组件 / useGraphEditor.ts 混合 JSON + Vue refs / 无 Pinia store

目标架构：

editor/
├── services/                GraphService.ts + AssetResolver.ts    # 纯函数数据层
├── stores/                  editorStore.ts                       # Pinia 全局状态 + undo/redo
├── composables/             useGraphEditor.ts                    # 编排层（→60行）
├── components/              Toolbar / SceneGraphPanel / NodeEditorPanel / SceneList / StatusBar
└── App.vue                  # 精简布局组合（→30行）

实施步骤：

1. 创建 editorStore.ts（Pinia）
2. 创建 GraphService.ts（纯函数剥离）
3. 精简 App.vue + useGraphEditor
4. 新增 SceneList.vue + StatusBar.vue

优先级建议（更新）

优先级	编号	说明
P0	E15	架构重构——所有后续功能的基础 ✅ 已完成 2026-06-13
P0	E4	i18n key 编辑
P0	E10	内嵌快速测试
P1	E1	热点编辑
P1	E6	顶级字段
P1	E12	JSON 校验
P2	E7/E8/E9	条件路由/关键节点/战斗
P2	E11	场景列表搜索
P2	E14	面板标签页
P3	E2/E3/E5	单字段编辑
P3	E13	撤销/重做