# 健身房管理系统前端技术架构详细设计文档

> 文档编号: GYM-FE-ARCH-001  
> 版本: v1.0  
> 日期: 2026-03-04  
> 作者: 张翔  
> 状态: 初稿

---

## 文档修订历史

| 版本 | 日期 | 作者 | 修订内容 |
| ---- | ---------- | ---- | -------- |
| v1.0 | 2026-03-04 | 张翔 | 创建前端技术架构详细设计 |

---

## 参考文档

- 《健身房管理系统基础版产品设计文档》 GYM-PRD-BASIC-001
- 《健身房管理系统基础版系统概要设计文档》 GYM-HLD-BASIC-001
- 《健身房管理系统基础版系统详细设计文档》 GYM-LLD-BASIC-001
- Vue 3 官方文档
- uniapp 官方文档
- TypeScript 官方文档

---

## 一、架构概述

### 1.1 架构目标

- **跨平台覆盖**：支持小程序、App、PC多端，满足不同用户角色需求
- **高性能**：首屏加载时间 < 2s，交互响应时间 < 100ms
- **高安全性**：符合金融级安全标准，保障用户数据和交易安全
- **高可维护性**：代码结构清晰，模块化设计，便于团队协作
- **高扩展性**：支持订阅模块动态加载，适应业务快速变化

### 1.2 客户端架构

```
┌─────────────────────────────────────────────────────────────────────────┐
│                          前端客户端架构                                │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │ 会员小程序 (uniapp+Vue3)                                      │   │
│  ├─────────────────────────────────────────────────────────────────┤   │
│  │ • 会员注册/登录  • 课程预约  • 扫码签到  • 会员卡管理        │   │
│  │ • 个人中心  • 消息通知  • 数据统计                            │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │ 教练端App (uniapp+Vue3)                                       │   │
│  ├─────────────────────────────────────────────────────────────────┤   │
│  │ • 课程管理  • 排班管理  • 会员管理  • 签到管理                │   │
│  │ • 数据统计  • 消息通知  • 个人中心                            │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │ 管理后台PC (Vue3+Vite+Element Plus)                          │   │
│  ├─────────────────────────────────────────────────────────────────┤   │
│  │ • 会员管理  • 课程管理  • 预约管理  • 签到管理               │   │
│  │ • 财务管理  • 数据统计  • 系统管理  • 订阅管理               │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘
```

### 1.3 技术栈选型

#### 1.3.1 核心框架

| 技术 | 版本 | 用途 | 选型理由 |
|------|------|------|----------|
| **Vue 3** | 3.4+ | 前端框架 | Composition API、响应式系统、生态成熟 |
| **uniapp** | 3.0+ | 跨平台框架 | 一次开发多端部署、性能优秀、生态完善 |
| **TypeScript** | 5.0+ | 类型系统 | 类型安全、开发体验、代码可维护性 |
| **Vite** | 5.0+ | 构建工具 | 快速热更新、优化的构建性能、插件生态 |

#### 1.3.2 状态管理

| 技术 | 版本 | 用途 | 选型理由 |
|------|------|------|----------|
| **Pinia** | 2.1+ | 状态管理 | Vue3官方推荐、API简洁、TypeScript支持好、模块化设计 |

#### 1.3.3 UI组件库

| 技术 | 版本 | 用途 | 选型理由 |
|------|------|------|----------|
| **Element Plus** | 2.5+ | PC端UI组件 | 功能完善、设计规范、TypeScript支持、文档齐全 |
| **uni-ui** | 1.5+ | 小程序/App UI组件 | 官方组件库、跨平台兼容、性能优化 |

#### 1.3.4 工具库

| 技术 | 版本 | 用途 | 选型理由 |
|------|------|------|----------|
| **Vue Router** | 4.2+ | 路由管理 | Vue官方路由、动态路由、路由守卫 |
| **Axios** | 1.6+ | HTTP客户端 | 拦截器、请求取消、TypeScript支持 |
| **Day.js** | 1.11+ | 日期处理 | 轻量级、API友好、国际化支持 |
| **Lodash-es** | 4.17+ | 工具函数 | 按需加载、性能优化、功能完善 |

#### 1.3.5 开发工具

