vr-shopxo-plugin/README.md

# 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](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)** | 开发日志（完整变更记录） |

### 🔧 实现参考

| 文档 | 说明 |
|------|------|
| [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 最新）

> 完整规格见 [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. 克隆
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 |