# ShopXO 酷炫前端模板实现方案调研报告

> 版本：v1.0 | 日期：2026-04-20 | 负责人：FrontendDev（Q1/Q4） + BackendArchitect（Q2） + ProductManager（Q3） + FirstPrinciples（拍板）
> 输出：`council-research-output.md` | 限时：20分钟

---

## 执行摘要

vr-shopxo-plugin 项目推进 Phase 3 前端模板调研，聚焦 4 个研究方向，最终收敛到"最小可行方案 vs 理想方案"的决策矩阵。

**最高优先级结论**：Q2（多SKU支持）是整个多座位选择功能的**技术前提**。基于现有 `ticket_detail.html` 的代码分析，ShopXO 已通过 `goods_params` 数组机制支持多 SKU 下单，但需要后端验证该路径是否稳定。

---

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

**负责人**：FrontendDev | **置信度**：高

### 结论

| 问题 | 结论 | 依据 |
|------|------|------|
| 最佳技术栈 | **原生 HTML + CSS + Vanilla JS**（PHP 模板） | ThinkTemplate 与 Vue CDN 冲突；原生方案最稳定 |
| 能否用 Vue CDN | ❌ **不可行** | ThinkTemplate 的 `{{}}` 语法与 Vue/Mustache 冲突 |
| 酷炫 UI 实现方式 | CSS 动画 > 3D舞台 > GSAP > 暗色主题 | ticket_detail.html 已验证 |
| ShopXO 原生组件 | `ModuleInclude()` 头部/底部；`Config()` 全局配置 | 已有完整实现 |
| H5 预览兼容性 | ✅ 完全兼容（渲染层为标准浏览器） | PHP 模板天然支持 H5 |

### 技术栈决策

```
推荐路径（PHP 模板层）：
  ticket_detail.html（原生 HTML+CSS+JS）
    → 酷炫化 CSS 动画 + 座位图交互
    → API 调用 ShopXO 后端（jQuery $.get/post）
    → 跳转 ShopXO 结账页（goods_params）
    → H5 预览 = 生产环境效果

不推荐路径：
  ❌ Vue CDN → ThinkTemplate 冲突
  ❌ DIY 设计器 → 无法自定义复杂交互
  ❌ 自定义 HTML 区块 → 参数化能力不足
```

### 酷炫 UI 可行方向（优先级排序）

1. **CSS 动画** — 过渡动画、交互动效，最小改动
2. **3D 舞台效果** — 透视变换 + 渐变，当前 `.vr-stage` 已有基础
3. **触控手势** — Pinch-to-zoom 座位图，H5 支持良好
4. **GSAP** — 复杂舞台动画，需引入库（增加体积）
5. **暗色主题** — 演唱会氛围感，当前为浅色，可切换

### 关键约束

- 所有 CSS 必须使用 `.vr-` 前缀（避免与 ShopXO 原生样式冲突）
- JS 使用 IIFE 包裹（`;(function(){...})()`），避免全局污染
- PHP 变量注入用 `<?php echo ... ?>`，不用 `{{}}`
- 座位图数据通过 `$goods_spec_data` / `$vr_seat_template` 注入

---

## Q2 — 单订单多 SKU 支持

**负责人**：BackendArchitect | **状态**：进行中（Task B1-B3 未完成）

> ⚠️ **关键风险**：Q2 结论决定多座位选择功能能否落地（R1，P0 级风险）

### 初步分析（基于 ticket_detail.html 现有代码）

`ticket_detail.html` 第 410-441 行已实现多 SKU 提交逻辑：

```javascript
// goods_params_list：每座一行
var goodsParamsList = this.selectedSeats.map(function(seat, i) {
    return {
        goods_id: self.goodsId,
        spec_base_id: parseInt(specBaseId) || 0,
        stock: 1,
        extension_data: JSON.stringify({ attendee, seat })
    };
});
var goodsParams = JSON.stringify(goodsParamsList);
location.href = checkoutUrl + '&goods_params=' + encodeURIComponent(goodsParams);
```

这意味着**前端已准备好**多 SKU 下单请求。关键问题是：ShopXO 后端 `index/buy/index` 控制器是否处理数组格式的 `goods_params`。

