204 lines
4.9 KiB
Markdown
204 lines
4.9 KiB
Markdown
# 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) |