148 lines
6.0 KiB
Markdown
148 lines
6.0 KiB
Markdown
# 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/PHASE_B_2026-04-25_PLAN.md](docs/PHASE_B_2026-04-25_PLAN.md)** | 🔴 **Phase B：B端核销开发计划**（安全基线 + 核心核销页 + 辅助管理页） |
|
||
| **[docs/EXPERIENCES.md](docs/EXPERIENCES.md)** | ⚠️ **踩坑经验（必读）** — 18条核心教训 |
|
||
| **[docs/DEVELOPMENT_LOG.md](docs/DEVELOPMENT_LOG.md)** | 开发日志（完整变更记录） |
|
||
|
||
### 🔧 实现参考
|
||
|
||
| 文档 | 说明 |
|
||
|------|------|
|
||
| [docs/DEVELOPMENT_GUIDELINES.md](docs/DEVELOPMENT_GUIDELINES.md) | ⚠️ **插件开发规范**（静态文件引用、$public_host、铁律、pre-commit 自检） |
|
||
| [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/DEBUG_STATIC_FILE_SYNC.md](docs/DEBUG_STATIC_FILE_SYNC.md) | ⚠️ **插件静态文件双目录陷阱**（app/ vs public/）|
|
||
|
||
### 📖 调研存档
|
||
|
||
| 文档 | 说明 |
|
||
|------|------|
|
||
| [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 | ✅ 完成 | 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](docs/PHASE_B_2026-04-25_PLAN.md) — B端核销 + 安全修复（Council 执行中）
|
||
|
||
---
|
||
|
||
## ⚠️ 踩坑经验（接手前必读）
|
||
|
||
> 完整列表见 [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 解析
|
||
5. **⚠️ 插件静态文件双目录陷阱**：`app/`（PHP runtime）和 `public/`（Nginx webroot）各有一份副本，修改后必须同步 → [docs/DEBUG_STATIC_FILE_SYNC.md](docs/DEBUG_STATIC_FILE_SYNC.md)
|
||
|
||
---
|
||
|
||
## 🚀 快速开始
|
||
|
||
```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 |
|