| 技术 | 版本 | 用途 | 选型理由 |
|------|------|------|----------|
| **ESLint** | 8.56+ | 代码检查 | 规则完善、插件生态、自动修复 |
| **Prettier** | 3.1+ | 代码格式化 | 统一风格、配置简单、编辑器集成 |
| **Husky** | 8.0+ | Git钩子 | 提交前检查、自动化流程 |
| **Commitlint** | 18.4+ | 提交规范 | 规范提交信息、自动化生成Changelog |

---

## 二、架构设计

### 2.1 分层架构

```
┌─────────────────────────────────────────────────────────────────────────┐
│                          前端分层架构                                  │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │ 表现层 (Presentation Layer)                                    │   │
│  ├─────────────────────────────────────────────────────────────────┤   │
│  │ • 页面组件  • 业务组件  • 基础组件  • 布局组件                │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                              │                                        │
│                              ▼                                        │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │ 状态管理层 (State Management Layer)                          │   │
│  ├─────────────────────────────────────────────────────────────────┤   │
│  │ • 全局状态  • 模块状态  • 组件状态  • 持久化状态            │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                              │                                        │
│                              ▼                                        │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │ 业务逻辑层 (Business Logic Layer)                              │   │
│  ├─────────────────────────────────────────────────────────────────┤   │
│  │ • Composables  • Hooks  • Utils  • Validators                 │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                              │                                        │
│                              ▼                                        │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │ 数据访问层 (Data Access Layer)                                │   │
│  ├─────────────────────────────────────────────────────────────────┤   │
│  │ • API Service  • WebSocket  • Cache  • Storage                │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                              │                                        │
│                              ▼                                        │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │ 基础设施层 (Infrastructure Layer)                             │   │
│  ├─────────────────────────────────────────────────────────────────┤   │
│  │ • 路由  • 拦截器  • 错误处理  • 日志  • 监控                 │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘
```

### 2.2 模块划分

#### 2.2.1 会员端模块

```
会员端 (Member Mini Program)
├── 认证模块 (Auth)
│   ├── 登录/注册
│   ├── 手机号验证
│   ├── 微信授权
│   └── 忘记密码
├── 会员模块 (Member)
│   ├── 个人信息
│   ├── 会员卡管理
│   ├── 权益管理
│   └── 等级体系
├── 预约模块 (Booking)
│   ├── 团课列表
│   ├── 课程详情
│   ├── 预约操作
│   └── 预约记录
├── 签到模块 (CheckIn)
│   ├── 扫码签到
│   ├── 签到记录
│   └── 签到统计
├── 消息模块 (Message)
│   ├── 系统通知
│   ├── 预约提醒
│   └── 消息中心
└── 个人中心 (Profile)
    ├── 设置
    ├── 帮助
    └── 关于
```

#### 2.2.2 教练端模块

```
教练端 (Coach App)
├── 认证模块 (Auth)
│   ├── 登录
│   └── 权限验证
├── 课程模块 (Course)
│   ├── 课程管理
│   ├── 排班管理
│   └── 课程统计
├── 会员模块 (Member)
│   ├── 会员列表
│   ├── 会员详情
│   └── 会员跟进
├── 签到模块 (CheckIn)
│   ├── 签到管理
│   ├── 代签操作
│   └── 签到统计
├── 数据模块 (Data)
│   ├── 课程数据
│   ├── 会员数据
│   └── 收入数据
└── 个人中心 (Profile)
    ├── 个人信息
    ├── 设置
    └── 帮助
```

#### 2.2.3 管理后台模块

```
管理后台 (Admin PC)
├── 认证模块 (Auth)
│   ├── 登录
│   ├── 权限管理
│   └── 角色管理
├── 会员模块 (Member)
│   ├── 会员管理
│   ├── 会员卡管理
│   ├── 权益管理
│   └── 等级管理
├── 课程模块 (Course)
│   ├── 课程管理
│   ├── 时段管理
│   └── 排班管理
├── 预约模块 (Booking)
│   ├── 预约管理
│   ├── 候补管理
│   └── 预约统计
├── 签到模块 (CheckIn)
│   ├── 签到记录
│   ├── 设备管理
│   └── 签到统计
├── 财务模块 (Finance)
│   ├── 订单管理
│   ├── 收入统计
│   └── 财务报表
├── 数据模块 (Data)
│   ├── 数据统计
│   ├── 数据分析
│   └── 报表导出
├── 系统模块 (System)
│   ├── 用户管理
│   ├── 角色权限
│   ├── 系统配置
│   └── 操作日志
└── 订阅模块 (Subscription)
    ├── 订阅管理
    ├── 模块管理
    └── 计费管理
```

