1

docs/technical/RUNTIME_PREVIEW_TEST_SAVE_ARCHIVE_ISOLATION_2026-04-26.md

@@ -0,0 +1,20 @@
+# 运行时预览与测试作品存档隔离（2026-04-26）
+
+## 背景
+
+幕预览和测试作品用于创作者检查玩法表现，不能被当作玩家正式游玩记录。若这类运行时复用正式 RPG 壳、story action 或 snapshot 接口，必须在进入个人存档页、游玩统计、作品游玩历史前被过滤。
+
+## 落地约束
+
+1. 前端预览态 `GameState` 必须写入 `runtimeMode: "preview"` 或 `runtimeMode: "test"`。
+2. 前端可同步写入 `runtimePersistenceDisabled: true` 作为更明确的禁存标记。
+3. `useRpgSessionPersistence` 自动存档必须跳过上述预览/测试态。
+4. runtime story 网关仍提交带禁存标记的 `snapshot`，避免服务端退回读取用户正式快照；服务端必须按禁存标记返回临时响应而不落库。
+5. SpacetimeDB projection 层必须兜底识别上述标记：即便有旧入口误写 `runtime_snapshot`，也不刷新 `profile_save_archive`、`profile_played_world`、`profile_dashboard_state` 和钱包流水。
+
+## 当前实现
+
+1. 幕预览运行时在启动游戏壳时写入 `runtimeMode: "preview"` 与 `runtimePersistenceDisabled: true`。
+2. 前端自动存档会跳过预览/测试态。
+3. runtime story 接口收到预览/测试快照时，只构造本次响应所需的临时 snapshot，不写入 `runtime_snapshot`。
+4. `server-rs/crates/spacetime-module/src/runtime/profile.rs` 在 profile projection 同步前统一短路预览/测试快照。