# zhy-test — 产研部用户端微信小程序

## 项目定位

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

## 技术栈

| 技术 | 版本 | 说明 |
|------|------|------|
| Vue | 3.5.x | 核心框架 |
| uni-app | 3.0.0 | 跨平台框架（当前仅编译微信小程序） |
| TypeScript | 5.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
├── 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

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

## 环境配置

| 文件 | API 地址 | 用途 |
|------|---------|------|
| `.env.local` | `http://localhost:48080` | 本地开发（配合后端 `--spring.profiles.active=local`） |
| `.env.dev` | `https://dscp-dev.hn12301.net` | 开发环境 |
| `.env.uat` | UAT 环境地址 | 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