IOT-Platform-Web 项目文档

📋 项目概述

项目名称: IOT-Platform-Web (物联网平台管理系统)
项目类型: Web前端应用
开发框架: Vue 3 + Vite
UI框架: Ant Design Vue
版本: v2.8.0
基于: Vue Vben Admin (精简版)

项目简介

IOT-Platform-Web是一个基于Vue 3和Vite构建的现代化物联网平台管理系统。项目采用Vue Vben Admin精简版作为基础框架，提供了完整的后台管理功能，包括设备管理、数据可视化、用户权限管理等核心功能。系统采用最新的前端技术栈，具有高性能、易维护、可扩展的特点。

🎯 核心功能

1. 设备管理

设备列表查看和管理
设备状态实时监控
设备配置和参数设置
设备分组和分类

2. 数据可视化

实时数据展示
图表和报表生成
数据统计分析
自定义仪表盘

3. 用户权限管理

用户账号管理
角色权限配置
动态路由权限
菜单权限控制

4. 系统配置

主题配置
国际化支持
系统参数设置
日志管理

5. Mock数据支持

开发环境Mock数据
API接口模拟
数据模拟生成

🏗️ 技术架构

核心技术栈

前端框架

Vue 3.2.33 - 渐进式JavaScript框架
TypeScript 4.6.3 - 类型安全的JavaScript超集
Vite 2.9.5 - 下一代前端构建工具

UI组件库

Ant Design Vue 3.2.0 - 企业级UI组件库
@ant-design/icons-vue 6.1.0 - 图标库
@ant-design/colors 6.0.0 - 颜色系统

状态管理

Pinia 2.0.12 - Vue 3官方推荐的状态管理库

路由管理

Vue Router 4.0.14 - Vue官方路由管理器

国际化

Vue I18n 9.1.9 - 国际化插件

工具库

Lodash-es 4.17.21 - JavaScript工具库
Axios 0.26.1 - HTTP客户端
Day.js 1.11.1 - 日期处理库
Crypto-js 4.1.1 - 加密库
Qs 6.10.3 - 查询字符串解析

数据可视化

ECharts 5.3.2 - 数据可视化图表库

代码编辑器

CodeMirror 5.65.3 - 代码编辑器
TinyMCE 5.10.3 - 富文本编辑器
Vditor 3.8.13 - Markdown编辑器

其他功能库

Intro.js 5.1.0 - 用户引导
Cropperjs 1.5.12 - 图片裁剪
Sortablejs 1.15.0 - 拖拽排序
XLSX 0.18.5 - Excel处理
Vue JSON Pretty 2.0.6 - JSON美化显示

📁 项目结构

IOT-Platform-Web/
├── build/                       # 构建配置
│   ├── vite/                   # Vite插件配置
│   ├── generate/               # 代码生成工具
│   ├── script/                 # 构建脚本
│   └── utils.ts                # 构建工具函数
├── mock/                        # Mock数据
├── public/                      # 静态资源
├── src/                         # 源代码
│   ├── api/                    # API接口
│   ├── assets/                 # 资源文件
│   ├── components/             # 公共组件
│   ├── design/                 # 设计系统
│   ├── directives/             # 自定义指令
│   ├── enums/                  # 枚举定义
│   ├── hooks/                  # 组合式函数
│   ├── layouts/                # 布局组件
│   ├── locales/                # 国际化文件
│   ├── logics/                 # 业务逻辑
│   ├── router/                 # 路由配置
│   ├── settings/               # 配置文件
│   ├── store/                  # 状态管理
│   ├── utils/                  # 工具函数
│   ├── views/                  # 页面组件
│   ├── App.vue                 # 根组件
│   └── main.ts                 # 入口文件
├── types/                       # 类型定义
├── .env                         # 环境变量
├── .env.development            # 开发环境变量
├── .env.production             # 生产环境变量
├── .env.test                   # 测试环境变量
├── .eslintrc.js                # ESLint配置
├── .prettierrc                 # Prettier配置
├── .stylelintignore            # Stylelint忽略配置
├── index.html                  # HTML模板
├── package.json                # 项目依赖
├── tsconfig.json               # TypeScript配置
├── vite.config.ts              # Vite配置
├── windi.config.ts             # WindiCSS配置
└── README.md                   # 项目说明

🔧 开发环境配置

必需工具

