sileya-ai
/
vr-shopxo-plugin
1
0
Fork 0
Code Issues 3 Pull Requests Packages Projects Releases Wiki Activity
vr-shopxo-plugin/docs/VR_PLUGIN_REFACTOR_BRIEFING.md

7.7 KiB
Raw Permalink Blame History

VR票务插件修复 — 任务简报

整理：西莉雅 时间：2026-04-16 CST 仓库：http://xmhome.ow-my.com:3000/sileya-ai/vr-shopxo-plugin

一、任务目标

将 vr_ticket 插件从 .backup_plugins/vr_ticket/ 迁移到 shopxo/app/plugins/vr_ticket/，使其能正常工作（参考已验证的 my_test_plugin 样本）。

二、当前环境（2026-04-16）

项目 值
ShopXO 版本 v6.8.0（官方最新）
数据库名 vrticket
表前缀 vrt_
后台入口 adminufgeyw.php
is_develop true
自定义菜单 shopxo/config/vrt_custom_menu.php（直接注入 sidebar，不走插件系统）
PHP 容器 shopxo-php（已重启生效）

三、参考样本：my_test_plugin（已验证工作正常）

文件结构：

shopxo/app/plugins/my_test_plugin/
├── Event.php              ← 事件回调（注意：不是 EventListener.php）
├── Hook.php               ← CSS/JS 钩子入口
├── config.json            ← 插件元数据（菜单通过 sidebar config 手动注入）
├── install.sql            ← 建表 SQL
├── uninstall.sql          ← 清理 SQL
├── admin/Admin.php        ← 所有后台控制器方法（单文件模式）
└── view/admin/admin/      ← 视图文件（3个 HTML）
    ├── index.html
    ├── form.html
    ├── layout.html
    └── buttons.html

关键配置（config.json）：

{
    "base": {
        "plugins": "my_test_plugin",
        "name": "我的测试插件",
        "version": "1.0.0"
    },
    "hook": {
        "plugins_css": ["app\\plugins\\my_test_plugin\\Hook"],
        "plugins_js":  ["app\\plugins\\my_test_plugin\\Hook"]
    }
}

路由机制（已验证）：

  • URL: /adminufgeyw.php?s=plugins/index/pluginsname/my_test_plugin/pluginscontrol/admin/pluginsaction/index
  • ShopXO 解析：pluginsname=my_test_plugin, pluginscontrol=admin, pluginsaction=index
  • ThinkPHP PSR-4：\app\plugins\my_test_plugin\admin\Admin::Index()
  • 映射文件：app/plugins/my_test_plugin/admin/Admin.php ✓

视图路径（已验证）：

  • ThinkPHP 解析：return view('/plugins/view/my_test_plugin/admin/view/admin/index');
  • 映射文件：app/plugins/my_test_plugin/view/admin/admin/index.html ✓

四、vr_ticket 插件现状（.backup_plugins/vr_ticket/）

4.1 文件结构

.backup_plugins/vr_ticket/
├── EventListener.php          ← ❌ 错误：ShopXO 规范文件名是 Event.php
├── plugin.json                ← 插件元数据
├── app.php                    ← 插件主入口
├── README.md
├── database/migrations/
│   ├── 001_vr_tables.sql      ← 建表 SQL（注意表名前缀）
│   └── fix_garbled_name.sql
├── service/
│   ├── BaseService.php
│   ├── TicketService.php
│   ├── SeatSkuService.php
│   └── AuditService.php
├── admin/
│   ├── Admin.php               ← 旧版单文件模式（已废弃）
│   ├── controller/
│   │   ├── Base.php
│   │   ├── Plugins.php
│   │   ├── SeatTemplate.php
│   │   ├── Ticket.php
│   │   ├── Venue.php
│   │   ├── Verification.php
│   │   └── Verifier.php
│   ├── seat_template/         ← ❌ 错误目录结构
│   ├── ticket/
│   ├── venue/
│   ├── verification/
│   ├── verifier/
│   └── view/                   ← ❌ 旧视图路径（view/admin/view/...）
│       ├── seat_template/list.html
│       ├── seat_template/save.html
│       ├── ticket/detail.html
│       ├── ticket/list.html
│       ├── venue/list.html
│       ├── venue/save.html
│       ├── verification/list.html
│       ├── verifier/list.html
│       └── verifier/save.html
└── view/goods/
    └── ticket_detail.html      ← 前端票务详情页（正确）

