249 lines
10 KiB
Markdown
249 lines
10 KiB
Markdown
# ShopXO VR票务插件 — 架构文档
|
||
|
||
> 版本：v1.1（2026-04-14 更新，整合 ShopXO 技术调研成果）
|
||
> 源码位置：council-research/shopxo-eval/.worktrees/shopxo-evaluator/shopxo-src/
|
||
|
||
## 项目概述
|
||
|
||
基于 ShopXO 生态的 VR 演唱会票务插件（Plan B）。
|
||
|
||
当 vr-ticket-mp 主线项目因维护成本或架构限制无法继续时，此插件作为 Plan B：
|
||
- **完全复用** ShopXO 已有能力（会员体系/积分/优惠券/微信支付）
|
||
- **仅扩展** 票务专属逻辑（场次/座位/观演人/QR核销）
|
||
- **不修改** ShopXO 核心代码，通过插件机制隔离
|
||
|
||
---
|
||
|
||
## 核心技术发现（2026-04-14 调研）
|
||
|
||
### 1. CustomView Ace 编辑器 ⭐
|
||
|
||
ShopXO 内置全代码自定义页面编辑器，HTML/CSS/JS 三栏，实时预览。
|
||
文件：`app/admin/view/default/customview/saveinfo.html`
|
||
访问：后台 → 营销 → 自定义页面管理
|
||
|
||
### 2. 商品详情页 30+ 钩子 ⭐
|
||
|
||
最佳注入点：`plugins_view_goods_detail_base_sku_top`（规格选择区顶部）
|
||
- 完全注入票务选座 UI
|
||
- 不修改核心代码
|
||
|
||
### 3. 按商品类型替换模板 ⭐
|
||
|
||
修改 `Goods.php Index()` 加 1 行判断：
|
||
```php
|
||
if($goods['item_type'] == 'ticket') {
|
||
return MyView('/goods/ticket_detail');
|
||
}
|
||
```
|
||
|
||
### 4. shopxo-uniapp 支持微信小程序 ⭐
|
||
|
||
HBuilderX 导入 → 配置 AppID → 发行 → 微信开发者工具
|
||
条件编译指令已配置（`#ifdef MP-WEIXIN`）
|
||
|
||
### 5. QR 码生成内置 ⭐
|
||
|
||
使用 `\base\Qrcode` 类 + phpqrcode 库：
|
||
```php
|
||
$qr_url = MyUrl('index/qrcode/index', ['content' => base64_encode($data)]);
|
||
```
|
||
|
||
### 6. 自提点核销页面可直接参考 ⭐
|
||
|
||
`pages/plugins/realstore/check/check.vue` — 完整 B 端核销 UI
|
||
- uni.scanCode 扫码
|
||
- 手动输入兼容
|
||
- 成功/失败状态展示
|
||
|
||
### 7. 订单 extension_data 存票务信息 ⭐
|
||
|
||
`sxo_order.extension_data` — JSON 扩展字段，可存核销状态
|
||
|
||
---
|
||
|
||
## 整体架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ ShopXO PHP 后端 │
|
||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────┐ │
|
||
│ │ 会员/积分 │ │ 商品/订单 │ │ 微信支付 │ │
|
||
│ │ coupons │ │ items/orders│ │ payment │ │
|
||
│ └──────────────┘ └──────────────┘ └──────────┘ │
|
||
│ │
|
||
│ ┌─────────────────────────────────────────────┐ │
|
||
│ │ vr_ticket 插件 │ │
|
||
│ │ ┌────────────────────────────────────────┐ │ │
|
||
│ │ │ EventService — 场次管理 │ │ │
|
||
│ │ │ TicketService — QR票生成/发放 │ │ │
|
||
│ │ │ VerifyService — 核销验证 │ │ │
|
||
│ │ └────────────────────────────────────────┘ │ │
|
||
│ │ ┌────────────────────────────────────────┐ │ │
|
||
│ │ │ 钩子: plugins_view_goods_detail_* │ │ │
|
||
│ │ │ 钩子: plugins_service_buy_order_* │ │ │
|
||
│ │ └────────────────────────────────────────┘ │ │
|
||
│ └─────────────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ shopxo-uniapp │
|
||
│ ┌──────────────┐ ┌──────────────────┐ │
|
||
│ │ 商品详情页 │ │ 票务选座页 │ ← Fork │
|
||
│ │goods-detail.vue│ │ ticket-buy.vue │ 自定义 │
|
||
│ └──────────────┘ └──────────────────┘ │
|
||
│ ┌──────────────┐ ┌──────────────────┐ │
|
||
│ │ 用户中心 │ │ 票夹页 │ ← 新建 │
|
||
│ │ user.vue │ │ ticket-wallet.vue│ │
|
||
│ └──────────────┘ └──────────────────┘ │
|
||
│ ┌──────────────┐ │
|
||
│ │ 核销页 │ ← Fork realstore/check.vue │
|
||
│ │ verify.vue │ │
|
||
│ └──────────────┘ │
|
||
└─────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 数据模型
|
||
|
||
### ShopXO 复用表
|
||
|
||
| 表 | 用途 |
|
||
|---|---|
|
||
| `sxo_user` | 会员 |
|
||
| `sxo_wallet` | 余额钱包 |
|
||
| `sxo_integral` | 积分 |
|
||
| `sxo_coupon` | 优惠券 |
|
||
| `sxo_order` | 订单 |
|
||
| `sxo_order_address` | 地址（含身份证） |
|
||
| `sxo_payment` | 支付配置 |
|
||
| `sxo_goods` | 商品（含票务商品） |
|
||
| `sxo_goods_spec_base` | SKU（座位=库存1） |
|
||
|
||
### 插件独立表
|
||
|
||
| 表 | 用途 |
|
||
|---|---|
|
||
| `vr_events` | 活动 |
|
||
| `vr_sessions` | 场次时间+库存 |
|
||
| `vr_tickets` | 电子票（含QR数据） |
|
||
| `vr_verifiers` | 核销员 |
|
||
| `vr_verifications` | 核销记录 |
|
||
|
||
---
|
||
|
||
## 插件目录结构
|
||
|
||
```
|
||
app/plugins/vr_ticket/
|
||
├── plugin.json # 插件声明
|
||
├── service/
|
||
│ ├── BaseService.php # 基础配置
|
||
│ ├── EventService.php # 活动/场次服务
|
||
│ ├── TicketService.php # 票生成/发放
|
||
│ └── VerifyService.php # 核销逻辑
|
||
├── view/
|
||
│ ├── Goods.php # 商品详情页钩子
|
||
│ └── User.php # 用户中心钩子
|
||
├── Admin/
|
||
│ ├── Controller/
|
||
│ │ ├── EventController.php
|
||
│ │ ├── SessionController.php
|
||
│ │ └── TicketController.php
|
||
│ └── View/
|
||
│ ├── event_list.html
|
||
│ ├── event_save.html
|
||
│ ├── session_list.html
|
||
│ ├── session_save.html
|
||
│ ├── ticket_list.html
|
||
│ └── verification_list.html
|
||
├── Api/
|
||
│ └── Controller/
|
||
│ ├── EventController.php # 活动API
|
||
│ ├── SessionController.php # 场次API
|
||
│ └── TicketController.php # 票/核销API
|
||
└── EventListener.php # ShopXO事件监听
|
||
|
||
database/migrations/ # 数据库迁移
|
||
static/vr_ticket/ # 静态资源
|
||
```
|
||
|
||
---
|
||
|
||
## 完整购票流程
|
||
|
||
```
|
||
1. 商家后台
|
||
→ VR票务插件 → 新建活动（关联ShopXO商品）
|
||
→ 添加场次（时间 + 座位图 + 票价 + 库存）
|
||
|
||
2. 用户前端
|
||
→ 首页浏览 → 进入商品详情页
|
||
→ 判断 item_type == 'ticket'
|
||
→ 跳转到票务选座页（pages/ticket-buy）
|
||
→ 选择座位 → 填写观演人信息
|
||
→ 提交订单 → 微信支付
|
||
|
||
3. 支付成功
|
||
→ ShopXO 支付回调
|
||
→ TicketService::OnOrderPaid() 触发
|
||
→ 生成 QR 票 → 存入 vr_tickets 表
|
||
→ 用户可在票夹页查看
|
||
|
||
4. 核销
|
||
→ 工作人员打开核销页（pages/plugins/vr-ticket-verify）
|
||
→ 扫描用户 QR 码
|
||
→ POST /api/ticket/verify
|
||
→ VerifyService 更新核销状态
|
||
→ 返回核销结果
|
||
```
|
||
|
||
---
|
||
|
||
## 与 vr-ticket-mp 对比
|
||
|
||
| 维度 | vr-ticket-mp（主线） | vr-shopxo-plugin（Plan B） |
|
||
|---|---|---|
|
||
| **后端** | Go + Gin（自建） | PHP + ThinkPHP（ShopXO） |
|
||
| **数据库** | Supabase Postgres | ShopXO MySQL |
|
||
| **前端** | uni-app（自建） | shopxo-uniapp（已有） |
|
||
| **会员体系** | Supabase Auth | ShopXO 内置 |
|
||
| **积分/优惠券** | 自建 | ShopXO 内置 |
|
||
| **微信支付** | 自建 | ShopXO 内置 |
|
||
| **QR 核销** | 自建 | 基于 ShopXO 已有机制 |
|
||
| **部署** | Docker | 虚拟主机即可 |
|
||
| **AI 参与度** | 80% | 85-90% |
|
||
| **维护成本** | 高 | 低 |
|
||
|
||
---
|
||
|
||
## 技术栈
|
||
|
||
- **PHP 8+** / ThinkPHP 8（ShopXO 生态）
|
||
- **MySQL 5.7+**（ShopXO 同一实例）
|
||
- **uni-app**（shopxo-uniapp，已支持微信小程序）
|
||
- **phpqrcode**（`extend/qrcode/phpqrcode.php`，内置）
|
||
- **uni.scanCode**（微信/支付宝等小程序扫码）
|
||
|
||
---
|
||
|
||
## 官方文档（开发前必查）
|
||
|
||
- 官方文档站：https://doc.shopxo.net/
|
||
- 插件开发文档：https://doc.shopxo.net/article/3.html
|
||
- 开发文档索引：https://doc.shopxo.net/article/4.html
|
||
- uniapp 打包教程：https://doc.shopxo.net/article/1/293727233598554112.html
|
||
- 完整索引：[docs/OFFICIAL_DOCS.md](docs/OFFICIAL_DOCS.md)
|
||
|
||
## 开发文档
|
||
|
||
| 文档 | 内容 |
|
||
|---|---|
|
||
| [docs/00_OVERVIEW.md](docs/00_OVERVIEW.md) | 项目总览 |
|
||
| [docs/01_SHOPXO_TECHNICAL_RESEARCH.md](docs/01_SHOPXO_TECHNICAL_RESEARCH.md) | ShopXO 技术能力完整调研 |
|
||
| [docs/02_FRONTEND_CUSTOMIZATION.md](docs/02_FRONTEND_CUSTOMIZATION.md) | shopxo-uniapp 编译与自定义 |
|
||
| [docs/03_VERIFICATION_SYSTEM.md](docs/03_VERIFICATION_SYSTEM.md) | 核销系统设计 |
|
||
| [docs/04_IMPLEMENTATION_ROADMAP.md](docs/04_IMPLEMENTATION_ROADMAP.md) | 实施路线图与 Agent 分工 |
|