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：存储其他应用级全局状态

离线支持

应用实现离线二维码核心功能，逻辑如下：

• 小程序启动时、网络状态变化时，调用 qrcodeListAPI() 获取二维码列表
• 将处理后的二维码数据存储在 OFFLINE_QR_DATA 缓存键中
• 离线二维码页面路径：pages/offlineBookingCode/index

页面结构

页面文件统一存放于 src/pages/ 目录，遵循 pages/[页面名称]/index.vue 命名规范。

核心页面清单：

• index：首页
• auth：授权/登录页
• booking：预约日期/时段选择页
• submit：预约确认页
• bookingList：用户预约列表页
• bookingDetail：预约详情页
• visitorList：访客管理页
• addVisitor：新增/编辑访客页
• me：个人中心页
• search：按身份证号查询二维码页
• volunteerLogin：志愿者管理员登录页
• verificationResult：票务核验结果页
• offlineBookingCode：离线预约码访问页

配置说明

环境配置

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

API 配置

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