### 2.3 目录结构

#### 2.3.1 会员端/教练端目录结构

```
src/
├── api/                    # API接口
│   ├── modules/
│   │   ├── auth.ts
│   │   ├── member.ts
│   │   ├── booking.ts
│   │   └── checkin.ts
│   └── request.ts          # Axios封装
├── assets/                 # 静态资源
│   ├── images/
│   ├── icons/
│   └── styles/
├── components/             # 组件
│   ├── base/              # 基础组件
│   ├── business/          # 业务组件
│   └── layout/            # 布局组件
├── composables/           # Composables
│   ├── useAuth.ts
│   ├── useBooking.ts
│   └── useCheckIn.ts
├── config/               # 配置
│   ├── app.config.ts
│   └── env.config.ts
├── hooks/                # Hooks
│   ├── useRequest.ts
│   └── useWebSocket.ts
├── pages/                # 页面
│   ├── index/
│   ├── auth/
│   ├── member/
│   ├── booking/
│   └── checkin/
├── stores/               # 状态管理
│   ├── auth.ts
│   ├── member.ts
│   ├── booking.ts
│   └── checkin.ts
├── types/                # 类型定义
│   ├── api.ts
│   ├── models.ts
│   └── index.ts
├── utils/                # 工具函数
│   ├── validator.ts
│   ├── formatter.ts
│   └── storage.ts
├── App.vue
└── main.ts
```

#### 2.3.2 管理后台目录结构

```
src/
├── api/                    # API接口
│   ├── modules/
│   │   ├── auth.ts
│   │   ├── member.ts
│   │   ├── course.ts
│   │   ├── booking.ts
│   │   ├── checkin.ts
│   │   ├── finance.ts
│   │   └── system.ts
│   └── request.ts          # Axios封装
├── assets/                 # 静态资源
│   ├── images/
│   ├── icons/
│   └── styles/
├── components/             # 组件
│   ├── base/              # 基础组件
│   ├── business/          # 业务组件
│   └── layout/            # 布局组件
├── composables/           # Composables
│   ├── useAuth.ts
│   ├── usePermission.ts
│   └── useTable.ts
├── config/               # 配置
│   ├── app.config.ts
│   └── env.config.ts
├── directives/           # 自定义指令
│   ├── permission.ts
│   └── loading.ts
├── hooks/                # Hooks
│   ├── useRequest.ts
│   └── useWebSocket.ts
├── layouts/              # 布局
│   ├── BasicLayout.vue
│   └── BlankLayout.vue
├── router/               # 路由
│   ├── index.ts
│   └── modules/
│       ├── auth.ts
│       ├── member.ts
│       ├── course.ts
│       └── system.ts
├── stores/               # 状态管理
│   ├── auth.ts
│   ├── permission.ts
│   ├── app.ts
│   └── user.ts
├── types/                # 类型定义
│   ├── api.ts
│   ├── models.ts
│   └── index.ts
├── utils/                # 工具函数
│   ├── validator.ts
│   ├── formatter.ts
│   ├── storage.ts
│   └── permission.ts
├── views/                # 页面
│   ├── auth/
│   ├── member/
│   ├── course/
│   ├── booking/
│   ├── checkin/
│   ├── finance/
│   ├── data/
│   ├── system/
│   └── subscription/
├── App.vue
└── main.ts
```

---

## 三、数据流设计

### 3.1 单向数据流

