# 4.map-frontend

**Repository Path**: ooyyh/4.map-frontend

## Basic Information

- **Project Name**: 4.map-frontend
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-02
- **Last Updated**: 2025-12-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Custom Template

一个基于 Vue 3 + TypeScript + Vite 的现代化前端项目模板

## ✨ 特性

- 🚀 **Vue 3** - 使用最新的 Vue 3 Composition API
- 📦 **TypeScript** - 完整的 TypeScript 支持
- 🎨 **Tailwind CSS** - 原子化 CSS 框架
- 🗂️ **Vue Router** - 官方路由管理
- 📊 **Pinia** - 现代化状态管理，支持持久化
- 🔄 **Axios** - HTTP 请求库，封装了请求拦截和响应处理
- 🛠️ **Vite** - 快速的构建工具
- 🎯 **组件化** - 完整的组件系统架构

## 📁 项目结构

```
src/
├── api/                 # API 接口
│   ├── index.ts        # API 统一导出
│   └── request.ts      # Axios 请求封装
├── assets/             # 静态资源
├── components/         # 公共组件
│   └── system/        # 系统级组件
│       └── Loading/   # Loading 组件
├── router/             # 路由配置
│   ├── index.ts       # 路由实例
│   └── routes.ts      # 路由定义
├── stores/             # Pinia 状态管理
│   └── index.ts       # Store 配置
├── styles/             # 样式文件
│   └── global.scss    # 全局样式
├── types/              # TypeScript 类型定义
├── views/              # 页面组件
├── App.vue            # 根组件
├── main.ts            # 应用入口
└── style.css          # 基础样式
```

## 🚀 快速开始

### 环境要求

- Node.js >= 16
- pnpm (推荐) 或 npm

### 安装依赖

```bash
# 使用 pnpm (推荐)
pnpm install

# 或使用 npm
npm install
```

### 开发

```bash
# 启动开发服务器
pnpm dev

# 或
npm run dev
```

### 构建

```bash
# 构建生产版本
pnpm build

# 或
npm run build
```

### 预览

```bash
# 预览构建结果
pnpm preview

# 或
npm run preview
```

## ⚙️ 配置

### 环境变量

在项目根目录创建 `.env` 文件：

```env
# API 基础地址
VITE_DEFAULT_REQUEST_URL=https://api.example.com

# 请求超时时间 (毫秒)
VITE_DEFAULT_REQUEST_TIMEOUT=5000
```

### 路径别名

项目已配置以下路径别名：

- `@` -> `src/`
- `@components` -> `src/components/`
- `@utils` -> `src/utils/`
- `@assets` -> `src/assets/`

## 📦 主要依赖

### 核心依赖

- **vue**: ^3.5.22 - Vue 3 框架
- **vue-router**: ^4.6.3 - 路由管理
- **pinia**: ^3.0.4 - 状态管理
- **pinia-plugin-persistedstate**: ^4.7.1 - Pinia 持久化插件
- **axios**: ^1.13.1 - HTTP 请求库
- **tailwindcss**: ^4.1.16 - CSS 框架

### 开发依赖

- **vite**: npm:rolldown-vite@7.1.14 - 构建工具
- **@vitejs/plugin-vue**: ^6.0.1 - Vite Vue 插件
- **typescript**: ~5.9.3 - TypeScript 支持
- **vue-tsc**: ^3.1.0 - Vue TypeScript 编译器
- **@tailwindcss/vite**: ^4.1.16 - Tailwind CSS Vite 插件

## 🛠️ 开发指南

### API 请求

项目已封装 Axios 请求，支持：

- 自动 loading 管理
- 请求/响应拦截
- 统一错误处理
- JWT Token 自动携带

```typescript
import request from '@/api/request';

// GET 请求
request({
  url: '/api/users',
  method: 'get',
  params: { page: 1 },
});

// POST 请求
request({
  url: '/api/users',
  method: 'post',
  data: { name: 'John' },
});
```

### 状态管理

使用 Pinia 进行状态管理，已配置持久化：

1. 安装命令

```bash
pnpm add pinia pinia-plugin-persistedstate
```

2. 创建 `src/stores/index.ts`:

```typescript
import { createPinia } from 'pinia';
import piniaPluginPersistedstate from 'pinia-plugin-persistedstate';

const pinia = createPinia();
pinia.use(piniaPluginPersistedstate);

export default pinia;

// 示例store
export const useCounterStore = defineStore('counter', {
  state: () => ({
    count: 0,
  }),
  persist: true, // 启用持久化
});
```

