diff --git a/docs/VR_PLUGIN_REFACTOR_BRIEFING.md b/docs/VR_PLUGIN_REFACTOR_BRIEFING.md new file mode 100644 index 0000000..d684e1f --- /dev/null +++ b/docs/VR_PLUGIN_REFACTOR_BRIEFING.md @@ -0,0 +1,196 @@ +# 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 官方插件开发手册 |