# ShopXO × uni-app 前端架构调研报告

> 调研时间：2026-04-17 13:20–13:53 GMT+8
> 调研人：西莉雅（Sileya）
> 参与：大头（Joery HU）
> 文档版本：v1.0.0
> 状态：**阶段性结论**，待美在二次深度调研后更新

---

## 一、执行摘要

### 核心结论

在 ShopXO 生态下，票务小程序的前端开发**不应该走 ShopXO 后台 DIY 设计器路线**，而应该：

```
fork shopxo-uniapp → 直接在 Vue/uni-app 源码层修改页面
    ↓
票务页面（首页/商品详情）完全自研
    ↓
商城标准页面（周边/分类/购物车）复用 shopxo-uniapp 原生实现
    ↓
H5 预览 = 小程序编译效果，CSS 完全一致
```

### 路径选择理由

| 维度 | DIY 设计器路线 | 直接改 Vue 源码路线 |
|------|---------------|-------------------|
| 开发速度 | ❌ 慢（需开发 shopxo-diy 组件再同步） | ✅ 快（直接写 Vue） |
| 自定义自由度 | ⚠️ 受限（只能嵌入静态区块） | ✅ 完全自由 |
| H5/小程序一致性 | ⚠️ 中间层 JSON 可能产生差异 | ✅ 同一套 CSS，两端一致 |
| 票务交互（选座等） | ❌ 无法可视化编辑 | ✅ 完整自定义 |
| 学习成本 | 高（需理解 shopxo-diy 注册机制） | 低（标准 Vue 3） |

---

## 二、实证调研结果

### 2.1 ShopXO 自定义模板 → uni-app 的编译关系

**结论：不存在"模板配置 → 编译成 uni-app"的链路。**

ShopXO 的"模板配置"是 PHP 后台渲染 Web 端（H5/PC）的概念。uni-app 前端是完全独立的项目，通过 API 对接 ShopXO 后端。两者是两套平行代码，不存在编译关系。

### 2.2 官方 uni-app 端：shopxo-uniapp

**源码地址：**
- GitHub: `github.com/gongfuxiang/shopxo-uniapp`
- Gitee: `gitee.com/zongzhige/shopxo-uniapp`
- DCloud 插件市场: `ext.dcloud.net.cn/plugin?id=6380`（可一键导入 HBuilderX）

**支持平台：**
- 微信小程序（MP-WEIXIN）
- QQ 小程序（MP-QQ）
- 百度小程序（MP-BAIDU）
- 支付宝小程序（MP-ALIPAY）
- 抖音/头条小程序（MP-TOUTIAO）
- 快手小程序（MP-KUAISHOU）
- H5
- APP（iOS/Android）

**主题机制：**
- 内置 8 种配色，默认红色（red）
- 主题在 `App.vue` 中改 `default_theme` 配置
- 也支持从 ShopXO 后台远程控制主题配色

**使用方式：**
1. 安装 ShopXO 后端系统（`install.shopxo.net`）
2. HBuilderX 导入 shopxo-uniapp 源码
3. 修改 `App.vue` 的 `request_url` + `static_url` 为目标商城地址
4. 运行/发行到目标平台

**GitHub Forks：100+**，说明大量企业在使用，但绝大多数是私人 fork，公开的票务类二次开发项目**不存在**。

### 2.3 DIY 装修组件：shopxo-diy

**源码地址：**
- GitHub: `github.com/gongfuxiang/shopxo-diy`
- Gitee: `gitee.com/zongzhige/shopxo-diy`

**技术栈：**
- Vue 3 + Vite + TypeScript + SCSS
- MIT 开源协议

**版本对应表（关键发现）：**

| shopxo-diy（DIY端） | ShopXO 后端版本 |
|---------------------|-----------------|
| v1.0.0 | v6.3.0 |
| v1.1.0 | v6.4.0 |
| v1.2.0 | v6.5.0 |
| v1.3.0 | v6.6.0 |
| v1.4.0 | v6.7.0 |
| v1.4.1 | v6.7.1 |
| v1.4.2 | v6.8.0 |

**说明：shopxo-diy 和 ShopXO 后端必须版本匹配**，不能混用。

**DIY 设计器的真实能力：**
- 支持拖拽的标准组件：商品、文章、图片魔方、热区、视频、轮播、自定义 HTML
- **不支持**：在设计器里可视化编辑自定义 Vue 组件（座位图、QR 票等）
- 自定义组件只能以"静态自定义 HTML 区块"方式嵌入设计器，无法参数化配置

**三层渲染架构：**

