Hooke / xyxBooking-weapp

Go to a project
Toggle navigation Toggle navigation pinning
hookehuyr
92b99b35 1 parent daed49bf

docs: 重构 README 文档以提供更清晰的项目概览与架构说明 

- 将项目介绍重构为更清晰的功能概览与技术栈说明
- 详细阐述项目结构、关键实现（如认证、离线兜底）与可复用能力
- 增加项目优缺点分析与明确的后续优化建议
- 移除过时的优化建议条目，更新为当前状态
Inline Side-by-side
Showing 1 changed file with 139 additions and 125 deletions
## 项目介绍
本项目是将原有H5预约系统迁移至微信小程序的实现。基于 Taro4 + Vue3 + NutUI 开发，保留了原有的功能和UI风格。
## 功能模块
1. **预约流程**
* 日期与时间段选择 (`pages/booking/index`)
* 预约信息确认与提交 (`pages/submit/index`)
* 预约记录查看 (`pages/bookingList/index`)
* 预约详情 (`pages/bookingDetail/index`)
2. **参观者管理**
* 参观者列表 (`pages/visitorList/index`)
* 添加/编辑参观者 (`pages/addVisitor/index`)
* 支持身份证号校验与脱敏显示
3. **个人中心**
* 预约码展示 (`pages/bookingCode/index`)
* 我的页面 (`pages/me/index`)
* 邀请码/证件号查询 (`pages/search/index`)
4. **弱网与离线模式**
* 弱网提示页 (`pages/weakNetwork/index`)
* 离线预约记录列表 (`pages/offlineBookingList/index`)
* 离线预约记录详情/离线二维码 (`pages/offlineBookingDetail/index`)
* 离线预约码入口页 (`pages/offlineBookingCode/index`)
* 离线预约缓存刷新与轮询 (`src/composables/useOfflineBookingCache.js`, `src/composables/useOfflineBookingCachePolling.js`)
* 网络从可用变为弱网/无网时，弹窗提示并可一键进入离线模式（`src/app.js`）
5. **义工核销**
* 义工登录与权限预检 (`pages/volunteerLogin/index`)
* 核销页（扫码核销 + 结果展示）(`pages/verificationResult/index`)
6. **公共功能**
* 全局路由封装 (`hooks/useGo`)
* API 请求封装 (`utils/request`, `api/index`)
* 登录授权流程 (`pages/auth/index`)
* 弱网提示文案统一管理 (`utils/uiText.js`)
# 西园寺预约微信小程序（xyxBooking-weapp）
将原有 H5 预约系统迁移至微信小程序的实现，基于 Taro 4 + Vue 3 + NutUI 开发，保留原有业务流程与 UI 风格，并补充了弱网/离线兜底能力。
## 功能概览
- 预约流程：须知 -> 日期/时段选择 -> 选择参观者 -> 提交订单 -> 支付 -> 查看预约码与记录
- 参观者管理：新增/删除参观者、证件号校验、脱敏展示
- 预约码展示：我的当日预约码、预约记录详情中的预约码
- 证件号查询：通过身份证号查询预约码（用于识别进闸机）
- 弱网/离线模式：弱网提示、离线预约记录列表/详情、离线预约码
- 义工核销：义工登录（权限预检）-> 扫码核销 -> 展示核销结果
## 技术栈
* **框架**: Taro 4.x
* **UI库**: NutUI 4.x (Vue3)
* **语言**: JavaScript (Vue3 Setup 语法糖)
* **样式**: Less + TailwindCSS (部分)
* **状态管理**: Pinia
* **路由**: Taro Router + 自定义 Hooks
- 框架：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 默认）
## 开发命令
```bash
pnpm install
pnpm dev:weapp
pnpm build:weapp
pnpm lint
```
## 项目结构
* `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 等)
## 项目运行
1. 安装依赖
```bash
pnpm install
```
2. 运行开发环境
```bash
pnpm dev:weapp
```
3. 打包构建
```bash
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()`
### 启动条件
轮询启动需要同时满足：
1. `ref_count > 0`：表示当前确实有人需要轮询（应用级启用会占用 1 个引用）
2. `network_usable === true`：网络类型可用（由 `src/utils/network.js` 判定）
### 运行流程
1. `enable_offline_booking_cache_polling(options)`：
* 缓存最后一次 `options`（用于网络恢复时重启轮询）
* 增加 `ref_count`
* 注册 `Taro.onNetworkStatusChange`（仅注册一次）
* 如果当前网络可用，则启动定时器，默认每 `60000ms` 刷新一次
2. 定时器 tick：
* 调用 `refresh_offline_booking_cache({ force: !!options?.force })`
* 内部会再次校验授权与网络，避免无效请求
3. 网络变更监听：
* 变为弱网/无网：立即停止轮询定时器
* 恢复为可用网络：若 `ref_count > 0`，用最后一次 `options` 重新启动轮询
4. `disable_offline_booking_cache_polling()`：
* 释放一次 `ref_count`
* 当 `ref_count === 0` 时：停止轮询并注销网络监听器
### options 说明
* `interval_ms`：轮询间隔（毫秒），默认 `60000`
* `immediate`：是否立即刷新一次，默认 `true`
* `force`：透传给 `refresh_offline_booking_cache`，用于强制刷新（默认 `false`）
## 优化建议 (TODO)
* [x] 小程序授权流程有问题 - 已处理
* [ ] 完善支付流程（目前为模拟/H5跳转）- 后端配合联调
* [ ] 优化图片资源加载（考虑使用 CDN 或分包）- 有离线模式看情况处理
* [x] 弱网环境下的离线预约记录 - 已实现（本地缓存 + 离线列表/详情）
* [ ] 义工核销接口联调与核销结果字段展示优化（依赖后端返回结构稳定）
* [ ] 增强网络请求的错误处理与重试机制
* [ ] 补充单元测试
```text
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](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](config/index.js) 的 designWidth 做了双设计宽度：
- NutUI 组件按 375 设计稿计算
- 其他页面按 750（Taro 默认）计算
## 关键实现说明
### 认证与会话续期
- 启动时在 [app.js](src/app.js) 尝试静默授权：`silentAuth()`
- 会话凭证使用 `sessionid` 存储在 Taro Storage（cookie 字符串）
- 请求层在 [utils/request.js](src/utils/request.js) 动态注入 cookie，并在 401 时触发刷新会话、重放原请求（配合 [utils/authRedirect.js](src/utils/authRedirect.js)）
- 授权失败时跳转授权页，并保存来源页，授权成功后回跳（router store 持久化路径）
### 弱网/离线兜底
两处兜底入口：
- 启动阶段：在 [app.js](src/app.js) 检测网络类型，弱网/无网时提示并可一键进入离线列表
- 请求阶段：在 [utils/request.js](src/utils/request.js) 捕获超时/网络错误，优先跳转离线列表；否则提示用户检查网络
离线数据来源：
- 离线预约记录缓存：`OFFLINE_BOOKING_DATA`（见 [useOfflineBookingCache.js](src/composables/useOfflineBookingCache.js)）
- 轮询刷新：见 [useOfflineBookingCachePolling.js](src/composables/useOfflineBookingCachePolling.js)（引用计数 + 网络监听，避免重复启动）
离线页面：
- 离线预约记录列表：`pages/offlineBookingList/index`
- 离线预约记录详情：`pages/offlineBookingDetail/index`
- 离线预约码入口：`pages/offlineBookingCode/index`
### 支付/退款（对接位）
- 支付拉起封装：见 [utils/wechatPay.js](src/utils/wechatPay.js) 与 [api/wx/pay.js](src/api/wx/pay.js)
- 取消预约（退款接口）：`icbcRefundAPI`（见 [api/index.js](src/api/index.js)），在预约详情页调用并刷新离线缓存
### 义工核销
- 核销端 API：见 [api/redeem.js](src/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
- 优化轮询策略：结合页面生命周期 onShow/onHide 控制轮询启停
- 资源优化：CDN 图片策略、分包策略、首屏关键资源预加载
- 构建性能：评估开启 Webpack 持久化缓存，缩短二次编译时间
......