```
┌─────────────────────────────────────────────────────────────────────────┐
│                          单向数据流设计                                │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐            │
│  │  用户   │ ──▶│  组件   │ ──▶│  Store  │ ──▶│  API    │            │
│  │  操作   │    │  Action │    │  State  │    │ Service │            │
│  └─────────┘    └─────────┘    └─────────┘    └─────────┘            │
│       │              │              │              │                    │
│       │              │              │              │                    │
│       │              │              │              ▼                    │
│       │              │              │      ┌─────────┐                │
│       │              │              │      │ 后端API │                │
│       │              │              │      └─────────┘                │
│       │              │              │              │                    │
│       │              │              │              ▼                    │
│       │              │              │      ┌─────────┐                │
│       │              │              │      │  数据库 │                │
│       │              │              │      └─────────┘                │
│       │              │              │              │                    │
│       │              │              │              ▼                    │
│       │              │              │      ┌─────────┐                │
│       │              │              │      │ 返回数据 │                │
│       │              │              │      └─────────┘                │
│       │              │              │              │                    │
│       │              │              ▼              │                    │
│       │              │      ┌─────────┐          │                    │
│       │              │      │ 更新    │◀─────────┘                    │
│       │              │      │ State   │                               │
│       │              │      └─────────┘                               │
│       │              │              │                                  │
│       │              ▼              ▼                                  │
│       │      ┌─────────────────────────┐                               │
│       │      │    重新渲染组件        │                               │
│       │      └─────────────────────────┘                               │
│       │              │                                                │
│       ▼              ▼                                                │
│  ┌─────────────────────────┐                                         │
│  │      更新UI显示         │                                         │
│  └─────────────────────────┘                                         │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘
```

### 3.2 状态管理策略

#### 3.2.1 状态分类

| 状态类型 | 存储位置 | 持久化 | 示例 |
|---------|----------|--------|------|
| **全局状态** | Pinia Store | 是 | 用户信息、权限、配置 |
| **模块状态** | Pinia Store | 否 | 当前页面数据、表单数据 |
| **组件状态** | Component State | 否 | 弹窗显示、加载状态 |
| **临时状态** | Component State | 否 | 输入框值、选择项 |

#### 3.2.2 状态持久化

```typescript
// stores/auth.ts
import { defineStore } from 'pinia'
import { ref } from 'vue'

export const useAuthStore = defineStore('auth', () => {
  const token = ref<string>('')
  const user = ref<User | null>(null)

  // 持久化到localStorage
  const $persist = () => {
    localStorage.setItem('auth_token', token.value)
    localStorage.setItem('auth_user', JSON.stringify(user.value))
  }

  const login = async (credentials: LoginRequest) => {
    const response = await api.login(credentials)
    token.value = response.token
    user.value = response.user
    $persist()
  }

  const logout = () => {
    token.value = ''
    user.value = null
    localStorage.removeItem('auth_token')
    localStorage.removeItem('auth_user')
  }

  return { token, user, login, logout }
})
```

### 3.3 实时数据处理

#### 3.3.1 WebSocket连接管理

```typescript
// hooks/useWebSocket.ts
import { ref, onUnmounted } from 'vue'

export function useWebSocket(url: string) {
  const ws = ref<WebSocket | null>(null)
  const connected = ref(false)
  const messageHandler = ref<(data: any) => void>(() => {})

  const connect = () => {
    ws.value = new WebSocket(url)
    
    ws.value.onopen = () => {
      connected.value = true
      startHeartbeat()
    }
    
    ws.value.onmessage = (event) => {
      const data = JSON.parse(event.data)
      messageHandler.value(data)
    }
    
    ws.value.onclose = () => {
      connected.value = false
      reconnect()
    }
    
    ws.value.onerror = (error) => {
      console.error('WebSocket error:', error)
    }
  }

  const disconnect = () => {
    if (ws.value) {
      ws.value.close()
      ws.value = null
    }
  }

  const send = (data: any) => {
    if (ws.value && connected.value) {
      ws.value.send(JSON.stringify(data))
    }
  }

  const reconnect = () => {
    setTimeout(() => {
      connect()
    }, 3000)
  }

  const startHeartbeat = () => {
    setInterval(() => {
      send({ type: 'ping' })
    }, 30000)
  }

  onUnmounted(() => {
    disconnect()
  })

  return {
    connected,
    connect,
    disconnect,
    send,
    onMessage: (handler: (data: any) => void) => {
      messageHandler.value = handler
    }
  }
}
```

#### 3.3.2 数据更新优化

```typescript
// composables/useRealTimeData.ts
import { ref, computed } from 'vue'
import { useWebSocket } from '@/hooks/useWebSocket'

export function useRealTimeData<T>(initialData: T, wsUrl: string) {
  const data = ref<T>(initialData)
  const { connected, connect, send, onMessage } = useWebSocket(wsUrl)

  const updateData = (newData: Partial<T>) => {
    data.value = { ...data.value, ...newData }
  }

  const subscribe = (channel: string) => {
    onMessage((message) => {
      if (message.channel === channel) {
        // 增量更新，减少重渲染
        updateData(message.data)
      }
    })
  }

  return {
    data,
    connected,
    connect,
    subscribe
  }
}
```