```
ShopXO PHP 后台（DIY 设计器）
    │
    │ 输出：页面配置 JSON → 存入数据库
    ↓
shopxo-diy（Vue 3 组件库）
    │ 负责渲染标准 DIY 组件
    ↓
ShopXO Web（H5/PC） + shopxo-uniapp（小程序/APP）
    │  两个端读同一份 JSON，各自渲染
    ↓
效果一致性由"同一套 JSON + 同一套 Vue 组件库"保证
```

**APP 预览能力：**
- ShopXO 后台 DIY 设计器只能在 Web 端（H5）预览
- shopxo-uniapp 的 `/pages/diy/diy.vue` 独立渲染同样 JSON
- **不存在**"设计后一键自动编译到 uni-app"的机制

### 2.4 第三方付费主题

**来源：ShopXO 应用商店（store.shopxo.net）**

| 开发者 | 版本 | 平台支持 | 特色 |
|--------|------|---------|------|
| chuyin | 1.0.0–2.2.1 | 微信/支付宝/QQ/百度小程序 + H5 + Android/iOS APP | 重构 UI、8种配色、一站一授权、永久免费适配官方插件 |

**注意：** shopro（ITmonkey-cn/shopro-uniapp）是独立电商系统，不是 ShopXO 的 fork，不完全兼容 ShopXO API，不能作为 ShopXO 的 uni-app 主题使用。

### 2.5 给 shopxo-diy 开发自定义组件的可行性

**技术层面：可以**，但流程较长：

```
1. fork shopxo-diy
2. 在 src/components/ 下开发 Vue 组件（如 SeatMap.vue）
3. 在 src/config/components.js 里注册组件名+配置
4. npm run build → 生成发布产物
5. ShopXO 后台加载新组件 → DIY 设计器以"自定义区块"嵌入
6. shopxo-uniapp 同步更新 shopxo-diy 版本
```

**限制：**
- 每次改组件都要 rebuild + 同步版本
- DIY 设计器里无法可视化配置组件参数（座位数、排数等）
- 对于票务选座这种复杂交互，自定义 HTML 区块的能力不足以支持

### 2.6 关键问题：H5 预览 = 小程序编译效果？

**是的，可以做到。**

uni-app 在 H5 和小程序上的 CSS 渲染**完全一致**，因为两者都基于 WebView：

```
H5 端：Chrome/WebView → CSS 引擎（标准浏览器）
小程序端：微信 WebView → 同样的 CSS 引擎
```

**uni-app CSS 规范注意事项：**

| 做法 | 说明 |
|------|------|
| 用 `rpx` 不用 `vw/vh` | rpx 是 uni-app 的响应式单位，H5/小程序都支持 |
| 用 `view` 不用 `div` | uni-app 跨平台标签 |
| 避免 `calc()` 混用单位 | `calc(100% - 215px)` 而非 `calc(100% - 215)` |
| 避免浏览器私有前缀 | 小程序不需要 |
| `position: fixed` 吸顶 | H5 用 `fixed`，小程序用 `absolute` + scroll-view 模拟（shopxo-uniapp 已有解决方案） |

**不需要 DIY 设计器作为中间层。** shopxo-uniapp 里的页面就是标准 Vue 文件，直接修改即可。

---

## 三、设计路径决策

### 3.1 推荐架构

```
┌─────────────────────────────────────────────────────┐
│  fork shopxo-uniapp（vr-shopxo-uniapp）             │
│                                                     │
│  ┌──────────────────────────────────────────────┐  │
│  │ DIY 设计器（ShopXO 后台）                      │  │
│  │  → 管理：普通商城首页楼层、分类页、活动页       │  │
│  │  → 输出：JSON → shopxo-uniapp /pages/diy/    │  │
│  └──────────────────────────────────────────────┘  │
│                                                     │
│  ┌──────────────────────────────────────────────┐  │
│  │ 直接修改 shopxo-uniapp 源码                   │  │
│  │                                              │  │
│  │ pages/index/index.vue → 首页双 Tab（票/周边）  │  │
│  │ pages/goods-detail/goods-detail.vue → 票务   │  │
│  │ pages/ticket-buy/ → 选座+购票主流程（新建）   │  │
│  │ pages/ticket-wallet/ → 票夹（新建）           │  │
│  │ pages/ticket-verify/ → B 端核销（新建）        │  │
│  └──────────────────────────────────────────────┘  │
│                                                     │
│  H5 预览 = 小程序编译效果（CSS 完全一致）           │
└─────────────────────────────────────────────────────┘
```