3. 在 `main.ts` 中引入：

```typescript
import pinia from './stores';

createApp(App).use(router).use(pinia).mount('#app');
```

4. 在组件中使用：

```typescript
import { useCounterStore } from '@/stores/index';

const counterStore = useCounterStore();

// 解构状态并保持响应式（仅解构 state，actions 直接从 store 调用）
const { count } = storeToRefs(counterStore);

// 调用 actions 依然通过 store 实例
const increment = () => {
  counterStore.increment();
};
```

### 组件开发

组件放置在 `src/components/` 目录下，按功能模块组织：

```
components/
├── common/      # 通用组件
├── business/    # 业务组件
└── system/      # 系统组件
```

## 🎨 样式规范

项目使用 Tailwind CSS，同时支持 SCSS：

- 全局样式：`src/styles/global.scss`
- 组件样式：推荐使用 Tailwind CSS 类名
- 特殊样式：可在组件中使用 scoped CSS

## 📋 Git 提交规范

> 参考文档：https://www.itcan.cn/2025/03/27/git-commit-rule/

为了保持代码提交历史的一致性和可读性，项目采用以下 Git 提交规范：

### 提交格式

提交信息格式：`<type>(<scope>): <subject>`

### Type 类型

- `feat`: 新功能 (feature)
- `fix`: 修复 bug
- `docs`: 文档变更
- `style`: 代码格式化，不影响代码逻辑
- `refactor`: 重构代码，既不是新增功能也不是修复 bug
- `perf`: 性能优化
- `test`: 增加测试或修改测试
- `chore`: 构建过程或辅助工具的变动
- `ci`: CI/CD 配置文件和脚本的变动
- `revert`: 回滚之前的提交

### Scope 范围

scope 用于说明本次提交影响的范围，可以是：

- `components`: 组件相关
- `views`: 页面相关
- `api`: API 接口相关
- `router`: 路由相关
- `stores`: 状态管理相关
- `utils`: 工具函数相关
- `styles`: 样式相关
- `config`: 配置文件相关
- `build`: 构建相关

### Subject 主题

subject 是对本次提交的简短描述，要求：

- 使用动词开头，如：添加、修改、删除、修复等
- 首字母小写
- 结尾不加句号
- 不超过 50 个字符

### 示例

```bash
# 新功能
git commit -m "feat(components): 添加 Loading 组件"
git commit -m "feat(api): 新增用户登录接口"

# 修复 bug
git commit -m "fix(router): 修复路由跳转异常问题"
git commit -m "fix(styles): 修复移动端样式错乱"

# 文档更新
git commit -m "docs(readme): 更新安装说明文档"

# 代码重构
git commit -m "refactor(stores): 重构用户状态管理逻辑"

# 性能优化
git commit -m "perf(utils): 优化数据过滤函数性能"

# 样式调整
git commit -m "style(components): 统一按钮组件样式格式"

# 测试相关
git commit -m "test(api): 添加 API 接口单元测试"

# 构建配置
git commit -m "chore(deps): 更新 Vue 依赖版本"
```

### 提交信息详细说明（可选）

如果需要更详细的说明，可以在 subject 后空一行添加 body：

```bash
git commit -m "feat(api): 新增用户认证接口

- 添加用户登录接口
- 添加 token 刷新机制
- 实现请求拦截器自动携带 token
- 添加 401 未授权自动跳转登录页"
```

### 分支命名规范

- `feature/功能名称` - 新功能开发
- `bugfix/问题描述` - bug 修复
- `hotfix/紧急修复` - 生产环境紧急修复
- `refactor/重构内容` - 代码重构
- `docs/文档更新` - 文档更新

### 提交前检查

提交代码前请确保：

1. 代码已通过 ESLint 检查
2. 所有测试用例通过
3. 提交信息符合规范
4. 不包含调试代码和 console.log

## 🔧 自定义配置

### Vite 配置

主要配置在 `vite.config.ts`：

- 路径别名
- 插件配置
- 构建优化

### TypeScript 配置

- `tsconfig.json` - 基础配置
- `tsconfig.app.json` - 应用配置
- `tsconfig.node.json` - Node.js 环境

## 📝 License

MIT License

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

---

**Happy Coding! 🎉**