world_snapshot/skill/SKILL.md

name	description
world_snapshot	世界状态快照模块（W-04 快照管理）——world_snapshot 表（checksum/version 递增）、快照生成（事务批量+checksum 一致性校验）、查询（分页 {list,total}）、恢复（事务回滚无脏数据）、编码字典 snapshot_status/snapshot_type 幂等落库、REST /api/* 统一前缀与错误结构 {code,message,field,detail}。

world_snapshot 模块（W-04 快照管理）

架构

world_snapshot 是域内业务模块：聚合 world/scene/entity 当前状态生成快照，支持查询与恢复。 通过 load_world_snapshot() 挂载到宿主应用（唯一集成点），无独立 app.py/端口。

数据模型

表 world_snapshot（models/world_snapshot.json）：

字段	类型	说明
id	str(32) PK	主键（getID）
world_id	str(32)	世界ID（关联 world）
name	str(255)	快照名称
snapshot_type	str(32)	full / incremental
snapshot_json	text	快照内容 JSON（world/scene/entity 聚合）
checksum	str(64)	sha256 校验和
version	int	快照版本，按 world 递增（max+1）
status	str(32)	active / restored / expired
snapshot_date	timestamp	快照日期
created_at / updated_at	timestamp	审计时间

唯一索引 uk_snap_world_version(world_id, version) 保证同世界版本不重复。

编码字典（init/data.json 幂等落库）：

• snapshot_status：active 生效中 / restored 已恢复 / expired 已过期
• snapshot_type：full 全量快照 / incremental 增量快照

核心逻辑

快照生成 create_snapshot

1. 输入白名单校验（world_id 必填且 ≤32、snapshot_type ∈ {full,incremental}、name ≤255）——非法输入 100% 拦截不落库
2. 同一事务内：select world ... for update 行锁该世界 → 批量聚合 scene/entity → 拼 snapshot_json → sha256 checksum
3. max(version)+1 递增（行锁 + 唯一索引双保险）
4. 事务提交；任何异常整体回滚，返回 {code,message,field,detail}

快照查询 get_snapshot / list_snapshots

• get：读单条，checksum 重算比对，不匹配返回 CHECKSUM_MISMATCH（数据损坏检测）
• list：分页 {list,total,page,page_size}；page/page_size 非整数、status/snapshot_type 不在白名单 → 拦截

快照恢复 restore_snapshot

1. 校验快照存在 + checksum 一致性
2. 同一事务内：先删后插写回 scene/entity（按目标表 information_schema 字段过滤防脏列）→ 更新 world.mode=active → 快照置 restored
3. 任一步异常 → 事务整体回滚，无脏数据

REST 端点（统一前缀 /api/*）

端点	方法	说明
/world_snapshot/api/snapshot_create.dspy	POST	生成快照
/world_snapshot/api/snapshot_get.dspy	GET/POST	查询单个（含 checksum 校验）
/world_snapshot/api/snapshot_list.dspy	GET/POST	分页列表 {list,total}
/world_snapshot/api/snapshot_update.dspy	POST	更新（白名单字段）
/world_snapshot/api/snapshot_delete.dspy	POST	删除快照记录
/world_snapshot/api/snapshot_restore.dspy	POST	恢复快照（事务回滚）
/world_snapshot/api/snapshot_types.dspy	GET	编码字典：快照类型 [{value,text}]
/world_snapshot/api/snapshot_statuses.dspy	GET	编码字典：快照状态 [{value,text}]
/world_snapshot/api/snapshot_worlds.dspy	GET	可选世界列表 [{value,text}]

成功结构：{"success":true, ...} 错误结构：{"code":"...","message":"...","field":"...","detail":"..."}

函数注册（三处同步）

world_snapshot/world_snapshot/init.py 实现 + world_snapshot/world_snapshot/__init__.py import + load_world_snapshot() 里 env.xxx = xxx。新增/删除函数必须三处同步。

陷阱

• 取库名禁止硬编码：.py 用 ServerEnv().get_module_dbname('world_snapshot')；.dspy 直接用全局 get_module_dbname()
• 事务 return 位置：return 必须在 async with 块外（块内 return 返回 None）
• sor.U 仅 2 参数：主键放 data 里；仅主键时校验非空更新字段
• sqlExe 必须带 ns：无参数查询也传 {}
• .dspy 禁止 import：函数经 load_*() 导出；预加载全局 json/debug/getID 等直接可用
• dbpools 单例 fork 陷阱：函数内 db = DBPools() 局部创建
• sor.C 不自动补 created_at：插入时显式设置 created_at/updated_at = curDateString()
• LIMIT/OFFSET 用整数：字符串会渲染成 LIMIT '5' 语法错误