From 207f49839b565fc6123914343da3f26331346a24 Mon Sep 17 00:00:00 2001 From: Council Date: Fri, 17 Apr 2026 13:54:13 +0800 Subject: [PATCH] docs: add 12_UNIAPP_FRONTEND_RESEARCH.md - shopxo-uniapp frontend architecture survey MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - ShopXO DIY designer limitations (cannot import custom Vue components) - shopxo-diy vs shopxo-uniapp architecture relationship - Recommended path: fork shopxo-uniapp, modify Vue source directly - H5/mini-program CSS consistency via rpx + uni-app WebView - Full evidence archive and pending deep-dive items for 美在 --- docs/12_UNIAPP_FRONTEND_RESEARCH.md | 363 ++++++++++++++++++++++++++++ 1 file changed, 363 insertions(+) create mode 100644 docs/12_UNIAPP_FRONTEND_RESEARCH.md diff --git a/docs/12_UNIAPP_FRONTEND_RESEARCH.md b/docs/12_UNIAPP_FRONTEND_RESEARCH.md new file mode 100644 index 0000000..6ce1a1b --- /dev/null +++ b/docs/12_UNIAPP_FRONTEND_RESEARCH.md @@ -0,0 +1,363 @@ +# 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/ +``` \ No newline at end of file