README.md



项目介绍

本项目是将原有H5预约系统迁移至微信小程序的实现。基于 Taro4 + Vue3 + NutUI 开发，保留了原有的功能和UI风格。


功能模块


预约流程


  日期与时间段选择 (pages/booking/index)
  预约信息确认与提交 (pages/submit/index)
  预约记录查看 (pages/bookingList/index)
  预约详情 (pages/bookingDetail/index)


参观者管理


  参观者列表 (pages/visitorList/index)
  添加/编辑参观者 (pages/addVisitor/index)
  支持身份证号校验与脱敏显示


个人中心


  预约码展示 (pages/bookingCode/index)
  我的页面 (pages/me/index)
  邀请码/证件号查询 (pages/search/index)


弱网与离线模式


  弱网提示页 (pages/weakNetwork/index)
  离线预约记录列表 (pages/offlineBookingList/index)
  离线预约记录详情/离线二维码 (pages/offlineBookingDetail/index)
  离线预约码入口页 (pages/offlineBookingCode/index)
  离线预约缓存刷新与轮询 (src/composables/useOfflineBookingCache.js, src/composables/useOfflineBookingCachePolling.js)
  网络从可用变为弱网/无网时，弹窗提示并可一键进入离线模式（src/app.js）


义工核销


  义工登录与权限预检 (pages/volunteerLogin/index)
  核销页（扫码核销 + 结果展示）(pages/verificationResult/index)


公共功能


  全局路由封装 (hooks/useGo)
  API 请求封装 (utils/request, api/index)
  登录授权流程 (pages/auth/index)
  弱网提示文案统一管理 (utils/uiText.js)


技术栈


  框架: Taro 4.x
  UI库: NutUI 4.x (Vue3)
  语言: JavaScript (Vue3 Setup 语法糖)
  样式: Less + TailwindCSS (部分)
  状态管理: Pinia
  路由: Taro Router + 自定义 Hooks


项目结构


  src/api: 接口定义
  src/assets: 图片等静态资源
  src/components: 公共组件 (qrCode, qrCodeSearch, reserveCard等)
  src/composables: 组合式函数 (离线缓存/轮询等)
  src/pages: 页面文件
  src/hooks: 组合式函数 (useGo等)
  src/stores: Pinia 状态管理 (main/router 等)
  src/utils: 工具函数 (request, authRedirect, network, uiText 等)


项目运行


安装依赖

pnpm install


运行开发环境

pnpm dev:weapp


打包构建

pnpm build:weapp


离线预约缓存轮询说明


目标

在「已授权 + 网络可用」时，定时刷新离线预约记录缓存（本地 storage：OFFLINE_BOOKING_DATA），用于弱网/离线兜底页面展示。


相关文件


  离线缓存刷新：src/composables/useOfflineBookingCache.js


  核心方法：refresh_offline_booking_cache({ force })


  轮询与网络监听：src/composables/useOfflineBookingCachePolling.js


  核心方法：enable_offline_booking_cache_polling(options) / disable_offline_booking_cache_polling()


  启动入口：src/app.js


  在授权成功后调用 enable_offline_booking_cache_polling()


启动条件

轮询启动需要同时满足：


 ref_count > 0：表示当前确实有人需要轮询（应用级启用会占用 1 个引用）
 network_usable === true：网络类型可用（由 src/utils/network.js 判定）


运行流程


 enable_offline_booking_cache_polling(options)：


  缓存最后一次 options（用于网络恢复时重启轮询）
  增加 ref_count

  注册 Taro.onNetworkStatusChange（仅注册一次）
  如果当前网络可用，则启动定时器，默认每 60000ms 刷新一次


 定时器 tick：


  调用 refresh_offline_booking_cache({ force: !!options?.force })

  内部会再次校验授权与网络，避免无效请求


 网络变更监听：


  变为弱网/无网：立即停止轮询定时器
  恢复为可用网络：若 ref_count > 0，用最后一次 options 重新启动轮询


 disable_offline_booking_cache_polling()：


  释放一次 ref_count

  当 ref_count === 0 时：停止轮询并注销网络监听器


options 说明


  interval_ms：轮询间隔（毫秒），默认 60000

  immediate：是否立即刷新一次，默认 true

  force：透传给 refresh_offline_booking_cache，用于强制刷新（默认 false）


优化建议 (TODO)


 小程序授权流程有问题 - 已处理

 完善支付流程（目前为模拟/H5跳转）- 后端配合联调

 优化图片资源加载（考虑使用 CDN 或分包）- 有离线模式看情况处理

 弱网环境下的离线预约记录 - 已实现（本地缓存 + 离线列表/详情）

 义工核销接口联调与核销结果字段展示优化（依赖后端返回结构稳定）

 增强网络请求的错误处理与重试机制

 补充单元测试