From 98bd6a52cfd51403d1fea6f2d7248691a8480119 Mon Sep 17 00:00:00 2001
From: Council <council@openclaw>
Date: Mon, 20 Apr 2026 09:43:29 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E5=85=85=20template=5Fsnapsho?=
 =?UTF-8?q?t=20=E5=89=8D=E7=AB=AFvs=E5=90=8E=E7=AB=AF=E8=81=8C=E8=B4=A3?=
 =?UTF-8?q?=E8=AF=B4=E6=98=8E=20+=20=E6=9B=B4=E6=96=B0=20Issue=20#13=20?=
 =?UTF-8?q?=E8=BF=9B=E5=BA=A6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/DEVELOPMENT_LOG.md      | 17 +++++++++++++++++
 docs/VR_GOODS_CONFIG_SPEC.md | 20 ++++++++++++++++++--
 2 files changed, 35 insertions(+), 2 deletions(-)

diff --git a/docs/DEVELOPMENT_LOG.md b/docs/DEVELOPMENT_LOG.md
index dac77df..4906863 100644
--- a/docs/DEVELOPMENT_LOG.md
+++ b/docs/DEVELOPMENT_LOG.md
@@ -583,3 +583,20 @@ c894e7018 fix: 复制 ShopXO public 模板
   - Step 2：BatchGenerate 写入 extends.seat_key
   - Step 3：GetGoodsViewData 重写
   - Step 4：ticket_detail.html JS seatKey 格式更新
+
+### 13.6 AdminGoodsSaveHandle template_snapshot 填充逻辑澄清
+
+**template_snapshot 的前端职责 vs 后端职责**：
+- **前端**（Admin 编辑页打开时）：用 `template_id` 读最新 vr_seat_templates，填充 `template_snapshot` 到表单数据，一并提交
+- **后端**（AdminGoodsSaveHandle save_thing_end）：检测 `template_snapshot` 是否缺失，若缺失则从 vr_seat_templates 读表填充，再写回 goods 表，然后 BatchGenerate
+
+这意味着：
+- `template_snapshot` 主要由**前端**在编辑页加载时填充
+- 后端只是兜底（兼容旧商品、或前端未传的情况）
+- BatchGenerate 仍读 `vr_seat_templates` 表（实时数据），不受 template_snapshot 影响
+- 前端展示用 `template_snapshot`，SKU 生成用 `vr_seat_templates`（数据层和展示层分离）
+
+**提交**：
+```
+bbea35d83 feat(AdminGoodsSaveHandle): 保存时自动填充 template_snapshot
+```
diff --git a/docs/VR_GOODS_CONFIG_SPEC.md b/docs/VR_GOODS_CONFIG_SPEC.md
index 34809e5..062ec33 100644
--- a/docs/VR_GOODS_CONFIG_SPEC.md
+++ b/docs/VR_GOODS_CONFIG_SPEC.md
@@ -104,10 +104,26 @@ key = 房间 ID，value = 该房间选中的分区字符数组。为什么用对
     4. BatchGenerate 生成 SKU
 ```
 
+### template_snapshot 的前端职责 vs 后端职责
+
+**前端职责（Admin 编辑页）**：
+- 用户打开新建/编辑页时，前端用 `template_id` 读取**最新** `vr_seat_templates`
+- 将 `venue` + `rooms` 快照填入 `template_snapshot`，随表单一起提交
+- 编辑过程中模板变化了？以打开页面时的快照为准，**不重新读**（避免不确定性）
+
+**后端职责（AdminGoodsSaveHandle）**：
+- 检测 `template_snapshot` 是否缺失，若缺失则从 `vr_seat_templates` 读表填充（兜底）
+- 将填充后的完整 config 写回 `goods.vr_goods_config`
+- 再执行 `BatchGenerate` 生成 SKU
+
+**数据层分离**：
+- `template_snapshot` → **前端渲染用**（展示层）
+- `vr_seat_templates` 实时读取 → **BatchGenerate 生成 SKU**（数据层）
+
 ### 现有前端兼容性
 
-- 前端只提交 `selected_rooms` / `selected_sections` / `sessions`，**不提交 `template_snapshot`**
-- `template_snapshot` 由后端在保存时自动填充
+- 前端在编辑页加载时填充 `template_snapshot` 并提交
+- `AdminGoodsSaveHandle` 若检测到未传则自动填充（兜底），完全透明
 - 现有商品编辑体验**完全不受影响**
 
 ### template_snapshot 的作用