zcglxt/QUICKSTART.md

# 资产管理系统前端 - 快速开始

## 环境要求

- Node.js >= 18.0.0
- npm >= 9.0.0 (或 pnpm/yarn)

## 快速启动

### 1. 安装依赖

```bash
npm install
```

### 2. 配置环境变量

复制 `.env.development` 文件并修改 API 地址:

```bash
cp .env.development .env.local
```

### 3. 启动开发服务器

```bash
npm run dev
```

访问 `http://localhost:3000`

### 4. 默认账号

开发环境可以使用以下测试账号:

- 用户名: `admin`
- 密码: `Admin123`

## 开发命令

```bash
# 启动开发服务器
npm run dev

# 构建生产版本
npm run build

# 预览生产构建
npm run preview

# 代码检查
npm run lint

# 代码格式化
npm run format

# 运行测试
npm run test
```

## 项目结构

```
src/
├── api/                    # API 接口
├── assets/                 # 静态资源
│   └── styles/             # 全局样式
├── components/             # 通用组件
├── composables/            # 组合式函数
├── layouts/                # 布局组件
├── router/                 # 路由配置
├── stores/                 # Pinia 状态管理
├── types/                  # TypeScript 类型定义
├── utils/                  # 工具函数
├── views/                  # 页面组件
├── App.vue                 # 根组件
└── main.ts                 # 应用入口
```

## 开发指南

### 创建新页面

1. 在 `src/views/` 下创建页面组件:

```vue
<template>
  <div class="page-name">
    <el-card>
      <!-- 页面内容 -->
    </el-card>
  </div>
</template>

<script setup lang="ts">
// 页面逻辑
</script>

<style scoped lang="scss">
.page-name {
  // 页面样式
}
</style>
```

2. 在 `src/router/index.ts` 添加路由:

```typescript
{
  path: '/page-name',
  name: 'PageName',
  component: () => import('@/views/PageName.vue'),
  meta: {
    title: '页面标题',
    icon: 'IconName'
  }
}
```

### 创建 API 接口

在 `src/api/` 下创建对应的 API 文件:

```typescript
import { request } from './request'

export const getSomething = (params: any) => {
  return request.get('/something', { params })
}

export const createSomething = (data: any) => {
  return request.post('/something', data)
}
```

### 创建状态管理

在 `src/stores/modules/` 下创建 store:

```typescript
import { defineStore } from 'pinia'
import { ref } from 'vue'

export const useSomethingStore = defineStore('something', () => {
  const data = ref(null)

  const fetchData = async () => {
    // 获取数据逻辑
  }

  return {
    data,
    fetchData
  }
})
```

### 创建组合式函数

在 `src/composables/` 下创建 composable:

```typescript
import { ref } from 'vue'

export function useSomething() {
  const loading = ref(false)
  const data = ref([])

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

  return {
    loading,
    data,
    doSomething
  }
}
```

## 代码规范

### 命名规范

- 组件文件: 大驼峰 - `AssetList.vue`
- 组件注册: 大驼峰 - `<AssetList />`
- 变量/函数: 小驼峰 - `assetList`
- 常量: 大写下划线 - `API_BASE_URL`
- 类型/接口: 大驼峰 - `AssetList`

### 组件开发

使用 `<script setup>` 语法:

```vue
<script setup lang="ts">
import { ref, computed } from 'vue'

// Props
interface Props {
  title: string
}
const props = defineProps<Props>()

// Emits
interface Emits {
  (e: 'update', value: string): void
}
const emit = defineEmits<Emits>()

// 响应式数据
const count = ref(0)

// 计算属性
const doubleCount = computed(() => count.value * 2)

// 方法
const increment = () => {
  count.value++
}
</script>
```

### 类型定义

所有 API 响应和组件 Props 都需要类型定义:

```typescript
interface User {
  id: number
  username: string
  email: string
}

interface ApiResponse<T> {
  code: number
  message: string
  data: T
}
```

## 样式指南

### 使用 SCSS 变量

```scss
<style scoped lang="scss">
.page-name {
  padding: 20px;
  background: $bg-color;

  .content {
    color: $text-primary;
  }
}
</style>
```

### 响应式设计

使用 Element Plus 的栅格系统:

```vue
<el-row :gutter="20">
  <el-col :xs="24" :sm="12" :md="8" :lg="6">
    <!-- 内容 -->
  </el-col>
</el-row>
```

## 常见问题

### Q: 为什么组件无法自动导入?

A: 检查 `vite.config.ts` 中的 `unplugin-auto-import` 和 `unplugin-vue-components` 配置。

### Q: 如何调试 API 请求?

A: 在浏览器开发者工具的 Network 标签中查看请求详情，或使用 console.log 打印响应数据。

### Q: 样式不生效怎么办?

A: 检查是否使用了 `scoped`，是否正确引入了全局样式文件。

### Q: TypeScript 类型错误?

A: 运行 `npm run lint` 检查类型错误，确保所有类型定义正确。

## 相关文档

- [Vue 3 文档](https://vuejs.org/)
- [Element Plus 文档](https://element-plus.org/)
- [Vite 文档](https://vitejs.dev/)
- [Pinia 文档](https://pinia.vuejs.org/)
- [开发规范指南](./development_standards_guide.md)
- [API 接口文档](./complete_api_reference.md)
- [页面原型文档](./frontend_page_prototypes.md)

## 获取帮助

如有问题,请联系开发团队或查阅相关文档。

---

**祝开发愉快! 🎉**