vr-shopxo-plugin/docs/08_SHOPXO_REQUIREMENTS_MAPPING.md

vr-shopxo-plugin 需求对照分析

ShopXO 插件机制 vs VR 演唱会票务需求 基于 shopxo-plugin-dev.md 整理

---

一、票务核心功能 vs ShopXO 机制

1. 商品模型（票 = item_type='ticket'）

ShopXO 原生商品表 item 有 item_type 字段扩展能力，但票务的特殊性在于：

• 票有时间场次（session），普通商品无此概念
• 票需要观演人信息，普通商品无此字段
• 票需要 QR 电子票，普通商品无此交付物

结论：票务插件需创建独立表 vr_events + vr_sessions + vr_tickets，与 ShopXO items 表平行存在，通过 item_id 关联。

2. 库存扣减（防超卖）

ShopXO 原生库存扣减：SELECT → UPDATE 两步，非原子操作，有超卖风险。

VR 票务方案：在支付回调 api/notify 中，使用 Postgres 风格 SQL（ShopXO 是 MySQL，需换为 MySQL 原子写法）：

-- MySQL 原子扣库存（FOR UPDATE SKIP LOCKED 等效写法）
START TRANSACTION;
SELECT stock FROM vr_sessions WHERE id=? AND stock>=? FOR UPDATE;
-- 如果库存足够
UPDATE vr_sessions SET stock=stock-? WHERE id=?;
INSERT INTO vr_tickets (...) VALUES (...);
COMMIT;

关键：必须在支付回调的 API 控制器中完成，不能依赖 ShopXO 原有订单流程。

3. 微信支付回调

ShopXO 支持支付插件机制（extend/payment/），但票务插件需要自己的支付回调路由：

POST /plugins/api?pluginsname=vr_ticket&pluginscontrol=api&pluginsaction=notify

ShopXO 原生支付回调由支付插件处理，票务插件的回调是：用户付款成功 → 票务插件生成电子票。

注意：ShopXO 的微信支付插件本身已处理微信支付回调，我们需要在 Event.php 中监听支付成功事件，或在回调路由中自己调用微信API验证。

4. 观演人信息

ShopXO 订单扩展字段能力有限，建议：

• 创建 vr_attendees 表（姓名、手机、证件号）
• 在订单 paid 状态的 webhook 或手动触发时写入
• 通过订单扩展字段 extension（JSON）关联 vr_attendees

5. QR 电子票

ShopXO 附件上传/管理能力完善，但 QR 生成需自己实现：

• PHP QR Code：phpqrcode/phpqrcode Composer 包
• 存储：vr_tickets.qr_data 存 QR 内容（AES_Encrypt），QR 图片可 CDN 化

6. B 端扫码核销

ShopXO 后台有门店核销机制（多门店插件），但票务核销是独立场景：

• 插件后台：admin/verify 控制器
• 扫码枪：调用微信扫一扫或直接输入 QR code
• 核销状态更新：vr_tickets.status = 'used'

---

二、ShopXO 原有功能借用分析

票务需求	ShopXO 原生能力	插件扩展方式	优先级
商品展示	✅ items 表	创建 vr_events 场次表	P0
会员体系	✅ 完善	不需开发	P0
钱包/余额	✅ 完善	不需开发	P0
优惠券	✅ 完善	不需开发	P0
微信支付	✅ 支付插件	直接用（不需改）	P0
订单管理	✅ orders 表	扩展 extension 字段	P0
库存扣减	⚠️ 非原子	支付回调自己写	P0
场次/SKU	❌ 无	独立表 vr_sessions	P0
观演人信息	❌ 无	独立表 vr_attendees	P0
QR 电子票	❌ 无	phpqrcode + 插件表	P0
B端核销	❌ 无	插件后台 admin 页面	P1
多场馆	❌ 无	vr_events 已有场馆字段	P2
周边商品	✅ items 原生	不需插件	P0

---

三、插件架构设计

数据库 E-R 图

vr_events (场次)
  └── vr_sessions (场次时间/库存)  1:N
        └── vr_tickets (电子票)  1:N
              └── vr_attendees (观演人)  N:1

items (ShopXO原生) ←── item_id ──→ vr_events (通过 item_id 关联)
orders (ShopXO原生) ←─ extension ──→ vr_attendees (JSON关联)

插件目录

app/plugins/vr_ticket/
├── config.json              # 插件配置（钩子：支付回调）
├── admin/
│   ├── controller/
│   │   ├── Event.php        # 场次管理 CRUD
│   │   ├── Ticket.php        # 电子票管理
│   │   └── Verify.php       # 核销管理
│   └── view/
│       ├── event/            # 场次管理视图
│       ├── ticket/
│       └── verify/           # 核销页面
├── index/
│   ├── controller/
│   │   ├── Index.php         # 前台插件首页
│   │   └── Ticket.php        # 我的票/QR展示
│   └── view/
│       ├── ticket/
│       └── my_tickets.blade.php
├── api/
│   └── controller/
│       └── Notify.php        # ★ 支付回调（最关键）
├── service/
│   └── BaseService.php
├── Event.php                 # 生命周期事件
├── common.php
└── hook/
    └── OrderPaid.php         # 订单支付成功钩子（可选）

支付回调流程

微信支付回调 → /plugins/api?pluginsname=vr_ticket&pluginscontrol=api&pluginsaction=notify
    │
    ├─ 1. 验证签名（微信API）
    ├─ 2. 查询 ShopXO orders 表确认支付状态
    ├─ 3. 读取订单 extension 中的 vr_session_id + vr_attendees
    ├─ 4. 原子扣库存（vr_sessions）
    ├─ 5. 生成 vr_tickets（AES_Encrypt QR content）
    ├─ 6. 写入 vr_attendees 记录
    └─ 7. 更新 orders.extension（票ID列表）

---

四、已知限制与绕过方案

限制	影响	绕过方案
ShopXO 订单流程不可扩展	无法在原生下单流程中插入观演人表单	独立购票页，支付后写入观演人
支付回调由支付插件处理	票务插件无法直接拦截微信回调	支付插件 → Event.PaySuccess → 票务钩子
插件不能 Hook 订单状态变更	无法监听 paid→fulfilled	支付回调中直接处理，或定时轮询
DIY 拖拽装修不可代码化	票务展示页无法 AI 生成	票务页面全部走插件视图，不走 DIY
MySQL 非 Postgres	无 FOR UPDATE SKIP LOCKED	START TRANSACTION + SELECT ... FOR UPDATE

---

五、下一步行动

1. 先确认支付插件的 PaySuccess 事件 — 从 extend/payment/ 源码确认是否触发 Event.PaySuccess
2. 创建插件骨架 — config.json + BaseService + Event.php
3. 设计数据库迁移脚本 — vr_events, vr_sessions, vr_tickets, vr_attendees
4. 实现支付回调 — api/Notify.php（核心链路）

---