From 7f32ad87c23cc20fa2201903067ca06f7d10e55b Mon Sep 17 00:00:00 2001
From: Council <council@openclaw>
Date: Mon, 20 Apr 2026 09:25:01 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20README=20=E9=87=8D=E6=9E=84=20+=20VR=5F?=
 =?UTF-8?q?GOODS=5FCONFIG=5FSPEC.md=20=E5=8A=A0=E7=9B=AE=E5=BD=95=20+=20?=
 =?UTF-8?q?=E8=BF=BD=E5=8A=A0=E5=BC=80=E5=8F=91=E6=97=A5=E5=BF=97=E7=AC=AC?=
 =?UTF-8?q?=E5=8D=81=E4=B8=89=E7=AB=A0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- README: 新增清晰文档索引（必读/实现参考/调研存档/历史存档四分类）
- VR_GOODS_CONFIG_SPEC.md: 加 Markdown TOC
- DEVELOPMENT_LOG.md: 追加第十三章（模板渲染修复 + v3.0 格式确认）
---
 README.md                    | 174 ++++++++++++++++++++---------------
 docs/DEVELOPMENT_LOG.md      |  79 ++++++++++++++++
 docs/VR_GOODS_CONFIG_SPEC.md |  10 ++
 3 files changed, 189 insertions(+), 74 deletions(-)

diff --git a/README.md b/README.md
index 4bb9763..2c779ee 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,7 @@
 # VR票务插件 for ShopXO
 
 > 基于 ShopXO 生态的 VR 演唱会票务解决方案（Plan B）
+> 仓库：`http://xmhome.ow-my.com:3000/sileya-ai/vr-shopxo-plugin`
 
 ---
 
@@ -14,104 +15,129 @@
 
 ---
 
-## ⚠️ 踩坑经验（接手本插件前必读）
+## 📚 文档索引
 
-> 本插件经历了一整夜重构调试，发现了大量反直觉的坑。**任何 agent 或开发者接手前，请先阅读这份经验文档，避免重蹈覆辙。**
+### 🔴 必读
 
-📋 **[docs/EXPERIENCES.md](docs/EXPERIENCES.md)** — ShopXO 插件踩坑经验全记录（16条核心教训）
+| 文档 | 说明 |
+|------|------|
+| **[docs/VR_GOODS_CONFIG_SPEC.md](docs/VR_GOODS_CONFIG_SPEC.md)** | ⚠️ **vr_goods_config JSON 格式 v3.0 完整规格**（商品配置核心） |
+| **[docs/PHASE2_PLAN.md](docs/PHASE2_PLAN.md)** | Phase 2 当前状态 + 下一步工作计划 |
+| **[docs/EXPERIENCES.md](docs/EXPERIENCES.md)** | ⚠️ **踩坑经验（必读）** — 16条核心教训 |
+| **[docs/DEVELOPMENT_LOG.md](docs/DEVELOPMENT_LOG.md)** | 开发日志（完整变更记录） |
 
