# 后台编辑器 + 商品发布注入方案设计 > 版本：v3.0 | 日期：2026-04-15 21:45 | 状态：**已确认，待执行** > > v3.0 更新（2026-04-15 21:45 大头确认）： > 1. venue 信息放入 seat_map 顶层（不独立建表） > 2. BatchGenerate() 必须支持按分区过滤（enabledZones 参数） > 3. 新增 sxo_goods.vr_ticket_config JSON 字段，老商品兼容 > 4. 增加美化版 seat_map 示例 JSON --- ## 一、整体架构一句话 **插件在 ShopXO 后台建一套"场馆配置"管理界面，用户发布票务商品时，选场馆 → 选分区 → 插件自动只生成这些分区的海量 Spec 并注入商品，用户全程不碰 ShopXO 原生 Spec 管理。** --- ## 二、三大核心区域 ``` ┌─────────────────────────────────────────────────────────────┐ │ ShopXO 原生后台 │ │ │ │ ┌──────────────────┐ ┌────────────────────────┐ │ │ │ 商品管理 │ ←→ │ 插件专属后台（新增） │ │ │ │ 发布/编辑商品 │ │ 场馆配置管理 │ │ │ │ （注入点） │ │ 座位分区模板编辑器 │ │ │ └──────────────────┘ └────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` ### 区域 A：插件专属后台（新增） 商户在 ShopXO 后台左侧菜单进入「VR票务」： ``` VR票务 ├── 场馆配置 ← Phase 3-1 新增 ├── 座位模板 ← 已存在（Phase 2） ├── 电子票管理 ← 已存在 ├── 核销员管理 ← 已存在 └── 核销记录 ← 已存在 ``` > ⚠️ **当前状态**：`Venue.php` 控制器不存在，Phase 3-1 从零新建。 ### 区域 B：ShopXO 商品发布页（注入点） > ⚠️ **待核实**：商品发布页 Tab 名称需对照 `saveinfo.html` 模板确认。 商户在 ShopXO 后台「商品管理 → 添加商品」： ``` 添加商品 [商品名称] [商品分类] ▼ 票务配置 ← ShopXO 原生区域，插件注入票务选择器 场馆：[请选择场馆 ▼] ← 来自 vr_seat_templates 表 分区：[□VIP区 □看台区 □普通区] ← 多选，根据场馆联动 [商品详情 富文本编辑器] ▼ 其他Tab（参数/图片等）← ShopXO 原生 ``` ### 区域 C：插件商品详情页（已存在） 用户在前台看到票务商品详情页，选座下单，已实现。 --- ## 三、场馆配置管理（区域 A） ### 3.1 seat_map 数据结构（v3.0 最终版） ```json { "venue": { "name": "国家体育馆", "address": "北京市朝阳区奥体中心", "image": "/uploads/vr/venue/national-stadium.jpg" }, "map": [ "AAAAAA", "BBBBBB", "CCCCCC" ], "seats": { "A": { "price": 899, "color": "#e74c3c", "label": "VIP区" }, "B": { "price": 599, "color": "#3498db", "label": "看台区" }, "C": { "price": 299, "color": "#2ecc71", "label": "普通区" } }, "sections": [ { "char": "A", "name": "VIP区", "color": "#e74c3c" }, { "char": "B", "name": "看台区", "color": "#3498db" }, { "char": "C", "name": "普通区", "color": "#2ecc71" } ], "row_labels": ["A", "B", "C"] } ``` **字段说明**： | 字段 | 类型 | 说明 | |------|------|------| | `venue` | object | 场馆信息。**v3.0 新增**。name 即 `$vr-场馆` spec 值，不再硬编码 | | `map` | string[] | 每排座位数字符串（A=6座，B=6座，C=6座），决定总座位数 | | `seats` | object | **字段名是 seats 不是 zones**。每行（char）的默认 price/color/label | | `sections` | object[] | 每个分区的元信息（char → name/color 映射），前端分区选择器用此渲染多选框 | | `row_labels` | string[] | 行标签，用于前端渲染座位坐标（"A_1", "A_2"...）| **`$vr-场馆` spec 值来源**：从 `seat_map.venue.name` 读取，Phase 3-1 改造 `BatchGenerate`。 **与旧数据的兼容性**： - 存量 seat_map 无 `venue` 顶层 → 降级取 `vr_seat_templates.name` 作为 `$vr-场馆` 值 - 存量 seat_map 无 `sections` 顶层 → 降级从 `seats` 推导 ### 3.2 美化版 seat_map 示例（Phase 3-1 表单填充示例） **示例 1：大型演唱会（3 区，每区 6 座）** ```json { "venue": { "name": "鸟巢", "address": "北京市朝阳区国家体育场南路1号", "image": "/uploads/vr/venue/bird-nest.jpg" }, "map": ["AAAAAA", "BBBBBB", "CCCCCC"], "seats": { "A": { "price": 1299, "color": "#e74c3c", "label": "内场VIP" }, "B": { "price": 899, "color": "#9b59b6", "label": "内场A区" }, "C": { "price": 599, "color": "#3498db", "label": "内场B区" } }, "sections": [ { "char": "A", "name": "内场VIP", "color": "#e74c3c" }, { "char": "B", "name": "内场A区", "color": "#9b59b6" }, { "char": "C", "name": "内场B区", "color": "#3498db" } ], "row_labels": ["A", "B", "C"] } ``` **示例 2：小型剧场（2 区，每区 4 座）** ```json { "venue": { "name": "上海音乐厅", "address": "上海市黄浦区延安东路523号", "image": "/uploads/vr/venue/shanghai-concert-hall.jpg" }, "map": ["AAAA", "BBBB"], "seats": { "A": { "price": 499, "color": "#f39c12", "label": "前排" }, "B": { "price": 299, "color": "#1abc9c", "label": "后排" } }, "sections": [ { "char": "A", "name": "前排", "color": "#f39c12" }, { "char": "B", "name": "后排", "color": "#1abc9c" } ], "row_labels": ["A", "B"] } ``` **示例 3：开放部分分区（电影院场景）** ```json { "venue": { "name": "IMAX 影城", "address": "北京市朝阳区建国路88号", "image": "/uploads/vr/venue/imax-cinema.jpg" }, "map": ["AAAAAA", "BBBBBB", "CCCCCC", "DDDDDD", "EEEEE"], "seats": { "A": { "price": 99, "color": "#e74c3c", "label": "情侣座" }, "B": { "price": 69, "color": "#3498db", "label": "VIP厅" }, "C": { "price": 49, "color": "#2ecc71", "label": "普通座" }, "D": { "price": 49, "color": "#2ecc71", "label": "普通座" }, "E": { "price": 39, "color": "#95a5a6", "label": "边座" } }, "sections": [ { "char": "A", "name": "情侣座", "color": "#e74c3c" }, { "char": "B", "name": "VIP厅", "color": "#3498db" }, { "char": "C", "name": "普通座", "color": "#2ecc71" }, { "char": "D", "name": "普通座", "color": "#2ecc71" }, { "char": "E", "name": "边座", "color": "#95a5a6" } ], "row_labels": ["A", "B", "C", "D", "E"] } ``` > 示例 3 场景：发布商品时只选 A+B 分区，C/D/E 暂不开放。`BatchGenerate(enabledZones=['A','B'])` 只生成 12 个座位 SKU。 ### 3.3 场馆配置管理页面 > ⚠️ **待实现**：当前 `Venue.php` 控制器不存在。 商户在插件后台「场馆配置 → 添加」看到的表单： ``` 【场馆基本信息】 场馆名称：[_______________________________] 场馆地址：[_______________________________] 场馆图片：[上传按钮] 【分区配置】（增删分区，拖拽排序） ┌──────────────────────────────────────────────────┐ │ Char │ 标签 │ 单价（元）│ 颜色 │ │ ├──────────────────────────────────────────────────┤ │ A │ 内场VIP │ 1299 │ [■红 ▼]│ [删除] │ ├──────────────────────────────────────────────────┤ │ B │ 内场A区 │ 899 │ [■紫 ▼]│ [删除] │ ├──────────────────────────────────────────────────┤ │ C │ 内场B区 │ 599 │ [■蓝 ▼]│ [删除] │ └──────────────────────────────────────────────────┘ [+ 添加分区] 【座位排布预览】（实时渲染） 🔴 🔴 🔴 🔴 🔴 🔴 ← A区（VIP，1299元） 🟣 🟣 🟣 🟣 🟣 🟣 ← B区（内场A区，899元） 🔵 🔵 🔵 🔵 🔵 🔵 ← C区（内场B区，599元） 每排座位数：[6___] 总座位数：18 【保存】 【取消】 ``` **技术实现**： - layui 表单 + Vue3 CDN（轻量，不破坏 ShopXO 后台 jQuery/layui 结构） - ~500 行前端代码，1-1.5 人天 - 保存：表单 → seat_map JSON → 写入 `vr_seat_templates.seat_map` - 颜色选择器：预设色盘（不引入额外依赖） --- ## 四、商品发布页注入（区域 B） ### 4.1 注入原理 ``` ShopXO admin Goods::SaveInfo() → 调用 hook plugins_view_admin_goods_save（Goods.php:159） → 触发 vr_ticket/hook/AdminGoodsSave.php → 返回票务配置面板 HTML → 插入 saveinfo.html base tab
内 ``` ### 4.2 钩子注册方式 > ⚠️ **重要**：ShopXO **不支持** `backend_hook` 字段，实际使用 `hooks` 数组。 **plugin.json 追加**（Phase 3-2）： ```json { "hooks": [ "plugins_service_order_pay_success_handle_end", "plugins_service_order_delete_success", "plugins_view_admin_goods_save", "plugins_service_goods_save_handle" ] } ``` ### 4.3 AdminGoodsSave.php（待新建） > ⚠️ **待实现**：`vr_ticket/` 下当前无此文件。 **文件**：`plugins/vr_ticket/hook/AdminGoodsSave.php` 职责： - 查询 `vr_seat_templates` 表，构造场馆下拉 + 分区多选 HTML - 返回 layui + Vue3 CDN 的票务配置面板 **数据来源**： ```php $templates = Db::name('vr_seat_templates') ->field('id, name, seat_map, category_id') ->where(['status' => 1]) ->select(); foreach ($templates as &$t) { $seatMap = json_decode($t['seat_map'], true); // v3.0: venue.name 优先，否则降级取模板 name $t['venue_name'] = $seatMap['venue']['name'] ?? $t['name']; // sections 用于渲染分区多选框 $t['zones'] = $seatMap['sections'] ?? []; } ``` ### 4.4 AdminGoodsSaveHandle.php（待新建） **文件**：`plugins/vr_ticket/hook/AdminGoodsSaveHandle.php` 触发时机：`plugins_service_goods_save_handle`（GoodsService.php:1550） 职责： ```php // 接收 POST: { template_id, selected_zones: ['A', 'C'] } $templateId = $params['vr_template_id'] ?? 0; $zones = $params['vr_zones'] ?? []; // e.g. ['A', 'C'] // 1. 生成 SKU（只生成选中分区） $result = SeatSkuService::BatchGenerate($goodsId, $templateId, $zones); // goodsId 从 $params['id'] 或新建商品的返回值中获取 // 2. 写入 vr_ticket_config 快照（Phase 3-3 新增字段） $snapshot = [ 'template_id' => $templateId, 'selected_zones' => $zones, 'spec_base_id_map' => $result['data']['spec_base_id_map'], 'created_at' => time(), ]; // Db::name('goods')->where('id', $goodsId)->update(['vr_ticket_config' => json_encode($snapshot)]); ``` --- ## 五、商品发布完整流程 **场景**：商户发布一张票务商品（只开放 A 区和 C 区） ``` Step 1：商户进入 ShopXO 后台 → 商品管理 → 添加商品 Step 2：填写基础信息 商品名称：周杰伦 VR 虚拟演唱会 商品分类：VR演出 Step 3：在票务配置面板选场馆和分区 票务配置 场馆：[鸟巢 ▼] 分区：[✓VIP区(A) □看台区(B) ✓普通区(C)] Step 4：点击发布 Save() → GoodsService::GoodsSave() → 触发 plugins_service_goods_save_handle → AdminGoodsSaveHandle 收到 POST → BatchGenerate(goodsId=123, templateId=1, enabledZones=['A','C']) → 只生成 A 区（6座）和 C 区（6座）= 12 个 SKU → 写入 sxo_goods_spec_base → 写入 vr_ticket_config JSON 快照 → 商品保存完成 Step 5：用户前台看到选座页 → 用户点击 A_1 座位 → specBaseIdMap['A_1'] = 2001（来自 vr_ticket_config.snapshot） → goodsParams: [{goods_id:123, spec_base_id:2001, stock:1}] → 下单 ``` --- ## 六、Spec 生成后内部结构（技术细节） > ⚠️ **表前缀**：ShopXO 原生表用 `sxo_`，插件自定义表用 `{$prefix}vrt_`。 ### sxo_goods_spec_base（每行 = 一个座位 SKU） | spec_base_id | goods_id | inventory | price | |---|---|---|---| | 2001 | 123 | 1 | 1299 | ← A_1 座位 | 2002 | 123 | 1 | 1299 | ← A_2 座位 | ... | 123 | 1 | 1299 | ← A_6 座位 | 5001 | 123 | 1 | 599 | ← C_1 座位 | ... | 123 | 1 | 599 | ← C_6 座位 > 注：B 区座位未生成（商户只选了 A + C） ### sxo_goods_spec_type（每行 = 一个规格维度） | id | goods_id | name | value | |---|---|---|---| | 1 | 123 | $vr-场馆 | `[{"name":"鸟巢"}]` | | 2 | 123 | $vr-分区 | `[{"name":"VIP区"},{"name":"普通区"}]` | | 3 | 123 | $vr-时段 | `[{"name":"待选场次"}]` | | 4 | 123 | $vr-座位号 | `[{"name":"A_1"},...{"name":"C_6"}]` | ### vr_ticket_config（sxo_goods 表新增字段） ```json { "template_id": 1, "selected_zones": ["A", "C"], "spec_base_id_map": { "A_1": 2001, "A_2": 2002, ..., "A_6": 2006, "C_1": 5001, "C_2": 5002, ..., "C_6": 5006 }, "created_at": 1744659200 } ``` --- ## 七、BatchGenerate 接口（含 v3.0 改造） ### 7.1 当前已实现版本（全量，v2.0） > ⚠️ 以下为当前 main 分支代码，**不支持**按分区过滤（Phase 3-3 需改造）： ```php public static function BatchGenerate(int $goodsId, int $seatTemplateId): array // 行为：按模板全部座位生成 SKU ``` ### 7.2 Phase 3-3 改造版本（按分区过滤） ```php public static function BatchGenerate( int $goodsId, int $seatTemplateId, array $enabledZones = [] // e.g. ['A', 'C'] — 空=全量 ): array // 内部逻辑改造： // foreach ($seatMap['map'] as $rowChar => $rowSeats) { // if (!empty($enabledZones) && !in_array($rowChar, $enabledZones)) { // continue; // 跳过未选中的分区 // } // foreach (range(1, strlen($rowSeats)) as $col) { // // 生成该座位 SKU... // } // } ``` **与旧版差异**： | 维度 | 旧版（全量） | 新版（v3.0） | |------|------------|-------------| | 参数 | `(goodsId, templateId)` | `(goodsId, templateId, enabledZones)` | | 行为 | 所有座位都生成 | 只生成 enabledZones 内的分区座位 | | 兼容性 | — | enabledZones 为空时退化为全量（向后兼容）| --- ## 八、vr_ticket_config 字段（v3.0 新增） ### 8.1 数据库迁移 ```sql -- EventListener.php 中追加（Phase 3-3） ALTER TABLE {$prefix}goods ADD COLUMN vr_ticket_config JSON COMMENT '票务配置快照：template_id/selected_zones/spec_base_id_map' AFTER extension_data; ``` **老商品兼容**：存量商品 `vr_ticket_config = NULL`，编辑页检测到为空时提示"请重新选择"。 ### 8.2 生命周期 | 时机 | 操作 | |------|------| | 发布商品时 | `AdminGoodsSaveHandle` 写入 `vr_ticket_config` | | 编辑商品时 | 从此字段还原"选择了哪些场馆/分区" → 不展示琳琅满目的 spec_base 列表 | | 删除商品时 | 钩子 `plugins_service_order_delete_success` 同步清理关联 spec | --- ## 九、与 ShopXO 原生 Spec 管理的关系 | 维度 | ShopXO 原生 Spec | 票务 Spec | |------|----------------|----------| | 谁创建 | 商户手动添加 | 插件自动生成（静默） | | 表前缀 | `sxo_` | `sxo_goods_spec_base` / `sxo_goods_spec_value` | | 商户感知 | 在后台规格管理看到 | 无感（注入的表单已覆盖场景） | | 用户在前台 | 购物车/下单流程 | 票务选座 UI | | 核销 | 不涉及 | 每座位一个 QR（vrt_vr_tickets）| --- ## 十、实施步骤 ### Phase 3-1：后台场馆配置管理（新建 admin 页面） - [x] 决策已确认：venue 信息存入 seat_map 顶层 - [x] 新建 `admin/controller/Venue.php`（CRUD + preview 调试接口） - [x] 新建 `admin/view/venue/list.html`（场馆列表页） - [x] 新建 `admin/view/venue/save.html`（Vue3 交互式表单编辑器：分区增删/座位排布/实时预览） - [x] `BatchGenerate()` venue.name 动态读取（不再硬编码"国家体育馆"） - [x] 将现有测试数据迁移为带 venue 的格式（vr_seat_templates id=1） - name = '国家体育馆'，venue.name = '国家体育馆'，3 区 × 6 座 = 18 座 - [ ] `BatchGenerate` 读取 `seat_map.venue.name`（不再硬编码） ### Phase 3-2：商品发布页注入 - [ ] `plugin.json` 的 `hooks` 数组追加 2 个钩子 - [ ] 新建 `hook/AdminGoodsSave.php`（注入票务配置 HTML） - [ ] 新建 `hook/AdminGoodsSaveHandle.php`（处理保存数据） - [ ] 场馆下拉 + 分区多选联动（Vue3，轻量） - [ ] 确认商品发布页实际 Tab 名称（对照 `saveinfo.html`） ### Phase 3-3：Spec 自动生成接入 + 按分区过滤 - [ ] `BatchGenerate()` 增加 `enabledZones` 参数 - [ ] `AdminGoodsSaveHandle` 从 POST 提取选中分区，传给 `BatchGenerate` - [ ] 数据库迁移：`sxo_goods` 新增 `vr_ticket_config` JSON 字段 - [ ] 发布时写入 `vr_ticket_config` 快照 ### Phase 3-4（优先级低）：商品编辑回显 - [ ] 编辑页加载时解析 `vr_ticket_config`，还原场馆 + 分区状态 - [ ] 编辑页票务配置面板回显 - [ ] 若修改了 venue/zone：提示重新生成 spec 或自动重建 --- ## 十一、v3.0 确认决策 | 决策点 | 确认结果 | |--------|---------| | venue 信息存在哪 | 存入 `seat_map.venue` 顶层，不独立建表 | | 是否支持按分区过滤 | **必须支持**，Phase 3-3 改造 BatchGenerate 增加 enabledZones 参数 | | 数据库扩展兼容性 | 新增 `sxo_goods.vr_ticket_config` JSON 字段，老商品留 NULL | | 老 seat_map 兼容性 | 降级处理：无 venue → 取模板 name；无 sections → 从 seats 推导 | --- ## 十二、勘误表（v1.0 → v2.0 → v3.0） | # | v1.0 描述 | 实际/修正 | |---|---------|---------| | 1 | `plugin.json` 用 `backend_hook` 注册 | ShopXO 用 `hooks` 数组 ✅ v2.0 已修正 | | 2 | seat_map 有 `venue` 顶层字段 | 不存在，v3.0 决策新增 ✅ | | 3 | seat_map 有 `zones` 顶层字段 | 实际是 `seats` + `sections` ✅ v2.0 已修正 | | 4 | BatchGenerate 全量生成 | v3.0 决策：必须支持按分区过滤 ✅ | | 5 | `goods_spec_base` 前缀是 `vrt_` | 原生表是 `sxo_` ✅ v2.0 已修正 | | 6 | `vr_ticket_config` 字段存在 | 不存在，v3.0 决策新增 ✅ | | 7 | 场馆配置管理是 Phase 2 已完成 | 待实现，Phase 3-1 ✅ v2.0 已修正 | | 8 | spec_base_id_map 是内存/缓存 | 持久化到 `vr_seat_templates.spec_base_id_map` ✅ v2.0 已修正 | | 9 | 商品分类需绑定票务配置 | 代码未强制校验，删除此约束 ✅ v2.0 已修正 | | 10 | 无 vr_ticket_config 导致编辑页 spec 堆满 | v3.0 决策：新增字段解决 ✅ |