# 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)`。

## 安装

```bash
pip install .            # 模块打包
```

宿主应用集成：

```python
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
```