hookehuyr

docs: 更新文档说明离线预约和义工核销功能

更新 CLAUDE.md 和 README.md 文档,详细说明离线预约记录缓存、轮询机制和义工核销流程
添加弱网文案统一管理和相关页面路径说明
完善项目目录结构和优化建议
......@@ -89,10 +89,27 @@ pnpm build:h5 # 构建H5端生产包
- `main.js``host.js``counter.js`:存储其他应用级全局状态
### 离线支持
应用实现离线二维码核心功能,逻辑如下:
- 小程序启动时、网络状态变化时,调用 `qrcodeListAPI()` 获取二维码列表
- 将处理后的二维码数据存储在 `OFFLINE_QR_DATA` 缓存键中
- 离线二维码页面路径:`pages/offlineBookingCode/index`
应用实现弱网/离线预约记录能力,核心逻辑如下:
- 离线预约记录缓存:`src/composables/useOfflineBookingCache.js`(key:`OFFLINE_BOOKING_DATA`
- 启动预加载:`src/app.js` 在合适时机调用 `refresh_offline_booking_cache()`
- 轮询刷新:`src/composables/useOfflineBookingCachePolling.js` 默认 60s 刷新一次
- 请求超时降级:`src/utils/request.js` 超时时优先跳转离线预约记录页(若存在本地缓存)
- 页面入口:
- 离线预约记录列表:`pages/offlineBookingList/index`
- 离线预约记录详情:`pages/offlineBookingDetail/index`
- 离线预约码入口:`pages/offlineBookingCode/index`
### 弱网文案统一
弱网相关 toast/modal/banner 文案统一在 `src/utils/uiText.js` 管理,避免多处硬编码。
### 义工核销
义工核销流程相关页面与关键点:
- 义工登录页:`pages/volunteerLogin/index`
- 进入页面先调用 `getUserInfoAPI()` 做权限预检
- 若已具备义工权限,直接跳转核销页;否则展示登录表单
- 核销页:`pages/verificationResult/index`
- 点击“核销”触发扫码并调用 `verifyTicketAPI()` 完成核销
- 展示核销接口返回的结果数据与状态
## 页面结构
页面文件统一存放于 `src/pages/` 目录,遵循 `pages/[页面名称]/index.vue` 命名规范。
......@@ -109,8 +126,11 @@ pnpm build:h5 # 构建H5端生产包
- `me`:个人中心页
- `search`:按身份证号查询二维码页
- `volunteerLogin`:志愿者管理员登录页
- `verificationResult`:票务核验结果页
- `offlineBookingCode`:离线预约码访问页
- `verificationResult`:核销页
- `weakNetwork`:弱网提示页
- `offlineBookingCode`:离线预约码入口页
- `offlineBookingList`:离线预约记录列表页
- `offlineBookingDetail`:离线预约记录详情页
## 配置说明
......
......@@ -20,10 +20,22 @@
* 我的页面 (`pages/me/index`)
* 邀请码/证件号查询 (`pages/search/index`)
4. **公共功能**
4. **弱网与离线模式**
* 弱网提示页 (`pages/weakNetwork/index`)
* 离线预约记录列表 (`pages/offlineBookingList/index`)
* 离线预约记录详情/离线二维码 (`pages/offlineBookingDetail/index`)
* 离线预约码入口页 (`pages/offlineBookingCode/index`)
* 离线预约缓存刷新与轮询 (`src/composables/useOfflineBookingCache.js`, `src/composables/useOfflineBookingCachePolling.js`)
5. **义工核销**
* 义工登录与权限预检 (`pages/volunteerLogin/index`)
* 核销页(扫码核销 + 结果展示)(`pages/verificationResult/index`)
6. **公共功能**
* 全局路由封装 (`hooks/useGo`)
* API 请求封装 (`utils/request`, `api/index`)
* 登录授权流程 (`pages/auth/index`)
* 弱网提示文案统一管理 (`utils/uiText.js`)
## 技术栈
......@@ -39,9 +51,11 @@
* `src/api`: 接口定义
* `src/assets`: 图片等静态资源
* `src/components`: 公共组件 (qrCode, qrCodeSearch, reserveCard等)
* `src/composables`: 组合式函数 (离线缓存/轮询等)
* `src/pages`: 页面文件
* `src/hooks`: 组合式函数 (useGo等)
* `src/utils`: 工具函数 (request, tools等)
* `src/stores`: Pinia 状态管理 (main/router 等)
* `src/utils`: 工具函数 (request, authRedirect, network, uiText 等)
## 项目运行
......@@ -62,9 +76,10 @@
## 优化建议 (TODO)
* [ ] 小程序授权流程有问题 - 已处理
* [ ] 完善支付流程(目前为模拟/H5跳转)- 后端配合
* [x] 小程序授权流程有问题 - 已处理
* [ ] 完善支付流程(目前为模拟/H5跳转)- 后端配合联调
* [ ] 优化图片资源加载(考虑使用 CDN 或分包)- 有离线模式看情况处理
* [ ] 弱网环境下的优化, 如: 用户端可以获取当前用户的预约码, 管理端可以根据预约码核销预约码
* [x] 弱网环境下的离线预约记录 - 已实现(本地缓存 + 离线列表/详情)
* [ ] 义工核销接口联调与核销结果字段展示优化(依赖后端返回结构稳定)
* [ ] 增强网络请求的错误处理与重试机制
* [ ] 补充单元测试
......
......@@ -74,6 +74,7 @@ export const use_offline_booking_cache_polling = (options) => {
const start = () => {
if (!enabled) return
polling_ref_count += 1
// TAG: 每次启动轮询时,都增加引用计数
start_offline_booking_cache_polling(options)
is_running.value = true
}
......@@ -81,6 +82,7 @@ export const use_offline_booking_cache_polling = (options) => {
const stop = () => {
if (!is_running.value) return
polling_ref_count = Math.max(0, polling_ref_count - 1)
// TAG: 每次停止轮询时,都减少引用计数
if (polling_ref_count === 0) {
stop_offline_booking_cache_polling()
}
......