66 lines
3.6 KiB
Markdown
66 lines
3.6 KiB
Markdown
---
|
||
name: world_snapshot
|
||
description: 世界状态快照模块（W-03）——聚合 world/scene/entity 当前状态生成快照，支持查询与恢复，与 world 表状态联动。
|
||
---
|
||
|
||
# world_snapshot 模块
|
||
|
||
世界状态快照模块（W-03）。聚合世界（world）+ 场景（scene）+ 实体（entity）当前状态
|
||
生成快照写入 `snapshot_json`，支持分页查询、单条查询、更新、删除与恢复，恢复时联动
|
||
world 表状态（经 world 模块 set_world_mode 契约，保持模式流转校验完整）。
|
||
|
||
## 数据模型
|
||
|
||
表 `world_snapshot`（models/world_snapshot.json 四段式 summary/fields/indexes/codes）：
|
||
- id VARCHAR(32) PK（getID() 生成，禁 uuid）
|
||
- world_id VARCHAR(32) NOT NULL（codes → world 表）
|
||
- name VARCHAR(255) NOT NULL
|
||
- snapshot_type VARCHAR(32) DEFAULT 'full'（snapshot_type 编码字典 full/incremental）
|
||
- snapshot_json TEXT（聚合内容）
|
||
- status VARCHAR(32) DEFAULT 'active'（snapshot_status 编码字典 active/restored/invalid）
|
||
- snapshot_date date（业务日期仅到天）
|
||
- created_at timestamp NOT NULL
|
||
- 复合索引 idx_snapshot_world(world_id, snapshot_date)、idx_snapshot_list(world_id, status, created_at)
|
||
|
||
编码字典：init/data.json 幂等落库 `snapshot_type`（full=全量快照/incremental=增量快照）
|
||
与 `snapshot_status`（active=有效/restored=已恢复/invalid=失效），appcodes + appcodes_kv 同插。
|
||
|
||
## 关键接口（经 load_world_snapshot() 注册到 ServerEnv）
|
||
|
||
- `create_snapshot(params)` → 校验 world 存在、snapshot_type 白名单（full/incremental），
|
||
聚合 world/scene/entity 当前状态写入 snapshot_json，必设 snapshot_date/created_at
|
||
- `get_snapshot(params)` → 按 id 单条查询
|
||
- `list_snapshots(params)` → 分页 {list, total, page, page_size}；count 与数据查询分离，
|
||
显式列清单（排除 TEXT），P95 达标
|
||
- `update_snapshot(params)` → 部分更新（排除 id/created_at/snapshot_json/_text）
|
||
- `delete_snapshot(params)` → 按 id 删除
|
||
- `restore_snapshot(params)` → 校验 snapshot_json 合法性、标记 status=restored、
|
||
联动 world 状态（经 env.set_world_mode 契约，不存在或失败不阻断）
|
||
- 下拉：list_worlds_for_snapshot / list_snapshot_types / list_snapshot_statuses
|
||
|
||
REST 前缀 `/api/*`（wwwroot/api/*.dspy）：
|
||
- create_snapshot.dspy / snapshot_update.dspy / snapshot_delete.dspy
|
||
- get_snapshot.dspy / list_snapshots.dspy / restore_snapshot.dspy
|
||
- get_search_world.dspy / get_search_snapshot_type.dspy / get_search_status.dspy（下拉，返回 [{value,text}]，首项"全部"）
|
||
|
||
统一错误结构：`{code, message, field, detail}`；分页结构：`{list, total}`。
|
||
|
||
## 陷阱
|
||
|
||
- 库名禁止硬编码：.py 用 `ServerEnv().get_module_dbname('world_snapshot')`，.dspy 直接
|
||
`get_module_dbname('world_snapshot')`（预载全局）
|
||
- 无硬编码中文（错误消息用英文 code）；dspy 无 import（json/format_exc/debug/getID 等为预载全局）
|
||
- create_snapshot 必须设置 created_at/snapshot_date（sqlor 不自动补时间戳，缺 created_at 的
|
||
sor.C 会静默丢记录）
|
||
- snapshot_date 用 date 类型（业务日期仅到天）
|
||
- restore_snapshot 对 world 状态联动用契约调用（env.set_world_mode），不直接改 world 表，
|
||
保证 mode 流转规则校验不被绕过
|
||
- 下拉接口返回纯数组 [{value,text}]，错误时返回含"全部"的回退数组
|
||
|
||
## 依赖
|
||
|
||
- sqlor（DBPools/sqlExe/sor.C/U/D/R）
|
||
- ahserver（ServerEnv、get_module_dbname）
|
||
- appbase（appcodes/appcodes_kv 编码字典）
|
||
- world / scene / entity（聚合数据源，经各自模块库名读取，缺失时降级为空）
|