---

## 四、组件设计

### 4.1 组件分类

#### 4.1.1 基础组件

| 组件名称 | 功能 | 适用端 |
|---------|------|--------|
| Button | 按钮 | 全端 |
| Input | 输入框 | 全端 |
| Select | 选择器 | 全端 |
| DatePicker | 日期选择器 | 全端 |
| Modal | 弹窗 | 全端 |
| Loading | 加载 | 全端 |
| Empty | 空状态 | 全端 |
| ErrorPage | 错误页 | 全端 |

#### 4.1.2 业务组件

| 组件名称 | 功能 | 适用端 |
|---------|------|--------|
| MemberCard | 会员卡展示 | 全端 |
| CourseCard | 课程卡片 | 全端 |
| BookingCard | 预约卡片 | 全端 |
| CheckInCode | 签到码 | 会员端/教练端 |
| QRCodeScanner | 二维码扫描 | 会员端/教练端 |
| DataChart | 数据图表 | 管理后台 |
| DataTable | 数据表格 | 管理后台 |

#### 4.1.3 布局组件

| 组件名称 | 功能 | 适用端 |
|---------|------|--------|
| PageLayout | 页面布局 | 全端 |
| TabBar | 底部导航 | 会员端/教练端 |
| Sidebar | 侧边栏 | 管理后台 |
| Header | 顶部导航 | 管理后台 |
| Footer | 底部 | 管理后台 |

### 4.2 组件设计原则

#### 4.2.1 单一职责原则

每个组件只负责一个功能，保持组件的简洁和可复用性。

```vue
<!-- Bad: 职责过多 -->
<template>
  <div>
    <input v-model="form.name" />
    <input v-model="form.phone" />
    <button @click="submit">提交</button>
    <div v-if="showChart">
      <chart :data="chartData" />
    </div>
  </div>
</template>

<!-- Good: 职责单一 -->
<template>
  <member-form :model="form" @submit="handleSubmit" />
  <data-chart v-if="showChart" :data="chartData" />
</template>
```

#### 4.2.2 Props设计

```typescript
// components/base/Button.vue
interface ButtonProps {
  type?: 'primary' | 'secondary' | 'danger'
  size?: 'small' | 'medium' | 'large'
  disabled?: boolean
  loading?: boolean
  block?: boolean
}

const props = withDefaults(defineProps<ButtonProps>(), {
  type: 'primary',
  size: 'medium',
  disabled: false,
  loading: false,
  block: false
})
```

#### 4.2.3 事件设计

```typescript
// components/base/DatePicker.vue
const emit = defineEmits<{
  change: [value: Date]
  confirm: [value: Date]
  cancel: []
}>()

// 使用
emit('change', new Date())
emit('confirm', new Date())
emit('cancel')
```

### 4.3 组件复用策略

#### 4.3.1 跨端组件

使用uniapp的条件编译实现跨端组件：

```vue
<template>
  <view class="button">
    <!-- #ifdef MP-WEIXIN -->
    <button open-type="getUserInfo" @getuserinfo="handleGetUserInfo">
      {{ text }}
    </button>
    <!-- #endif -->
    
    <!-- #ifdef APP-PLUS -->
    <button @click="handleClick">
      {{ text }}
    </button>
    <!-- #endif -->
  </view>
</template>
```

#### 4.3.2 业务组件封装

```vue
<!-- components/business/CourseCard.vue -->
<template>
  <view class="course-card" @click="handleClick">
    <image :src="course.coverImage" mode="aspectFill" />
    <view class="course-info">
      <text class="course-name">{{ course.name }}</text>
      <text class="course-time">{{ course.startTime }}</text>
      <text class="course-capacity">
        {{ course.bookedCount }}/{{ course.capacity }}
      </text>
    </view>
  </view>
</template>

<script setup lang="ts">
interface Course {
  id: number
  name: string
  coverImage: string
  startTime: string
  bookedCount: number
  capacity: number
}

interface Props {
  course: Course
}

const props = defineProps<Props>()
const emit = defineEmits<{
  click: [course: Course]
}>()

const handleClick = () => {
  emit('click', props.course)
}
</script>
```

