vr-shopxo-plugin/plan.md

# vr-shopxo-plugin Phase 2 Bugfix — plan.md

> 版本：v1.0 | 日期：2026-04-16 | Agent：council/FrontendDev
> 背景：Phase 2 后台管理两个致命问题 — 侧栏乱码 + 路由无法渲染

---

## 问题总览

| # | 问题 | 症状 | 优先级 |
|---|------|------|--------|
| **P1** | 插件控制器路由无法渲染 | 内容区空白，"template not exists" | 高 |
| **P2** | 侧边栏插件名乱码 | `VR票务`（应为 `VR票务`） | 中 |

---

## P1 — 路由无法渲染问题

### 已知现象
- 访问 `adminwatekc.php?s=VrTicket/SeatTemplateList` → 侧栏正常，主内容区空白
- ShopXO `Plugins/Index` 控制器调用插件时有 `strtolower+ucfirst` 类名匹配问题
- 当前 `SeatTemplate.php` 在 `admin/controller/` 子目录

### 已知正确模式（freightfee/answers）
```
app/plugins/{plugin}/
├── Admin.php              ← 直接在插件根目录，继承 think\Controller
├── Hook.php
├── config.json
└── admin/view/...         ← 视图在 admin/view/ 子目录
```

### 当前 vr_ticket 结构（有问题）
```
app/plugins/vr_ticket/
├── admin/controller/SeatTemplate.php  ← ❌ 在子目录
└── admin/view/seat_template/list.html
```

### 任务清单

- [ ] **P1-T1**: 验证 `strtolower+ucfirst` 路由匹配机制
  - 检查 `app/plugins/Plugins.php` 中 Index 控制器如何拼装类名
  - 确认是否只匹配 `app/plugins/{plugin}/Admin.php`（根目录）
- [ ] **P1-T2**: 对比 Admin.php 根目录模式 vs 当前 admin/controller/ 子目录模式
  - 分析 ShopXO Plugins/Index 源码
  - 确认 `strtolower+ucfirst` 匹配规则
- [ ] **P1-T3**: 实施修复 — 新建 Admin.php 到插件根目录（参考 freightfee）
  - 重构 SeatTemplate/Ticket/Verification/Verifier 控制器到根目录 Admin.php
  - 确认继承 `think\Controller`
  - 参考 freightfee/answers/Admin.php 实现
- [ ] **P1-T4**: 验证修复后路由 `adminwatekc.php?s=VrTicket/SeatTemplateList` 能否正常渲染

---

## P2 — 侧栏插件名乱码问题

### 已知现象
- 侧栏显示：`VR票务`（应为 `VR票务`）
- 这是 UTF-8 字符串被当作 Latin1/ISO-8859-1 解码的结果
- 乱码规律：`票` (E7 A5 8A) → Latin1 解码为 `票务`

### 乱码根因假设
| 假设 | 可能性 | 验证方式 |
|------|--------|----------|
| 数据库 `vrt_power` 表 name 字段 latin1 编码存储 | 高 | 检查 MySQL `SHOW CREATE TABLE vrt_power` |
| 数据库连接 charset 不匹配 | 中 | 检查 ShopXO 数据库配置 charset |
| plugin.json 编码问题 | 低 | 检查 plugin.json 文件实际编码 |
| PHP 视图模板文件编码 | 低 | 检查 header.html/china.html 等 |

### 任务清单

- [ ] **P2-T1**: 确认乱码根因 — 检查 vrt_power 表结构
  - `SHOW CREATE TABLE vrt_power`
  - `SHOW FULL COLUMNS FROM vrt_power`
  - 确认 name 字段 charset 和 collate
- [ ] **P2-T2**: 如果是数据库 latin1 问题 — 修复方案
  - 方案A：ALTER TABLE 转换 latin1 → utf8mb4
  - 方案B：MySQL CONVERT/CAST 函数读取时转换
  - 方案C：PHP 层以 latin1 读出再转 utf8
- [ ] **P2-T3**: 如果是 plugin.json 问题 — 验证文件编码
  - `file --mime plugin.json`
  - 确认文件是 UTF-8 无 BOM

---

## 视图路径问题

### 问题描述
- 插件视图用 `../../../plugins/view/{plugin}/admin/xxx` 相对路径
- 在 Docker 容器内无法 resolve（绝对路径问题）

### 任务清单

- [ ] **P3-T1**: 确认 ShopXO 官方推荐的插件视图路径写法
  - 查找 ShopXO Plugins/Index 中 view() 方法如何拼接路径
  - 检查 freightfee 的 Admin.php 如何 return View()
- [ ] **P3-T2**: 确认 vr_ticket 视图路径在修复 Admin.php 后是否正确

---

## GitHub 参考插件

- [ ] **REF-T1**: 推荐 2-3 个有后台管理界面的 ShopXO 插件（GitHub 搜索）
  - 关键词：`shopxo plugin admin` site:github.com
  - 优先选：有完整 admin/view/ 和 Admin.php 的插件

---

## 阶段划分

| 阶段 | 内容 | 负责 |
|------|------|------|
| **Round 1（规划）** | 分析根因，制定修复方案 | FrontendDev |
| **Round 2（执行）** | 实施修复，截图验证 | FrontendDev |
| **Round 3（综合）** | 合并到 main，完整验证 | 所有成员 |

---

## 依赖关系

- P1-T1 必须先完成（P1-T3 依赖 T1/T2 的结论）
- P2-T1 必须先完成（确认根因后才能选修复方案）
- P3-T1 依赖 P1-T3（等 Admin.php 重构后再验证视图路径）

---

## 交付物

1. `council-output/PHASE2_BUGFIX.md` — 根因分析报告
2. 修复后的 `shopxo/app/plugins/vr_ticket/Admin.php`
3. 修复后的控制器和视图路径
4. 修复后的乱码问题（数据库层或配置层）

## 状态

| 任务 | 状态 | 备注 |
|------|------|------|
| P1-T1 | [Pending] | 需检查 Plugins.php 源码 |
| P1-T2 | [Pending] | 对比模式分析 |
| P1-T3 | [Pending] | 实施修复 |
| P1-T4 | [Pending] | 截图验证 |
| P2-T1 | [Pending] | 数据库编码确认 |
| P2-T2 | [Pending] | 数据库修复（如需要） |
| P2-T3 | [Pending] | plugin.json 验证（如需要） |
| P3-T1 | [Pending] | 视图路径机制分析 |
| REF-T1 | [Pending] | GitHub 参考插件 |