vr-shopxo-plugin/plan.md

# vr-shopxo-plugin Phase 2 后台管理 — 实施计划

> 版本：v1.0 | 制定日期：2026-04-15 | Agent：council/FrontendDev

---

## 目标概述

Phase 2 后台管理页面开发，涵盖：
1. 座位模板管理（CRUD）
2. 电子票列表 / 详情 / 导出
3. 核销员管理（增删改查）
4. 核销记录查询
5. Admin 控制器鉴权（P1 安全问题）

---

## 阶段划分

| Phase | 任务 | 状态 |
|---|---|---|
| **Phase 1** | 研究方向讨论（各 Agent 输出 Research Direction List） | [Done] |
| **Phase 2** | 资料收集 + 技术验证（阻塞性问题确认） | [In Progress] |
| **Phase 3** | 后台 API 设计 + 权限模型 | [Pending] |
| **Phase 4** | Admin 控制器实现 | [Pending] |
| **Phase 5** | 后台视图层（HTML）实现 | [Pending] |
| **Phase 6** | 核验与安全加固 | [Pending] |

---

## Round 2 代码研究结论（FrontendDev）

> ⚠️ **阻塞性问题已确认解决**：ShopXO 插件鉴权通过 `AdminService::LoginInfo()` 实现，`Base.php` 正确调用，无阻塞。

### 关键发现

#### FR-1 确认：Layui + 正确 URL 格式
- ShopXO v6.8.0 后台使用 **Layui**（非 Vue）
- 现有视图正确使用 `public/head` + `public/footer` 模板片段
- **URL 路由格式**：`PluginsAdminUrl('vr_ticket', 'seat_template', 'list')` 生成 `/admin/plugins/index?pluginsname=vr_ticket&pluginscontrol=seat_template&pluginsaction=list`
- ⚠️ **现有代码问题**：所有视图使用 `MyUrl('plugins_vr_ticket/admin/...')` 非标准格式，需统一改为 `PluginsAdminUrl()`
- ⚠️ **根目录 plugin.json 命名错误**：使用 `"name": "vr-ticket"` (连字符)，应为 `"vr_ticket"` (下划线)，与物理目录名一致

#### FR-2 确认：ShopXO Admin 风格规范
- 布局：`layui-fluid` → `layui-card` → `layui-card-header/body`
- 表格：`layui-table`，JS 中 `table.render({url: ..., cols: [[...]]})`
- 表单：`layui-form` + `layui-form-pane`
- 按钮：`layui-btn layui-btn-normal|primary|danger`
- 状态：`layui-badge layui-bg-green|blue|gray`

#### FR-3 待研究：座位图编辑器
- ⚠️ 现有 `seat_template/save.html` 为空，需补充座位图编辑器
- 建议：使用 Canvas 或 SVG 方案，参考开源 Vue/JS 库

#### FR-4 待改进：CSV 导出
- `Ticket::export()` 已实现，但无分页限制（大数据量 OOM 风险）
- 建议：使用流式导出 (`fputcsv`) 或后台队列

#### FR-5 待协同：权限控制
- `Base.php` 仅做 `IsLogin()` 检查，未做 `IsPower()` 权限校验
- 与 BackendArchitect + SecurityEngineer 协同确认权限模型

### 缺失的视图文件（需补充）

| 文件 | 状态 |
|------|------|
| `admin/view/verifier/list.html` | ❌ 不存在 |
| `admin/view/verifier/save.html` | ❌ 不存在 |
| `admin/view/ticket/detail.html` | ❌ 不存在 |
| `admin/view/seat_template/save.html` | ✅ 已存在（需补充座位图编辑器） |
| `admin/view/verification/list.html` | ✅ 已存在（Layui 日期选择器已集成） |

### 现有控制器完整性

