xuchao/pingxiangcard
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: 初始化项目 — uni-app + Vue3 + TypeScript 脚手架

Browse Source
This commit is contained in:
jacobxu666
2026-06-14 17:16:18 +08:00
commit 046e84a564
37 changed files with 13763 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/superpowers/specs/2026-06-13-hunan12301-design.md
+337
View File
@@ -0,0 +1,337 @@
# 湖南12301文旅综合平台 — 第一迭代设计文档
**文档版本**：v1.0
**创建日期**：2026-06-13
**实现方案**：方案 A — 由底向上
---
## 一、迭代范围
第一迭代聚焦 **基础层搭建 + 用户端核心流程**，具体包含：
| 阶段 | 内容 |
|------|------|
| **Phase 1：基础层** | 分包目录、路由配置、API 层改造、Store 设计、环境配置、共享组件 |
| **Phase 2：用户端核心页面** | 首页、年卡列表/详情、确认购买、激活年卡、入园码 |
**不包含在第一迭代**：
- 管理端页面（卡管理、景区管理）→ 第二迭代
- H5 版本登录（OAuth / 手机号）→ 后续扩展
- 权益查看、景区预约、预约记录、使用记录 → 后续迭代
- 真实微信支付接入 → 第一版用模拟支付
---
## 二、项目架构
### 2.1 分包目录结构
```
zhy-test/
├── src/
│ ├── pages/ # 主包（共享入口）
│ │ ├── index/index.vue # 入口页（改造：默认跳转用户端首页）
│ │ └── login/login.vue # 登录页（改造为微信授权登录）
│ │
│ ├── packages/
│ │ ├── user/ # 用户端分包
│ │ │ └── pages/
│ │ │ ├── index/index.vue # 用户首页（宫格式）
│ │ │ ├── card/list.vue # 年卡列表
│ │ │ ├── card/detail.vue # 年卡详情
│ │ │ ├── card/buy.vue # 确认购买（模拟支付）
│ │ │ ├── card/activate.vue # 激活年卡
│ │ │ ├── card/qrcode.vue # 入园码（卡片式）
│ │ │ ├── card/bind.vue # 绑定年卡
│ │ │ └── profile/index.vue # 个人中心
│ │ │
│ │ └── admin/ # 管理端分包（第二迭代，暂不实现）
│ │
│ ├── api/ # 接口层
│ │ ├── request.ts # HTTP 封装（改造现有）
│ │ ├── user.ts # 用户/登录接口（改造）
│ │ ├── card.ts # 年卡接口（新增）
│ │ └── order.ts # 订单/支付接口（新增）
│ │
│ ├── store/ # Pinia Store
│ │ ├── user.ts # 用户状态（改造现有）
│ │ └── card.ts # 年卡状态（新增）
│ │
│ ├── components/ # 共享组件（新增）
│ │ ├── card-item.vue # 年卡卡片组件
│ │ └── empty-state.vue # 空状态组件
│ │
│ ├── config/ # 环境配置（新增）
│ │ └── index.ts # 根据环境变量切换 baseURL
│ │
│ └── utils/ # 工具函数（扩展现有）
│ └── index.ts
```
### 2.2 pages.json 路由配置
主包保留 `pages/index`（入口跳转）和 `pages/login`，用户端页面全部放入 `packages/user` 分包。
```json
{
"pages": [
{ "path": "pages/index/index", "style": { "navigationBarTitleText": "湖南12301" } },
{ "path": "pages/login/login", "style": { "navigationBarTitleText": "登录" } }
],
"subPackages": [
{
"root": "packages/user",
"pages": [
{ "path": "pages/index/index", "style": { "navigationBarTitleText": "文旅专区" } },
{ "path": "pages/card/list", "style": { "navigationBarTitleText": "年卡列表" } },
{ "path": "pages/card/detail", "style": { "navigationBarTitleText": "年卡详情" } },
{ "path": "pages/card/buy", "style": { "navigationBarTitleText": "确认购买" } },
{ "path": "pages/card/activate", "style": { "navigationBarTitleText": "激活年卡" } },
{ "path": "pages/card/qrcode", "style": { "navigationBarTitleText": "入园码" } },
{ "path": "pages/card/bind", "style": { "navigationBarTitleText": "绑定年卡" } },
{ "path": "pages/profile/index", "style": { "navigationBarTitleText": "个人中心" } }
]
}
],
"tabBar": {
"color": "#7A7E83",
"selectedColor": "#4A90D9",
"backgroundColor": "#ffffff",
"list": [
{ "pagePath": "packages/user/pages/index/index", "text": "首页" },
{ "pagePath": "packages/user/pages/profile/index", "text": "我的" }
]
}
}
```
### 2.3 多环境配置
| 环境 | baseURL | 触发方式 | 配置文件 |
|------|---------|----------|----------|
| 本地开发 | `http://localhost:80` | `pnpm dev:h5` | `.env.local` |
| 开发环境 | `https://dscp-dev.hn12301.net` | `--mode dev` | `.env.dev` |
| 预发布 | `https://dscp-uat.hn12301.net` | `--mode uat` | `.env.uat` |
通过 `config/index.ts` 统一读取 `import.meta.env.VITE_API_BASE_URL`。
---
## 三、API 层设计
### 3.1 request.ts 改造
**改造要点**：
- `baseURL` 从 `config/index.ts` 读取（替代空字符串）
- Token 管理保持现有 `uni.getStorageSync` / `uni.setStorageSync` 模式
- 请求拦截器自动注入 `Authorization: Bearer <token>`
- 响应拦截器：`code === 200` 成功，`401` 清除 token 并跳转登录页
- 保留 `get()` / `post()` / `put()` / `del()` 便捷方法
### 3.2 接口模块定义
```typescript
// api/user.ts（改造）
wxLogin(code: string) // POST /manage-api/auth/wx-login → { accessToken, refreshToken, userId }
getUserInfo() // GET /manage-api/user/info → UserInfo
// api/card.ts（新增）
getCardList(params?) // GET /manage-api/card/list → CardInfo[]
getCardDetail(id: string) // GET /manage-api/card/detail?id=xxx → CardDetail
activateCard(cardId, data) // POST /manage-api/card/activate → boolean
bindCard(cardNo: string) // POST /manage-api/card/bind → boolean
getMyCards() // GET /manage-api/card/my-list → MyCard[]
getEntryQrCode(cardId: string) // GET /manage-api/card/qrcode?cardId=xxx → { qrCode, expireTime }
// api/order.ts（新增）
createOrder(data) // POST /manage-api/order/create → OrderInfo
mockPay(orderId: string) // POST /manage-api/order/mock-pay → { success: true }（模拟支付）
getOrderList(params?) // GET /manage-api/order/list → OrderInfo[]
getOrderDetail(id: string) // GET /manage-api/order/detail?id=xxx → OrderDetail
```
> **注意**：接口路径和参数格式需在实现时与后端实际接口对齐。以上为预定义，实现阶段根据后端实际接口调整。
---
## 四、Store 设计
### 4.1 user store（改造现有）
```
State:
token: string // 访问令牌
refreshToken: string // 刷新令牌
userInfo: UserInfo | null // 用户信息
Computed:
isLogin: boolean // !!token
Actions:
wxLogin(): Promise // 调用 wx.login() 获取 code，发送后端换取 token
logout(): void // 清除状态和 storage
fetchUserInfo(): Promise // 获取当前用户信息
```
### 4.2 card store（新增）
```
State:
cardList: CardInfo[] // 年卡列表
currentCard: CardDetail // 当前查看的年卡详情
myCards: MyCard[] // 我的年卡列表
Actions:
fetchCardList(params?): Promise // 获取年卡列表
fetchCardDetail(id): Promise // 获取年卡详情
fetchMyCards(): Promise // 获取我的年卡
activateCard(cardId, data): Promise // 激活年卡
bindCard(cardNo): Promise // 绑定年卡
getEntryQrCode(cardId): Promise // 获取入园码
```
---
## 五、微信登录设计
### 5.1 登录流程
```
用户打开小程序
→ 检查本地是否有 token
→ 有 token → 直接进入用户端首页
→ 无 token → 跳转登录页
→ 用户点击"微信登录"按钮
→ uni.login() 获取 code
→ POST /manage-api/auth/wx-login { code }
→ 后端返回 { accessToken, refreshToken, userId }
→ 存入 Store + Storage
→ 跳转用户端首页
```
### 5.2 平台策略
| 平台 | 第一迭代 | 后续扩展 |
|------|----------|----------|
| 微信小程序 | `wx.login()` 授权登录 | — |
| H5 | 不支持（提示请在微信小程序中使用） | 微信 OAuth / 手机号登录 |
### 5.3 降级方案
如果后端微信登录接口尚未就绪，可临时使用现有账号密码登录接口，在 `user store` 的 `wxLogin()` 方法中预留切换点。
---
## 六、用户端页面设计
### 6.1 首页（宫格式）
**路由**：`/packages/user/pages/index/index`
**布局**：
- 顶部：标题栏 "湖南12301文旅专区"
- 中部：2×2 宫格功能入口（购买年卡 / 激活绑定 / 景区预约 / 我的记录）。其中"景区预约"和"我的记录"在第一迭代中点击后弹出"即将上线"提示
- 下部：推荐年卡列表（卡片式展示）
- 底部：TabBar（首页 / 我的）— 权益 Tab 在后续迭代中补充
### 6.2 年卡列表
**路由**：`/packages/user/pages/card/list`
**布局**：
- 顶部搜索栏
- 分类筛选标签
- 年卡卡片列表（使用 card-item 组件）
- 每个卡片：封面图 + 名称 + 价格 + 简要权益
### 6.3 年卡详情
**路由**：`/packages/user/pages/card/detail`
**布局**：
- 顶部封面大图
- 年卡名称 + 价格（原价划线）
- 权益说明列表
- 权益景区横滑卡片
- 底部固定按钮：立即购买
### 6.4 确认购买（模拟支付）
**路由**：`/packages/user/pages/card/buy`
**布局**：
- 订单信息卡片（卡种名称 / 价格 / 有效期）
- 支付方式选择（第一版仅"模拟支付"）
- 底部按钮：确认支付
- 支付成功后跳转到激活页面
### 6.5 激活年卡
**路由**：`/packages/user/pages/card/activate`
**布局**：
- 年卡信息展示
- 实名信息表单（姓名 / 身份证号 / 手机号）
- 底部按钮：立即激活
- 激活成功后跳转到入园码页面
### 6.6 入园码（卡片式）
**路由**：`/packages/user/pages/card/qrcode`
**布局**：
- 年卡信息卡片（渐变色背景，显示姓名和有效期）
- 二维码区域（白色卡片，居中显示）
- 提示文字："扫码入园 · 每60秒自动刷新"
- 底部操作按钮：预约景区 / 刷新二维码
### 6.7 个人中心
**路由**：`/packages/user/pages/profile/index`（TabBar 页面）
**布局**：
- 用户头像 + 昵称卡片
- 我的年卡入口
- 订单管理入口
- 使用记录入口
- 退出登录按钮
---
## 七、页面导航流程
```
小程序启动
→ pages/index/index（入口页，自动跳转）
→ packages/user/pages/index/index（用户首页）
核心购买流程：
用户首页 → 年卡列表 → 年卡详情 → 确认购买 → 模拟支付 → 激活年卡 → 入园码
TabBar 常驻页面：
首页（packages/user/pages/index/index）
我的（packages/user/pages/profile/index）
非 Tab 页面（navigateTo）：
年卡列表、年卡详情、确认购买、激活年卡、入园码、绑定年卡
```
---
## 八、共享组件
| 组件 | 路径 | 用途 |
|------|------|------|
| `card-item.vue` | `components/card-item.vue` | 年卡卡片展示（封面/名称/价格/权益摘要） |
| `empty-state.vue` | `components/empty-state.vue` | 空状态提示（图标 + 文案 + 操作按钮） |
---
## 九、关键约束
1. **接口对齐**：API 路径和参数为预定义，实现时需与后端实际接口对齐
2. **模拟支付**：第一版不接入真实微信支付，使用模拟支付接口跑通流程
3. **UI 优先级**：功能先行，使用 uni-ui 默认样式，后续迭代美化
4. **仅小程序**：第一迭代仅支持微信小程序平台，H5 登录后缀扩展
5. **管理端预留**：`packages/admin/` 目录结构预留，不在第一迭代实现
docs/superpowers/specs/2026-06-13-hunan12301-spec.md
+150
View File
@@ -0,0 +1,150 @@
# 湖南12301文旅综合平台 - 规格说明书
**文档版本**：v1.0
**最后更新**：2026-06-13
---
## 一、项目基本信息
| 项 | 内容 |
|---|---|
| **项目名称** | 湖南12301文旅综合平台 |
| **技术栈** | uni-app + Vue 3 + Composition API + TypeScript + Pinia + uni-ui |
| **构建工具** | Vite |
| **环境配置** | local / dev / uat 三套 |
| **接口架构** | 后端统一 API 层封装所有第三方 |
| **目标平台** | 微信小程序 + H5 + App（Android/iOS） |
---
## 二、双端架构
### 2.1 目录结构
```
湖南12301/
├── src/
│ ├── pages/ # 主包（共享页面）
│ │ ├── index/ # 首页（双端入口选择）
│ │ └── login/ # 登录页
│ ├── packages/
│ │ ├── admin/ # 【综合管理端】商家/管理员
│ │ │ └── pages/
│ │ │ ├── index/ # 管理端首页
│ │ │ ├── card/ # 卡管理
│ │ │ └── scenic/ # 景区管理
│ │ └── user/ # 【文旅专区端】C端用户
│ │ └── pages/
│ │ ├── index/ # 用户端首页
│ │ ├── card/ # 年卡购买/激活/绑定/入园码
│ │ ├── rights/ # 权益查看（免票景区/特惠商品）
│ │ ├── scenic/ # 景区预约
│ │ ├── booking/ # 预约记录
│ │ ├── usage/ # 使用记录
│ │ └── profile/ # 个人中心（我的年卡/订单）
│ ├── components/ # 共享组件
│ ├── api/ # 共享接口层
│ ├── store/ # Pinia 共享状态
│ └── utils/ # 工具函数
```
### 2.2 发布模式
| 模式 | 编译命令 | 说明 |
|---|---|---|
| 聚合版 | `npm run build:all` | 双端合一，首页选择入口 |
| 管理端独立版 | `npm run build:admin` | 商家/管理员独立小程序 |
| 用户端独立版 | `npm run build:user` | C端用户独立小程序 |
---
## 三、综合管理端功能（商家/管理员）
### 3.1 TabBar 设计
| Tab | 路由 | 说明 |
|---|---|---|
| 🏠 | 首页 | 数据概览 |
| 🎫 | 卡管理 | 年卡列表/编辑 |
| 📍 | 景区管理 | 景区列表/编辑 |
| 👤 | 我的 | 个人设置 |
### 3.2 功能模块
| 模块 | 路由 | 功能 |
|---|---|---|
| **首页** | `/packages/admin/pages/index/index` | 数据概览（待扩展） |
| **卡管理** | `/packages/admin/pages/card/list` | 年卡列表、创建/编辑年卡 |
| **景区管理** | `/packages/admin/pages/scenic/list` | 景区列表、创建/编辑景区 |
---
## 四、文旅专区端功能（C端用户）
### 4.1 TabBar 设计
| Tab | 路由 | 说明 |
|---|---|---|
| 🏠 | 首页 | 年卡展示、推荐景区、Banner |
| 🎫 | 权益 | 免票景区、特惠商品 |
| 👤 | 我的 | 我的年卡、订单、预约、积分等 |
### 4.2 功能模块
| 序号 | 模块 | 路由 | 功能 |
|---|---|---|---|
| 1 | **年卡购买** | `/packages/user/pages/card/buy` | 卡种列表 → 选择卡种 → 确认订单 → 微信支付 |
| 2 | **年卡激活** | `/packages/user/pages/card/activate` | 激活已购买的年卡 |
| 3 | **年卡绑定** | `/packages/user/pages/card/bind` | 输入卡号绑定已有年卡 |
| 4 | **入园码** | `/packages/user/pages/card/qrcode` | 生成/展示入园二维码 |
| 5 | **权益查看** | `/packages/user/pages/rights/index` | 免票景区列表、特惠商品列表（含搜索/筛选/排序） |
| 6 | **景区预约** | `/packages/user/pages/scenic/book` | 选择景区 → 选择时间 → 确认预约 |
| 7 | **预约记录** | `/packages/user/pages/booking/list` | 查看/取消已预约记录 |
| 8 | **使用记录** | `/packages/user/pages/usage/list` | 已入园/已使用记录 |
| 9 | **订单管理** | `/packages/user/pages/profile/order` | 全部/待支付/已完成订单 |
| 10 | **我的年卡** | `/packages/user/pages/profile/my-card` | 已购年卡列表、到期时间 |
### 4.3 权益查看子功能
| 功能 | 说明 |
|---|---|
| **搜索** | 关键词搜索景区/商品 |
| **分类筛选** | 按分类筛选（景区/影院/温泉/亲子乐园等） |
| **排序** | 按距离/热度/时间排序 |
### 4.4 核心业务流程
```
购买年卡：
年卡展示 → 选择卡种 → 微信支付 → 支付成功 → 年卡激活 → 我的年卡
权益使用：
查看权益 → 选择景区 → 景区预约 → 生成入园码 → 入园核销 → 使用记录
年卡绑定：
已有年卡 → 输入卡号 → 验证 → 绑定成功 → 查看权益
```
---
## 五、API 接口模块
| 模块 | 接口描述 |
|---|---|
| **用户模块** | 登录、获取用户信息 |
| **年卡模块** | 卡种列表、卡种详情、年卡激活、年卡绑定、我的年卡列表 |
| **权益模块** | 免票景区列表、特惠商品列表、景区/商品详情 |
| **预约模块** | 创建预约、取消预约、预约列表 |
| **核销模块** | 生成入园码、验证入园码 |
| **订单模块** | 创建订单、微信支付、订单列表、订单详情 |
---
## 六、环境配置
| 环境 | 标识 | 用途 |
|---|---|---|
| 本地开发 | `local` | 本机开发调试 |
| 测试环境 | `dev` | 团队联调、测试验证 |
| 预发布环境 | `uat` | 生产环境验证、灰度测试 |