pixi-demo/docs/superpowers/specs/2026-04-19-remove-legacy-Game-pipeline-design.md

去除旧 src/Game/ 管线 — 设计规格

日期: 2026-04-19
范围: 测试项目，允许破坏性修改。策略：A 一次到位；场景切换 API 仅保留 changeScene，移除 changeStage 别名。

---

1. 三种执行顺序（择一）

方案	做法	优点	缺点
1 — 先删目录	直接删除 src/Game/，按编译错误逐个修	最快暴露所有断裂引用	错误面大，需一次性修完
2 — 先迁消费者（推荐）	先改 page_init、page_welcome2、init.ts、SceneManager，最后再删 Game/	每步可 build 验证，心智负担小	中间状态短暂存在两套路径
3 — 薄兼容层	保留 @/Game 仅 re-export 新 API	外部脚本 import 路径不变	与「彻底去旧」目标冲突，不采用

推荐：方案 2。与「一次到位」不矛盾：同一 PR/会话内完成，但实现顺序降低返工。

---

2. 删除清单（src/Game/ 整目录）

以下文件在迁移完成后 全部删除，不再保留 re-export：

• index.ts（initGame、defineWindow、gameManager、stageManager、windows）
• Game.ts（旧渲染/方向逻辑，与 core/Game 重复）
• Stage.ts
• type.ts（PWindow、IWindow）
• Position.ts（依赖旧 gameManager；已由 utils/Position + core/Game 覆盖）
• Sound.ts（模块加载时 sound.add('my-sound', …) 副作用）
• Assets.ts（loadAsset / unLoadAsset / initAssets；与 core/AssetManager 重复）
• Loader.ts、detectOrient.ts（仅旧 Game.ts 使用）

---

3. 页面迁移规格

3.1 page_init.ts → BaseScene

• export default class InitScene extends BaseScene，constructor() 中 super("init", SceneType.Normal)（与现有入口名 init 一致）。
• 资源：loadBundle 内使用 assetManager.loadBundle("load-screen", onProgress) 替代 loadAsset；返回值类型以 Pixi Assets.loadBundle 结果为准，保持现有 this.assets[...] 索引方式需验证 manifest 中 bundle 结构一致。
• 布局：layout 保持现有 UI 构建逻辑；Position 改为 @/utils/Position（position.get(...) 或项目既有用法）。
• 音频：不再 import 旧 Game/Sound。在 initApp 早期（或常驻 _global 的 loadBundle）调用 soundManager.add("my-sound", "/bg.mp3", { singleInstance: true }) 一次即可；onUnLoad 继续 soundManager.stop("my-sound")。
• 切换：所有 changeStage → changeScene；isHolderLast 选项行为不变。

3.2 page_welcome2.ts → BaseScene

• export default class Welcome2Scene extends BaseScene，super("welcome2", SceneType.Normal)。
• 移除 defineWindow / PWindow；layout / onLoad / onUnLoad / update 逻辑平移。
• 交互：changeStage("welcome") → changeScene("welcome")（含 touchend / mousedown 中需一致）。

---

4. 启动与场景注册

4.1 init.ts

• 移除 DefineWindowModule 类型及对 default 为「非函数对象且含 abstractClass」分支的处理。
• 仅接受：export default 为 构造函数，且 new 后满足 IBaseScene（含 stage）。非法模块 warn 并跳过。
• 移除与 _type、defineWindowName 相关的可变回填注释可简化为一句：场景名来自文件名 page_<name>.ts 的 <name>，类型仅来自 BaseScene 构造函数传入的 SceneType。
• 入口场景名：维持常量 "init"（硬编码可接受；若后续要配置化，另起任务）。

4.2 main.ts（可选改进）

• 去掉 setTimeout(200)，改为顶层 void initApp().catch(...) 或 DOMContentLoaded 后 await initApp()，避免魔法延迟。若与 game.setOrientation 顺序有关，则顺序写为：await initApp() 之后再 setOrientation，或把方向写入 initApp 末尾由调用方传入配置（本规格 最小改动 为：去 setTimeout，保持 initApp 内现有顺序）。

---

5. SceneManager.ts

• registerScene 中删除对 changeStage 的注入与注释中的「兼容旧 PWindow」段落。
• 仅注入 changeScene（保持现有语义）。

---

6. 枚举与类型清理

• src/enums/index.ts：删除 EP、EDirection 及其「Legacy exports」注释块（删除后全仓应无引用）。
• 全仓 grep EP、EDirection、PWindow、IWindow、defineWindow、@/Game 确保为零（测试代码与注释除外）。

---

7. 验证与回归

• 运行 TypeScript 检查与生产构建（pnpm build 或 npm run build，以仓库 package.json 为准）。
• 手动：启动后进入 init → 切 welcome / welcome2 → 返回；常驻 0global 仍挂载；无控制台未捕获异常。

---

8. 非目标（本规格不做）

• 不改变 SceneManager 异步 changeScene 的对外类型（void 注入）——可另开任务改为 Promise。
• 不重写 Button / 组件 API。
• 不合并 docs/superpowers/specs/2026-04-19-pixijs-framework-refactor-design.md（该文档仍为高层框架说明；本文档为本次去旧的可执行范围）。

---

9. 自检（规格成文时已核对）

• 无 TBD / 占位符。
• 与「仅 changeScene」「删整目录 Game/」无矛盾。
• 范围限于去旧与页面迁 BaseScene；未扩张到大型渲染重构。