### 3.2 页面职责划分

| 页面 | 来源 | 修改方式 |
|------|------|---------|
| 首页（票务 Tab） | shopxo-uniapp 改写 | 完全自研，座位图/场次组件 |
| 首页（周边 Tab） | shopxo-uniapp 改写 | 复用商品列表，DIy 数据输出 |
| 商品详情（票务） | shopxo-uniapp 改写 | 自定义跳转选座流程 |
| 商品详情（周边） | shopxo-uniapp 原生 | 复用原生 UI |
| 分类/搜索/购物车/订单 | shopxo-uniapp 原生 | 复用原生流程 |
| 票夹（我的票） | 新建 | 票务专属页面 |
| B 端核销 | 新建 | 扫码 + API 验证 |

### 3.3 技术选型

| 技术项 | 选型 | 理由 |
|--------|------|------|
| 前端框架 | shopxo-uniapp（fork） | 完整对接 ShopXO API，节省 80% 开发量 |
| CSS 方案 | 纯 CSS / SCSS | 与官方一致，不需要 Tailwind 等新框架 |
| 主题色 | CSS Custom Properties | shopxo-uniapp 已有 8 色体系，可复用 |
| 响应式 | rpx | uni-app 标准响应式单位，H5/小程序一致 |
| 打包工具 | HBuilderX | uni-app 官方 IDE |
| 开发模式 | 直接改 Vue 源码 | 不走 DIY 设计器，完全控制 |

### 3.4 与 vr-shopxo-plugin 的关系

```
shopxo-uniapp（H5/小程序/APP 前端）
    │
    │ API 调用（GET/POST）
    ↓
ShopXO PHP 后端 + vr-shopxo-plugin（票务插件）
    │
    │ 数据库读写
    ↓
vr_sessions / vr_tickets / vr_seat_templates / vr_attendees 等表
```

uniapp 前端通过 API 调用 ShopXO 后端接口，vr-shopxo-plugin 的数据库表通过插件自定义接口暴露，前端无需感知底层 PHP 实现。

---

## 四、原始调研资料清单

### 4.1 线上资料

| 编号 | 来源 | URL | 关键内容 |
|------|------|-----|---------|
| R1 | GitHub shopxo-uniapp | `github.com/gongfuxiang/shopxo-uniapp` | 官方 uni-app 端，支持全平台，8种配色 |
| R2 | GitHub shopxo-diy | `github.com/gongfuxiang/shopxo-diy` | DIY 组件库，Vue 3+Vite+TypeScript，版本对应表 |
| R3 | GitHub shopxo | `github.com/gongfuxiang/shopxo` | ShopXO 主仓库，v6.8.0 |
| R4 | DCloud 插件市场 | `ext.dcloud.net.cn/plugin?id=6380` | 一键导入 HBuilderX |
| R5 | ShopXO 文档 | `doc.shopxo.net/article/2.html` | uni-app 使用教程，request_url 配置 |
| R6 | ShopXO 文档 | `doc.shopxo.net/article/4/265292898306621440.html` | 目录结构（v2.2.0+） |
| R7 | ShopXO 文档 | `doc.shopxo.net/article/3.html` | 插件开发文档索引 |
| R8 | uni-app 官网 | `zh.uniapp.dcloud.io/matter.html` | 跨端注意事项，H5/小程序 CSS 一致性说明 |
| R9 | uni-app 文档 | `zh.uniapp.dcloud.io/tutorial/syntax-css.html` | rpx/calc 等 CSS 规范 |
| R10 | 微信开放社区 | `developers.weixin.qq.com/community/develop/article/doc/0000a6de494e78235c3dc87b75b013` | 第三方开发者分享的 shopxo 小程序主题（黄色主题） |
| R11 | 掘金 | `juejin.cn/post/7043972891381071880` | ShopXO uni-app 主题分享 |
| R12 | ShopXO 应用商店 | `store.shopxo.net/goods-41.html` | 第三方付费主题（chuyin，v1.0.0-2.2.1） |
| R13 | GitHub shopxo-uniapp | `github.com/gongfuxiang/shopxo-uniapp/network/members` | 100+ forks 列表（2026-04-17 采集） |
| R14 | CSDN | `blog.csdn.net/qq_35393869/article/details/114523844` | ShopXO 开发文档目录 |

### 4.2 本地 vr-shopxo-plugin 文档