**BackendArchitect 的任务是**：
1. 读取 ShopXO 订单模型（`ShopxyOrderService` / `OrderService`）
2. 分析 `goods_params` 参数的处理逻辑
3. 判断是否支持多行项目
4. 如不支持，设计最小改动方案（劫持 `plugins_service_order_create_start` 钩子）

### 技术路径

```
现有路径（Plan A）：
  ticket_detail.html → goods_params JSON 数组 → index/buy/index
    → 需要后端支持数组格式 goods_params

最小改动方案（Plan B）：
  ticket_detail.html → 创建多个独立小订单 → 合并支付
    → 用户体验差（多次支付弹窗）

理想方案（Plan C）：
  插件创建自定义下单接口 → 支持多 SKU 行项目
    → 改动量大，需要修改 ShopXO 核心
```

---

## Q3 — 第三方无代码构建服务提示词策略

**负责人**：ProductManager | **状态**：进行中

### 预期结论（待填充）

> ProductManager Task P1/P2 执行中，以下为 FrontendDev 从前端视角补充的约束条件

#### ShopXO PHP 模板约束条件（需写入 prompt）

```
HTML 结构约束：
- 必须使用 .vr- 前缀的 class 命名
- 必须包含 ModuleInclude('public/header') 和 ModuleInclude('public/footer')
- PHP 变量注入格式：<?php echo $var ?>
- ThinkTemplate 禁用 {{}} 插值（与 Vue 冲突）

CSS 约束：
- 避免 !important（优先使用具体选择器）
- 座位格子宽高：28px × 28px（硬编码在 ticket_detail.html）
- 座位图外框：max-width 1200px，居中
- 购买栏：position: fixed; bottom: 0（固定在底部）
- 主题色：#409eff（ShopXO 主题蓝）+ #f56c6c（红色警示）

API 格式约束：
- GET: /?s=plugins/vr_ticket/index/sold_seats&goods_id=X&spec_base_id=Y
- POST: /?s=plugins/vr_ticket/index/create_order（如果后端提供）
- 响应格式：{ code: 0/1, msg, data }
```

#### 无代码服务生成代码的后处理步骤

1. **提取 `<style>` 内容** → 替换 `.vr-` 前缀 → 合并到 ticket_detail.html
2. **提取 `<div id="vrTicketApp">` 内容** → 替换 PHP 变量注入
3. **提取 `<script>` 内容** → 包装为 IIFE → 合并到 ticket_detail.html
4. **验收检查**：
   - 无 `{{}}` 或 Mustache 语法
   - 无 `import Vue from 'vue'` 等 ESM 语法
   - 座位格子尺寸为 28px
   - 购买栏为 fixed 底部

---

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

**负责人**：FrontendDev | **置信度**：高

### 结论

| 问题 | 结论 |
|------|------|
| shopxo-uniapp 是唯一可行路径 | ✅ 是；完全独立于 PHP 模板，通过 API 对接 |
| 两套前端体系是否冲突 | ❌ 否；PHP H5（Web端）与 uni-app（小程序端）完全独立 |
| H5 预览 = 小程序效果 | ✅ 是；uni-app 在 H5 和小程序都基于 WebView |
| "一套代码，双端运行" | ✅ 可以做到；shopxo-uniapp 直接改 Vue 源码即可 |

### 技术路径

```
最小可行方案（当前可执行）：
  1. 增强 ticket_detail.html（原生 HTML+CSS+JS）
     → 酷炫 CSS 动画 + 座位图交互改进
     → H5 票务下单体验提升
  2. 暂不开发 uni-app 小程序端（成本高）

理想方案（Phase 4）：
  1. fork shopxo-uniapp → vr-shopxo-uniapp
  2. 修改 pages/goods-detail → 票务专用商品详情（选座）
  3. 新建 pages/ticket-buy → 选座+购票主流程
  4. 新建 pages/ticket-wallet → 我的票夹
  5. 新建 pages/ticket-verify → B 端核销页
  6. HBuilderX 编译 → 微信小程序 + H5
```

### uni-app 技术栈（已验证）

