xuchao/pingxiangcard
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6ee484d8a31448ee385f10e53b99dc9ed4944f75
pingxiangcard/docs/superpowers/specs/2026-06-13-hunan12301-design.md
T

12 KiB
Raw Blame History

湖南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 分包。

{
  "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 接口模块定义

// 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/ 目录结构预留，不在第一迭代实现
Reference in New Issue View Git Blame Copy Permalink