vr-shopxo-plugin/docs/VR_PLUGIN_REFACTOR_BRIEFING.md

# 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）：**
```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 官方插件开发手册 |