173 lines
6.5 KiB
Markdown
173 lines
6.5 KiB
Markdown
# 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 原子写法）：
|
||
|
||
```sql
|
||
-- 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（核心链路）
|
||
|
||
---
|