363 lines
15 KiB
Markdown
363 lines
15 KiB
Markdown
# 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/
|
||
``` |