---
name: world_snapshot
description: 世界状态快照模块（W-03）——聚合 world/scene/entity 当前状态生成快照，支持查询与恢复，与 world 表状态联动。
---

# world_snapshot 模块

世界状态快照模块（W-03）。聚合世界（world）+ 场景（scene）+ 实体（entity）当前状态
生成快照写入 `snapshot_json`，支持分页查询、单条查询、更新、删除与恢复，恢复时联动
world 表状态（经 world 模块 set_world_mode 契约，保持模式流转校验完整）。

## 数据模型

表 `world_snapshot`（models/world_snapshot.json 四段式 summary/fields/indexes/codes）：
- id VARCHAR(32) PK（getID() 生成，禁 uuid）
- world_id VARCHAR(32) NOT NULL（codes → world 表）
- name VARCHAR(255) NOT NULL
- snapshot_type VARCHAR(32) DEFAULT 'full'（snapshot_type 编码字典 full/incremental）
- snapshot_json TEXT（聚合内容）
- status VARCHAR(32) DEFAULT 'active'（snapshot_status 编码字典 active/restored/invalid）
- snapshot_date date（业务日期仅到天）
- created_at timestamp NOT NULL
- 复合索引 idx_snapshot_world(world_id, snapshot_date)、idx_snapshot_list(world_id, status, created_at)

编码字典：init/data.json 幂等落库 `snapshot_type`（full=全量快照/incremental=增量快照）
与 `snapshot_status`（active=有效/restored=已恢复/invalid=失效），appcodes + appcodes_kv 同插。

## 关键接口（经 load_world_snapshot() 注册到 ServerEnv）

- `create_snapshot(params)` → 校验 world 存在、snapshot_type 白名单（full/incremental），
  聚合 world/scene/entity 当前状态写入 snapshot_json，必设 snapshot_date/created_at
- `get_snapshot(params)` → 按 id 单条查询
- `list_snapshots(params)` → 分页 {list, total, page, page_size}；count 与数据查询分离，
  显式列清单（排除 TEXT），P95 达标
- `update_snapshot(params)` → 部分更新（排除 id/created_at/snapshot_json/_text）
- `delete_snapshot(params)` → 按 id 删除
- `restore_snapshot(params)` → 校验 snapshot_json 合法性、标记 status=restored、
  联动 world 状态（经 env.set_world_mode 契约，不存在或失败不阻断）
- 下拉：list_worlds_for_snapshot / list_snapshot_types / list_snapshot_statuses

REST 前缀 `/api/*`（wwwroot/api/*.dspy）：
- create_snapshot.dspy / snapshot_update.dspy / snapshot_delete.dspy
- get_snapshot.dspy / list_snapshots.dspy / restore_snapshot.dspy
- get_search_world.dspy / get_search_snapshot_type.dspy / get_search_status.dspy（下拉，返回 [{value,text}]，首项"全部"）

统一错误结构：`{code, message, field, detail}`；分页结构：`{list, total}`。

## 陷阱

- 库名禁止硬编码：.py 用 `ServerEnv().get_module_dbname('world_snapshot')`，.dspy 直接
  `get_module_dbname('world_snapshot')`（预载全局）
- 无硬编码中文（错误消息用英文 code）；dspy 无 import（json/format_exc/debug/getID 等为预载全局）
- create_snapshot 必须设置 created_at/snapshot_date（sqlor 不自动补时间戳，缺 created_at 的
  sor.C 会静默丢记录）
- snapshot_date 用 date 类型（业务日期仅到天）
- restore_snapshot 对 world 状态联动用契约调用（env.set_world_mode），不直接改 world 表，
  保证 mode 流转规则校验不被绕过
- 下拉接口返回纯数组 [{value,text}]，错误时返回含"全部"的回退数组

## 依赖

- sqlor（DBPools/sqlExe/sor.C/U/D/R）
- ahserver（ServerEnv、get_module_dbname）
- appbase（appcodes/appcodes_kv 编码字典）
- world / scene / entity（聚合数据源，经各自模块库名读取，缺失时降级为空）