vr-shopxo-plugin/ARCHITECTURE.md

ShopXO VR票务插件 — 架构文档

版本：v1.3（2026-04-14 更新，venue_data 直接写入 sxo_goods，vr_sessions 职责明确） 源码位置：council-research/shopxo-eval/.worktrees/shopxo-evaluator/shopxo-src/

项目概述

基于 ShopXO 生态的 VR 演唱会票务插件（Plan B）。

当 vr-ticket-mp 主线项目因维护成本或架构限制无法继续时，此插件作为 Plan B：

• 完全复用 ShopXO 已有能力（会员体系/积分/优惠券/微信支付）
• 仅扩展 票务专属逻辑（场次/座位/观演人/QR核销）
• 优先通过插件机制扩展，如插件机制不够用（如商品详情页按类型返回不同模板），允许直接修改 ShopXO 源码的最小范围（MIT 协议允许）。原则：改源码比绕弯快时，直接改；以进度为先，不为「不修改」而引入额外复杂度。

---

8. 场馆系统 + 选座地图（完整方案）⭐⭐⭐

详见 docs/06_SEAT_MAP_INTEGRATION.md

核心架构（2026-04-14 更新）：

1. 字符地图是行业标准：场馆平面图 → 字符串地图（如 aaa___aaa）→ 前端渲染为 SVG/DOM
2. venue_data 直接存在 sxo_goods：每个票务商品 = 1 场演出，sxo_goods.venue_data（LONGTEXT）存完整配置
3. venue_data JSON 内容：venue（场馆+座位图）+ sessions[]（场次列表）+ spec_base_id_map（座位→SKU映射）
4. vr_venues：场馆主数据（名称/地址/座位图），多个商品/场次可复用同一个场馆
5. vr_sessions：每个演出场次（日期+时间），共用 venue 的座位图，独立库存
6. spec_base_id_map：seat_id（如 "3_5"）→ spec_base_id → ShopXO 购买流程
7. ShopXO spec 系统无硬限制：3场馆×2票种×500座位=3000 SKU 完全可行

数据流：

sxo_goods.venue_data JSON
  ├── venue.seat_map         → 前端渲染座位图
  ├── sessions[]             → 场次选择器
  └── spec_base_id_map       → 选座 → Buy API → 原子扣 spec_base.inventory

核心技术发现（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. 按商品类型替换模板（已有更优方案，优先用 Hook）⭐

⚠️ 已更新（2026-04-14 下午）：原计划修改 Goods.php，现发现 site_type=3（虚拟商品）可绕过：

• site_type=3 时 ShopXO 不显示 extraction popup，也不要求选择地址
• 直接通过 plugins_view_goods_detail_base_sku_top 注入票务选座 UI
• Goods.php 不再需要修改，完全通过插件 Hook 实现

原 Goods.php 修改方案保留作为备案（如 Hook 无法满足时）： 在 Goods.php Index() 中增加 1 行判断： 这是 ShopXO 允许范围内，实现「特定商品类型使用独立模板」的唯一方式。 所有其他功能均通过插件钩子实现，不修改核心代码。

// app/index/controller/Goods.php Index() 方法，约第 440 行
// 在 return MyView(); 之前插入：

if(!empty($goods['item_type']) && $goods['item_type'] == 'ticket') {
    return MyView('/goods/ticket_detail');  // 自定义票务模板
}
return MyView();  // 默认模板

对应模板文件：app/index/view/default/goods/ticket_detail.html（ShopXO 主题目录下）

4. shopxo-uniapp 支持微信小程序 ⭐

HBuilderX 导入 → 配置 AppID → 发行 → 微信开发者工具 条件编译指令已配置（#ifdef MP-WEIXIN）

5. QR 码生成内置 ⭐

使用 \base\Qrcode 类 + phpqrcode 库：

$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/00_OVERVIEW.md	项目总览
docs/01_SHOPXO_TECHNICAL_RESEARCH.md	ShopXO 技术能力完整调研
docs/02_FRONTEND_CUSTOMIZATION.md	shopxo-uniapp 编译与自定义
docs/03_VERIFICATION_SYSTEM.md	核销系统设计
docs/04_IMPLEMENTATION_ROADMAP.md	实施路线图与 Agent 分工