jacobxu666andClaude
c062dee3e6
- CLAUDE.md: 修正 TypeScript 版本为 4.9.x，补充 project.config.json 说明、type-check 命令、UAT 环境地址 - docs: 新增赣湘全域旅游年卡及超级玩家卡关联景区表 - pnpm: 添加 pnpm-workspace.yaml 及 pnpm-lock.yaml Co-Authored-By: Claude <noreply@anthropic.com>
153 lines
6.4 KiB
Markdown
153 lines
6.4 KiB
Markdown
# 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 }
|
||
```
|
||
|
||
## 运行命令
|
||
|
||
```bash
|
||
# 安装依赖
|
||
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
|