Hooke / xyxBooking-weapp

Go to a project
Toggle navigation Toggle navigation pinning
Switch branch/tag
README.md 7.96 KB

西园寺预约微信小程序（xyxBooking-weapp）

将原有 H5 预约系统迁移至微信小程序的实现，基于 Taro 4 + Vue 3 + NutUI 开发，保留原有业务流程与 UI 风格，并补充了弱网/离线兜底能力。

功能概览

  • 预约流程：须知 -> 日期/时段选择 -> 选择参观者 -> 提交订单 -> 支付 -> 查看预约码与记录
  • 参观者管理：新增/删除参观者、证件号校验、脱敏展示
  • 预约码展示：我的当日预约码、预约记录详情中的预约码
  • 证件号查询：通过身份证号查询预约码（用于识别进闸机）
  • 弱网/离线模式：弱网提示、离线预约记录列表/详情、离线预约码
  • 义工核销：义工登录（权限预检）-> 扫码核销 -> 展示核销结果

技术栈

  • 框架：Taro 4.1.9 + Vue 3（setup 语法糖）
  • UI：NutUI 4（@nutui/nutui-taro + icons-vue-taro）
  • 状态管理：Pinia（taro-plugin-pinia）
  • 网络请求：axios-miniprogram（封装拦截器与认证续期）
  • 样式：Less + TailwindCSS（小程序端通过 weapp-tailwindcss 兼容）
  • 构建：Webpack 5（Taro 默认）

开发命令

# 安装依赖
pnpm install

# 开发模式
pnpm dev:weapp      # 微信小程序
pnpm dev:h5         # H5 端

# 构建
pnpm build:weapp    # 微信小程序生产包
pnpm build:h5       # H5 端生产包

# 代码质量
pnpm lint           # ESLint 检查并修复
pnpm format         # Prettier 格式化
pnpm lint:no-fix    # 仅检查不修复

代码质量保障

项目已配置完整的代码质量保障体系：

✅ 已配置工具

  • ESLint：代码风格检查和潜在错误检测
  • Prettier：代码格式化统一
  • EditorConfig：编辑器配置统一
  • Husky：Git Hooks 自动化
  • lint-staged：提交前仅检查本次修改文件

📋 初始配置步骤

# 1. 安装代码质量相关依赖
pnpm add -D eslint prettier eslint-plugin-vue husky lint-staged

# 2. 初始化 Husky（自动设置 Git Hooks）
bash scripts/setup-husky.sh

# 3. 提交代码时会自动运行检查
git add .
git commit -m "feat: 添加新功能"

📚 详细配置文档

查看 docs/development-guide.md 获取完整的配置使用说明。

🎯 Claude Code 开发配置

项目配置了完善的 Claude Code 全局规则，支持：

  • Vue 3 最佳实践
  • Taro 开发规范
  • 小程序特性适配
  • 多端兼容处理
  • 代码审查清单

全局规则位于 ~/.claude/rules/：

  • taro-patterns.md - Taro 开发规范
  • miniprogram-checklist.md - 小程序检查清单
  • taro-cross-platform.md - 多端兼容指南
  • vue-patterns.md - Vue 3 最佳实践
  • frontend-testing.md - 前端测试指南
  • code-review.md - 代码审查清单

项目结构

config/                      Taro 构建配置（alias、designWidth、tailwind 插件等）
doc/                         需求/说明文档（弱网离线、核销等）
src/
  app.js                     应用入口（启动授权、网络监听、离线缓存预加载/轮询）
  app.config.js              小程序路由与窗口配置
  api/                       API 常量与封装（含 wx 支付、义工核销）
  assets/                    静态资源（images、styles）
  components/                业务组件（预约码、预约记录卡、离线二维码等）
  composables/               组合式逻辑（离线缓存、轮询）
  hooks/                     路由封装（useGo/useReplace）
  pages/                     页面（按 pages/<name>/index.vue 组织）
  stores/                    Pinia store（router/main/host/counter）
  utils/                     工具（request/authRedirect/network/uiText/wechatPay 等）