| Controller | list | save | delete | detail | export |
|------------|------|------|--------|--------|--------|
| SeatTemplate | ✅ | ✅ | ✅ | — | — |
| Ticket | ✅ | — | — | ✅ | ✅ |
| Verifier | ✅ | ✅ | ✅ | — | — |
| Verification | ✅ | — | — | — | — |

---

## 任务清单

### 座位模板管理
- [x] 座位模板列表页（seat_template/list.html）— URL 修正完成
- [x] 座位模板新增/编辑页（seat_template/save.html）— URL 修正完成
- [ ] 座位图可视化编辑器集成
- [ ] 分类绑定功能（已支持，需需求确认）

### 电子票管理
- [x] 电子票列表页（ticket/list.html）— URL 修正完成
- [x] 票详情页（ticket/detail.html）— 新建完成
- [x] 批量导出功能（CSV）— URL 修正完成
- [x] 票状态筛选（未核销/已核销/已退款）— 已实现

### 核销员管理
- [x] 核销员列表页（verifier/list.html）— 新建完成
- [x] 核销员新增/编辑页（verifier/save.html）— 新建完成
- [x] 核销员禁用功能（verifier/delete）— 已实现（软禁用）
- [ ] 核销员绑定店铺/场次（需需求确认）

### 核销记录
- [x] 核销记录列表页（verification/list.html）— URL 修正完成
- [ ] 多条件查询（时间/核销员/场次）— 已实现基础功能
- [ ] 核销统计看板（待需求确认）

### Admin 鉴权（P1 安全）
- [x] 所有 Admin 控制器继承 Base controller（BackendArchitect 完成）
- [ ] 鉴权中间件验证（SecurityEngineer Task S1）
- [ ] 敏感操作日志审计（SecurityEngineer Task S4）

---

## Research Direction List（FrontendDev 输出）

### FR-1: ShopXO Admin UI 框架选型
**背景**：ShopXO 后台使用 Layui，需确认是否继续使用还是迁移 Vue。

**结论（Round 2 确认）**：
- ✅ ShopXO v6.8.0 后台使用 **Layui**（非 Vue），应继续使用以保持兼容性
- ✅ Layui 2.x + ThinkPHP 6 无冲突
- ✅ 正确 URL 生成方式：`PluginsAdminUrl('vr_ticket', 'controller', 'action')`
- ⚠️ 现有代码使用 `MyUrl('plugins_vr_ticket/admin/...')` 需统一修正

Key Questions:
- [x] ShopXO 官方后台（v6.8.0）使用的是什么 UI 版本？→ **Layui**
- [x] Layui 是否支持 Vue 3？如果不支持，混用 Vue + Layui 是否会导致冲突？→ **不使用 Vue 3，保持 Layui**
- [x] 票务插件是否应保持与 ShopXO 原生风格一致，还是可以独立升级？→ **保持一致**
- [ ] 是否有 ShopXO 插件使用 Vue 3 的先例？→ **未发现，建议不迁移**

### FR-2: 现有 ShopXO Admin 页面风格适配
**背景**：保持与 ShopXO 原生后台风格一致可降低学习成本。

**结论（Round 2 确认）**：
- ✅ 布局规范：`layui-fluid` → `layui-card` → `layui-card-header/body`
- ✅ 表格：`layui-table` + `table.render()`
- ✅ 表单：`layui-form` + `layui-form-pane`
- ✅ 按钮：`layui-btn` + 颜色类
- ✅ 状态：`layui-badge` + `layui-bg-green/blue/gray`
- ✅ 模板：`{include file="public/head" /}` + `{include file="public/footer" /}`

Key Questions:
- [x] ShopXO 后台使用的是什么设计系统（颜色/字体/间距规范）？→ **已确认上述规范**
- [x] 表格组件（数据列表）用的是 Layui table 还是自建？→ **Layui table**
- [x] 分页、筛选、搜索的通用组件封装在哪里？→ **Layui form + table 内置**
- [x] 弹窗/表单布局的规范是什么？→ **`layui-card` + `layui-form`**