---

## 五、路由设计

### 5.1 路由结构

#### 5.1.1 会员端路由

```typescript
// router/index.ts
const routes = [
  {
    path: '/pages/index/index',
    name: 'Home',
    meta: { title: '首页' }
  },
  {
    path: '/pages/auth/login',
    name: 'Login',
    meta: { title: '登录' }
  },
  {
    path: '/pages/member/profile',
    name: 'Profile',
    meta: { title: '个人中心', requiresAuth: true }
  },
  {
    path: '/pages/booking/list',
    name: 'BookingList',
    meta: { title: '课程列表', requiresAuth: true }
  },
  {
    path: '/pages/booking/detail',
    name: 'BookingDetail',
    meta: { title: '课程详情', requiresAuth: true }
  },
  {
    path: '/pages/checkin/scan',
    name: 'CheckInScan',
    meta: { title: '扫码签到', requiresAuth: true }
  }
]
```

#### 5.1.2 管理后台路由

```typescript
// router/index.ts
const routes = [
  {
    path: '/login',
    name: 'Login',
    component: () => import('@/views/auth/Login.vue'),
    meta: { title: '登录' }
  },
  {
    path: '/',
    component: () => import('@/layouts/BasicLayout.vue'),
    redirect: '/dashboard',
    children: [
      {
        path: 'dashboard',
        name: 'Dashboard',
        component: () => import('@/views/dashboard/Index.vue'),
        meta: { title: '仪表盘', requiresAuth: true }
      },
      {
        path: 'member',
        name: 'Member',
        redirect: '/member/list',
        meta: { title: '会员管理', requiresAuth: true, permission: 'member:view' },
        children: [
          {
            path: 'list',
            name: 'MemberList',
            component: () => import('@/views/member/List.vue'),
            meta: { title: '会员列表' }
          },
          {
            path: 'detail/:id',
            name: 'MemberDetail',
            component: () => import('@/views/member/Detail.vue'),
            meta: { title: '会员详情' }
          }
        ]
      }
    ]
  }
]
```

### 5.2 路由守卫

#### 5.2.1 认证守卫

```typescript
// router/guards/auth.ts
import { useAuthStore } from '@/stores/auth'

router.beforeEach((to, from, next) => {
  const authStore = useAuthStore()
  
  if (to.meta.requiresAuth && !authStore.token) {
    next('/login')
  } else {
    next()
  }
})
```

#### 5.2.2 权限守卫

```typescript
// router/guards/permission.ts
import { usePermissionStore } from '@/stores/permission'

router.beforeEach((to, from, next) => {
  const permissionStore = usePermissionStore()
  
  if (to.meta.permission && !permissionStore.hasPermission(to.meta.permission as string)) {
    next('/403')
  } else {
    next()
  }
})
```

### 5.3 动态路由

```typescript
// router/dynamic.ts
import { usePermissionStore } from '@/stores/permission'

export function setupDynamicRoutes() {
  const permissionStore = usePermissionStore()
  const routes = permissionStore.generateRoutes()
  
  routes.forEach(route => {
    router.addRoute(route)
  })
}
```

---

## 六、API设计

### 6.1 Axios封装

```typescript
// api/request.ts
import axios, { AxiosInstance, AxiosRequestConfig, AxiosResponse } from 'axios'
import { useAuthStore } from '@/stores/auth'

class Request {
  private instance: AxiosInstance

  constructor(config: AxiosRequestConfig) {
    this.instance = axios.create(config)
    this.setupInterceptors()
  }

  private setupInterceptors() {
    // 请求拦截器
    this.instance.interceptors.request.use(
      (config) => {
        const authStore = useAuthStore()
        if (authStore.token) {
          config.headers.Authorization = `Bearer ${authStore.token}`
        }
        return config
      },
      (error) => {
        return Promise.reject(error)
      }
    )

    // 响应拦截器
    this.instance.interceptors.response.use(
      (response: AxiosResponse) => {
        const { code, data, message } = response.data
        
        if (code === 200) {
          return data
        } else {
          return Promise.reject(new Error(message))
        }
      },
      (error) => {
        if (error.response?.status === 401) {
          const authStore = useAuthStore()
          authStore.logout()
          window.location.href = '/login'
        }
        return Promise.reject(error)
      }
    )
  }

  public get<T = any>(url: string, config?: AxiosRequestConfig): Promise<T> {
    return this.instance.get(url, config)
  }

  public post<T = any>(url: string, data?: any, config?: AxiosRequestConfig): Promise<T> {
    return this.instance.post(url, data, config)
  }

  public put<T = any>(url: string, data?: any, config?: AxiosRequestConfig): Promise<T> {
    return this.instance.put(url, data, config)
  }

  public delete<T = any>(url: string, config?: AxiosRequestConfig): Promise<T> {
    return this.instance.delete(url, config)
  }
}

export default new Request({
  baseURL: import.meta.env.VITE_API_BASE_URL,
  timeout: 10000
})
```