-> **最关键的3条**：
-> 1. `{{:ModuleInclude('public/footer')}}` 缺失 → 页面无限加载（不是后端死循环）
-> 2. Vue 3 `[[ ]]` 插值禁止用于 `<textarea>`（导致浏览器卡死）
-> 3. 字段名不能猜，必须查源码（已有人踩过）
+### 🔧 实现参考
+
+| 文档 | 说明 |
+|------|------|
+| [docs/GOODS_PHP_MODIFICATION.md](docs/GOODS_PHP_MODIFICATION.md) | Goods.php 1行改动说明 |
+| [docs/09_SHOPXO_HOOKS_REFERENCE.md](docs/09_SHOPXO_HOOKS_REFERENCE.md) | ShopXO 全部钩子清单（从源码提取） |
+| [docs/07_SHOPXO_PLUGIN_MECHANISM.md](docs/07_SHOPXO_PLUGIN_MECHANISM.md) | 插件开发机制 |
+| [docs/08_SHOPXO_REQUIREMENTS_MAPPING.md](docs/08_SHOPXO_REQUIREMENTS_MAPPING.md) | 票务需求 → ShopXO 机制映射 |
+
+### 📖 调研存档
+
+| 文档 | 说明 |
+|------|------|
+| [docs/01_SHOPXO_TECHNICAL_RESEARCH.md](docs/01_SHOPXO_TECHNICAL_RESEARCH.md) | ShopXO 技术能力调研 |
+| [docs/02_FRONTEND_CUSTOMIZATION.md](docs/02_FRONTEND_CUSTOMIZATION.md) | uni-app 前端定制 |
+| [docs/03_VERIFICATION_SYSTEM.md](docs/03_VERIFICATION_SYSTEM.md) | 核销系统设计 |
+| [docs/06_SEAT_MAP_INTEGRATION.md](docs/06_SEAT_MAP_INTEGRATION.md) | 座位图集成 |
+| [docs/14_TEMPLATE_RENDER_INVESTIGATION.md](docs/14_TEMPLATE_RENDER_INVESTIGATION.md) | 模板渲染调研 |
+| [docs/COUNCIL_EVALUATION_REPORT.md](docs/COUNCIL_EVALUATION_REPORT.md) | Council 安全评审报告 |
+
+### 🗂️ 历史存档（已过时，仅供参考）
+
+| 文档 | 说明 |
+|------|------|
+| `docs/ALIGNMENT.md` | 早期规划对齐记录 |
+| `docs/SPEC_DESIGN_DECISION.md` | 早期设计决策 |
+| `docs/ROUND2_ANALYSIS.md` | 第二轮分析 |
+| `docs/VR_PLUGIN_REFACTOR_BRIEFING.md` | 重构简报 |
+| `docs/PHASE2_RESEARCH_ARCHIVE.md` | Phase 2 调研存档 |
+| `docs/PHASE2_DEVELOPMENT_LOG.md` | Phase 2 旧版开发日志 |
 
 ---
 
-## 核心能力
+## 🗺️ vr_goods_config JSON 结构（v3.0 最新）
 
-| 能力 | 实现方式 |
-|---|---|
-| 场次管理 | ShopXO spec = 场次（无需独立表） |
-| 商品详情页定制 | **改 `Goods.php` 1 行** + 自定义模板 |
-| 选座 UI | 自定义 Vue 组件，Fork shopxo-uniapp |
-| 观演人收集 | 插件钩子，下单时写入 `vr_tickets` 表 |
-| QR 电子票 | 支付成功后钩子生成，AES 加密 |
-| 微信小程序 | shopxo-uniapp 已支持，HBuilderX 一键发行 |
-| B 端核销 | Fork `realstore/check/check.vue`，完整参考 |
-| 会员/积分/优惠券 | 全部复用 ShopXO 内置能力 |
+> 完整规格见 [docs/VR_GOODS_CONFIG_SPEC.md](docs/VR_GOODS_CONFIG_SPEC.md)
+
+```json
+{
+  "version": 3.0,
+  "template_id": 4,
+  "selected_rooms": ["room_id_xxx"],
+  "selected_sections": { "room_id_xxx": ["A", "B"] },
+  "sessions": [{ "start": "15:00", "end": "16:59" }],
+  "template_snapshot": {
+    "venue": { "name": "...", "address": "...", "location": {}, "images": [] },
+    "rooms": [{ "id": "...", "name": "...", "map": [...], "sections": [...], "seats": {...} }]
+  }
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `version` | 协议版本（当前 3.0） |
+| `template_id` | 发布/编辑时读取最新 vr_seat_templates 的依据 |
+| `selected_rooms` | 用户选择：启用了哪些演播 |
+| `selected_sections` | 用户选择：key=房间ID，value=该房间选中的分区字符数组 |
+| `sessions` | 用户管理的场次列表 |
+| `template_snapshot` | 发布时从 vr_seat_templates 读取并存储的快照（含 venue + rooms） |
 
 ---
 
-## 快速开始
+## 🏗️ 项目状态
+
+| 阶段 | 状态 | 说明 |
+|------|------|------|
+| Phase 1 | ✅ 完成 | 商品详情页座位图 + 观演人表单 + 模板渲染 |
+| **Phase 2** | 🔜 **进行中** | Issue #13：vr_goods_config v3.0 落地 |
+| Phase 3 | ❌ 未开始 | 核销 API + 后台 4 控制器联调 |
+
+**Phase 2 当前工作**：[Issue #13](http://xmhome.gitop.top:3000/sileya-ai/vr-shopxo-plugin/issues/13) — vr_goods_config v3.0 落地实现
+
+---
+
+## ⚠️ 踩坑经验（接手前必读）
+
+> 完整列表见 [docs/EXPERIENCES.md](docs/EXPERIENCES.md)
+
+1. ThinkTemplate `{include file="..."}` 在 Linux 下因 `view_depr=/` 导致路径拼接错误 → 改用 PHP `ModuleInclude()`
+2. Vue 3 `[[ ]]` 插值禁止用于 `<textarea>` → 浏览器卡死
+3. 字段名不能猜，必须查源码
+4. ShopXO `MyView()` 加载插件模板时 view_path 被覆盖 → 影响 ModuleInclude 解析
+
+---
+
+## 🚀 快速开始
 
 ```bash