### FR-3: 座位图编辑器集成方案
**背景**：座位模板需要可视化编辑，复杂度高。

Key Questions:
- [ ] 是否有开源的 Vue 座位图编辑器可以集成？→ **待调研**
- [ ] Canvas vs SVG vs CSS Grid，哪个方案最适合票务座位图？→ **待调研**
- [ ] 座位图编辑后如何序列化存储到 seat_map JSON？→ **已有 `plugins_vr_seat_templates.seat_map` 字段**
- [ ] 编辑器是否需要支持拖拽、分区着色、座位类型标注？→ **待需求确认**

### FR-4: 数据导出方案（CSV/Excel）
**背景**：电子票列表需要支持批量导出。

Key Questions:
- [ ] ShopXO 后台是否有现成的导出组件？→ **待调研**
- [ ] 大量数据（10000+ 条）导出的处理策略是什么（流式导出 vs 后台队列）？→ **已有 `ExportCsv()`，需改进流式处理**
- [ ] 是否需要支持 Excel 格式（.xlsx）还是只需 CSV？→ **待需求确认**
- [x] 导出字段如何与 vr_tickets 表字段对应？→ **`Ticket::export()` 已实现**

### FR-5: 响应式与权限控制
**背景**：后台页面需要同时支持不同屏幕和权限级别。

Key Questions:
- [ ] ShopXO 后台的权限体系是如何设计的（RBAC？按钮级？字段级？）？→ **待 BackendArchitect 确认**
- [ ] 票务管理员是否需要独立的角色？与 ShopXO 管理员如何隔离？→ **待 BackendArchitect + SecurityEngineer 协同**
- [ ] 后台页面是否需要支持移动端（PAD 核销场景）？→ **核销端考虑移动端，Admin 后台 PC 优先**
- [ ] 操作日志记录哪些字段（用户/时间/操作/IP/变更前后）？→ **待 SecurityEngineer 确认（Task S4）**

---

## 依赖关系

- FR-1、FR-2 优先完成，决定技术栈选型
- FR-3 依赖 FR-1 的选型结论
- FR-4 可在 Phase 3 后端 API 确定后并行进行
- FR-5 与 SecurityEngineer 协同，需要等 BackendArchitect 输出权限模型

---

## 进度追踪

| 任务 | 负责人 | 状态 |
|---|---|---|
| 座位模板管理 | [Pending] | - |
| 电子票管理 | [Pending] | - |
| 核销员管理 | [Pending] | - |
| 核销记录 | [Pending] | - |
| Admin 鉴权 | [Pending] | - |

---

## Round 3 执行总结（FrontendDev）

| 文件 | 操作 | 说明 |
|------|------|------|
| `seat_template/list.html` | 修正 URL | `MyUrl()` → `PluginsAdminUrl()` |
| `seat_template/save.html` | 修正 URL | 返回按钮 URL 修正 |
| `verification/list.html` | 修正 URL | `MyUrl()` → `PluginsAdminUrl()` |
| `ticket/list.html` | 修正 URL | `MyUrl()` → `PluginsAdminUrl()` |
| `ticket/detail.html` | 新建 | 完整票详情页（QR码/关联信息/状态） |
| `verifier/list.html` | 新建 | 核销员列表页（搜索/状态筛选/禁用） |
| `verifier/save.html` | 新建 | 核销员新增/编辑表单页 |
| `plan.md` | 更新 | 任务状态更新 |

**剩余待完成（FrontendDev）**：
- FR-3: 座位图可视化编辑器（需需求确认）
- FR-4: CSV 导出大数据量优化（BackendArchitect 已用 cursor 优化）
- seat_template/save.html 座位图编辑器集成

**待 SecurityEngineer 协同**：
- S1: 鉴权覆盖完整性验证
- S4: 审计日志设计

---

## 共识投票

[CONSENSUS: NO] — 核心视图层基本完成，座位图编辑器和安全任务待后续