docs: add 12_UNIAPP_FRONTEND_RESEARCH.md - shopxo-uniapp frontend architecture survey

- 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

@@ -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/
+```