vr-shopxo-plugin/docs/PLAN_PHASE3_FRONTEND.md

# Phase 3 前端模板开发计划

> 日期：2026-04-20 | 状态：进行中
> 背景：Council 调研结论 + CSS 样式机制确认 → Demo 快速落地

---

## 一、调研结论摘要（Council 651e0bf2）

### Q2 — 单订单多SKU（多座位选择的前提）

**结论：✅ 可行，走购物车路线**

ShopXO `BuyService.php:86` 循环处理 `goods_data` 数组，每行独立 `spec_base_id`。现有 `ticket_detail.html` Plan A 代码已写好，但 `submit()` 函数有 bug：只把第一个座位编码进 URL，后续座位丢失。

**最小改动（Demo 1天可上线）：**
- 修复 `submit()`：将 `goodsParamsList` 整体编码，POST 到购物车 `CartSave`，再跳转合并支付
- 绕过 `OrderSplitService` 拆单风险（购物车结算路径不触发按仓库拆单）

### Q1 — ShopXO 自定义模板最佳实践

**结论：原生 PHP + 内联 JS，渐进增强**

- ShopXO view/goods/ 模板使用原生 PHP + 原生 JS，session/buy 控制器直接 render
- 不走 DIY 设计器（只支持静态 HTML 区块，无法参数化）
- H5 直接浏览器预览，无需构建

### Q3 — 第三方无代码构建服务

**结论：辅助有限，座位图等核心交互必须手写**

- 无代码服务适合静态展示区块（票务介绍、艺人信息图）
- 座位图等高交互组件无法用无代码工具精确生成
- 生成代码后需后处理：路径替换 + 变量注入

### Q4 — uni-app 兼容性技术栈选型

**结论：fork shopxo-uniapp，票务页面自研**

- fork `shopxo-uniapp` → `vr-shopxo-uniapp`
- 票务页面（ticket-seat / ticket-wallet / ticket-verify）自研 Vue 3 组件
- 商城标准页面复用 shopxo-uniapp 原生实现
- CSS 一致（H5/小程序都基于 WebView）

---

## 二、CSS 样式注入机制（ShopXO 官方能力）

### 三层注入体系

| 层级 | 机制 | 甲方操作入口 |
|------|------|------------|
| **CSS 变量** | `header_style_root.html` 定义 `:root` 变量，后台主题配置可改 | ShopXO 后台「主题配色」 |
| **插件 CSS Hook** | `plugins_css_data` 钩子注入独立 CSS 文件 | 替换 `static/plugins/vr_ticket/css/ticket.css` |
| **内联 `<style>`** | 当前 `.vr-ticket-page` 样式块，完全隔离 | 直接修改 `ticket_detail.html` |

### CSS 变量体系（ShopXO 官方）

`header_style_root.html` 定义了完整的 CSS 变量系统：

```css
/* 主色 */
--color-main: #E22C08;           /* 可在后台改为甲方品牌色 */
--color-main-light: #ffe3de;
--color-main-hover: #EA6B52;

/* 圆角 */
--border-radius-sm: 0.2rem;
--border-radius: 0.4rem;
--border-radius-lg: 0.8rem;

/* 阴影 */
--box-shadow: 0 5px 20px rgba(50,55,58,0.1);
--box-shadow-sm: 0 2px 8px rgba(50,55,58,0.1);
--box-shadow-lg: 0 8px 34px rgba(50,55,58,0.1);
```

vr_ticket 模板内的 `.vr-ticket-page` 可以直接引用这些变量，实现主题色统一。例如：
```css
.vr-purchase-btn {
    background: var(--color-main);          /* 继承 ShopXO 主题色 */
    border-radius: var(--border-radius-lg);
    box-shadow: var(--box-shadow-sm);
}
```

### 插件 CSS Hook（推荐方案）

在插件 service 中注册 `plugins_css_data` 钩子，加载独立 CSS 文件：

