VR票务插件 for ShopXO

基于 ShopXO 生态的 VR 演唱会票务解决方案（Plan B） 仓库：http://xmhome.ow-my.com:3000/sileya-ai/vr-shopxo-plugin

---

⚡ 核心原则

怎么快怎么来。怎么方便怎么来。尽可能少改动，少引入复杂度。但完全允许修改 ShopXO 核心代码。

• 我们是自己部署 ShopXO，核心代码完全可以改
• 改动的优先级：改核心 < 用 Hook < 引入新复杂度
• 改核心文件时，写清楚「升级 ShopXO 后需重新应用的位置」

---

📚 文档索引

🔴 必读

文档	说明
docs/VR_GOODS_CONFIG_SPEC.md	⚠️ vr_goods_config JSON 格式 v3.0 完整规格（商品配置核心）
docs/PHASE2_PLAN.md	Phase 2 当前状态 + 下一步工作计划
docs/PHASE_B_2026-04-25_PLAN.md	🔴 Phase B：B端核销开发计划（安全基线 + 核心核销页 + 辅助管理页）
docs/EXPERIENCES.md	⚠️ 踩坑经验（必读） — 18条核心教训
docs/DEVELOPMENT_LOG.md	开发日志（完整变更记录）

🔧 实现参考

文档	说明
docs/DEVELOPMENT_GUIDELINES.md	⚠️ 插件开发规范（静态文件引用、$public_host、铁律、pre-commit 自检）
docs/GOODS_PHP_MODIFICATION.md	Goods.php 1行改动说明
docs/09_SHOPXO_HOOKS_REFERENCE.md	ShopXO 全部钩子清单（从源码提取）
docs/07_SHOPXO_PLUGIN_MECHANISM.md	插件开发机制
docs/08_SHOPXO_REQUIREMENTS_MAPPING.md	票务需求 → ShopXO 机制映射
docs/DEBUG_STATIC_FILE_SYNC.md	⚠️ 插件静态文件双目录陷阱（app/ vs public/）

📖 调研存档

文档	说明
docs/01_SHOPXO_TECHNICAL_RESEARCH.md	ShopXO 技术能力调研
docs/02_FRONTEND_CUSTOMIZATION.md	uni-app 前端定制
docs/03_VERIFICATION_SYSTEM.md	核销系统设计
docs/06_SEAT_MAP_INTEGRATION.md	座位图集成
docs/14_TEMPLATE_RENDER_INVESTIGATION.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 最新）

完整规格见 docs/VR_GOODS_CONFIG_SPEC.md

{
  "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	✅ 完成	vr_goods_config v3.0 + C端票夹 + 出票链路
Phase 3	🔜 下一步	B端核销开发（docs/PHASE_B_2026-04-25_PLAN.md）

当前主线：docs/PHASE_B_2026-04-25_PLAN.md — B端核销 + 安全修复（Council 执行中）

---

⚠️ 踩坑经验（接手前必读）

完整列表见 docs/EXPERIENCES.md

1. ThinkTemplate {include file="..."} 在 Linux 下因 view_depr=/ 导致路径拼接错误 → 改用 PHP ModuleInclude()
2. Vue 3 [[ ]] 插值禁止用于 <textarea> → 浏览器卡死
3. 字段名不能猜，必须查源码
4. ShopXO MyView() 加载插件模板时 view_path 被覆盖 → 影响 ModuleInclude 解析
5. ⚠️ 插件静态文件双目录陷阱：app/（PHP runtime）和 public/（Nginx webroot）各有一份副本，修改后必须同步 → docs/DEBUG_STATIC_FILE_SYNC.md

---

🚀 快速开始

# 1. 克隆
git clone http://xmhome.ow-my.com:3000/sileya-ai/vr-shopxo-plugin.git

# 2. 上传插件
cp -r vr_ticket /path/to/shopxo/app/plugins/

# 3. 数据库迁移
mysql -u root -p < app/plugins/vr_ticket/install.sql

# 4. 修改 Goods.php（让 ShopXO 加载票务详情页）
# 详见 docs/GOODS_PHP_MODIFICATION.md

# 5. 后台安装
# 管理后台 → 应用中心 → 插件管理 → 安装 VR票务插件

---

官方文档

资源	URL
官方文档首页	https://doc.shopxo.net/
插件开发文档	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	https://gitee.com/zongzhige/shopxo-uniapp