Hooke / xysBooking

西园寺预约（xysBooking）

面向游客的预约 H5（以微信内打开为主），包含预约下单/支付/预约码展示/预约记录；同时提供义工端登录与扫码核销能力。

技术栈

• Vue 3 + Vue Router（Hash）
• Vite（含动态导入增强、Vant 组件自动注册、AutoImport）
• Pinia（全局状态、keep-alive include）
• Vant 4（移动端 UI）
• axios（统一拦截器与错误处理）
• weixin-js-sdk（JSSDK 初始化、扫码）
• Less（全局变量注入：src/assets/styles/base.less）

业务功能概览

• 预约链路
  • 预约须知：/notice
  • 选择日期/时段：/booking
  • 参观者管理（新增/删除/选择）：/me、/addVisitor、/submit
  • 提交预约 + 支付跳转：/submit（支付落地页由后端返回/拼接）
  • 支付回跳反馈：/callback
  • 预约成功页：/success
  • 预约码展示：/bookingCode（组件化二维码展示）
  • 预约记录列表/详情/取消：/bookingList、/bookingDetail（含取消预约退款入口）
• 查询链路
  • 身份证查询预约码：/search
• 授权与环境
  • 微信授权页：/auth（401 自动跳转）
  • 微信扫码能力测试：/wxScanTest
• 义工核销
  • 义工登录：/volunteerLogin
  • 扫码核销结果页：/verificationResult

运行与构建

• 安装依赖：npm i
• 本地开发：npm run dev（或 npm run start 以 host 方式启动）
• 构建：npm run build
• 构建（含 vue-tsc）：npm run build-ts

发布

• 一键编译上传（部署到 jcedu）：npm run jcedu_upload
• 其它环境：npm run oa_upload、npm run dev_upload
• 旧发布脚本：publish.sh（本地构建后搬运到指定目录并提交）

环境变量（.env*）

• VITE_BASE：资源公共路径（生产通常为 /f/reserve/）
• VITE_PORT：本地端口
• VITE_PROXY_PREFIX：代理前缀（默认 /srv/）
• VITE_PROXY_TARGET：代理目标
• VITE_OUTDIR：构建输出目录名（默认 reserve）
• VITE_CONSOLE：是否开启调试（项目内按需使用）
• VITE_OPENID / VITE_ID 等：开发/测试辅助字段（以实际后端规则为准）

项目结构

.
├── build/                     开发代理配置
├── src/
│   ├── api/                   接口层（业务接口、微信相关、核销相关）
│   │   ├── fn.js              接口统一包装：fn / fetch
│   │   ├── index.js           预约业务 API 集合
│   │   ├── redeem.js          义工核销 API
│   │   └── wx/                微信签名/JSAPI 列表/支付等
│   ├── assets/                静态资源（图片、全局 less）
│   ├── common/                公共工具（mixin/tool/vueuse 示例等）
│   ├── components/            通用组件（二维码、预约卡片等）
│   ├── composables/           组合式能力（登录流程、分享等）
│   ├── hooks/                 hooks（路由跳转、节流防抖、keep-alive 控制等）
│   ├── store/                 Pinia store
│   ├── utils/                 工具库（axios、环境判断、版本更新检测等）
│   ├── views/                 页面（与 route.js 一一对应）
│   ├── App.vue                应用根组件（JSSDK 初始化、版本更新提示）
│   ├── main.js                入口（注册 Vant、Pinia、Router，挂载 axios）
│   ├── route.js               静态路由表（页面 meta.title）
│   └── router.js              路由实例 + 动态路由注入（mock + generateRoute）
├── vite.config.js             Vite 配置（别名、代理、Less 注入、构建输出等）
└── package.json               脚本与依赖

关键实现说明（便于快速定位）

• 微信 JSSDK 全局初始化
  • 入口：App.vue
  • 行为：启动时调用后端签名接口 wxJsAPI，执行 wx.config，并把初始化 Promise 复用到 window.__wx_ready_promise 供页面等待
• 接口统一返回/错误处理
  • axios 拦截器：src/utils/axios.js
    • 默认公共参数：f=reserve、client_name=智慧西园寺
    • 401 时跳转 /auth（核销端 reserve_admin 请求不跳）
  • API 包装：src/api/fn.js
    • 约定后端结构：{ code, data, msg, show }，code === 1 视为成功
• 版本更新提示（生产环境）
  • 实现：src/utils/versionUpdater.js
  • 思路：轮询拉取 VITE_BASE 指向的入口 HTML，对比 <script> 快照，提示用户刷新
• 路由与页面
  • 路由表：src/route.js
  • 路由实例：src/router.js

可复用能力（迁移到其它项目的候选清单）

• 通用网络层
  • axios 拦截器基座（公共参数、401 重定向、可静默错误）：axios.js
  • API 调用封装（fn/fetch/uploadFn）：fn.js
• 微信能力基座
  • JSSDK 初始化复用（window.__wx_ready_promise 约定 + 统一入口初始化逻辑）：App.vue
  • 扫码结果归一化/核销流程模板（适合复制到其它“扫码核销/验票”类项目）：verificationResult.vue
• 前端工程化工具
  • 版本更新检测器 Updater（适合静态部署、文件名带 hash 的站点）：versionUpdater.js
  • 动态路由组装（后端路由 -> vue-router 结构）：generateRoute.js
  • 路由跳转 hooks（useGo/useReplace）：useGo.js
• 业务 UI 组件雏形
  • 预约记录卡片、二维码展示组件（可沉淀为“订单卡片/票码”组件库能力）：src/components/*

项目优缺点（当前状态）

优点

• 业务主链路完整：预约 -> 支付 -> 预约码 -> 记录/详情/取消；另有核销端闭环
• 网络层与接口层有统一入口，页面调用成本低（fn(fetch.xxx)）
• 微信 JSSDK 做了全局初始化复用，页面侧只需要等待 Promise
• 生产环境具备“版本更新提示”，降低缓存导致的线上问题
• Vite 工具链与 Vant 按需自动注册已接入，上手开发快

缺点 / 风险点

• 包管理与锁文件混用（npm/yarn lock 同时存在，未见 pnpm-lock），依赖一致性风险较高
• 缺少显式的 lint/test 脚本与 CI 校验，回归风险主要依赖人工
• router.js 里使用 import.meta.globEager；在 Vite v3+ 已废弃，建议改为 import.meta.glob('...', { eager: true })（来源：https://v3.vitejs.dev/guide/migration）
• 项目内存在 TypeScript 相关产物/依赖（d.ts、tsconfig、vue-tsc），但主体代码以 JS 为主，规范不够统一
• generatePackage.js 统一导出常用依赖虽然省 import，但会增加页面与项目工具集的耦合度（迁移/重构成本上升）

---

库：git@gitlab.kmlab.com:hooke1234/xysBooking.git