| 编号 | 文件 | 关键内容 |
|------|------|---------|
| L1 | `docs/07_SHOPXO_PLUGIN_MECHANISM.md` | 插件开发机制、config.json、钩子系统、生命周期事件 |
| L2 | `docs/09_SHOPXO_HOOKS_REFERENCE.md` | 完整钩子清单（v6.8.0），商品详情页/用户中心/订单等注入点 |
| L3 | `docs/02_FRONTEND_CUSTOMIZATION.md` | shopxo-uniapp 编译流程、pages.json 路由、条件编译指令、商品详情页改造方案 |
| L4 | `docs/09_SHOPXO_HOOKS_REFERENCE.md` | 票务插件推荐钩子（`plugins_service_order_pay_success_handle_end` 等） |
| L5 | `ARCHITECTURE.md` | 整体架构，读写分离，商品模型（ticket/physical/bundle） |

---

## 五、关键发现汇总

### 5.1 关于 ShopXO DIY 设计器

1. **不支持**直接把自定义 Vue 组件导入设计器
2. **不支持**设计后自动编译到 uni-app（需手动同步版本）
3. **支持**以"自定义 HTML"方式嵌入静态区块（但无法参数化）
4. 适合场景：非技术人员修改标准商城页面（首页楼层/分类等）
5. 不适合场景：票务选座交互、QR 票卡片等复杂自定义 UI

### 5.2 关于 shopxo-diy

1. Vue 3 + Vite + TypeScript + SCSS 技术栈
2. 与 ShopXO 后端版本强绑定（v1.4.2 ↔ v6.8.0）
3. 可开发自定义组件，但注册机制复杂，改完需 rebuild
4. 组件风格：CSS Custom Properties 主题切换，SCSS 变量

### 5.3 关于 shopxo-uniapp

1. 完整独立项目，通过 API 对接 ShopXO 后端
2. `App.vue` 改 `request_url` / `static_url` 即可连接任意 ShopXO 实例
3. 页面是标准 Vue 文件，**直接修改，不需要经过 DIY 设计器**
4. 支持全平台（小程序/H5/APP），CSS 在 H5 和小程序间完全一致

### 5.4 关于 H5 和小程序的一致性

1. uni-app 的 H5 和小程序都基于 WebView，CSS 渲染一致
2. 关键：用 rpx 不用 vw/vh，用 view 不用 div，避免混用单位
3. 不需要任何中间层即可实现"预览=发行效果"

---

## 六、待美在深度调研事项

以下事项需美在从**代码层面**做二次深入解析，待完成后更新本文档：

1. **shopxo-uniapp 源码结构扫描**
   - 关键页面文件位置（index/goods-detail/cart/user）
   - API 层封装方式（`get_request_url` 全局方法）
   - 全局组件注册机制（`pages/index/index.vue` 的 `usingComponents`）
   - 主题色 CSS 变量体系（8 色实现方式）

2. **shopxo-diy 组件注册机制**
   - `src/config/` 目录的组件配置格式
   - 如何注册一个自定义组件（如 `SeatMap.vue`）
   - 与 ShopXO 后端的 JSON 数据格式对接方式

3. **票务商品详情页的 Hook 注入点**
   - `plugins_view_goods_detail_base_sku_top` 的实际返回位置
   - 是否存在从 Hook 跳转到独立页面的成熟方案
   - 商品详情页完整模板继承链（从哪个基文件继承）

4. **支付成功回调到票务记录的完整链路**
   - `plugins_service_order_pay_success_handle_end` 钩子的触发时机
   - 订单数据中如何区分票务商品和普通商品
   - 观演人信息的存储位置（订单扩展字段还是独立表）

5. **B 端核销页面的权限控制**
   - 后台核销员角色（`vr_verifiers`）如何与 ShopXO 后台用户关联
   - 核销 API 的鉴权方式（后台登录态还是独立 token）

---

## 七、版本历史

| 版本 | 日期 | 修改内容 |
|------|------|---------|
| v1.0.0 | 2026-04-17 | 初始版本，涵盖本次调研全部发现 |

---

## 八、参考链接（快速访问）

```
shopxo-uniapp GitHub:   https://github.com/gongfuxiang/shopxo-uniapp
shopxo-diy GitHub:      https://github.com/gongfuxiang/shopxo-diy
ShopXO 文档目录:        https://doc.shopxo.net/
uni-app CSS 规范:       https://zh.uniapp.dcloud.io/tutorial/syntax-css.html
uni-app 跨端注意:       https://zh.uniapp.dcloud.io/matter.html
DCloud 插件市场:        https://ext.dcloud.net.cn/plugin?id=6380
ShopXO 安装包:          https://install.shopxo.net/
```