### 6.2 API模块化

```typescript
// api/modules/member.ts
import request from '../request'

export interface Member {
  id: number
  name: string
  phone: string
  avatar?: string
  level: number
  exp: number
}

export interface MemberListParams {
  page: number
  pageSize: number
  keyword?: string
  level?: number
}

export interface MemberListResponse {
  list: Member[]
  total: number
}

export const memberApi = {
  // 获取会员列表
  getList: (params: MemberListParams) => {
    return request.get<MemberListResponse>('/member/list', { params })
  },
  
  // 获取会员详情
  getDetail: (id: number) => {
    return request.get<Member>(`/member/${id}`)
  },
  
  // 创建会员
  create: (data: Partial<Member>) => {
    return request.post<Member>('/member', data)
  },
  
  // 更新会员
  update: (id: number, data: Partial<Member>) => {
    return request.put<Member>(`/member/${id}`, data)
  },
  
  // 删除会员
  delete: (id: number) => {
    return request.delete(`/member/${id}`)
  }
}
```

---

## 七、性能优化

### 7.1 加载性能优化

#### 7.1.1 代码分割

```typescript
// 路由懒加载
const routes = [
  {
    path: '/member/list',
    component: () => import('@/views/member/List.vue')
  }
]
```

#### 7.1.2 资源优化

```typescript
// vite.config.ts
export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          'vue-vendor': ['vue', 'vue-router', 'pinia'],
          'element-plus': ['element-plus'],
          'utils': ['lodash-es', 'dayjs']
        }
      }
    }
  }
})
```

### 7.2 运行时性能优化

#### 7.2.1 虚拟滚动

```vue
<template>
  <virtual-list
    :data="memberList"
    :item-size="80"
    :buffer="10"
  >
    <template #default="{ item }">
      <member-item :member="item" />
    </template>
  </virtual-list>
</template>
```

#### 7.2.2 防抖节流

```typescript
// utils/debounce.ts
export function debounce<T extends (...args: any[]) => any>(
  fn: T,
  delay: number
): (...args: Parameters<T>) => void {
  let timer: ReturnType<typeof setTimeout>
  
  return function(this: any, ...args: Parameters<T>) {
    clearTimeout(timer)
    timer = setTimeout(() => {
      fn.apply(this, args)
    }, delay)
  }
}

// 使用
const handleSearch = debounce((keyword: string) => {
  searchMembers(keyword)
}, 300)
```

### 7.3 渲染性能优化

#### 7.3.1 减少重渲染

```vue
<template>
  <member-item
    v-for="member in memberList"
    :key="member.id"
    :member="member"
    @click="handleMemberClick"
  />
</template>

<script setup lang="ts">
import { shallowRef } from 'vue'

// 使用shallowRef减少响应式开销
const memberList = shallowRef<Member[]>([])
</script>
```

#### 7.3.2 计算属性缓存

```typescript
const filteredMembers = computed(() => {
  return memberList.value.filter(member => 
    member.name.includes(searchKeyword.value)
  )
})
```

---

## 八、安全设计

### 8.1 XSS防护

```typescript
// utils/sanitize.ts
import DOMPurify from 'dompurify'

export function sanitizeHtml(html: string): string {
  return DOMPurify.sanitize(html)
}

// 使用
const safeHtml = sanitizeHtml(userInput)
```

### 8.2 CSRF防护

```typescript
// api/request.ts
instance.interceptors.request.use((config) => {
  const csrfToken = getCookie('csrf_token')
  if (csrfToken) {
    config.headers['X-CSRF-Token'] = csrfToken
  }
  return config
})
```

### 8.3 数据加密