4.2 已知问题清单

# 问题 严重性 修复方向
1 EventListener.php → 应改为 Event.php 🔴 致命 重命名文件
2 表名 plugins_vr_xxx → 应为 vrt_vr_xxx（实际前缀是 vrt_，不是 plugins_） 🔴 致命 全局替换所有 Db::name() 和 SQL
3 admin/view/xxx/yyy.html → 应为 view/admin/admin/xxx.html 🔴 致命 重组视图目录结构
4 视图中的 return view('/plugins/view/vr_ticket/admin/view/...') 路径需重新核对 🔴 致命 对照 my_test_plugin 修正路径
5 plugin.json 的 menus 配置在当前环境不生效（sidebar 加载问题） 🟡 中等 暂不使用 menus，用 vrt_custom_menu.php 注入
6 admin/controller/ 目录下有多个独立控制器文件（旧结构） 🟡 中等 统一为单文件 Admin.php 模式
7 Venue.php 控制器有重复实现（Admin.php 里也有 VenueList/VenueSave） 🟡 中等 清理冗余，统一到 Admin.php
8 Base.php 控制器基类存在但鉴权链已修复（继承 Common） 🟢 轻微 确认 Base.php 正确继承 Common

五、数据库表结构（来自 001_vr_tables.sql）

表前缀：vrt_（不是 plugins_vr_）

  • vrt_vr_seat_templates — 座位模板（seat_map JSON）
  • vrt_vr_tickets — 电子票（ticket_code / qr_data / seat_info）
  • vrt_vr_verifiers — 核销员（user_id 关联 ShopXO 用户）
  • vrt_vr_verifications — 核销记录（ticket_id / verifier_id）
  • vrt_vr_audit_log — 审计日志（action/operator/target）

注意：ShopXO Db::name() 的表名映射规则是：去掉前缀部分后拼接。即 Db::name('plugins_vr_seat_templates') → 实际查 vrt_plugins_vr_seat_templates（表不存在）。正确写法：Db::name('vr_seat_templates') → vrt_vr_seat_templates。

六、修复任务清单

P0 — 必须修复（插件能跑起来）

  • 重命名 EventListener.php → Event.php
  • 统一为 admin/Admin.php 单文件控制器模式（参考 my_test_plugin）
  • 重组视图目录：view/admin/admin/{功能}/{action}.html
  • 修正所有 Db::name('plugins_vr_xxx') → Db::name('vr_xxx')
  • 修正 SQL 文件中的表名（vrt_plugins_vr_ → vrt_vr_）
  • 在 vrt_custom_menu.php 添加 vr_ticket 菜单入口
  • 复制修复后的插件到 shopxo/app/plugins/vr_ticket/

P1 — 功能验证

  • 座位模板 CRUD（后台）
  • 电子票列表 + 票详情 + QR 显示
  • 核销员管理
  • 核销记录列表

P2 — 清理

  • 删除 admin/controller/ 旧文件
  • 删除 admin/seat_template/ 等错误目录
  • 更新 plugin.json（去除 menus，走 sidebar config）
  • 确认 plugin.json 的 plugins 名称字段与目录名一致

七、工作要求

  1. 工作留痕：所有修改记录保存到 shopxo/.edit-log/{date}/
  2. 分步提交：每完成一个 P0 子项 commit 一次，commit message 明确描述改动
  3. 二次审查：完成后提交给 Anthropic/Google 模型做二次 review
  4. 不走 Council 提交自动 merge：所有 commit 留在本地 worktree，由西莉娅手动审核后 push

八、关键文件索引

文件 说明
shopxo/app/plugins/my_test_plugin/ 已验证的工作样本
.backup_plugins/vr_ticket/ 需要修复的旧代码
shopxo/config/vrt_custom_menu.php 侧边栏菜单配置（参考格式）
shopxo/app/service/AdminPowerService.php 侧边栏注入代码位置（第 598 行）
shopxo/public/static/common/iconfont/iconfont.css 可用图标列表（534个）
docs/插件手册.md ShopXO 官方插件开发手册