From d5edb76f33331460e0746be986ea01611faff59a Mon Sep 17 00:00:00 2001 From: Council Date: Wed, 15 Apr 2026 08:03:37 +0800 Subject: [PATCH] docs: add guiding principle + Goods.php modification guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 核心原则：怎么快怎么来，怎么方便怎么来，少改动少复杂度，完全允许改核心 - README.md: 写入核心原则，更新技术发现，标注 Goods.php 方案为推荐 - docs/GOODS_PHP_MODIFICATION.md: 票务模板替换的具体修改步骤（Phase 2 关键文档） --- README.md | 58 +++++++++++---- docs/GOODS_PHP_MODIFICATION.md | 130 +++++++++++++++++++++++++++++++++ 2 files changed, 173 insertions(+), 15 deletions(-) create mode 100644 docs/GOODS_PHP_MODIFICATION.md diff --git a/README.md b/README.md index 2a3f894..0cf84b4 100644 --- a/README.md +++ b/README.md @@ -2,19 +2,33 @@ > 基于 ShopXO 生态的 VR 演唱会票务解决方案（Plan B） +--- + +## ⚡ 核心原则 + +**怎么快怎么来。怎么方便怎么来。尽可能少改动，少引入复杂度。但完全允许修改 ShopXO 核心代码。** + +- 我们是自己部署 ShopXO，核心代码完全可以改 +- 改动的优先级：改核心 < 用 Hook < 引入新复杂度 +- 改核心文件时，写清楚「升级 ShopXO 后需重新应用的位置」 + +--- + ## 核心能力 | 能力 | 实现方式 | |---|---| -| 场次管理 | 插件独立表 `vr_events` / `vr_sessions` | -| 商品详情页定制 | 30+ 钩子注入，或 1 行控制器代码替换模板 | +| 场次管理 | ShopXO spec = 场次（无需独立表） | +| 商品详情页定制 | **改 `Goods.php` 1 行** + 自定义模板 | | 选座 UI | 自定义 Vue 组件，Fork shopxo-uniapp | -| 观演人收集 | 插件钩子收集，下单时写入 `vr_tickets` 表 | -| QR 电子票 | ShopXO 内置 `\base\Qrcode` + phpqrcode | +| 观演人收集 | 插件钩子，下单时写入 `vr_tickets` 表 | +| QR 电子票 | 支付成功后钩子生成，AES 加密 | | 微信小程序 | shopxo-uniapp 已支持，HBuilderX 一键发行 | | B 端核销 | Fork `realstore/check/check.vue`，完整参考 | | 会员/积分/优惠券 | 全部复用 ShopXO 内置能力 | +--- + ## 快速开始 ```bash @@ -22,21 +36,30 @@ git clone http://xmhome.ow-my.com:3000/sileya-ai/vr-shopxo-plugin.git # 2. 上传插件到 ShopXO -cp -r vr-shopxo-plugin/app/plugins/vr_ticket /path/to/shopxo/app/plugins/ +cp -r vr_ticket /path/to/shopxo/app/plugins/ -# 3. 数据库迁移 -# 访问 /admin/plugins/vr_ticket/migrate 或手动执行 SQL +# 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 # 4. 后台安装 # 管理后台 → 应用中心 → 插件管理 → 安装 VR票务插件 -# 5. shopxo-uniapp 改造 +# 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 | @@ -46,22 +69,27 @@ cp -r vr-shopxo-plugin/app/plugins/vr_ticket /path/to/shopxo/app/plugins/ | **开发文档索引** | 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/OFFICIAL_DOCS.md](docs/OFFICIAL_DOCS.md) | ## 技术调研文档 -- [ShopXO 技术能力调研](docs/01_SHOPXO_TECHNICAL_RESEARCH.md) — DIY/CustomView/钩子/插件完整分析 -- [uni-app 前端定制](docs/02_FRONTEND_CUSTOMIZATION.md) — 小程序编译与自定义组件 -- [核销系统设计](docs/03_VERIFICATION_SYSTEM.md) — QR 生成/核销 API/票夹 -- [实施路线图](docs/04_IMPLEMENTATION_ROADMAP.md) — Agent 分工与开发计划 +- [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） +## 关键发现（2026-04-14/15） - ✅ ShopXO 内置 **CustomView Ace 编辑器**（全代码自定义页面） -- ✅ 商品详情页 **30+ 插件钩子**，最佳注入点 `plugins_view_goods_detail_base_sku_top` +- ✅ 商品详情页 **30+ 插件钩子** - ✅ shopxo-uniapp **已支持微信小程序**，条件编译已配置 - ✅ ShopXO 内置 **phpqrcode** QR 码生成库 - ✅ `realstore/check/check.vue` 是 **B 端核销页最佳参考** +- ✅ `site_type=3`（虚拟商品）可绕过地址选择弹出 +- ✅ ShopXO 完全支持修改核心代码（自己部署原则） +- ✅ **推荐：改 Goods.php 1 行**，比 Hook 方案更干净（符合核心原则） ## 项目状态 diff --git a/docs/GOODS_PHP_MODIFICATION.md b/docs/GOODS_PHP_MODIFICATION.md new file mode 100644 index 0000000..ae7e36c --- /dev/null +++ b/docs/GOODS_PHP_MODIFICATION.md @@ -0,0 +1,130 @@ +# Goods.php 票务模板替换修改 + +> ⚡ 核心原则：怎么快怎么来。改核心文件是允许的。 +> 适用范围：ShopXO v6.8.0，文件：`app/index/controller/Goods.php` + +--- + +## 修改位置 + +文件：`{SHOPXO_ROOT}/app/index/controller/Goods.php` +方法：`Index()`（商品详情页主方法） +位置：在 `return MyView();` 之前插入判断逻辑 + +--- + +## 修改内容 + +### 1. 在方法开头加载票务插件数据（可选，用于传递 venue_data 给模板） + +在 `$assign` 数组构建部分（约 line 110-130），在 `MyViewAssign($assign);` 之前加入： + +```php +// === VR票务插件：注入票务数据到模板 === +// 票务商品（item_type=ticket 或 venue_data 非空）注入座位图数据 +if (!empty($goods['venue_data']) || (isset($goods['item_type']) && $goods['item_type'] == 'ticket')) { + // 加载 vr_seat_templates 中的座位图配置 + $category_id = $goods['category_id'] ?? 0; + if ($category_id > 0) { + $seat_template = Db::name('plugins_vr_seat_templates') + ->where('category_id', $category_id) + ->where('status', 1) + ->find(); + if (!empty($seat_template)) { + $assign['vr_seat_template'] = $seat_template; + $assign['vr_is_ticket_goods'] = 1; + } + } +} +// === VR票务插件 END === +``` + +### 2. 在 `return MyView();` 之前加入模板判断（约 line 437-440） + +找到： +```php +// 商品详情 +$assign = array_merge($assign, GetGoodsDetails($goods_id, $params)); +MyViewAssign($assign); +return MyView(); +``` + +替换为： +```php +// 商品详情 +$assign = array_merge($assign, GetGoodsDetails($goods_id, $params)); +MyViewAssign($assign); + +// === VR票务插件：票务商品使用独立模板 === +// 判断依据：venue_data 非空 或 item_type == 'ticket' +$is_ticket = false; +if (!empty($assign['goods']['venue_data']) || !empty($assign['goods']['item_type'])) { + $is_ticket = ($assign['goods']['item_type'] ?? '') === 'ticket' + || !empty($assign['goods']['venue_data']); +} +if (!empty($is_ticket) && !empty($assign['vr_is_ticket_goods'])) { + return MyView('/goods/ticket_detail'); +} +// === VR票务插件 END === + +return MyView(); +``` + +--- + +## 新建票务模板文件 + +路径：`{SHOPXO_ROOT}/app/index/view/default/goods/ticket_detail.html` + +参考 `app/index/view/default/goods/detail.html`，重写以下部分： + +1. **隐藏**标准规格选择器（`.goods-detail-spec`） +2. **隐藏**原价/现价区域（`.goods-detail-panel-price`） +3. **隐藏**购物车/立即购买按钮（`.goods-detail-buy-nav`） +4. **注入**票务选座 UI（使用 `$vr_seat_template.seat_map` 数据） +5. **保留**商品相册、商品详情 tab、商品参数 tab + +--- + +## 升级 ShopXO 后的重应用步骤 + +当升级 ShopXO 后，此修改需要重新应用： + +1. 下载新版本 ShopXO +2. 对比旧版本 `app/index/controller/Goods.php` 和新版本，找到 `return MyView();` 的位置 +3. 重新应用上述修改 +4. 模板文件 `ticket_detail.html` 不受影响（独立文件） + +建议：将此修改内容写入 `docs/GOODS_PHP_MODIFICATION.md`，升级前对照检查。 + +--- + +## 为什么不只用 Hook？ + +Hook 方案（`plugins_view_goods_detail_base_sku_top` 注入）的缺点： +- 仍需加载完整标准模板（CSS/JS 全部加载） +- 需要 CSS 选择器隐藏标准元素（脆弱，ShopXO 升级后选择器可能失效） +- 注入位置固定，不够灵活 + +改 Goods.php 方案的优点： +- 1 行判断，模板完全自控 +- 零无用 CSS/JS 加载 +- 性能更好 + +--- + +## 备选方案：纯 Hook（ShopXO 升级时不需重应用） + +如果不修改 Goods.php，可用 Hook 方案（但需接受上述缺点）： + +```php +// config.json hook 注册 +"hook": { + "plugins_view_goods_detail_base_sku_top": [ + "\\app\\plugins\\vr_ticket\\view\\Goods::InjectTicketUI" + ], + "plugins_service_goods_data": [ + "\\app\\plugins\\vr_ticket\\service\\GoodsService::InjectVenueData" + ] +} +```