207 lines
10 KiB
Markdown
207 lines
10 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## 项目定位
|
||
|
||
**爱上萍乡**用户端微信小程序（C端），基于 uni-app + Vue 3 + TypeScript + Pinia。仅包含用户端功能，不含管理端。
|
||
|
||
## 技术栈
|
||
|
||
| 技术 | 版本 | 说明 |
|
||
|------|------|------|
|
||
| Vue | 3.5.x | 核心框架 |
|
||
| uni-app | 3.0.0-alpha | 跨平台框架（当前仅编译微信小程序） |
|
||
| TypeScript | 4.9.x | 类型系统 |
|
||
| Pinia | 3.x | 状态管理（仅 user store） |
|
||
| Vite | 5.2.8 | 构建工具 |
|
||
| @dcloudio/uni-ui | 1.5.x | UI 组件库（easycom 自动导入） |
|
||
| sass | 1.101.x | 样式预处理 |
|
||
|
||
## 运行命令
|
||
|
||
```bash
|
||
pnpm install # 安装依赖
|
||
pnpm run dev:mp-weixin # 微信小程序开发构建
|
||
pnpm run build:mp-weixin # 微信小程序生产构建
|
||
pnpm run type-check # TypeScript 类型检查（vue-tsc --noEmit）
|
||
```
|
||
|
||
构建产物在 `dist/build/mp-weixin/`，用微信开发者工具导入此目录。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
src/
|
||
├── api/ # API 接口层
|
||
│ ├── request.ts # HTTP 封装（uni.request + Token 注入 + 401 处理）
|
||
│ ├── types.ts # 公共类型定义
|
||
│ ├── user.ts # 微信登录（两种方式）
|
||
│ ├── card.ts # 年卡接口
|
||
│ └── order.ts # 订单接口
|
||
├── components/ # 公共组件
|
||
│ ├── mc-glass.vue # 毛玻璃卡片
|
||
│ ├── card-item.vue # 年卡列表项
|
||
│ ├── empty-state.vue # 空状态占位
|
||
│ ├── announcement-modal.vue # 公告弹窗
|
||
│ ├── confirm-modal.vue # 确认弹窗
|
||
│ ├── design-button.vue # 设计系统按钮
|
||
│ ├── design-card.vue # 设计系统卡片
|
||
│ ├── design-input.vue # 设计系统输入框
|
||
│ └── section-label.vue # 区块标题
|
||
├── config/
|
||
│ └── index.ts # API_BASE / TOKEN_KEY / 环境变量
|
||
├── mock/ # Mock 数据（VITE_USE_MOCK=true 时启用）
|
||
│ ├── index.ts # USE_MOCK 开关
|
||
│ ├── images.ts # 图片 URL
|
||
│ ├── notice.ts # 公告数据
|
||
│ ├── scenic.ts # 景区列表数据
|
||
│ └── scenic-detail.ts # 景区详情数据
|
||
├── pages/ # 主包页面
|
||
│ ├── index/index.vue # 首页（轮播 + 热门景区 + 精选活动）
|
||
│ ├── qrcode/index.vue # 入园码（tabBar 旅游卡）
|
||
│ ├── login/login.vue # 登录页（微信手机号授权）
|
||
│ ├── login/agreement.vue # 服务条款
|
||
│ ├── login/privacy.vue # 隐私条款
|
||
│ └── profile/index.vue # 个人中心（tabBar）
|
||
├── packages/user/ # 分包：用户相关（年卡、订单、预约）
|
||
│ ├── api/
|
||
│ │ ├── card.ts # 年卡 API
|
||
│ │ └── order.ts # 订单 API
|
||
│ ├── pages/
|
||
│ │ ├── card/list.vue # 年卡列表
|
||
│ │ ├── card/detail.vue # 年卡详情
|
||
│ │ ├── card/buy.vue # 年卡购买
|
||
│ │ ├── card/activate.vue # 年卡激活
|
||
│ │ ├── card/qrcode.vue # 入园码
|
||
│ │ ├── card/bind.vue # 年卡绑定
|
||
│ │ ├── bind.vue # 绑卡激活
|
||
│ │ ├── buy.vue # 超级玩家卡购买
|
||
│ │ ├── union-buy.vue # 工会购买
|
||
│ │ ├── card-notice.vue # 用卡须知
|
||
│ │ ├── order/list.vue # 订单列表
|
||
│ │ ├── order/detail.vue # 订单详情
|
||
│ │ ├── reserve/index.vue # 景区预约
|
||
│ │ ├── reserve/success.vue # 预约成功/详情
|
||
│ │ └── reserve/list.vue # 预约/使用记录
|
||
│ └── mock/
|
||
│ └── order.ts # 订单 mock 数据
|
||
├── packages/content/ # 分包：内容展示（景区、公告、帮助）
|
||
│ └── pages/
|
||
│ ├── scenic-list.vue # 景区列表（custom navbar）
|
||
│ ├── scenic-detail.vue # 景区详情
|
||
│ ├── notice-list.vue # 通知公告
|
||
│ ├── usage-guide.vue # 使用说明
|
||
│ └── faq.vue # 常见问题
|
||
├── store/
|
||
│ └── user.ts # 用户状态（token 持久化 + 登录判断）
|
||
├── styles/ # 设计系统样式
|
||
│ ├── main.scss # 入口（全局样式）
|
||
│ ├── _tokens.scss # 设计令牌（对齐 uni.scss）
|
||
│ ├── _mixins.scss # 混入（text-display / text-body / text-mono 等）
|
||
│ ├── _animations.scss # 动画
|
||
│ └── _utilities.scss # 工具类
|
||
├── static/ # 静态资源（tabBar 图标、logo 等）
|
||
├── utils/
|
||
│ └── index.ts # 工具函数（showToast / navigateTo 等）
|
||
├── App.vue # 根组件（隐私协议检查）
|
||
├── main.ts # 入口（createSSRApp + Pinia）
|
||
├── manifest.json # uni-app 配置（AppID）
|
||
├── pages.json # 路由 + tabBar + 分包 + easycom
|
||
└── uni.scss # 全局 SCSS 变量（自动注入到每个组件）
|
||
```
|
||
|
||
## 架构设计
|
||
|
||
### 分层
|
||
|
||
```
|
||
页面(.vue) → API 层(api/*.ts) → request.ts → uni.request → 后端
|
||
↕
|
||
Store(store/user.ts) ← 仅管理 token + 登录状态
|
||
```
|
||
|
||
- **页面直接调用 API**，不经过 store（年卡、订单等模块）
|
||
- **只有 user 模块使用 store**，因为需要跨页面共享 token 和登录状态
|
||
- **request.ts** 统一处理 Token 注入、401 跳转、响应格式解析（兼容 `code`/`errcode` 两种业务状态码）
|
||
|
||
### 路由
|
||
|
||
- 3 个 tabBar 页面：首页、旅游卡（入园码）、我的
|
||
- 主包：首页、登录、隐私/服务条款、个人中心
|
||
- 分包 `packages/user`：年卡、订单、预约功能
|
||
- 分包 `packages/content`：景区列表/详情、公告、使用说明、FAQ
|
||
|
||
### 微信登录
|
||
|
||
两种登录方式并存：
|
||
|
||
1. **OAuth2 登录**（当前使用）：`wx.login()` → `encryptedData` + `iv` → `POST /open-api/auth/oauth2` → 返回 `openId` 作为 token
|
||
2. **手机号登录**（旧方式）：`button[open-type=getPhoneNumber]` → `phoneCode` + `loginCode` → `POST /mp-api/auth/wx-login`
|
||
|
||
### 后端对接
|
||
|
||
- 后端项目：`jxxx-dscp`（Spring Boot 2.7 + MyBatis-Plus）
|
||
- 路由渠道：`RouteChannel.MP_API`（`/mp-api`）
|
||
- 认证方式：Bearer Token（`Authorization: Bearer {accessToken}`）
|
||
- 响应格式：`{ code, msg, data, errcode, errmsg }`（`code === 200` 或 `errcode === 0` 视为成功）
|
||
- 用户表：`member` 表，`channel = 99`（Channel_CY，产研小程序）
|
||
- Token 表：`system_oauth2_access_token`，`clientId = "mp-99"`
|
||
|
||
### Mock 系统
|
||
|
||
通过环境变量 `VITE_USE_MOCK=true` 启用。各页面在 `onLoad` 中检查 `USE_MOCK` 标志，为 true 时直接从 mock 文件渲染数据，不发起网络请求。
|
||
|
||
## 设计系统
|
||
|
||
样式体系基于 **uv-ui 设计系统**（`uv-*` 变量命名），通过 `uni.scss` 全局注入 SCSS 变量，每个组件无需额外 import 即可使用。
|
||
|
||
### 核心变量
|
||
|
||
| 类别 | 变量前缀 | 示例 |
|
||
|------|----------|------|
|
||
| 品牌色 | `$uv-primary` / `$color-accent` | `#3c9cff` |
|
||
| 语义色 | `$uv-error` / `$uv-success` / `$uv-warning` | 红/绿/橙 |
|
||
| 中性色 | `$uv-main-color` / `$uv-bg-color` / `$uv-border-color` | 黑/灰/白 |
|
||
| 字体 | `$font-family-display` / `$font-family-body` | 思源宋体 / PingFang |
|
||
| 字号 | `$font-size-*` | `xxs: 18rpx` ~ `display: 72rpx` |
|
||
| 间距 | `$spacing-*` | `0` ~ `160rpx` |
|
||
| 圆角 | `$radius-*` | `sm: 8rpx` ~ `full: 9999rpx` |
|
||
| 阴影 | `$shadow-*` | `sm` ~ `xl` + `accent` |
|
||
|
||
### 字体
|
||
|
||
- 展示字体：`SourceHanSerifCN`（思源宋体），用于标题
|
||
- 正文字体：系统字体栈（`-apple-system, PingFang SC, Helvetica Neue`）
|
||
- 等宽字体：`Menlo, Monaco, Courier New`
|
||
|
||
### 样式文件
|
||
|
||
- `uni.scss` — **source of truth**，自动注入到每个组件
|
||
- `src/styles/_tokens.scss` — 兼容层，对齐 `uni.scss` 的值，供 `main.scss` 使用
|
||
- `src/styles/main.scss` — 全局样式入口，在 `App.vue` 中通过 `@use` 导入
|
||
- 另外还有 `_mixins.scss`、`_animations.scss`、`_utilities.scss`
|
||
|
||
## 环境配置
|
||
|
||
| 文件 | API 地址 | 用途 |
|
||
|------|---------|------|
|
||
| `.env.local` | `http://localhost:48080` | 本地开发（配合后端 local profile） |
|
||
| `.env.dev` | `https://dscp-dev.hn12301.net` | 开发环境 |
|
||
| `.env.uat` | `https://dscp-uat.hn12301.net` | UAT 测试 |
|
||
|
||
## Git 远程
|
||
|
||
- `gitee` → `https://gitee.com/jacobxu666/zhy-mp-test.git`（唯一远程，`main` 跟踪此分支）
|
||
- 当前分支：`xuchao`
|
||
|
||
## 开发注意事项
|
||
|
||
1. **API 前缀**：所有接口走 `/mp-api`（不是 `/manage-api`，那是管理后台）
|
||
2. **Token 管理**：`app_token` 存在 `uni.storage` 中，通过 `request.ts` 的 `getToken/setToken/removeToken` 管理
|
||
3. **分包策略**：年卡/订单/预约放 `packages/user`，景区内容放 `packages/content`，主包仅放首页/登录/个人中心/入园码
|
||
4. **条件编译**：`#ifdef MP-WEIXIN` 包裹微信特有逻辑
|
||
5. **隐私协议**：`App.vue` 中 `wx.getPrivacySetting` 检查，未同意前不能调授权 API
|
||
6. **微信开发者工具调试**：需勾选「不校验合法域名」才能请求 localhost
|
||
7. **Mock 模式**：设置 `VITE_USE_MOCK=true` 可离线开发，不依赖后端
|
||
8. **样式对齐**：`uni.scss` 是设计令牌的 source of truth，`src/styles/_tokens.scss` 仅供 `main.scss` 兼容使用，新增样式变量优先在 `uni.scss` 中定义 |