world_snapshot/skill/SKILL.md

name	description
world_snapshot	世界状态快照模块（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（聚合数据源，经各自模块库名读取，缺失时降级为空）