7.4 KiB

Raw Blame History

ShopXO VR票务插件 — 架构文档

项目概述

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

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

完全复用 ShopXO 已有能力（会员体系/积分/优惠券/微信支付）
仅扩展 票务专属逻辑（场次/观演人/QR核销）
不修改 ShopXO 核心代码，通过插件机制隔离

目标用户

朋友的合作伙伴：需要一个可上线、后期可 AI 改动的轻量商城小程序。

核心设计思路

商品模型统一

票务作为 ShopXO 商品类型的扩展：

ShopXO items 表
  └── item_type = 'ticket' 时，启用插件逻辑
      ├── 关联 vr_events（场次表）
      ├── 关联 vr_sessions（场次时间）
      └── 关联 vr_attendees（观演人）

ShopXO orders 表
  └── 订单项 item_type='ticket' → 插件处理履约
      └── 触发 vr_tickets 表写入 → 生成 QR 票

与 ShopXO 的边界

能力	来源	说明
商品目录/上下架	ShopXO	复用 items 表
会员体系/充值/积分	ShopXO	复用 user/wallet/integral 表
优惠券	ShopXO	复用 coupons 表
微信支付	ShopXO	复用 payment 表 + 回调
场次/日期管理	插件	独立表 vr_events/sessions
观演人信息	插件	独立表 vr_attendees
QR 电子票	插件	独立表 vr_tickets
核销组件	插件	独立 B 端页面

数据库设计

插件独立表

-- 场次表
vr_events (
  id, goods_id,        -- 关联 ShopXO items.id
  name,                -- "周杰伦2026巡回演唱会"
  venue,               -- 场馆
  cover_image,
  status,
  created_at
)

-- 场次时间表
vr_sessions (
  id, event_id,
  session_time,        -- 2026-06-01 20:00
  total_stock,         -- 总库存
  available_stock,     -- 可用库存（扣减用 FOR UPDATE SKIP LOCKED）
  price,
  status,
  created_at
)

-- 观演人表
vr_attendees (
  id, order_id, order_item_id,
  session_id,
  real_name,
  id_card,             -- 可选
  phone,
  ticket_code,         -- UUID，唯一
  qr_data,             -- 加密后的 QR 内容
  status,               -- pending/issued/used/cancelled
  created_at
)

-- QR 票表
vr_tickets (
  id, attendee_id,
  ticket_code,
  qr_image_path,       -- QR码图片路径
  issued_at,            -- 支付成功时生成
  used_at,              -- 核销时间
  created_at
)

-- 核销记录表
vr_verifications (
  id, ticket_id, verifier_id,
  verified_at,
  ip_address,
  location
)

插件目录结构

shopxo-vr-ticket-plugin/
├── plugin.json                    # 插件声明
├── app/
│   ├── Admin/                    # 管理端
│   │   ├── Controller/
│   │   │   ├── EventController.php
│   │   │   ├── SessionController.php
│   │   │   └── TicketController.php
│   │   ├── Route.php             # 管理端路由
│   │   └── View/                 # 管理页面
│   │       ├── event_list.html
│   │       ├── session_edit.html
│   │       └── ticket_list.html
│   ├── Api/                      # C端API
│   │   ├── EventController.php   # 场次详情
│   │   ├── SessionController.php # 可用场次
│   │   ├── CheckoutController.php# 下单钩子（收集观演人）
│   │   └── TicketController.php  # 我的票/票夹
│   ├── EventListener.php         # 监听 ShopXO 支付成功事件
│   ├── Model/
│   │   ├── VrEvent.php
│   │   ├── VrSession.php
│   │   ├── VrAttendee.php
│   │   └── VrTicket.php
│   └── Service/
│       ├── EventService.php
│       ├── TicketService.php      # QR 生成 + 发放
│       └── VerificationService.php# 核销逻辑
├── database/
│   └── migrations/                # 插件数据库迁移
│       ├── 001_create_vr_events.php
│       ├── 002_create_vr_sessions.php
│       ├── 003_create_vr_attendees.php
│       └── 004_create_vr_tickets.php
├── static/
│   └── admin/                    # 管理端静态资源
└── README.md

核心流程

1. 票务发布流程

商家后台 → 插件菜单 → 新建活动
  → 关联 ShopXO 商品（填写价格/库存）
  → 添加场次（时间+价格+库存）
  → 上架

2. 用户购票流程

首页浏览 → 商品详情 → 选择场次 → 立即购买
  → 填写观演人信息（1-N人，场次配置决定）
  → 提交订单（插件收集 attendees）
  → 微信支付
  → 支付回调 → 插件生成 QR 票
  → 票夹页显示电子票

3. 核销流程

B端核销员 → 扫码页面 → 扫描 QR
  → API 校验 ticket_code
  → 标记 used_at
  → 返回核销结果

关键技术决策

库存扣减

采用 FOR UPDATE SKIP LOCKED（与 vr-ticket-mp 相同策略）：

BEGIN;
SELECT available_stock FROM vr_sessions
  WHERE id = ? AND available_stock >= ? FOR UPDATE SKIP LOCKED;
-- 若成功，执行 UPDATE available_stock = available_stock - ?
COMMIT;

QR 票安全

// qr_data = AES_Encrypt(json_encode([
//   'code' => $attendee->ticket_code,
//   'event_id' => $event_id,
//   'exp' => time() + 86400 * 30  // 30天有效期
// ]), $secret_key)

核销时解密验证，防止伪造。

与 ShopXO 的事件对接

// EventListener.php
class EventListener
{
    // 监听 ShopXO 支付成功事件
    public function onOrderPaid($order_id)
    {
        $items = $this->orderService->getOrderItems($order_id);
        foreach ($items as $item) {
            if ($item->item_type === 'ticket') {
                $this->ticketService->issueTickets($item);
            }
        }
    }
}

与 vr-ticket-mp 的对比

维度	vr-ticket-mp（主线）	ShopXO 插件（Plan B）
后端	Go + Gin（自建）	PHP + ThinkPHP（ShopXO）
数据库	Supabase Postgres	ShopXO MySQL
前端	uni-app（自建）	shopxo-uniapp（已有）
会员体系	Supabase Auth	ShopXO 内置
积分/优惠券	自建	ShopXO 内置
微信支付	自建	ShopXO 内置
部署	Docker	虚拟主机即可
开发成本	高（全部自建）	低（复用 ShopXO）
适合场景	票务为主，商城为辅	商城为主，票务为辅

技术栈

语言：PHP 8+
框架：ThinkPHP 8（ShopXO 生态）
前端：Vue.js（插件管理端）+ uni-app（ShopXO 已有）
数据库：MySQL（ShopXO 同一实例）
QR生成：phpqrcode / endroid/qr-code

开发计划（Agent 集群并行）

阶段	工作内容	负责人
Phase 0	插件骨架 + 本地跑通 demo	李狗蛋
Phase 1	数据库设计 + 迁移脚本	妮可
Phase 2	场次管理 CRUD + API	李狗蛋
Phase 3	下单钩子 + 观演人收集	小老D
Phase 4	支付回调 + QR 票生成	西莉娅
Phase 5	B端核销页 + 扫码API	小老D
Phase 6	Uni-app 改造（观演人表单 + 票夹）	妮可
Phase 7	联调 + 测试 + 部署文档	西莉娅

预计：2-3 周 MVP，1 个月完整上线。

7.4 KiB Raw Blame History Unescape Escape