haoliang-net/docs/02-前端全局规范.md

CNC机床数据采集系统 - 前端全局规范

最后更新：2026-04-25 状态：设计中

---

说明

本文档为全局规范汇总，定义所有页面通用的技术规则。各模块的页面设计（布局、字段、交互流程等）见 docs/02-功能清单/管理后台/ 和 docs/02-功能清单/大屏/ 对应模块子文件。

---

全局规范

组件规范

组件	用途	配置参数
el-table	列表展示	border, stripe, size=default, header-cell-style背景#f5f7fa
el-table-column	列定义	show-overflow-tooltip=true 默认开启
el-pagination	分页	page-sizes=[20,50,100], background=true, layout=total,sizes,prev,pager,next,jumper
el-form	表单	label-width=120px, label-position=right, size=default
el-dialog	弹窗	close-on-click-modal=false, close-on-press-escape=true, destroy-on-close=true
el-select	下拉	filterable=true, clearable=true
el-date-picker	日期	type=daterange, value-format=YYYY-MM-DD, clearable=true
el-input	输入	clearable=true, maxlength按字段定义
el-button	按钮	size=default, 操作类type=primary, 危险类type=danger
el-message	轻提示	成功success, 失败error, 警告warning
el-message-box	确认框	type=warning
el-tag	状态标签	size=small, 按状态配color
el-tooltip	提示	placement=top

防重复请求

• 所有写操作按钮点击后立即loading=true+disabled=true
• 请求锁requestLock指令，同一按钮1秒内不可重复点击
• axios拦截器，相同URL+参数的请求500ms内自动去重

超时与加载反馈

• API超时30秒(可配置)
• 列表页v-loading指令
• 弹窗提交按钮loading+弹窗内遮罩
• 超时提示el-message error

操作确认机制

• 删除：确定删除【{name}】？此操作不可恢复。
• 停用/启用：确定{操作}？
• 批量操作：确定对选中的{N}项执行{操作}？
• 产量修正：确定修正产量？修正后将记录审计日志。

脏数据检测

• 编辑弹窗关闭时：若表单有未保存修改，弹出确认
• 表单组件内维护isDirty状态，对比初始值与当前值
• 路由切换时：beforeRouteLeave守卫

操作结果反馈

场景	反馈方式	持续时间
创建成功	el-message success {资源}创建成功	3秒
修改成功	el-message success 保存成功	3秒
删除成功	el-message success {资源}已删除	3秒
操作失败	el-message error {具体错误信息}	5秒
批量操作	el-message info 已{操作}{N}项	3秒

校验规则

字段类型	规则	错误提示	触发时机
必填	required	此项为必填	blur
IP地址	pattern正则	请输入正确的IP地址	blur
URL	pattern正则	请输入正确的HTTP地址	blur
数字	type:number	请输入数字	blur
正整数	pattern正则	请输入正整数	blur
长度限制	maxlength	最多{N}个字符	input
编码唯一	async validator API调用	此{字段}已存在	blur

Mock数据规格

成功响应: code=0, message=success, data=对象 分页列表: code=0, data={items:[], total:160, page:1, pageSize:20} 失败响应: code=40001, message=具体错误, data=null

空状态设计

场景	展示
列表无数据	el-empty description=暂无数据 image-size=120
查询无结果	el-empty description=未找到匹配的数据，请调整查询条件
图表无数据	居中显示暂无数据灰色文字

错误码处理

错误码	含义	前端处理
0	成功	正常处理data
40001	参数校验失败	el-message error显示message
40002	资源不存在	el-message warning+刷新列表
40003	资源已存在	el-message error+聚焦冲突字段
40101	Token无效/过期	清除Token跳转登录页
50001	服务器内部错误	el-message error服务器错误
50002	采集服务不可达	el-message warning采集服务未响应

管理后台Layout

┌──────────────────────────────────────────────────────────┐
│ [顶部栏] height=48px                                      │
│ 左：系统名称「CNC机床数据采集系统」                         │
│ 右：管理员 ▼ → [修改密码] [退出登录]                       │
├────────┬─────────────────────────────────────────────────┤
│ [侧边栏]│ [内容区] padding=20px                           │
│ width=  │                                                 │
│ 200px   │                                                 │
│         │                                                 │
│ 仪表盘  │                                                 │
│ 设备管理│                                                 │
│ 品牌模板│                                                 │
│ 采集地址│                                                 │
│ 员工管理│                                                 │
│ 产量报表│                                                 │
│ 告警中心│                                                 │
│ 系统设置│                                                 │
│ 操作日志│                                                 │
│ 大屏配置│                                                 │
├────────┤                                                 │
│ [折叠]  │                                                 │
└────────┴─────────────────────────────────────────────────┘

