# MobVue 项目文档

## 项目概述

MobVue 是一个精心制作的移动端 H5 应用模板，基于 Vue3、Vite、TypeScript、Vant 等主流技术栈开发。本项目是一个电商/柜机管理系统，支持微信和企业微信登录，具备完整的用户认证、商品管理、订单处理、审批流程等功能。

## 项目特性

### 🔥 技术特性
- **Vue3**: 采用最新的 Composition API 和 script setup 语法
- **TypeScript**: 严格模式，无 `any` 类型
- **Vite**: 极速的开发体验和构建性能
- **Vant**: 轻量、可定制的移动端 Vue 组件库
- **Pinia**: 现代化的状态管理
- **UnoCSS**: 高性能的原子化 CSS 引擎

### 📱 移动端适配
- **Px2Vw**: 自动将 px 转换为 vw 单位
- **宽屏友好**: 适配各种屏幕尺寸
- **浏览器兼容**: 支持多种浏览器和低版本

### 🔒 安全与权限
- **页面级权限**: 路由守卫控制页面访问
- **按钮级权限**: 细粒度的操作权限控制
- **微信认证**: 支持微信和企业微信登录
- **防御水印**: 防止敏感信息泄露

### 🧩 业务功能
- **商品管理**: 商品列表、详情展示
- **订单系统**: 订单创建、结算、详情查看
- **柜机管理**: 智能柜机绑定和管理
- **审批流程**: 审批申请、处理、核销
- **用户中心**: 个人信息、余额管理

## 目录结构

```
src/
├── common/           # 通用模块
│   ├── apis/        # API 接口
│   ├── assets/      # 静态资源
│   ├── composables/ # 组合式函数
│   ├── components/  # 通用组件
│   └── utils/       # 工具函数
├── layout/          # 布局组件
├── pages/           # 页面组件
├── pinia/           # 状态管理
├── router/          # 路由配置
├── http/            # HTTP 请求
└── plugins/         # 插件配置
```

## 快速开始

### 环境要求
- Node.js 20.x 或 22+
- pnpm 9.x 或 10+
- 最新版 Visual Studio Code

### 安装依赖
```bash
pnpm i
```

### 开发环境
```bash
pnpm dev
```

### 构建项目
```bash
# 预发布环境
pnpm build:staging

# 生产环境
pnpm build
```

### 代码检查
```bash
# 代码校验与格式化
pnpm lint

# 单元测试
pnpm test
```

## 核心模块说明

### 1. 路由系统 (src/router/)
- **一级路由设计**: 清晰且缓存友好
- **权限守卫**: 页面访问权限控制
- **布局配置**: 可配置的导航栏和标签栏

### 2. 状态管理 (src/pinia/)
- **用户状态**: 用户信息、登录状态
- **微信状态**: 微信认证相关状态
- **购物车**: 商品选择和结算
- **订单状态**: 订单处理流程

### 3. API 管理 (src/common/apis/)
- **用户接口**: 登录、用户信息
- **商品接口**: 商品列表、详情
- **订单接口**: 订单创建、查询
- **柜机接口**: 柜机管理
- **审批接口**: 审批流程

### 4. 布局系统 (src/layout/)
- **导航栏**: 自定义标题和返回按钮
- **标签栏**: 底部导航切换
- **响应式**: 适配不同页面需求

## 开发指南

### 添加新页面
1. 在 `src/pages/` 下创建 Vue 组件
2. 在 `src/router/index.ts` 中添加路由配置
3. 配置页面元信息 (meta)

### 状态管理
使用 Pinia 进行状态管理，遵循组合式 API 规范：

```typescript
export const useMyStore = defineStore("myStore", () => {
  const state = ref<StateType>(initialValue)

  const action = () => {
    // 业务逻辑
  }

  return { state, action }
})
```

### API 开发
API 接口统一在 `src/common/apis/` 目录下管理：

```typescript
export const getDataApi = (params: ParamsType) => {
  return request<ResponseType>({
    url: "/api/data",
    method: "GET",
    params
  })
}
```

### 样式规范
- 使用 UnoCSS 原子化类名
- 优先使用预设的快捷方式
- 自定义样式在 CSS 变量中定义

## 部署说明

### 环境变量
项目支持多环境配置，通过 `.env` 文件管理：

```env
VITE_BASE_URL=接口基础地址
VITE_PUBLIC_PATH=公共路径
VITE_ROUTER_HISTORY=路由模式
```

### 构建优化
- 代码分割：Vue 相关库独立打包
- 压缩优化：移除 console 和 debugger
- 浏览器兼容：传统浏览器支持

## 常见问题

### 微信认证问题
- 确保微信回调地址配置正确
- 检查企业微信 corpid 配置
- 验证 openid 获取逻辑

### 权限控制
- 页面权限在路由守卫中控制
- 按钮权限使用自定义指令
- 角色权限在用户信息中配置

### 移动端适配
- 使用 vw 单位进行响应式设计
- 测试不同屏幕尺寸的显示效果
- 确保触摸交互的流畅性

## 贡献指南

### 代码提交规范
- `feat`: 新功能
- `fix`: 修复错误
- `perf`: 性能优化
- `refactor`: 重构代码
- `docs`: 文档和注释
- `test`: 单元测试相关

### 开发流程
1. Fork 项目
2. 创建功能分支
3. 提交代码变更
4. 创建 Pull Request

## 许可证

[MIT License](./LICENSE) © 2025-PRESENT [pany](https://github.com/pany-ang)