CLAUDE.md（项目开发指南）

本文档为 Claude Code（claude.ai/code）处理本仓库代码时提供操作指引。

项目概述

这是一款西园寺预约类微信小程序，由原有H5系统迁移改造而来，基于 Taro 4 + Vue 3 + NutUI 技术栈构建。

常用命令

开发环境启动

pnpm install              # 安装项目依赖
pnpm dev:weapp           # 启动微信小程序开发模式
pnpm dev:h5              # 启动H5端开发模式
pnpm dev:alipay          # 启动支付宝小程序开发模式
pnpm dev:tt              # 启动抖音小程序开发模式

生产包构建

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

架构设计

设计宽度体系

项目采用双设计宽度体系，配置文件路径为 config/index.js：

• NutUI 组件：基准宽度 375px
• 其他所有页面：基准宽度 750px（Taro 默认值）

路径别名

路径别名在 config/index.js 中配置，具体映射关系如下：

• @/utils → src/utils
• @/components → src/components
• @/images → src/assets/images
• @/assets → src/assets
• @/composables → src/composables
• @/api → src/api
• @/stores → src/stores
• @/hooks → src/hooks

认证与授权流程

核心文件：src/utils/authRedirect.js、src/utils/request.js、src/app.js

项目实现了具备自动会话刷新能力的完整认证流程，核心逻辑如下：

1. 会话存储：将 sessionid 存储在 Taro 缓存中，作为核心认证令牌
2. 启动静默认证：小程序启动时，src/app.js 调用 silentAuth() 执行静默认证
3. 401 自动刷新：src/utils/request.js 中的响应拦截器捕获 401 错误后，调用 refreshSession() 刷新会话并重试原请求
4. 认证页重定向：若静默刷新失败，自动重定向至 /pages/auth/index，并保存跳转前的页面路径
5. 路由状态管理：src/stores/router.js 持久化存储认证完成后的返回路径，用于认证成功后跳转

关键实现细节：

• silentAuth() 和 refreshSession() 共享单例 auth_promise，避免并发场景下重复发起认证请求
• 请求拦截器每次发起请求时，从缓存中动态获取最新的 sessionid
• 通过 __is_retry 标识位控制，防止请求无限重试循环

API 层设计

核心文件：src/api/index.js、src/api/fn.js、src/utils/request.js

• 所有 API 接口地址常量统一定义在 src/api/index.js 中
• 基于 axios-miniprogram 封装请求实例，并添加自定义请求/响应拦截器
• 基础请求 URL 和默认参数（f、client_name）在 src/utils/config.js 中配置
• API 函数命名规范：统一采用 xxxAPI(params) 格式

路由系统

核心文件：src/hooks/useGo.js

封装自定义路由函数，核心特性如下：

• 支持短路径写法（如 'notice' 或 '/notice'）
• 自动补全为完整页面路径 pages/notice/index
• 内置查询参数序列化处理逻辑
• 针对 tabbar 页面，自动使用 switchTab 方式跳转

使用建议：页面导航优先使用 useGo()，页面重定向优先使用 useReplace()。

样式方案

• 组件样式：主要基于 Less 编写
• 工具类样式：使用 TailwindCSS（小程序端通过 weapp-tailwindcss 插件做兼容处理）
• UI 组件库：集成 NutUI 4.x，已在 config/index.js 中配置组件自动导入
• 为兼容小程序环境，禁用 Tailwind 的 preflight 样式重置功能

状态管理

• 采用 Pinia 做状态管理，配合 taro-plugin-pinia 插件实现适配
• 状态文件统一存放于 src/stores/ 目录：
  • router.js：管理认证完成后的返回路径
  • main.js、host.js、counter.js：存储其他应用级全局状态

离线支持

应用实现弱网/离线预约记录能力，核心逻辑如下：

• 离线预约记录缓存：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 命名规范。

核心页面清单：

• index：首页
• auth：授权/登录页
• booking：预约日期/时段选择页
• submit：预约确认页
• bookingList：用户预约列表页
• bookingDetail：预约详情页
• visitorList：访客管理页
• addVisitor：新增/编辑访客页
• me：个人中心页
• search：按身份证号查询二维码页
• volunteerLogin：志愿者管理员登录页
• verificationResult：核销页
• weakNetwork：弱网提示页
• offlineBookingCode：离线预约码入口页
• offlineBookingList：离线预约记录列表页
• offlineBookingDetail：离线预约记录详情页

配置说明

环境配置

• 基础请求 URL 在 src/utils/config.js 中根据开发/生产环境自动切换
• 开发模式下提供带注释的 openid 覆盖配置，用于本地调试测试

API 配置

• 默认请求参数在 src/utils/config.js 中配置
• 所有后端请求统一通过 /srv/?a=... 格式的接口转发
• 固定自定义参数：f='reserve'、client_name='智慧西园寺'

代码编写

组件编写

• 所有组件均基于 NutUI 4.x 组件库编写
• 组件文件统一存放于 src/components/ 目录，遵循 [组件名称].vue 命名规范
• 组件 props 定义清晰，注释详细，符合 Vue 组件规范

功能编写

• 对于复杂逻辑需要进行封装，避免在页面中直接编写复杂逻辑
• 封装逻辑统一存放于 src/composables/ 目录，遵循 use[功能名称].js 命名规范
• 封装函数注释详细，参数/返回值/异常情况均需说明

代码风格

工作流程