world_snapshot 世界状态快照模块（W-04 快照管理）

用途

聚合 world/scene/entity 当前状态生成世界快照，支持分页查询、详情查看（checksum 一致性校验）、 更新、删除与恢复（事务写回 scene/entity，失败整体回滚无脏数据）。

功能

• 快照生成：同一事务批量聚合 world/scene/entity + sha256 checksum + version 按世界递增
• 快照查询：分页 {list,total}；单条含 checksum 数据一致性校验（损坏检测）
• 快照恢复：checksum 校验 → 先删后插写回 scene/entity → 世界状态联动；失败事务回滚
• 编码字典 snapshot_status / snapshot_type 经 init/data.json 幂等落库
• REST 统一前缀 /api/*，错误结构 {code,message,field,detail}，非法输入 100% 拦截不落库

数据表

world_snapshot：id(32 PK), world_id(32), name(255), snapshot_type(32), snapshot_json(text), checksum(64, sha256), version(int), status(32), snapshot_date(timestamp), created_at/updated_at(timestamp)。 唯一索引 (world_id, version)。

安装

pip install .            # 模块打包

宿主应用集成：

from world_snapshot.init import load_world_snapshot

def init():
    load_world_snapshot()

RBAC：python3 scripts/load_path.py（为 /world_snapshot/* 各 path 显式注册 logined 权限）。

REST 端点

见 skill/SKILL.md（/world_snapshot/api/snapshot_*.dspy 系列）。

目录

world_snapshot/
├── world_snapshot/        # Python 包（init.py 核心逻辑 + __init__.py）
├── models/                # world_snapshot.json 表定义
├── json/                  # world_snapshot.json CRUD 定义
├── init/data.json         # 编码字典种子（snapshot_status/snapshot_type）
├── wwwroot/               # index.ui + snapshot_generate/restore.ui + api/*.dspy
├── scripts/load_path.py   # RBAC 注册
├── skill/SKILL.md         # 模块技能文档
└── pyproject.toml