顶部栏规范：

• 高度48px，背景色#409EFF（Element Plus primary），文字白色
• 左侧：系统名称，font-size=16px，font-weight=bold
• 右侧：管理员下拉菜单，el-dropdown，trigger=click
  • [修改密码]：打开修改密码弹窗（见09-系统设置）
  • [退出登录]：确认"确定退出登录？" → 清除Token → 跳转/login

侧边栏规范：

• 宽度200px，可折叠至64px（仅图标）
• 折叠按钮：底部，el-icon Fold/Expand
• 菜单项：el-menu，background=#304156，text=#bfcbd9，active-text=#409EFF
• 当前路由自动高亮，使用 el-menu 的 default-active 绑定当前路由path
• 菜单项无子菜单（均为一级），无折叠子菜单

侧边栏菜单项与路由映射：

菜单名称	路由	图标(el-icon)
仪表盘	/dashboard	Odometer
设备管理	/machine	Monitor
品牌模板	/brand	PriceTag
采集地址	/collect-address	Link
员工管理	/worker	User
产量报表	/production	DataAnalysis
告警中心	/alert	Bell
系统设置	/settings	Setting
操作日志	/log	Document
大屏配置	/screen-config	Monitor

内容区规范：

• padding=20px
• 最大宽度不限（全宽）
• 背景#f0f2f5
• 面包屑在内容区顶部，非顶部栏中

路由总表

路由	组件	权限	需Token	重定向/备注
/login	LoginPage	无	否	登录页，独立Layout（无侧边栏）
/	Layout	admin	是	管理后台框架，重定向→/dashboard
/dashboard	DashboardPage	admin	是	嵌套在Layout内
/machine	MachineListPage	admin	是	嵌套在Layout内
/machine/:id	MachineDetailPage	admin	是	嵌套在Layout内
/brand	BrandListPage	admin	是	嵌套在Layout内
/brand/create	BrandEditPage	admin	是	新增品牌
/brand/:id/edit	BrandEditPage	admin	是	编辑品牌（复用同一组件）
/collect-address	CollectAddressListPage	admin	是	嵌套在Layout内
/collect-address/:id	CollectAddressDetailPage	admin	是	嵌套在Layout内
/worker	WorkerListPage	admin	是	嵌套在Layout内
/worker/:id	WorkerDetailPage	admin	是	嵌套在Layout内
/production	ProductionPage	admin	是	嵌套在Layout内
/alert	AlertPage	admin	是	嵌套在Layout内
/settings	SettingsPage	admin	是	嵌套在Layout内
/log	LogPage	admin	是	嵌套在Layout内
/screen-config	ScreenConfigPage	admin	是	嵌套在Layout内
/screen	ScreenPage	无	否	大屏看板，独立Layout（全屏，无侧边栏）

axios封装与路由守卫

axios实例配置：

• baseURL：'/'（同IIS站点，无跨域）
• timeout：30000（30秒，可通过cnc_sys_config配置）
• 请求拦截：自动添加 Authorization: Bearer {token} header（从localStorage取token）
• 响应拦截：
  • code=0 → 正常返回data
  • code=40101 → 清除localStorage.token → router.push('/login') → 弹出el-message warning"登录已过期"
  • code=40001/40002/40003/50001/50002 → 按错误码处理表执行
  • HTTP状态码非200 → el-message error "网络异常"

路由守卫（router.beforeEach）：