-# 1. 克隆本仓库
+# 1. 克隆
 git clone http://xmhome.ow-my.com:3000/sileya-ai/vr-shopxo-plugin.git
 
-# 2. 上传插件到 ShopXO
+# 2. 上传插件
 cp -r vr_ticket /path/to/shopxo/app/plugins/
 
-# 3. 数据库迁移（Phase 1）
-mysql -u root -p < database/migrations/001_vr_seat_templates.sql
-mysql -u root -p < database/migrations/002_vr_tickets.sql
-mysql -u root -p < database/migrations/003_vr_verifiers.sql
-mysql -u root -p < database/migrations/004_vr_verifications.sql
+# 3. 数据库迁移
+mysql -u root -p < app/plugins/vr_ticket/install.sql
 
-# 4. 后台安装
+# 4. 修改 Goods.php（让 ShopXO 加载票务详情页）
+# 详见 docs/GOODS_PHP_MODIFICATION.md
+
+# 5. 后台安装
 # 管理后台 → 应用中心 → 插件管理 → 安装 VR票务插件
-
-# 5. 修改 Goods.php（Phase 2）
-# 在 ShopXO 源码 app/index/controller/Goods.php 的 Index() 方法中：
-# 在 return MyView(); 之前加入 ticket 类型判断（见 docs/GOODS_PHP_MODIFICATION.md）
-
-# 6. shopxo-uniapp 改造
-# HBuilderX 导入 shopxo-uniapp
-# 添加 pages/ticket-buy/ 和 pages/ticket-verify/
-# 配置 manifest.json 的 AppID
-# 发行 → 微信小程序
 ```
 
 ---
 
-## 官方文档（开发前必查）
+## 官方文档
 
 | 资源 | URL |
 |---|---|
 | 官方文档首页 | https://doc.shopxo.net/ |
-| **插件开发文档** | https://doc.shopxo.net/article/3.html |
-| **开发文档索引** | https://doc.shopxo.net/article/4.html |
+| 插件开发文档 | https://doc.shopxo.net/article/3.html |
+| 开发文档索引 | https://doc.shopxo.net/article/4.html |
 | uniapp 打包教程 | https://doc.shopxo.net/article/1/293727233598554112.html |
-| shopxo-uniapp Gitee | https://gitee.com/zongzhige/shopxo-uniapp |
-
-## 技术调研文档
-
-- [docs/EXPERIENCES.md](docs/EXPERIENCES.md) — ⚠️ **踩坑经验（必读）** — 16条核心教训
-- [docs/01_SHOPXO_TECHNICAL_RESEARCH.md](docs/01_SHOPXO_TECHNICAL_RESEARCH.md) — ShopXO 技术能力调研
-- [docs/02_FRONTEND_CUSTOMIZATION.md](docs/02_FRONTEND_CUSTOMIZATION.md) — uni-app 前端定制
-- [docs/03_VERIFICATION_SYSTEM.md](docs/03_VERIFICATION_SYSTEM.md) — 核销系统设计
-- [docs/04_IMPLEMENTATION_ROADMAP.md](docs/04_IMPLEMENTATION_ROADMAP.md) — 实施路线图
-- [docs/07_SHOPXO_PLUGIN_MECHANISM.md](docs/07_SHOPXO_PLUGIN_MECHANISM.md) — 插件开发机制
-- [docs/08_SHOPXO_REQUIREMENTS_MAPPING.md](docs/08_SHOPXO_REQUIREMENTS_MAPPING.md) — 票务需求 → ShopXO 机制映射
-- [docs/09_SHOPXO_HOOKS_REFERENCE.md](docs/09_SHOPXO_HOOKS_REFERENCE.md) — ShopXO 全部钩子清单（从源码提取）
-
-## 关键发现（2026-04-14/15）
-
-- ✅ ShopXO 内置 **CustomView Ace 编辑器**（全代码自定义页面）
-- ✅ 商品详情页 **30+ 插件钩子**
-- ✅ shopxo-uniapp **已支持微信小程序**，条件编译已配置
-- ✅ ShopXO 内置 **phpqrcode** QR 码生成库
-- ✅ `realstore/check/check.vue` 是 **B 端核销页最佳参考**
-- ✅ `site_type=3`（虚拟商品）可绕过地址选择弹出
-- ✅ ShopXO 完全支持修改核心代码（自己部署原则）
-- ✅ **推荐：改 Goods.php 1 行**，比 Hook 方案更干净（符合核心原则）
-
-## 项目状态
-
-✅ **Phase 1 完成**：商品详情页座位图 + 观演人表单
-🔜 **Phase 2 进行中**：后台管理（场馆/座位模板/电子票/核销员）
-  - ✅ 场馆 CRUD + Vue3 编辑器
-  - 🔜 后台管理添加商品 Hook（快速选择场馆信息）
-
-## 仓库地址
-
-`http://xmhome.ow-my.com:3000/sileya-ai/vr-shopxo-plugin`
+| shopxo-uniapp | https://gitee.com/zongzhige/shopxo-uniapp |
diff --git a/docs/DEVELOPMENT_LOG.md b/docs/DEVELOPMENT_LOG.md
index 605effd..dac77df 100644
--- a/docs/DEVELOPMENT_LOG.md
+++ b/docs/DEVELOPMENT_LOG.md
@@ -504,3 +504,82 @@ c894e7018 fix: 复制 ShopXO public 模板
 | 更新 ticket_detail.html JS（rooms[] 结构） | 待定 | GetGoodsViewData() 输出确定后 |
 | AdminGoodsSaveHandle SKU 生成 | 待定 | 新格式已确认 |
 | loadSoldSeats() 实现 | 待定 | vr_tickets 有数据后 |
