# ZYUAS Neo - 企业官网重构项目

> 使用 Vue 3 + TypeScript + Element Plus + Vite + SCSS 构建的企业官方网站

**版本：** v1.1.0  
**构建状态：** ✅ 成功  
**类型检查：** ✅ 通过  
**最后更新：** 2026-02-26

---

## 📋 目录

1. [项目简介](#-项目简介)
2. [技术栈](#-技术栈)
3. [快速开始](#-快速开始)
4. [项目结构](#-项目结构)
5. [已完成功能](#-已完成功能)
6. [TypeScript 类型系统](#-typescript-类型系统)
7. [设计系统](#-设计系统)
8. [SCSS 样式系统](#-scss-样式系统)
9. [响应式布局](#-响应式布局)
10. [图标使用指南](#-图标使用指南)
11. [开发规范](#-开发规范)
12. [构建与部署](#-构建与部署)
13. [常见问题](#-常见问题)

---

## 📦 项目简介

使用 **Vue 3 + TypeScript + Element Plus + Vite + SCSS** 构建的企业官方网站，替代原有的 Vue 2 + Bootstrap 版本。

### 技术升级对比

| 组件 | 原版本 | 新版本 | 改进 |
|------|--------|--------|------|
| 框架 | Vue 2.7.16 | Vue 3.5.25 | Composition API + TypeScript |
| 构建工具 | Webpack 4 | Vite 7 | 10x 更快构建 |
| UI 框架 | Bootstrap 3 | Element Plus 2.13 | 现代化组件库 |
| 路由 | Vue Router 3 | Vue Router 4 | 完整 TS 支持 |
| 状态管理 | Vuex 3 | Pinia 3 | 更简洁的 API |
| 轮播 | Swiper 4 | Swiper 12 | 最新特性 |
| 样式 | CSS | SCSS | 变量 + 混入系统 |
| 类型系统 | - | TypeScript 5.9 | 编译时类型检查 |

---

## 🛠️ 技术栈

| 技术 | 版本 | 说明 |
|------|------|------|
| Vue | 3.5.25 | Composition API + `<script setup lang="ts">` |
| TypeScript | 5.9.3 | 完整类型系统支持 |
| Element Plus | 2.13.2 | UI 组件库 |
| Vite | 7.3.1 | 下一代构建工具 |
| Vue Router | 4.6.4 | 路由管理 |
| Pinia | 3.0.4 | 状态管理 |
| Swiper | 12.1.2 | 轮播组件 |
| SCSS | latest | CSS 预处理器 |
| Animate.css | latest | 动画库 |

---

## 🚀 快速开始

```bash
# 进入项目目录
cd zyuas-neo

# 安装依赖
npm install

# 开发模式
npm run dev
# 访问 http://localhost:5173

# 类型检查
npm run type-check

# 生产构建（含类型检查）
npm run build

# 跳过类型检查构建
npm run build:skip-typecheck

# 预览构建结果
npm run preview
```

### 构建状态

✅ **构建成功** - 生产构建已通过 (`npm run build`)  
✅ **类型检查通过** - TypeScript 编译无错误 (`npm run type-check`)

```bash
✓ 1563 modules transformed.
✓ built in 4.12s

dist/
├── index.html
└── static/
    ├── *.css
    ├── *.js
    └── assets/
```

---

## 📁 项目结构

```
zyuas-neo/
├── src/
│   ├── assets/
│   │   ├── styles/
│   │   │   ├── variables.scss    # SCSS 变量
│   │   │   ├── mixins.scss       # SCSS 混入
│   │   │   ├── components.scss   # 可复用组件
│   │   │   └── global.scss       # 全局样式
│   │   └── images/               # 图片资源 (65+ 文件)
│   ├── types/
│   │   ├── vite-env.d.ts         # Vite 环境类型
│   │   ├── nav.ts                # 导航类型定义
│   │   └── home.ts               # 首页类型定义
│   ├── components/
│   │   ├── Header.vue.ts         # 头部导航 (TypeScript)
│   │   ├── Footer.vue.ts         # 页脚 (TypeScript)
│   │   └── GoTop.vue.ts          # 回到顶部 (TypeScript)
│   ├── config/
│   │   └── nav-config.ts         # 导航配置 (TypeScript)
│   ├── router/
│   │   └── index.ts              # 路由配置 (TypeScript)
│   ├── views/
│   │   ├── HomePage.vue.ts       # 首页 (TypeScript)
│   │   ├── Products/             # 产品页面 (5 个，TypeScript)
│   │   ├── Solutions/            # 解决方案页面 (5 个，TypeScript)
│   │   ├── AIDevelopment/        # AI 开发页面 (3 个，TypeScript)
│   │   ├── News/                 # 新闻页面 (TypeScript)
│   │   ├── Info/                 # 公司信息 (TypeScript)
│   │   └── ContactUs/            # 联系我们 (TypeScript)
│   ├── App.vue.ts                # 根组件 (TypeScript)
│   └── main.ts                   # 入口文件 (TypeScript)
├── index.html
├── package.json
├── tsconfig.json                 # TypeScript 配置
├── tsconfig.node.json            # Node 环境配置
├── vite.config.ts                # Vite 配置
└── README.md
```

---

## ✅ 已完成功能

### 核心页面 (22 个)

| 类别 | 页面 | 文件数 | 状态 |
|------|------|--------|------|
| 首页 | HomePage | 1 | ✅ |
| 产品与服务 | Products | 5 | ✅ |
| 解决方案 | Solutions | 5 | ✅ |
| AI 开发 | AIDevelopment | 3 | ✅ |
| 其他 | News/Info/ContactUs | 3 | ✅ |
| 公共组件 | Header/Footer/GoTop | 3 | ✅ |

### 技术特性

- [x] TypeScript 完整类型支持
- [x] SCSS 样式系统（变量 + 混入 + 可复用组件）
- [x] 响应式布局（移动端/平板/桌面）
- [x] Element Plus 组件集成
- [x] Swiper 12 轮播
- [x] 路由懒加载
- [x] 页面过渡动画
- [x] 全局图标注册
- [x] 编译时类型检查

---

## 🔷 TypeScript 类型系统

### 类型配置文件

```json
// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "strict": true,
    "jsx": "preserve",
    "moduleResolution": "bundler",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}
```

### 类型定义文件

#### `src/types/nav.ts` - 导航类型

```typescript
export interface NavItem {
  name: string
  path: string
  children: NavChildItem[]
}

export interface NavChildItem {
  name: string
  path: string
}

export interface NavAction {
  name: string
  path: string
  type: 'primary' | 'secondary'
}
```

#### `src/types/home.ts` - 首页类型

```typescript
export interface SwiperSlide {
  img: string
  title: string
  content: string
}

export interface SolutionItem {
  path: string
  title: string
  description: string
  image: string
}
```

### 在组件中使用类型

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { SolutionItem } from '@/types/home'

const solutionsList = ref<SolutionItem[]>([
  {
    path: '/solutions/surveying',
    title: '基础测绘',
    description: '快速进行大范围二维、三维建模',
    image: '...'
  }
])
</script>
```

### 可用命令

| 命令 | 说明 |
|------|------|
| `npm run type-check` | 仅类型检查 |
| `npm run build` | 生产构建（含类型检查） |
| `npm run build:skip-typecheck` | 跳过类型检查构建 |

---

## 🎨 设计系统

### 主题色

```scss
$primary-color: #1e73be;      // 主色（蓝色）
$primary-light: #3b82f6;      // 亮蓝
$primary-dark: #185a9d;       // 深蓝
$primary-gradient: linear-gradient(135deg, #1e73be, #3b82f6);
```

### 中性色

```scss
$text-primary: #1a1a1a;       // 主文本
$text-regular: #555555;       // 常规文本
$text-tertiary: #666666;      // 次要文本
$text-muted: #999999;         // 弱化文本
```

### 间距系统

```scss
$spacer-1: 10px;
$spacer-2: 20px;
$spacer-3: 30px;
$spacer-4: 40px;
$spacer-5: 50px;
$spacer-6: 60px;
```

### 圆角与阴影

```scss
// 圆角
$radius-sm: 8px;
$radius-md: 12px;
$radius-lg: 16px;
$radius-xl: 20px;

// 阴影
$shadow-sm: 0 2px 8px rgba(0, 0, 0, 0.08);
$shadow-md: 0 8px 32px rgba(0, 0, 0, 0.12);
$shadow-lg: 0 20px 60px rgba(0, 0, 0, 0.15);
```

---

## 📐 SCSS 样式系统

### 变量文件 (`variables.scss`)

```scss
// 主题色
$primary-color: #1e73be;
$primary-light: #3b82f6;

// 中性色
$text-primary: #1a1a1a;
$text-regular: #555555;

// 间距
$spacer-1: 10px;
$spacer-2: 20px;

// 断点
$breakpoint-sm: 576px;
$breakpoint-md: 768px;
$breakpoint-lg: 992px;
$breakpoint-xl: 1200px;
```

### 混入文件 (`mixins.scss`)

```scss
// 响应式
@mixin mobile { @media (max-width: 767px) { @content; } }
@mixin tablet { @media (min-width: 768px) and (max-width: 991px) { @content; } }
@mixin desktop { @media (min-width: 992px) { @content; } }

// Flexbox
@mixin flex-center { display: flex; align-items: center; justify-content: center; }
@mixin flex-between { display: flex; align-items: center; justify-content: space-between; }

// 玻璃拟态
@mixin glass-morphism {
  background: rgba(255, 255, 255, 0.8);
  border: 1px solid rgba(255, 255, 255, 0.5);
  backdrop-filter: blur(10px);
}
```

### 在 Vue 文件中使用

```vue
<template>
  <div class="page">
    <div class="page-banner">
      <h1>标题</h1>
    </div>
  </div>
</template>

<script setup lang="ts">
// TypeScript 代码
</script>

<style lang="scss">
@import '@/assets/styles/variables';
@import '@/assets/styles/mixins';

.page {
  padding: $spacer-3;

  @include mobile {
    padding: $spacer-2;
  }
}
</style>
```

---

## 📱 响应式布局

### 容器边距系统

| 断点 | 屏幕宽度 | 容器边距 | 说明 |
|------|----------|----------|------|
| 桌面端 | > 1200px | 20px | 标准边距 |
| 平板端 | 768px - 1200px | 30px | 增加边距 |
| 移动端 | < 768px | 20px | 标准边距 |

### 响应式字体

| 元素 | 桌面端 | 平板端 | 移动端 |
|------|--------|--------|--------|
| 根字体 | 16px | 16px | 14px |
| 章节标题 | 36px | 28px | 24px |
| 大标题 | 42px | 32px | 28px |

### 断点混入

```scss
// 移动端 (< 768px)
@include mobile {
  .element {
    // 移动端样式
  }
}

// 平板端 (768px - 991px)
@include tablet {
  .element {
    // 平板端样式
  }
}

// 桌面端 (>= 992px)
@include desktop {
  .element {
    // 桌面端样式
  }
}
```

---

## 🔣 图标使用指南

### 已用图标清单

#### 导航组件
| 图标 | 用途 |
|------|------|
| `ArrowDown`, `ArrowRight` | 下拉菜单、按钮 |
| `Menu`, `Close` | 移动端导航 |
| `ArrowUp` | 回到顶部 |

#### 首页
| 图标 | 用途 |
|------|------|
| `ArrowLeft`, `ArrowRight` | 轮播图导航 |
| `Connection` | 解决方案链接 |
| `Star`, `Monitor`, `Picture`, `DataAnalysis` | 技术优势 |
| `Service`, `Timer`, `Medal` | 服务优势 |

### 图标使用方式

```vue
<script setup lang="ts">
import { ArrowRight, Star } from '@element-plus/icons-vue'
</script>

<template>
  <el-icon><ArrowRight /></el-icon>
</template>
```

### 类型声明

所有 Element Plus 图标已在 `src/types/vite-env.d.ts` 中声明：

```typescript
declare module '@element-plus/icons-vue' {
  export const ArrowDown: any
  export const ArrowRight: any
  export const CircleCheckFilled: any
  // ... 更多图标
}
```

---

## 📝 开发规范

### 组件命名

- 使用 PascalCase（大驼峰）
- 页面组件首字母大写
- 公共组件首字母大写

### TypeScript 代码风格

- 使用 `<script setup lang="ts">` 语法
- 为所有 `ref`/`reactive` 添加类型注解
- 为函数参数和返回值添加类型注解
- 使用 `interface` 定义对象类型

```typescript
// ✅ 推荐
interface User {
  name: string
  age: number
}

const user = ref<User>({
  name: 'John',
  age: 30
})

const greet = (name: string): string => {
  return `Hello, ${name}`
}
```

### 样式规范

```vue
<style lang="scss">
// 1. 先导入变量和混入
@import '@/assets/styles/variables';
@import '@/assets/styles/mixins';

// 2. 使用 SCSS 变量
.my-component {
  color: $text-primary;
  padding: $spacer-3;

  // 3. 使用混入
  @include mobile {
    padding: $spacer-2;
  }
}
</style>
```

### 文件组织

```
src/
├── types/              # TypeScript 类型定义
├── assets/
│   ├── styles/         # 全局样式
│   └── images/         # 图片资源
├── components/         # 公共组件
├── views/             # 页面组件
├── router/            # 路由配置
└── config/            # 配置文件
```

---

## 🏗️ 构建与部署

### 开发环境

```bash
npm run dev
# 访问 http://localhost:5173
```

### 生产构建

```bash
# 含类型检查（推荐）
npm run build

# 跳过类型检查
npm run build:skip-typecheck
```

### 构建输出

```bash
✓ 1563 modules transformed.
✓ built in 4.12s

dist/
├── index.html              0.96 kB
└── static/
    ├── element-plus-*.js   # Element Plus (1MB+)
    ├── vue-vendor-*.js     # Vue 相关 (100KB+)
    ├── swiper-*.js         # Swiper (69KB)
    └── *.css, *.js         # 其他资源
```

### 推荐部署平台

- Vercel
- Netlify
- GitHub Pages
- 阿里云 OSS
- 腾讯云 COS
- Nginx 服务器

---

## ❓ 常见问题

### TypeScript 类型错误

**问题：** 编译时报 `Property 'xxx' does not exist on type` 错误

**解决：** 为对象添加正确的类型注解或使用 `interface` 定义

```typescript
// ❌ 错误
const data = ref({})
data.value.name = 'test'

// ✅ 正确
interface Data {
  name: string
}
const data = ref<Data>({ name: '' })
```

### 图标类型未找到

**问题：** `Module has no exported member 'Xxx'`

**解决：** 在 `src/types/vite-env.d.ts` 中添加图标声明

```typescript
declare module '@element-plus/icons-vue' {
  export const Xxx: any
}
```

### 构建产物过大

**问题：** 构建后文件过大

**解决：**
1. 使用路由懒加载（已实现）
2. 压缩图片资源
3. 使用 CDN 加载 Element Plus

---

## 📊 项目统计

| 类型 | 数量 |
|------|------|
| Vue 组件 (TypeScript) | 22 |
| TypeScript 配置文件 | 3 |
| 类型定义文件 | 4 |
| SCSS 文件 | 4 |
| 图片资源 | 65+ |
| 路由 | 17 |
| 总代码行数 | ~5500+ |
| 构建时间 | ~4.1s |

---

## 🌐 浏览器支持

- Chrome >= 90
- Firefox >= 88
- Safari >= 14
- Edge >= 90

---

## 📄 许可证

MIT

---

**上海展域航空技术有限公司** © 2025