• 访问/login → 如果localStorage有token → 重定向/dashboard
• 访问/api/admin/**路由 → 如果localStorage无token → 重定向/login?redirect=当前路由
• 访问/screen → 放行（免认证）
• 其他 → 放行

Token管理：

• 存储：localStorage.setItem('token', value)
• 读取：localStorage.getItem('token')
• 清除：localStorage.removeItem('token')
• 登录成功后跳转：redirect参数存在则跳redirect，否则跳/dashboard

---

前端工程开发规范

最后更新：2026-04-26 本章节为1:1可交互界面生成的工程实现规范

技术栈

类别	选型	版本要求
框架	Vue3	>=3.4
构建工具	Vite	>=5.0
语言	TypeScript	>=5.0
UI组件库	Element Plus	>=2.5
路由	Vue Router 4	>=4.3
HTTP	Axios	>=1.6
图表	ECharts	>=5.5
Mock	vite-plugin-mock	>=3.0

项目目录

D:\opencode\haoliang\frontend\
├── index.html
├── package.json
├── tsconfig.json
├── vite.config.ts                # mock插件 + proxy配置
├── mock/                         # Mock数据定义（按模块拆分）
│   ├── login.ts
│   ├── dashboard.ts
│   ├── machine.ts
│   ├── brand.ts
│   ├── collect-address.ts
│   ├── worker.ts
│   ├── production.ts
│   ├── alert.ts
│   ├── settings.ts
│   ├── log.ts
│   └── screen.ts
└── src/
    ├── main.ts
    ├── App.vue
    ├── router/
    │   └── index.ts              # 路由定义（双套：正常路由 + /mock前缀路由）
    ├── composables/
    │   └── useMockMode.ts        # Mock模式检测
    ├── utils/
    │   └── request.ts            # axios封装（根据mock模式切换baseURL）
    ├── layouts/
    │   ├── AdminLayout.vue       # 管理后台Layout（顶部栏+侧边栏+内容区）
    │   └── ScreenLayout.vue      # 大屏Layout（全屏独立）
    ├── views/                    # 页面组件（按模块目录）
    │   ├── login/
    │   ├── dashboard/
    │   ├── machine/
    │   ├── brand/
    │   ├── collect-address/
    │   ├── worker/
    │   ├── production/
    │   ├── alert/
    │   ├── settings/
    │   ├── log/
    │   ├── screen-config/
    │   └── screen/
    ├── styles/
    │   ├── admin.scss            # 管理后台全局样式
    │   └── screen.scss           # 大屏深色主题样式
    └── types/                    # TypeScript类型定义

Mock方案：URL前缀切换

核心规则： 同一组件、同一套交互逻辑，仅axios请求路径不同。

/mock/dashboard  →  axios请求走 /mock-api/**  →  vite-plugin-mock拦截返回Mock JSON
/dashboard       →  axios请求走 /api/**        →  Vite proxy转发到真实后端

使用体验

阶段	URL	行为
开发阶段（后端未就绪）	http://localhost:5173/mock/dashboard	Mock数据完整展示
开发阶段（后端未就绪）	http://localhost:5173/dashboard	界面正常，API请求404
后端就绪后	http://localhost:5173/dashboard	直接对接真实API
后端就绪后	http://localhost:5173/mock/dashboard	仍可切回Mock对比

Mock模式检测

// src/composables/useMockMode.ts
// 根据 route.path.startsWith('/mock') 判断是否为Mock模式
// 返回 computed<boolean> isMock

axios baseURL切换

// src/utils/request.ts
// if (isMock) baseURL = '/mock-api'
// else      baseURL = '/api'
// 其余拦截逻辑不变（Token/错误码/超时等）

路由定义

// src/router/index.ts
// 函数生成两套路由：
// 1. 正常路由：/dashboard, /machine, /login ...
// 2. Mock前缀路由：/mock/dashboard, /mock/machine, /mock/login ...
// 两套路由复用同一组件，Mock路由额外注入mock标识

Mock数据文件

mock/*.ts 文件内容来源：
  - 各页面.md中的Mock数据章节
  - 数据结构严格匹配页面.md中定义的JSON
  - 一个模块一个文件，按API路径组织

Vite配置

// vite.config.ts
// 1. vite-plugin-mock 配置 mock/**.ts
// 2. proxy 配置：
//    /mock-api/** → mock插件拦截（开发环境）
//    /api/**      → proxy到后端（可配置target，默认http://localhost:5800）

CSS规范

• 方案：Element Plus默认主题 + 局部scoped样式
• 管理后台：Element Plus默认蓝色主题(#409EFF)，背景#f0f2f5
• 大屏看板：独立深色主题(#0f0f1a背景/#1a1a2e卡片)，样式文件 styles/screen.scss
• 不引入Tailwind CSS

大屏独立规范

• 独立Layout：ScreenLayout.vue（全屏，无侧边栏/面包屑）
• 独立路由：/screen 和 /mock/screen
• 独立主题：深色背景，通过 screen.scss 覆盖Element Plus默认样式
• 免认证：/api/screen/** 不需要Token
• 自动刷新：定时器按卡片配置的刷新策略轮询

强制要求

• 思考过程使用中文：所有AI助手的推理、分析、思考过程必须使用中文输出
• 控制台输出中文：所有控制台输出、日志、提示信息使用中文，不得出现乱码
• 所有文档使用中文：项目内所有文档、注释、界面文案使用中文
• 组件文案中文：所有界面文字（按钮/标签/提示/空状态/确认框）必须使用中文
• 代码注释中文：所有代码注释使用中文

---

CRUD页面必填项

页面文件完整模板见 功能清单文件夹创建规范.md 第五节（共20项）。以下为本项目CRUD页面的最小必填项——20项的子集。未列出的项，若本模块有特殊需求则补充填写，无特殊需求则省略（继承全局规范即可）。

默认继承全局规范、页面文件无需重复填写的项目：

• 防重复请求(8)、超时与加载反馈(9)、操作确认机制(10)、操作结果反馈(12)、校验规则(14)、响应式布局(15)、空状态设计(18)、错误码处理(19)、安全规范(20)
• 仅当本页面有不同于全局规范的特殊逻辑时，才在页面文件中补充对应项

列表页必填项

序号	必填项	说明
1	基本信息	路由、权限、入口、面包屑
2	界面布局	ASCII图
3	查询条件	字段/控件/必填/默认值/校验/联动，无筛选则写"无"
4	列表字段	字段名/列宽/排序/筛选/固定/超长处理/对齐
5	操作按钮	名称/权限编码/位置/显示条件/点击行为
6	弹窗规格	弹窗宽度/遮罩/ESC/表单字段定义，无弹窗则写"无"
7	状态机	状态值/颜色/可用操作，无状态则写"无"
8	交互流程	每个操作的主流程+异常处理
9	空状态	列表无数据/查询无结果的展示

弹窗表单字段必填列：

列	说明
字段	中文名
控件	el-input/el-select等+具体参数
必填	是/否
默认值	无则写"-"
校验	必填/格式/唯一性等，无则写"-"
联动	值变化时影响哪些字段，无则写"-"

详情页必填项

序号	必填项	说明
1	基本信息	路由(含参数)、权限、入口、面包屑
2	界面布局	ASCII图
3	数据区块	每个区块的展示字段+控件类型
4	操作按钮	名称/位置/行为
5	交互流程	加载/刷新/跳转

统计/仪表盘页必填项

序号	必填项	说明
1	基本信息	路由、权限、入口、面包屑
2	界面布局	ASCII图（统计卡片+表格/图表区域）
3	数据区块	每个区块的数据来源API+刷新策略
4	操作按钮	名称/位置/行为
5	状态机	状态值/颜色（如有）
6	交互流程	加载/自动刷新/跳转
7	空状态	各区块无数据的展示

登录/特殊页必填项

序号	必填项	说明
1	基本信息	路由、入口
2	界面布局	ASCII图
3	表单字段	字段/控件/校验（如有表单）
4	操作按钮	名称/行为
5	交互流程	成功/失败/跳转
6	安全规范	Token存储/过期/登出策略

---

模块设计进度

具体页面设计见 docs/02-功能清单/管理后台/{编号}-{模块名}/ 对应子文件

编号	模块	页面数	设计状态	备注
01	登录	1	✅ 已设计	见 管理后台/01-登录/01-01-登录页面.md
02	仪表盘	1	✅ 已设计	见 管理后台/02-仪表盘/02-01-仪表盘页面.md
03	设备管理	2	✅ 已设计	列表页+详情页，见 管理后台/03-设备管理/
04	品牌模板	2	✅ 已设计	列表页+编辑页，见 管理后台/04-品牌模板/
05	采集地址	2	✅ 已设计	列表页+详情页(采集历史+原始JSON)，见 管理后台/05-采集地址/
06	员工管理	2	✅ 已设计	列表页+详情页，见 管理后台/06-员工管理/
07	产量报表	1	✅ 已设计	含修正+导出+数据缺失标记，见 管理后台/07-产量报表/
08	告警中心	1	✅ 已设计	含批量标记+统计，见 管理后台/08-告警中心/
09	系统设置	1	✅ 已设计	3Tab:配置项+车间管理+修改密码，见 管理后台/09-系统设置/
10	车间管理	-	🔀 已合并	合并至09-系统设置
11	操作日志	1	✅ 已设计	双Tab:修正审计日志+系统运行日志，见 管理后台/11-操作日志/
12	大屏配置	1	✅ 已设计	见 管理后台/12-大屏配置/12-01-大屏配置页面.md

大屏模块：

编号	模块	页面数	设计状态	备注
大屏-01	大屏看板	1	✅ 已设计	免认证，深色主题，卡片式自动刷新，见 大屏/01-01-大屏看板页面.md