demo —— W-07 实时演示模块

用途

在元景（scense）平台中为世界（world）提供「实时演示」能力：编辑器点击「演示」进入预览态， 可在演示中实时编辑实体（前端 <1s 反映）、保存脚本即热加载、切换视角/暂停继续/全屏、 多人同时预览。演示期间的任何改动只落在演示覆盖层，结束演示后正式数据不变（状态隔离）。

功能点（W-07a ~ W-07j）

编号	功能	接口
W-07a	开始演示（进入预览态）	POST /demo/api/start.dspy
W-07b	结束演示（清理覆盖层）	POST /demo/api/stop.dspy
W-07c	编辑实体实时反映(<1s)	POST /demo/api/entity_edit.dspy
W-07d	脚本保存热加载	POST /demo/api/hotload.dspy
W-07e	视角切换	POST /demo/api/camera.dspy
W-07f	暂停/继续	POST /demo/api/pause.dspy
W-07g	全屏	POST /demo/api/fullscreen.dspy
W-07h	状态隔离（演示改动不污染正式数据）	覆盖层表 + stop 清理
W-07i	查看实体属性	POST /demo/api/entity_attrs.dspy
W-07j	多人预览	POST /demo/api/presence.dspy
-	状态轮询（500ms，<1s 反映）	POST /demo/api/state.dspy

数据表（models/*.json）

• demo_session：演示会话（status=preview/paused/ended，camera_mode，viewer_count，extra_json）
• demo_session_state：实体状态覆盖层（base_json=基线快照，demo_json=演示中当前值）
• demo_hot_script：演示中热加载脚本
• demo_presence：多人预览在线表

状态隔离原理

演示开始把实体当前状态复制为 base_json（只读基线）；演示中编辑只写 demo_session_state.demo_json， 从不写正式 entity/scene/world 表。stop_demo 删除会话+覆盖层+脚本+在线表 —— 正式数据零污染。

前端

• wwwroot/demo_viewer.ui + demo_viewer.js：three.js 渲染世界 + 500ms 轮询 state.dspy
• wwwroot/index.ui：模块入口卡片

安装 / 集成（Sage 宿主）

1. pip install .（模块包）
2. app/sage.py：from demo.init import load_demo + load_demo() 于 init()
3. build.sh：安装循环加入 demo；ln -sf <module>/wwwroot <sage>/wwwroot/demo
4. scripts/load_path.py：注册 RBAC（logined）；中央 load_path.py 同步登记
5. global_menu.ui：{"name":"demo","label":"实时演示","url":"{{entire_url('/demo/index.ui')}}","target":"app.sage_main_content"}
6. 部署库名由宿主 get_module_dbname('demo') 决定，模块内禁止硬编码 DBNAME

验收口径

• 启动/结束演示接口 200；演示中编辑实体前端 <1s 反映（500ms 轮询）；退出后正式 entity/world 数据不变
• 每个功能点正例 + 反例自测（见 skill/SKILL.md 与 docs/）