pingxiangcard/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目定位

项目定位

湖南12301文旅专区用户端微信小程序（C端），基于 uni-app + Vue 3 + TypeScript + Pinia。仅包含用户端功能，不含管理端。

技术栈

技术	版本	说明
Vue	3.5.x	核心框架
uni-app	3.0.0	跨平台框架（当前仅编译微信小程序）
TypeScript	4.9.x	类型系统
Pinia	3.x	状态管理（仅 user store）
Vite	5.2.8	构建工具
@dcloudio/uni-ui	1.5.12	UI 组件库（easycom 自动导入）

微信小程序配置

• AppID: wx636bc46a6570e9fd
• 后端接口前缀: /mp-api（对应后端 RouteChannel.MP_API）
• API 基础地址: 由 .env.* 文件的 VITE_API_BASE_URL 控制

目录结构

zhy-test/
├── src/
│   ├── api/                          # API 接口层
│   │   ├── request.ts                # HTTP 封装（uni.request + Token 注入 + 401 处理）
│   │   ├── types.ts                  # TypeScript 类型定义
│   │   ├── user.ts                   # 微信登录 + 用户信息
│   │   ├── card.ts                   # 年卡列表/详情/激活/绑定/入园码
│   │   └── order.ts                  # 订单创建/支付/查询
│   ├── components/                   # 公共组件
│   │   ├── McGlass.vue               # 毛玻璃卡片
│   │   ├── card-item.vue             # 年卡列表项
│   │   └── empty-state.vue           # 空状态占位
│   ├── config/
│   │   └── index.ts                  # API_BASE / TOKEN_KEY / REFRESH_TOKEN_KEY
│   ├── pages/                        # 主包页面
│   │   ├── index/index.vue           # 首页（轮播 + 热门景区 + 精选活动）
│   │   ├── login/login.vue           # 登录页（微信手机号授权登录）
│   │   └── profile/index.vue         # 个人中心（tabBar）
│   ├── packages/user/pages/card/     # 分包：年卡功能（减小主包体积）
│   │   ├── list.vue                  # 年卡列表（搜索 + 分类筛选）
│   │   ├── detail.vue                # 年卡详情（权益 + 景区 + 富文本）
│   │   ├── buy.vue                   # 购买确认 + 模拟支付
│   │   ├── activate.vue              # 实名激活（姓名 + 身份证 + 手机）
│   │   ├── qrcode.vue                # 入园码（60秒自动刷新）
│   │   └── bind.vue                  # 卡号绑定
│   ├── static/                       # 静态资源（logo + tabBar 图标）
│   ├── store/
│   │   └── user.ts                   # 用户状态（token 持久化 + 登录判断）
│   ├── utils/
│   │   └── index.ts                  # 工具函数（showToast / navigateTo 等）
│   ├── App.vue                       # 根组件（隐私协议检查 + 自动获取用户信息）
│   ├── main.ts                       # 入口（createSSRApp + Pinia）
│   ├── manifest.json                 # uni-app 配置（AppID）
│   ├── pages.json                    # 路由 + tabBar + 分包 + easycom
│   └── uni.scss                      # 全局 SCSS 变量
├── .env.local                        # 本地开发环境
├── .env.dev                          # 开发环境
├── .env.uat                          # UAT 环境
├── package.json
├── project.config.json               # 微信开发者工具配置
├── vite.config.ts
└── tsconfig.json

架构设计

分层

页面(.vue) → API 层(api/*.ts) → HTTP 封装(request.ts) → uni.request → 后端
                ↕
          Store(store/user.ts) ← 仅管理 token + 登录状态

• 页面直接调用 API，不经过 store（年卡、订单等模块）
• 只有 user 模块使用 store，因为需要跨页面共享 token 和登录状态
• request.ts 统一处理 Token 注入、401 跳转、响应格式解析

后端对接

• 后端项目：jxxx-dscp（Spring Boot 2.7 + MyBatis-Plus）
• 路由渠道：RouteChannel.MP_API（/mp-api）
• 认证方式：Bearer Token（Authorization: Bearer {accessToken}）
• 响应格式：{ errcode, errmsg, data, traceid }（框架自动包装 ResDto）
• 用户表：member 表，channel = 99（Channel_CY，产研小程序）
• Token 表：system_oauth2_access_token，clientId = "mp-99"

微信登录流程

前端 button[open-type=getPhoneNumber]
  → phoneCode + wx.login() → loginCode
  → POST /mp-api/auth/wx-login { loginCode, phoneCode }
  → 后端 jscode2session → openId
  → 后端 getuserphonenumber → phoneNumber
  → 查找/创建 member → 创建 token
  → 返回 LoginResponse { accessToken, refreshToken, userId, openId, mobile }

运行命令

# 安装依赖
pnpm install

# 微信小程序开发构建
pnpm run dev:mp-weixin

# 微信小程序生产构建
pnpm run build:mp-weixin

# TypeScript 类型检查
pnpm run type-check

# 构建产物目录
dist/build/mp-weixin/   # 用微信开发者工具导入此目录

环境配置

文件	API 地址	用途
.env.local	http://localhost:48080	本地开发（配合后端 --spring.profiles.active=local）
.env.dev	https://dscp-dev.hn12301.net	开发环境
.env.uat	https://dscp-uat.hn12301.net	UAT 测试

数据库环境

环境	地址	数据库
本地（local profile）	localhost:3306	dscp_business_dev
开发（dev）	120.26.254.65:3306	dscp_business_dev
UAT	47.99.164.129:3306	dscp_business

开发注意事项

1. API 前缀：所有接口走 /mp-api（不是 /manage-api，那是管理后台）
2. Token 管理：app_token / app_refresh_token 存在 uni.storage 中
3. 分包策略：年卡功能放分包（packages/user），首页/登录/个人中心在主包
4. 条件编译：#ifdef MP-WEIXIN 包裹微信特有逻辑
5. 隐私协议：App.vue 中 wx.getPrivacySetting 检查，未同意前不能调授权 API
6. 微信开发者工具调试：需勾选「不校验合法域名」才能请求 localhost