stand_acs/acs2/nladmin-ui/FE_DEVELOPMENT_GUIDE.md

# 前端开发手册

## 1. 项目概述

### 1.1 项目简介
本项目是 **EL-ADMIN** 前端管理系统，基于 Vue 2.x 技术栈构建，是一个功能完善的企业级后台管理系统。

### 1.2 技术栈

| 技术 | 版本 | 说明 |
|------|------|------|
| Vue | 2.6.10 | 前端框架 |
| Vue Router | 3.0.2 | 路由管理 |
| Vuex | 3.1.0 | 状态管理 |
| Element UI | 2.15.8 | UI组件库 |
| Axios | 0.18.1 | HTTP客户端 |
| ECharts | 4.2.1 | 图表库 |
| LogicFlow | 1.2.1 | 流程图编辑器 |

### 1.3 主要功能模块

- **系统管理**：用户管理、角色管理、菜单管理、部门管理、数据字典等
- **ACS管理**：设备管理、任务管理、区域管理、路线规划等
- **布局管理**：地图管理、设备布局等
- **监控管理**：日志监控、在线监控、大屏展示等
- **轨迹管理**：轨迹配置、轨迹后台管理

---

## 2. 开发环境配置

### 2.1 环境要求

| 工具 | 最低版本 | 推荐版本 |
|------|----------|----------|
| Node.js | >= 8.9 | >= 14.x |
| npm | >= 3.0.0 | >= 6.x |

### 2.2 安装依赖

```bash
# 进入项目目录
cd d:\诺力git\stand_acs\acs2\nladmin-ui

# 安装依赖
npm install
```

### 2.3 开发命令

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

# 生产环境构建
npm run build:prod

# 测试环境构建
npm run build:stage

# ESLint代码检查
npm run lint

# 单元测试
npm run test:unit

# 生成新页面（模板）
npm run new
```

---

## 3. 项目结构

```
src/
├── api/                 # API接口定义
│   ├── acs/             # ACS模块接口
│   ├── layout/          # 布局模块接口
│   ├── system/          # 系统模块接口
│   ├── monitor/         # 监控模块接口
│   └── ...
├── assets/              # 静态资源
│   ├── icons/           # SVG图标
│   ├── images/          # 图片资源
│   ├── styles/          # 全局样式
│   └── js/              # 第三方JS库
├── components/          # 公共组件
│   ├── Crud/            # CRUD组件
│   ├── Dict/            # 数据字典组件
│   ├── Permission/      # 权限组件
│   └── IconSelect/      # 图标选择组件
├── layout/              # 布局组件
│   ├── components/      # 布局子组件
│   └── mixin/           # 布局混入
├── router/              # 路由配置
│   ├── index.js         # 路由权限控制
│   └── routers.js       # 路由定义
├── store/               # Vuex状态管理
│   ├── modules/         # 状态模块
│   ├── getters.js       # 计算属性
│   └── index.js         # 状态入口
├── utils/               # 工具函数
│   ├── request.js       # Axios封装
│   ├── auth.js          # 认证工具
│   └── nladmin.js       # 通用工具
├── views/               # 页面视图
│   ├── system/          # 系统管理页面
│   ├── acs/             # ACS管理页面
│   ├── monitor/         # 监控页面
│   └── dashboard/       # 仪表盘
├── i18n/                # 国际化配置
├── App.vue              # 根组件
├── main.js              # 入口文件
└── settings.js          # 系统配置
```

---

## 4. 核心模块说明

### 4.1 入口文件 (main.js)

**职责**：项目初始化、全局配置、第三方库注册

**关键配置**：
- Element UI 全局配置（默认尺寸、表格边框等）
- 全局方法挂载（parseTime、resetForm、selectDictLabel等）
- 国际化配置

### 4.2 路由管理

#### 4.2.1 路由定义 (router/routers.js)

路由采用异步路由加载方式，支持动态菜单加载：

```javascript
{
  path: '/system/user',
  component: Layout,
  redirect: '/system/user/index',
  name: 'User',
  meta: { title: 'user', icon: 'user', roles: ['admin', 'user'] },
  children: [
    {
      path: 'index',
      component: () => import('@/views/system/user/index'),
      name: 'UserIndex',
      meta: { title: 'userList', icon: 'user', roles: ['admin', 'user'] }
    }
  ]
}
```

#### 4.2.2 权限控制 (router/index.js)

实现了完整的路由守卫机制：
- 登录状态检查
- 动态菜单加载
- 权限验证

### 4.3 HTTP请求封装 (utils/request.js)

**核心特性**：
- 请求拦截器：自动添加Token、语言标识
- 响应拦截器：统一错误处理、401/403状态码处理
- 支持blob下载错误处理

```javascript
// 请求拦截器
service.interceptors.request.use(
  config => {
    if (getToken()) {
      config.headers['Authorization'] = 'Bearer ' + getToken()
    }
    config.headers['Accept-Language'] = localStorage.getItem('lang')
    return config
  }
)
```

### 4.4 状态管理 (store/)

| 模块 | 职责 |
|------|------|
| app.js | 应用基础状态（侧边栏、设备信息等） |
| permission.js | 权限路由状态 |
| settings.js | 系统设置（主题、布局等） |
| tagsView.js | 标签页状态 |
| user.js | 用户信息状态 |

---

## 5. 开发规范

### 5.1 代码规范

#### 5.1.1 ESLint规则

项目使用 `eslint-plugin-vue` 进行代码检查，配置文件：`.eslintrc.js`

**核心规则**：
- 使用 4 空格缩进
- 语句结尾必须有分号
- 单引号优先
- 禁止未使用的变量
- Vue组件必须有name属性

#### 5.1.2 Git钩子

通过 `husky` 和 `lint-staged` 实现提交前代码检查：

```javascript
"husky": {
  "hooks": {
    "pre-commit": "lint-staged"
  }
},
"lint-staged": {
  "src/**/*.{js,vue}": [
    "eslint --fix",
    "git add"
  ]
}
```

### 5.2 组件开发规范

#### 5.2.1 组件命名

- **组件名**：大驼峰命名（PascalCase），如 `UserList.vue`
- **组件文件**：放在对应模块目录下

#### 5.2.2 组件结构

```vue
<template>
  <!-- 模板内容 -->