```typescript
// utils/crypto.ts
import CryptoJS from 'crypto-js'

const SECRET_KEY = 'your-secret-key'

export function encrypt(text: string): string {
  return CryptoJS.AES.encrypt(text, SECRET_KEY).toString()
}

export function decrypt(ciphertext: string): string {
  const bytes = CryptoJS.AES.decrypt(ciphertext, SECRET_KEY)
  return bytes.toString(CryptoJS.enc.Utf8)
}
```

### 8.4 CSP策略

```html
<!-- index.html -->
<meta http-equiv="Content-Security-Policy" 
      content="default-src 'self'; 
               script-src 'self' 'unsafe-inline' 'unsafe-eval'; 
               style-src 'self' 'unsafe-inline'; 
               img-src 'self' data: https:;">
```

---

## 九、测试策略

### 9.1 单元测试

```typescript
// components/__tests__/Button.spec.ts
import { mount } from '@vue/test-utils'
import { describe, it, expect } from 'vitest'
import Button from '@/components/base/Button.vue'

describe('Button', () => {
  it('renders text correctly', () => {
    const wrapper = mount(Button, {
      slots: {
        default: 'Click me'
      }
    })
    expect(wrapper.text()).toBe('Click me')
  })

  it('emits click event', async () => {
    const wrapper = mount(Button)
    await wrapper.trigger('click')
    expect(wrapper.emitted('click')).toBeTruthy()
  })
})
```

### 9.2 E2E测试

```typescript
// e2e/booking.spec.ts
import { test, expect } from '@playwright/test'

test('user can book a course', async ({ page }) => {
  await page.goto('/booking/list')
  await page.click('[data-testid="course-card"]:first-child')
  await page.click('[data-testid="book-button"]')
  await expect(page.locator('[data-testid="success-message"]')).toBeVisible()
})
```

---

## 十、监控与日志

### 10.1 错误监控

```typescript
// utils/sentry.ts
import * as Sentry from '@sentry/vue'

export function setupSentry(app: App) {
  Sentry.init({
    app,
    dsn: import.meta.env.VITE_SENTRY_DSN,
    environment: import.meta.env.MODE,
    tracesSampleRate: 1.0,
    beforeSend(event) {
      // 过滤敏感信息
      if (event.request) {
        delete event.request.cookies
      }
      return event
    }
  })
}
```

### 10.2 性能监控

```typescript
// utils/analytics.ts
import { onCLS, onFID, onLCP } from 'web-vitals'

export function setupPerformanceMonitoring() {
  onCLS((metric) => {
    console.log('CLS:', metric.value)
  })
  
  onFID((metric) => {
    console.log('FID:', metric.value)
  })
  
  onLCP((metric) => {
    console.log('LCP:', metric.value)
  })
}
```

---

## 十一、部署策略

### 11.1 构建配置

```typescript
// vite.config.ts
export default defineConfig({
  base: '/',
  build: {
    outDir: 'dist',
    assetsDir: 'assets',
    sourcemap: false,
    minify: 'terser',
    terserOptions: {
      compress: {
        drop_console: true,
        drop_debugger: true
      }
    }
  }
})
```

### 11.2 环境配置

```typescript
// .env.development
VITE_API_BASE_URL=http://localhost:8080/api
VITE_APP_TITLE=健身房管理系统(开发环境)

// .env.production
VITE_API_BASE_URL=https://api.example.com/api
VITE_APP_TITLE=健身房管理系统
```

---

## 十二、总结

本文档详细描述了健身房管理系统的前端技术架构，包括：

1. **技术栈选型**：Vue3 + uniapp + TypeScript + Pinia + Vite
2. **架构设计**：分层架构、模块划分、目录结构
3. **数据流设计**：单向数据流、状态管理、实时数据处理
4. **组件设计**：组件分类、设计原则、复用策略
5. **路由设计**：路由结构、路由守卫、动态路由
6. **API设计**：Axios封装、API模块化
7. **性能优化**：加载性能、运行时性能、渲染性能
8. **安全设计**：XSS防护、CSRF防护、数据加密、CSP策略
9. **测试策略**：单元测试、E2E测试
10. **监控与日志**：错误监控、性能监控
11. **部署策略**：构建配置、环境配置

该架构设计充分考虑了跨平台需求、性能优化、安全性、可维护性和可扩展性，为健身房管理系统的前端开发提供了完整的技术指导。