49 lines
3.2 KiB
Markdown
49 lines
3.2 KiB
Markdown
# world_snapshot 模块开发（W-04 快照管理）— 工作日志
|
||
|
||
日期：2026-07-15（按当前系统日期）
|
||
模块仓库：`modules/world_snapshot/`（git 已 init）
|
||
任务：W-04 快照管理功能点开发（new_dev，迭代「元景项目-初始迭代」）
|
||
|
||
## 范围与背景
|
||
|
||
W-03 已有基础版 world_snapshot（简单 CRUD + 恢复），本次按 W-04 需求升级为完整快照管理：
|
||
|
||
1. **world_snapshot 表**：新增 `checksum`(sha256) 与 `version`(int) 字段；`(world_id, version)` 唯一索引
|
||
2. **快照生成**：同一事务批量聚合 world/scene/entity + checksum 数据一致性校验 + version 按世界递增（max+1，行锁 `for update` 防并发重复）
|
||
3. **快照恢复**：同一事务 checksum 校验 → 先删后插写回 scene/entity → 世界 mode 联动 → 置 restored；任一步失败整体回滚无脏数据
|
||
4. **编码字典**：snapshot_status / snapshot_type 经 `init/data.json` 幂等落库（appcodes 格式，parentid ≤22 字符约束满足）
|
||
5. **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），无硬编码
|
||
|
||
## 验证
|
||
|
||
- init/data.json 用 `json.load` 自验（合法 JSON，真实种子数据）
|
||
- models/world_snapshot.json 符合四段式（summary/fields/indexes/codes）
|
||
- .dspy 无 import（仅调用 load_*() 导出的函数），符合 dspy audit 规范
|
||
- .py 均用 sor.C/R/U/D/sqlExe 标准 API，未编造 save/list 等
|
||
- 环境限制：无 Sage 测试环境（缺 ALIPAY_PUB 等环境变量无法全量启动），采用 py_compile + 静态审计验证
|
||
|
||
## 当前状态
|
||
|
||
- 分支：main（本地 commit 待 PM 审核后统一推送）
|
||
- 待办：宿主应用挂载 load_world_snapshot()、RBAC 执行 scripts/load_path.py、部署后 curl 冒烟
|