</template>

<script>
export default {
  name: 'ComponentName',
  components: {},
  props: {},
  data() {
    return {}
  },
  computed: {},
  watch: {},
  created() {},
  mounted() {},
  methods: {}
}
</script>

<style scoped>
/* 样式 */
</style>
```

### 5.3 API接口规范

#### 5.3.1 接口定义

每个模块对应一个API文件，统一放在 `src/api/` 目录下：

```javascript
import request from '@/utils/request'

export function getList(params) {
  return request({
    url: '/api/system/user',
    method: 'get',
    params
  })
}
```

#### 5.3.2 接口命名

| 操作 | 方法 | 命名示例 |
|------|------|----------|
| 查询列表 | GET | `getList` |
| 查询详情 | GET | `getInfo` |
| 新增 | POST | `add` |
| 更新 | PUT | `update` |
| 删除 | DELETE | `delete` |

### 5.4 国际化规范

项目支持中文、英文、印尼语三种语言，配置文件位于 `src/i18n/langs/`

**使用方式**：

```vue
<template>
  <span>{{ $t('user.userName') }}</span>
</template>

<script>
export default {
  mounted() {
    console.log(this.$t('common.success'))
  }
}
</script>
```

---

## 6. 常用工具函数

### 6.1 时间处理

```javascript
// 格式化时间
this.parseTime(new Date(), '{y}-{m}-{d} {h}:{i}:{s}')
```

### 6.2 数据字典

```javascript
// 获取字典标签
this.selectDictLabel(dictList, value)

// 获取多个字典标签
this.selectDictLabels(dictList, values, ',')
```

### 6.3 表单操作

```javascript
// 重置表单
this.resetForm('formName')

// 添加日期范围
this.addDateRange(params, startDate, endDate)
```

### 6.4 树结构处理

```javascript
// 处理树形数据
const treeData = this.handleTree(data, 'id', 'parentId')
```

---

## 7. CRUD开发指南

### 7.1 使用Crud组件

项目提供了通用的Crud组件，简化增删改查操作：

```vue
<template>
  <div class="app-container">
    <Crud ref="crud" :option="crudOption" />
  </div>
</template>

<script>
import { crud } from '@/mixins/crud'

export default {
  name: 'User',
  mixins: [crud],
  data() {
    return {
      crudOption: {
        title: 'user',
        url: '/api/system/user',
        columns: [
          { label: 'userName', prop: 'username' },
          { label: 'email', prop: 'email' }
        ]
      }
    }
  }
}
</script>
```

### 7.2 自定义表单

```vue
<template>
  <el-dialog :title="title" :visible.sync="visible">
    <el-form ref="form" :model="form" label-width="100px">
      <el-form-item label="用户名" prop="username">
        <el-input v-model="form.username" />
      </el-form-item>
    </el-form>
    <div slot="footer">
      <el-button @click="visible = false">取消</el-button>
      <el-button type="primary" @click="submit">确定</el-button>
    </div>
  </el-dialog>
</template>
```

---

## 8. 权限管理

### 8.1 按钮权限

使用 `v-permission` 指令控制按钮显示：

```vue
<el-button v-permission="['admin', 'user:edit']" type="primary">编辑</el-button>
```

### 8.2 角色权限

路由配置中通过 `meta.roles` 控制访问权限：

```javascript
{
  path: 'index',
  component: () => import('@/views/system/user/index'),
  meta: { roles: ['admin', 'user'] }
}
```

---

## 9. 构建部署

### 9.1 环境变量

| 文件 | 环境 | 说明 |
|------|------|------|
| .env.development | 开发环境 | 本地开发配置 |
| .env.production | 生产环境 | 生产部署配置 |

### 9.2 构建命令

```bash
# 生产构建
npm run build:prod

# 构建产物目录：dist/
```

### 9.3 部署方式

1. 将 `dist/` 目录部署到静态服务器
2. 配置Nginx反向代理：

```nginx
server {
  listen 80;
  server_name your-domain.com;
  
  location / {
    root /path/to/dist;
    index index.html;
    try_files $uri $uri/ /index.html;
  }
  
  location /api {
    proxy_pass http://backend-server:8080;
    proxy_set_header Host $host;
  }
}
```

---