```php
// plugins/vr_ticket/hook/ViewGoodsSpiderCss.php
public function handle()
{
    return 'plugins/vr_ticket/css/ticket.css';
}
```

甲方样式微调时，只需替换 `static/plugins/vr_ticket/css/ticket.css`，不需要改 PHP 模板。

### 当前 ticket_detail.html 样式结构

```
ticket_detail.html
├── <style> 完全独立的内联样式块（.vr-ticket-page 等）
├── HTML 结构（.vr-ticket-page #vrTicketApp）
├── 内联 JS（vrTicketApp 对象）
└── ModuleInclude('public/footer')
```

样式完全隔离，不受 ShopXO 升级影响。甲方设计师可以专注修改 CSS，不需要理解 PHP 模板逻辑。

---

## 三、Demo 交付计划（最小可行方案）

### 目标：1天内上线可演示的多座位下单 Demo

### 当前代码状态

- `ticket_detail.html` 已有 Plan A 代码（submit 函数存在 URL 编码 bug）
- 座位图渲染正常（A/B/C 三排 + 舞台 + 颜色分区 + 选座 UI + 观演人表单）
- `loadSoldSeats()` 是 TODO，需要后端配合

### Demo 交付清单

#### P0 — 必须完成（Demo 当天）

| 任务 | 文件 | 说明 | 优先级 |
|------|------|------|--------|
| **修复 submit() bug** | `ticket_detail.html` | 当前只传第一个座位，需整体编码 goodsParamsList | 🔴 P0 |
| **购物车路由接通** | `ticket_detail.html` | 改用 `CartSave` API 提交多座位，跳转合并支付 | 🔴 P0 |
| **场次切换重置已选座位** | `ticket_detail.html` | `selectSession()` 调用座位重置逻辑（已有代码未调用） | 🔴 P0 |
| **座位类型图例** | `ticket_detail.html` | 已完成 ✅，确认正常显示 | ✅ 已完成 |
| **购买栏按钮状态联动** | `ticket_detail.html` | 已实现 ✅，`disabled` 状态根据选座数量变化 | ✅ 已完成 |

#### P1 — Demo 当天完成后继续

| 任务 | 文件 | 说明 | 优先级 |
|------|------|------|--------|
| **loadSoldSeats() 实现** | `ticket_detail.html` + 后端 | AJAX 调用后端接口，标记已售座位 | 🟡 P1 |
| **座位图缩放/拖拽交互** | `ticket_detail.html` | 原生 JS < 200 行实现 | 🟡 P1 |
| **CSS 样式文件分离** | `static/vr_ticket/css/ticket.css` | 从内联 `<style>` 抽离，通过 `plugins_css_data` 钩子注册 | 🟡 P1 |
| **甲方主题色变量接入** | `ticket_detail.html` <style> | 将硬编码色值改为 `var(--color-main)` 等变量 | 🟡 P1 |

#### P2 — 后续迭代

| 任务 | 说明 | 优先级 |
|------|------|--------|
| shopxo-uniapp fork | 建立 `vr-shopxo-uniapp` 项目骨架 | 🟢 P2 |
| ticket-seat.vue | uni-app 选座核心组件 | 🟢 P2 |
| B 端核销页 | 小程序扫码核销页面 | 🟢 P2 |

---

## 四、关键技术细节

### 4.1 submit() 修复方案

**当前 bug：** `location.href = checkoutUrl + '&goods_params=' + encodeURIComponent(goodsParams)`
URL 方式只能传字符串，多座位数据会被截断或丢失。

**修复方案：** 走购物车 API + 合并支付