路径别名

在 config/index.js 配置：

  • @/utils -> src/utils
  • @/components -> src/components
  • @/assets -> src/assets
  • @/api -> src/api
  • @/stores -> src/stores
  • @/hooks -> src/hooks
  • @/composables -> src/composables

设计宽度体系

在 config/index.js 的 designWidth 做了双设计宽度：

  • NutUI 组件按 375 设计稿计算
  • 其他页面按 750（Taro 默认）计算

关键实现说明

认证与会话续期

  • 启动时在 app.js 尝试静默授权：silentAuth()
  • 会话凭证使用 sessionid 存储在 Taro Storage（cookie 字符串）
  • 请求层在 utils/request.js 动态注入 cookie，并在 401 时触发刷新会话、重放原请求（配合 utils/authRedirect.js）
  • 授权失败时跳转授权页，并保存来源页，授权成功后回跳（router store 持久化路径）

弱网/离线兜底

两处兜底入口：

  • 启动阶段：在 app.js 检测网络类型，弱网/无网时提示并可一键进入离线列表
  • 请求阶段：在 utils/request.js 捕获超时/网络错误，优先跳转离线列表；否则提示用户检查网络

离线数据来源：

离线页面：

  • 离线预约记录列表：pages/offlineBookingList/index
  • 离线预约记录详情：pages/offlineBookingDetail/index
  • 离线预约码入口：pages/offlineBookingCode/index

支付/退款（对接位）

义工核销

  • 核销端 API：见 api/redeem.js
  • 页面：pages/volunteerLogin/index（权限预检/登录）与 pages/verificationResult/index（扫码核销与结果展示）

可复用能力（迁移到其他项目的价值）

  • 请求层：src/utils/request.js
    • 默认参数合并、cookie 注入、弱网降级
    • 401 自动续期与原请求重放（与 authRedirect 配合）
  • 认证/回跳：src/utils/authRedirect.js + src/stores/router.js
    • 静默授权单例锁（避免并发登录）
    • 保存来源页与授权后回跳
  • 弱网/离线缓存：src/composables/useOfflineBookingCache*.js
    • 离线数据结构抽取、缓存读写、轮询刷新、网络切换处理
  • 路由工具：src/hooks/useGo.js
    • 短路径补全、query 序列化、tabbar 兼容处理（可扩展）
  • 弱网文案统一：src/utils/uiText.js
    • 将 toast/modal 文案集中管理，避免页面散落硬编码

项目优缺点

优点

  • 业务链路完整（预约、支付、预约码、记录、核销），页面目录清晰
  • 认证流程健壮：会话续期、并发合并、授权回跳可控
  • 弱网/离线兜底完善：启动检查 + 请求降级 + 离线列表/详情闭环
  • 工具化程度高：request/authRedirect/useGo/uiText 等可复用模块明确
  • 样式体系兼容小程序：Less + Tailwind（配合 weapp-tailwindcss）

不足

  • 自动化测试缺失（暂无单元测试/集成测试与 CI 校验）
  • 部分工具函数存在重复实现（例如证件号脱敏在多处出现）
  • 轮询逻辑仅在卸载时清理，页面 onHide 场景可能仍在请求（可优化为按页面可见性启停）
  • Webpack 持久化缓存未开启（config/index.js 中 cache.enable=false）
  • 少量文件头部元信息/注释规范不一致（例如个别文件仍为“文件描述”占位）

优化建议（下一步）

  • 补充测试：优先覆盖 request/authRedirect/offline cache 的关键边界
  • 抽离通用工具：已完成（证件号脱敏与状态映射已统一到 utils）
  • 优化轮询策略：已完成（二维码轮询按页面生命周期启停）
  • 资源优化：CDN 图片策略、分包策略、首屏关键资源预加载
  • 构建性能：评估开启 Webpack 持久化缓存，缩短二次编译时间