56 lines
2.0 KiB
Markdown
56 lines
2.0 KiB
Markdown
# 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
|
||
```
|