+
+---
+
+## 十三、模板渲染修复 + vr_goods_config v3.0 格式确认（2026-04-20 上午）
+
+### 13.1 模板渲染修复
+
+**问题**：ThinkTemplate 的 `{include file="public/head"}` 在 Linux 下因 `view_depr=/` 导致路径拼接错误。
+
+**方案（路线 B）**：ThinkTemplate → PHP ModuleInclude：
+- `{include file=...}` → `<?php echo ModuleInclude(...) ?>`
+- `{:Config()} / {:IsMobileLogin()}` → `<?php echo Config() ?> / <?php echo IsMobileLogin() ?>`
+- `{$var|default='...'}` → `<?php echo $var ?? '...' ?>`
+- `{if}...{/if}` → `<?php if():?>...<?php endif;?>`
+
+复制 ShopXO `app/index/view/default/public/` → `plugins/vr_ticket/view/goods/public/`
+
+**提交记录**：
+```
+349ec063c fix: 替换 ThinkTemplate 标签为 PHP ModuleInclude
+c894e7018 fix: 复制 ShopXO public 模板 + 修复 footer_page 不存在问题
+1b0ac3276 fix: 替换为票务专用精简 footer（449行→53行）
+```
+
+### 13.2 vr_goods_config JSON 格式 v3.0 最终确认
+
+**变更历程**：
+- v2.0：rooms 直接嵌入，但 selected_sections 格式不确定
+- v3.0（最终）：增加 `template_snapshot` 字段，selected_sections 确认为对象格式
+
+**最终 v3.0 结构**：
+```json
+{
+  "version": 3.0,
+  "template_id": 4,
+  "selected_rooms": ["room_id_xxx"],
+  "selected_sections": { "room_id_xxx": ["A", "B"] },
+  "sessions": [{ "start": "15:00", "end": "16:59" }],
+  "template_snapshot": {
+    "venue": { ... },
+    "rooms": [{ "id": "...", "map": [...], "sections": [...], "seats": {...} }]
+  }
+}
+```
+
+**核心设计决策**：
+- `template_id`：发布/编辑时读取最新 vr_seat_templates 的依据
+- `template_snapshot`：发布时从 vr_seat_templates 读取并存储的快照，前端渲染数据来源
+- `selected_sections`：对象格式 `{ room_id: ["A","B"] }`（每个房间各自的选择）
+- `spec_base_id_map`：不入库，GetGoodsViewData 从 `goods_spec_base.extends->seat_key` 动态构建
+- `seat_key` 格式：`{roomId}_{rowLabel}_{colNum}`（无 MD5）
+- 现有前端编辑体验**完全不受影响**（前端只提交选择项，template_snapshot 由后端保存时填充）
+
+### 13.3 spec_base_id_map 断路问题
+
+**根因**：BatchGenerate 生成 GoodsSpecBase.id 后，从未写入 spec_base_id_map。
+
+**解决方案**：
+- BatchGenerate 写入 `goods_spec_base.extends.seat_key = "roomId_rowLabel_colNum"`
+- GetGoodsViewData 从 `extends.seat_key` 动态构建 `spec_base_id_map`
+
+### 13.4 Git 状态
+
+```
+741f25451 docs: v3.0 最终规格 - template_snapshot 字段 + selected_sections 对象格式
+6daa33232 docs: new vr_goods_config spec + Phase 2 v3.0 plan
+1b0ac3276 fix: 替换为票务专用精简 footer
+c894e7018 fix: 复制 ShopXO public 模板
+349ec063c fix: 替换 ThinkTemplate 标签为 PHP ModuleInclude
+7bd896764 feat(Phase 2): 完成票务商品前端展示层
+```
+
+### 13.5 Issue 记录
+
+- **Issue #13**：[P0] vr_goods_config v3.0 落地实现
+  - Step 1：AdminGoodsSaveHandle 填充 template_snapshot
+  - Step 2：BatchGenerate 写入 extends.seat_key
+  - Step 3：GetGoodsViewData 重写
+  - Step 4：ticket_detail.html JS seatKey 格式更新
diff --git a/docs/VR_GOODS_CONFIG_SPEC.md b/docs/VR_GOODS_CONFIG_SPEC.md
index 51ec6fe..34809e5 100644
--- a/docs/VR_GOODS_CONFIG_SPEC.md
+++ b/docs/VR_GOODS_CONFIG_SPEC.md
@@ -3,6 +3,16 @@
 > 版本：v3.0 | 日期：2026-04-20 | 状态：**已确认，待实现**
 > 关联 Issue：#13
 
+## 目录
+- [一、vr_goods_config 完整结构](#一vr_goods_config-完整结构)
+- [二、设计意图](#二设计意图)
+- [三、spec_base_id_map 生成与存储](#三spec_base_id_map-生成与存储)
+- [四、AdminGoodsSaveHandle 改动方案](#四admingoodsshandler-改动方案)
+- [五、前端数据结构](#五前端数据结构)
+- [六、需要修改的文件](#六需要修改的文件)
+- [七、降级兼容](#七降级兼容)
+- [八、已确认的设计决策](#八已确认的设计决策)
+
 ---
 
 ## ⚠️ v3.0 vs 旧版本的区别