refactor: 拆分D2 Sleep表现并接入快照

Docs/D2Sleep表现系统拆分与存档重构方案.md

@@ -0,0 +1,130 @@
+# D2 Sleep 表现系统拆分与存档重构方案
+
+## 目标
+
+将 D2 Sleep 新增的轱辘、风筝、全屏序列帧、虚焦和门近景控制从通用 `SpriteShowcase` 中剥离，同时为通用图片与 D2 专属表现分别建立可扩展的语义快照。
+
+本次重构保持 Yarn 命令名、参数默认值、Addressable key、场景视觉参数和剧情文本不变。
+
+## 职责边界
+
+### SpriteShowcase
+
+只保留跨章节可复用的能力：
+
+- 普通小图显示、隐藏。
+- 普通大图显示、隐藏。
+- 背景淡入淡出。
+- 通用即时清理。
+- 通用图片终态的捕获与恢复。
+- 在图片切换、隐藏或清理前触发 `PresentationChanging`，通知场景专属表现清除叠加层。
+
+`SpriteShowcase` 不再持有 D2 配置、运行时节点、遮罩、序列帧协程、虚焦材质或 D2 Tween。
+
+### Day2SleepPresentationController
+
+D2 Sleep 场景级统一入口，负责：
+
+- 普通小图、轱辘、风筝和大图特效的互斥。
+- 监听 `SpriteShowcase.PresentationChanging` 并停止全部 D2 表现。
+- 为 Yarn 和 `DreamDoorSystem` 提供稳定 API。
+- 捕获、恢复 D2 专属表现的语义终态。
+
+内部 Presenter：
+
+| 类型 | 职责 |
+| --- | --- |
+| `ReelMotionPresenter` | 轱辘底图/运动层、SpriteMask、`reel_tension` 常驻拉锯循环 |
+| `KitePresentation` | 风筝相机节点、底图、遮罩、sway/accent 层、资源加载与显隐 |
+| `KiteRigDriver` | 风筝连续运动、风况、高度、镜头补偿与对焦算法 |
+| `LargeSpriteEffectsPresenter` | 全屏序列帧、虚焦、大图缩放/透明度及 Tween |
+
+## Yarn 与系统调用
+
+D2 专属命令移动到 `Day2SleepYarnCommand`：
+
+- `show_sprite_motion`
+- `sprite_motion`
+- `kite_show`
+- `kite_state`
+- `kite_wind`
+- `kite_accent`
+- `kite_hide`
+- `show_large_sprite_animation`
+- `set_large_sprite_blur`
+- `tween_large_sprite_blur`
+- `tween_large_sprite_blur_async`
+
+普通 `show_sprite`、`show_large_sprite`、`hide_*` 和 Showcase 背景命令仍由 `BaseYarnCommand` 调用 `SpriteShowcase`。
+
+`DreamDoorSystem` 的大图换图、近景缩放和透明度控制调用 `Day2SleepPresentationController`。Bloom、曝光、海浪和终端逻辑仍属于 `DreamDoorSystem`。
+
+## 存档模型
+
+存档只记录可重建的语义终态，不保存 Coroutine、Tween、运行时 GameObject、SpriteMask、材质实例或随机运动瞬时相位。
+
+### showcase section
+
+稳定 id：`showcase`，RestoreOrder：69。
+
+`ShowcaseSnapshotDto`：
+
+- `displayMode`：`None` / `Small` / `Large`。
+- `picName`：逻辑图片名，不保存加载后的 `Sprite`。
+- `isBackgroundVisible`：背景遮罩终态。
+
+恢复时通过 `ResourceSystem` 重新加载图片，并以 0 秒时长应用终态。
+
+### day2SleepPresentation section
+
+稳定 id：`day2SleepPresentation`，RestoreOrder：70。
+
+`Day2SleepPresentationSnapshotDto` 按模式保存：
+
+| 模式 | 保存内容 |
+| --- | --- |
+| `SmallMotion` | 图片名、motion profile |
+| `Kite` | 目标高度、风向、乱度 |
+| `LargeEffects` | 序列帧前缀/帧数/帧间隔、虚焦参数、缩放倍率、透明度 |
+
+`kite_accent` 属于一次性顿挫，不进入快照；轱辘和风筝的随机相位在恢复后从对应语义状态重新开始。
+
+若当前没有 D2 专属状态，Provider 返回 `null`，不写入该 section。通用大图叠加了 D2 虚焦或门近景效果时，会同时写入 `showcase` 与 `day2SleepPresentation`：先恢复底图，再恢复特效。
+
+### 恢复顺序
+
+相关表现 Provider 顺序为：
+
+1. `showcase`（69）：恢复普通底图和背景。
+2. `day2SleepPresentation`（70）：恢复 D2 动态层或大图特效。
+3. `playTool`（71）：恢复物品展示 UI。
+4. `screen`（80）：恢复饱和度和全屏遮罩。
+
+旧存档没有新增 section 时直接跳过，不提升 `schemaVersion`。旧 `showcase` JSON 中的额外字段由 Json.NET 忽略。
+
+## 场景迁移
+
+`梦境` 场景保留原 `SpriteShowcase` 组件及脚本 GUID，只留下三个 Renderer 引用。新增 `Day2SleepPresentationController`，迁移原对焦材质和三组风筝设置。轱辘、风筝和遮罩节点仍在运行时动态创建。
+
+## 生命周期清理
+
+- 普通图片切换前：`PresentationChanging` 清理 D2 表现。
+- D2 模式切换前：控制器清理普通图片与上一种 D2 表现。
+- 返回菜单、切章和读档前：`GameManager` 分别清理 D2 控制器与 `SpriteShowcase`。
+- 组件禁用或销毁：停止 Coroutine/Tween、隐藏运行时节点、关闭 SpriteMask，并恢复大图材质属性、缩放和透明度。
+
+## 验证范围
+
+- Unity 编译和现有 EditMode 测试通过。
+- FP/Fiction Day1 普通小图、大图和背景淡入淡出无回退。
+- D2 Sleep 轱辘、风筝、全屏序列帧、星图虚焦和 DreamDoor 近景表现保持一致。
+- 普通图片命令能中断并清理任意 D2 动效。
+- 通用小图/大图、风筝、轱辘、序列帧和大图特效可按快照恢复。
+- 返回菜单、切章、读档和重复进入梦境后没有残留动态节点、材质属性或 DOTween。
+
+## 不在本次范围
+
+- 不保存动画的逐帧进度、Tween 中间值或随机种子。
+- 不重构 Bloom、曝光和 `DreamDoorSystem` 自身状态机。
+- 不修改 Yarn 剧情内容或 `#line:` 标签。
+- 不修改现有资源名、Addressable key 和视觉参数。