```javascript
submit: function() {
    // 1. 收集所有座位数据（现有代码正常）
    var goodsParamsList = this.selectedSeats.map(function(seat, i) {
        var specBaseId = self.specBaseIdMap[seat.seatKey] || self.sessionSpecId;
        var seatAttendee = attendeeData[i] || {};
        return {
            goods_id: self.goodsId,
            spec_base_id: parseInt(specBaseId) || 0,
            stock: 1,
            extension_data: JSON.stringify({
                attendee: seatAttendee,
                seat: { seatKey: seat.seatKey, label: seat.label, price: seat.price }
            })
        };
    });

    // 2. 逐座提交到购物车
    var deferreds = goodsParamsList.map(function(params) {
        return $.post(__goods_cart_save_url__, {
            goods_id: params.goods_id,
            spec_id: params.spec_base_id,
            stock: params.stock,
            // extension_data 作为自定义字段存储
        });
    });

    // 3. 全部成功后跳转合并支付
    $.when.apply($, deferreds).done(function() {
        location.href = __root__ + '?s=index/cart/index';
    }).fail(function() {
        alert('座位已被占用，请重新选择');
    });
}
```

**为什么走购物车路线：**
- `BuyCart` → `BuyTypeGoodsList` → 直接调用 `BuyGoods`，完美支持多 `goods_data` 行
- 购物车结算路径不触发 `OrderSplitService` 按仓库拆单（只按商品拆）
- `plugins_service_order_pay_success_handle_end` 钩子正常触发，QR 票生成不受影响

### 4.2 CSS 变量主题化方案

当前 `ticket_detail.html` 内联样式中的硬编码色值，全部改为 CSS 变量：

```css
/* 改造前 */
.vr-purchase-btn { background: linear-gradient(135deg, #409eff, #3b8ef8); }

/* 改造后 */
.vr-purchase-btn {
    background: linear-gradient(135deg, var(--color-main), var(--color-main-hover));
    border-radius: var(--border-radius-lg);
    box-shadow: var(--box-shadow-sm);
}
```

甲方想要调整主题色时，有三条路：
1. **后台改**：ShopXO 管理后台 → 主题配色 → 自动同步到所有 `var(--color-*)` 变量
2. **文件改**：替换 `static/plugins/vr_ticket/css/ticket.css`
3. **代码改**：直接修改 `ticket_detail.html` 的 `<style>` 块

### 4.3 specBaseIdMap 降级策略

```javascript
var specBaseId = self.specBaseIdMap[seat.seatKey] || self.sessionSpecId;
```

- 如果 `seatKey`（如 "A_1"）在 `specBaseIdMap` 中有对应记录 → 座位级 SKU（精确到每个座位）
- 如果 `specBaseIdMap` 中没有（如后台未批量创建座位规格）→ 降级到 `sessionSpecId`（Zone 级别，同一 zone 全部座位共享一个 SKU）

**后台需要提前创建座位规格**，vr_ticket 后台管理界面需增加「批量生成座位规格」功能。

---

## 五、文件清单

| 文件 | 当前状态 | 下一步 |
|------|---------|--------|
| `shopxo/app/plugins/vr_ticket/view/goods/ticket_detail.html` | Plan A 代码有 bug | 修复 submit()，接购物车 |
| `shopxo/app/plugins/vr_ticket/static/css/ticket.css` | 不存在 | 从 ticket_detail.html 抽离样式 |
| `docs/council-research-output.md` | ✅ 已完成 | 无需修改 |
| `shopxo/app/service/BuyService.php` | 参考 | 无需修改（走购物车路线） |
| `shopxo/app/service/SeatSkuService.php` | 有缺陷（单模板模式） | 等待 Issue #15/#16 修复 |

---

## 六、技术风险

| 风险 | 严重程度 | 缓解 |
|------|---------|------|
| `submit()` 只传第一座位（已发现） | 🔴 高 | 修复 submit()，改走购物车 API |
| OrderSplitService 拆单（多座位变多笔支付） | 🔴 高 | 购物车路线绕过 |
| 座位级 SKU 后台未创建（specBaseIdMap 空） | 🟡 中 | 降级到 Zone 级别 + 后台增加批量生成功能 |
| 甲方主题色调整后样式不一致 | 🟡 中 | CSS 变量化，所有色值引用 `var(--color-*)` |
| shopxo-uniapp fork 官方更新同步成本 | 🟢 低 | 票务页面与商城页面目录隔离 |