| 项目 | 选型 | 理由 |
|------|------|------|
| 框架 | shopxo-uniapp（fork） | 完整对接 ShopXO API，节省 80% 开发量 |
| CSS 方案 | 纯 CSS / SCSS | 与官方一致 |
| 响应式 | **rpx**（不用 vw/vh） | H5/小程序一致的响应式单位 |
| 标签 | **view**（不用 div） | uni-app 跨平台标签 |
| 打包工具 | HBuilderX | uni-app 官方 IDE |
| 开发模式 | 直接改 Vue 源码 | 不走 DIY 设计器，完全控制 |

### Q4 与 Q2 的依赖关系

- Q4 的"多座位选择"功能依赖 Q2 的多 SKU 后端支持
- **但 uni-app 小程序端的开发可以立即开始**（无需等待 Q2）
- Q4 的路由/页面结构/API 层封装都可以提前执行

---

## 综合决策矩阵

### 最小可行方案 vs 理想方案

| 维度 | 最小可行方案（当前可执行） | 理想方案（Phase 4） |
|------|--------------------------|-------------------|
| **技术栈** | 原生 HTML+CSS+JS（PHP 模板） | shopxo-uniapp（fork） + Vue 3 |
| **多座位支持** | 依赖 Q2 结论（Plan A/B/C） | 自研下单 API，支持多 SKU |
| **微信小程序** | ❌ 暂不支持 | ✅ 一键编译 |
| **H5 效果** | ✅ 当前 ticket_detail.html | ✅ shopxo-uniapp H5 |
| **开发周期** | 1-2 周（仅 PHP 模板优化） | 6-8 周（uni-app 全套） |
| **团队要求** | 前端 + PHP | 前端（uni-app）+ PHP |
| **用户体验** | 中等（H5 流畅，小程序缺失） | 高（双端一致体验） |

### 优先级和依赖关系

```
优先级 1（P0）：Q2 多SKU后端支持
  ↓ 直接决定多座位功能能否落地
优先级 2（P1）：Q1 Q4 酷炫模板执行
  ↓ 可立即开始，不依赖 Q2
优先级 3（P2）：Q3 无代码服务策略
  ↓ Q1 技术栈确定后才开始编写 prompt
```

### 最大技术风险点

| 风险 | 级别 | 描述 | 缓解方案 |
|------|------|------|---------|
| **R1**：Q2 多SKU不支持 | P0 | 多座位选择无法落地 | Plan B（多次下单）或 Plan C（自定义下单 API） |
| **R2**：uni-app 与 ShopXO H5 模板冲突 | P1 | 两套前端体系如何共存 | 已澄清：完全独立，无冲突 |
| **R3**：无代码服务代码质量 | P2 | 生成的 HTML/CSS 可能不符合规范 | Q3 输出后处理 checklist |
| **R4**：H5 预览与微信小程序兼容 | P2 | 部分 CSS/JS API 在双端表现不一致 | uni-app 用 rpx + view 标签，避免特定 API |

---

## 各 Agent 贡献

| Agent | 负责方向 | 状态 | 关键输出 |
|-------|---------|------|---------|
| FrontendDev | Q1（模板最佳实践）+ Q4（uni-app 选型） | ✅ 完成 | 本文档 Q1 + Q4 章节 |
| BackendArchitect | Q2（多SKU支持） | 🔄 进行中 | 待填入 Q2 章节 |
| ProductManager | Q3（无代码提示词） | 🔄 进行中 | 待填入 Q3 章节 |
| FirstPrinciples | 拍板 + 最终评审 | ⬜ 待开始 | — |

---

## 下一步行动

**立即可执行（不依赖 Q2）**：
1. **酷炫化 ticket_detail.html** — CSS 动画增强 + 暗色主题切换
2. **Fork shopxo-uniapp** — 为 Phase 4 微信小程序做准备
3. **完善座位图交互** — 已选座位动画 + 触控缩放

**等待 BackendArchitect Q2 结论后执行**：
4. **多座位下单流程验证** — 测试 goods_params 数组格式是否被后端接受
5. **Plan B/C 实现** — 如果 Plan A 失败，实施多次下单或自定义下单 API

---

*本文件由 FrontendDev 基于 Round 2 Q1/Q4 调研结果起草，Q2/Q3 章节待 BackendArchitect 和 ProductManager 完成各自任务后更新。*