# 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/）