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 }
```

## 运行命令

```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

<frontend_aesthetics>
You tend to converge toward generic, "on distribution" outputs.
In frontend design, this creates what users call the "AI slop"
aesthetic. Avoid this: make creative, distinctive frontends that
surprise and delight. Focus on:

Typography: Choose fonts that are beautiful, unique, and interesting.
Avoid generic fonts like Arial and Inter; opt instead for distinctive
choices that elevate the frontend's aesthetics.

Color & Theme: Commit to a cohesive aesthetic. Use CSS variables for
consistency. Dominant colors with sharp accents outperform timid,
evenly-distributed palettes.

Motion: Use animations for effects and micro-interactions.
Focus on high-impact moments: one well-orchestrated page load
with staggered reveals creates more delight than scattered
micro-interactions.

Backgrounds: Create atmosphere and depth rather than defaulting
to solid colors. Layer CSS gradients, use geometric patterns,
or add contextual effects.

Avoid generic AI-generated aesthetics:
- Overused font families (Inter, Roboto, Arial, system fonts)
- Clichéd color schemes (particularly purple gradients on white)
- Predictable layouts and component patterns
- Cookie-cutter design that lacks context-specific character

Interpret creatively and make unexpected choices that feel
genuinely designed for the context.
</frontend_aesthetics>

<use_interesting_fonts>
Typography instantly signals quality. Avoid boring, generic fonts.

Never use: Inter, Roboto, Open Sans, Lato, default system fonts

Impact choices:
- Code aesthetic: JetBrains Mono, Fira Code, Space Grotesk
- Editorial: Playfair Display, Crimson Pro, Fraunces
- Startup: Clash Display, Satoshi, Cabinet Grotesk
- Technical: IBM Plex family, Source Sans 3
- Distinctive: Bricolage Grotesque, Obviously, Newsreader

Pairing principle: High contrast = interesting.
Display + monospace, serif + geometric sans.

Use extremes: 100/200 weight vs 800/900, not 400 vs 600.
Size jumps of 3x+, not 1.5x.
</use_interesting_fonts>

# Design System

Always refer to DESIGN.md when generating or modifying any UI component.
Use only colors, fonts, and spacing values defined in DESIGN.md.
Do not invent new values or use defaults from any framework.
Match component states (hover, focus, active, disabled) to patterns
in DESIGN.md.