Node.js: ^12 或 >=14
包管理器: pnpm (推荐) / npm / yarn

环境变量配置

开发环境 (.env.development)

# 是否开启Mock
VITE_USE_MOCK = false

# 公共路径
VITE_PUBLIC_PATH = /

# 跨域代理配置
VITE_PROXY = [["/basic-api","https://www.znntest.xyz"],["/upload","http://localhost:3300/upload"]]

# 是否删除console
VITE_DROP_CONSOLE = false

# 基础接口地址
VITE_GLOB_API_URL=/basic-api

# 文件上传地址
VITE_GLOB_UPLOAD_URL=/upload

# 接口前缀
VITE_GLOB_API_URL_PREFIX=

生产环境 (.env.production)

# 是否开启Mock
VITE_USE_MOCK = true

# 公共路径
VITE_PUBLIC_PATH = /

# 是否删除console
VITE_DROP_CONSOLE = true

# 压缩方式: gzip | brotli | none
VITE_BUILD_COMPRESS = 'none'

# 是否删除原文件
VITE_BUILD_COMPRESS_DELETE_ORIGIN_FILE = false

# 基础接口地址
VITE_GLOB_API_URL=/basic-api

# 文件上传地址
VITE_GLOB_UPLOAD_URL=/upload

# 是否启用图片压缩
VITE_USE_IMAGEMIN= true

# 是否使用PWA
VITE_USE_PWA = false

# 是否兼容旧浏览器
VITE_LEGACY = false

🚀 快速开始

1. 安装依赖

# 使用pnpm (推荐)
pnpm install

# 或使用npm
npm install

# 或使用yarn
yarn install

2. 启动开发服务器

# 使用pnpm
pnpm dev

# 或使用npm
npm run dev

# 或使用yarn
yarn dev

开发服务器将在 https://localhost:5173 启动（默认端口）

3. 构建生产版本

# 生产环境构建
pnpm build

# 测试环境构建
pnpm build:test

# 无缓存构建
pnpm build:no-cache

4. 预览构建结果

# 预览生产构建
pnpm preview

# 或先构建再预览
pnpm preview:dist

📦 构建配置

Vite配置要点

// vite.config.ts
export default {
  base: VITE_PUBLIC_PATH,
  server: {
    https: true,              // 启用HTTPS
    host: true,               // 监听所有本地IP
    port: VITE_PORT,          // 端口配置
    proxy: createProxy(VITE_PROXY)  // 代理配置
  },
  build: {
    target: 'es2015',
    cssTarget: 'chrome80',
    outDir: OUTPUT_DIR,
    brotliSize: false,        // 关闭brotli大小显示
    chunkSizeWarningLimit: 2000
  }
}

代理配置

开发环境支持多个代理配置：

VITE_PROXY = [
  ["/basic-api", "https://www.znntest.xyz"],
  ["/upload", "http://localhost:3300/upload"]
]

🎨 主题配置

主题颜色

项目支持自定义主题颜色，默认使用Arco Blue：

// 主题色配置
@primary-color: #165DFF;

布局配置

{
  "colorWeek": false,      // 色弱模式
  "navbar": true,          // 显示导航栏
  "menu": true,            // 显示菜单
  "footer": false,         // 显示页脚
  "themeColor": "#165DFF", // 主题颜色
  "menuWidth": "14rem"     // 菜单宽度
}

🔌 API接口

接口配置

// 基础API地址
const API_URL = import.meta.env.VITE_GLOB_API_URL

// 上传地址
const UPLOAD_URL = import.meta.env.VITE_GLOB_UPLOAD_URL

// 接口前缀
const API_PREFIX = import.meta.env.VITE_GLOB_API_URL_PREFIX

请求封装

项目使用Axios进行HTTP请求封装，支持：

请求拦截
响应拦截
错误处理
请求取消
请求重试

🧪 代码质量

ESLint配置

// .eslintrc.js
module.exports = {
  extends: [
    'plugin:vue/vue3-recommended',
    'plugin:@typescript-eslint/recommended',
    'prettier'
  ],
  rules: {
    // 自定义规则
  }
}

Prettier配置

// prettier.config.js
module.exports = {
  printWidth: 100,
  tabWidth: 2,
  useTabs: false,
  semi: true,
  singleQuote: true,
  trailingComma: 'all'
}

Stylelint配置

