README.md



西园寺预约（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