world_snapshot 模块开发（W-04 快照管理）— 工作日志

日期：2026-07-15（按当前系统日期）模块仓库：modules/world_snapshot/（git 已 init）任务：W-04 快照管理功能点开发（new_dev，迭代「元景项目-初始迭代」）

范围与背景

W-03 已有基础版 world_snapshot（简单 CRUD + 恢复），本次按 W-04 需求升级为完整快照管理：

world_snapshot 表：新增 checksum(sha256) 与 version(int) 字段；(world_id, version) 唯一索引
快照生成：同一事务批量聚合 world/scene/entity + checksum 数据一致性校验 + version 按世界递增（max+1，行锁 for update 防并发重复）
快照恢复：同一事务 checksum 校验 → 先删后插写回 scene/entity → 世界 mode 联动 → 置 restored；任一步失败整体回滚无脏数据
编码字典：snapshot_status / snapshot_type 经 init/data.json 幂等落库（appcodes 格式，parentid ≤22 字符约束满足）
REST 规范：统一前缀 /api/*（wwwroot/api/snapshot_*.dspy），错误结构 {code,message,field,detail}，分页 {list,total}，非法输入 100% 拦截不落库（白名单校验）

models/world_snapshot.json —— 表定义（checksum/version/唯一索引/codes 引用）
init/data.json —— 编码字典种子
world_snapshot/init.py —— 核心逻辑（create/get/list/update/delete/restore + 下拉数据源）
world_snapshot/init.py —— 包导出（三处注册同步）
json/world_snapshot.json —— CRUD 定义（editable + 顶层 new/update/delete/list_data_url）
wwwroot/api/*.dspy —— 9 个 REST 薄封装
wwwroot/index.ui / snapshot_generate.ui / snapshot_restore.ui —— 前端页面
scripts/load_path.py —— RBAC 显式注册（无通配符）
pyproject.toml / README.md / skill/SKILL.md

version 递增：select coalesce(max(version),0)+1 + 事务内 for update 行锁 world 行，配 (world_id,version) 唯一索引双保险，防并发重复
checksum 校验：sha256(snapshot_json)，生成时写入；查询/恢复时重算比对，不匹配返回 CHECKSUM_MISMATCH
恢复事务：_restore_children 先删后插（按 information_schema 字段过滤防脏列），异常冒泡 → sqlorContext 整体回滚
非法输入拦截：world_id 必填/长度、snapshot_type/status 白名单、page/page_size 整数化、name 长度，全部校验通过才落库
取库名：统一 ServerEnv().get_module_dbname('world_snapshot')（.py）与全局 get_module_dbname()（.dspy），无硬编码