// stylelint.config.js
module.exports = {
  extends: [
    'stylelint-config-standard',
    'stylelint-config-prettier'
  ]
}

代码检查命令

# ESLint检查
pnpm lint:eslint

# Prettier格式化
pnpm lint:prettier

# Stylelint检查
pnpm lint:stylelint

# Lint-staged
pnpm lint:lint-staged

🔄 Git提交规范

项目遵循Angular提交规范：

feat: 新功能
fix: 修复问题/BUG
style: 代码风格相关
perf: 性能优化
refactor: 重构
revert: 撤销修改
test: 测试相关
docs: 文档/注释
chore: 依赖更新/脚手架配置
workflow: 工作流改进
ci: 持续集成
types: 类型定义文件更改
wip: 开发中

提交命令

# 使用commitizen提交
pnpm commit

# 或使用czg
czg

📊 性能优化

构建优化

代码分割 - 自动代码分割和懒加载
Tree Shaking - 移除未使用的代码
压缩 - 代码压缩和混淆
图片优化 - 图片压缩和格式转换
CDN加速 - 静态资源CDN部署

运行时优化

路由懒加载 - 按需加载路由组件
组件懒加载 - 使用defineAsyncComponent
虚拟滚动 - 大列表虚拟滚动
防抖节流 - 高频事件优化
缓存策略 - 合理使用缓存

🔐 安全配置

环境变量安全

敏感信息不要提交到版本控制
使用.env.local存储本地敏感配置
生产环境使用环境变量注入

XSS防护

使用Vue的模板语法自动转义
避免使用v-html
对用户输入进行验证和过滤

CSRF防护

使用Token验证
配置CORS策略
验证Referer头

📱 浏览器兼容性

生产环境

>0.2%
not dead
not op_mini all

开发环境

last 1 chrome version
last 1 firefox version
last 1 safari version

🧪 测试

单元测试

pnpm test:unit

测试框架

Jest - 单元测试框架
Vue Test Utils - Vue组件测试工具

📚 相关资源

官方文档

🛠️ 常见问题

1. 依赖安装失败

# 清理缓存
pnpm store prune

# 重新安装
rm -rf node_modules
pnpm install

2. 端口被占用

修改.env.development中的端口配置：

VITE_PORT = 5174

3. 代理不生效

检查VITE_PROXY配置格式是否正确，确保没有换行。

4. 构建失败

# 清理构建缓存
pnpm clean:cache

# 重新构建
pnpm build

📝 更新日志

详见 CHANGELOG.md 和 CHANGELOG.zh_CN.md

👥 开发团队

原作者: vben (anncwb@126.com)
项目: Vue Vben Admin
定制: IOT Platform Team

📄 许可证

MIT License

📞 联系方式

如有问题或建议，请通过以下方式联系：

GitHub Issues
项目维护团队

文档版本: v1.0
最后更新: 2025-01-27
文档状态: 正式版

📋 项目概述​

项目简介​

🎯 核心功能​

1. 设备管理​

2. 数据可视化​

3. 用户权限管理​

4. 系统配置​

5. Mock数据支持​

🏗️ 技术架构​

核心技术栈​

前端框架​

UI组件库​

状态管理​

路由管理​

国际化​

工具库​

数据可视化​

代码编辑器​

其他功能库​

📁 项目结构​

🔧 开发环境配置​

必需工具​

环境变量配置​

开发环境 (.env.development)​

生产环境 (.env.production)​

🚀 快速开始​

1. 安装依赖​

2. 启动开发服务器​

3. 构建生产版本​

4. 预览构建结果​

📦 构建配置​

Vite配置要点​

代理配置​

🎨 主题配置​

主题颜色​

布局配置​

🔌 API接口​

接口配置​

请求封装​

🧪 代码质量​

ESLint配置​

Prettier配置​

Stylelint配置​

代码检查命令​

🔄 Git提交规范​

提交命令​

📊 性能优化​

构建优化​

运行时优化​

🔐 安全配置​

环境变量安全​

XSS防护​

CSRF防护​

📱 浏览器兼容性​

生产环境​

开发环境​

🧪 测试​

单元测试​

测试框架​

📚 相关资源​

官方文档​

相关仓库​

🛠️ 常见问题​

1. 依赖安装失败​

2. 端口被占用​

3. 代理不生效​

4. 构建失败​

📝 更新日志​

👥 开发团队​

📄 许可证​

📞 联系方式​