最近给一家小型企业重新做了一套员工工资管理系统技术栈最终敲定的是Node.js Vue 前后端分离。说实话这套组合在中小团队的内网系统里相当能打后端 Node.js 扛住接口和业务逻辑前端 Vue 负责交互页面的快速迭代两边又都是 JavaScript团队协作的沟通成本低到可以忽略。系统做完之后员工档案管理、工资项配置、月度算薪、审核发放、历史明细查询、报表导出整个流程都能在一个系统里跑通。如果你正好在做技术选型或者想拿一个真实项目练手 Vue 和 Node.js这篇文章值得你耐心看完。我打算把整个项目从需求梳理、技术选型、环境搭建、后端接口、前端页面到常见坑位完整拆开讲一遍。里面大部分内容是我实际编码和排障过程中的记录属于那种“网上查得到但不会有人系统讲过”的经验。1. 这个工资管理系统到底要解决什么问题1.1 传统工资管理方式的痛点在没有这套系统之前这家企业的工资核算基本就是靠三样东西Excel 表格、微信聊天记录和财务的个人记忆。每个月算薪的时候人事把考勤记录导出来发给财务财务再对着员工基础工资表手动核算加班费、绩效、社保扣款每一项都得手工处理。这种模式的毛病特别典型。第一Excel 文件在多人之间传来传去版本容易错乱经常出现两个人手里的工资表对不上数。第二公式嵌套稍微复杂一点就有人不小心拖错单元格错误还特别难排查往往是工资都发出去了才发现问题。第三工资数据是极其敏感的信息但用聊天工具传文件全程没有访问控制和操作留痕风控上完全不可控。所以客户提需求的时候核心诉求其实就一句话把每个月算工资这个“手工流水线”变成一条可追溯、权限分明的系统流程。要求倒不复杂但非常看重明细留痕和审批闭环。1.2 核心功能模块拆解我把需求梳理成下面几个模块后面所有开发都是围绕这个清单展开的员工档案管理维护员工基本信息、入职日期、部门岗位、薪资标准支持离职员工归档。部门与岗位管理树形结构工资计算时按部门进行汇总和权限过滤。考勤与工时数据接入支持导入 Excel 考勤表也能通过接口对接考勤机数据。工资项配置自定义工资组成比如基本工资、绩效奖金、餐补、交通补贴、社保、公积金、个税。月度工资计算按月份生成工资单系统根据配置的工资项自动汇总计算。审核与发放工资单生成后需要主管和财务两级审核确认后标记为已发放。历史记录与明细查询员工可查看个人历史工资明细管理员可查看全员记录。报表统计与导出月度工资总额、部门人力成本、年度薪资趋势等统计支持导出。多级权限控制员工、部门主管、财务、系统管理员四种角色数据权限按部门和操作权限双重隔离。这里有个容易被忽略的点工资系统不像普通 CRUD 系统那样“能增删改查就行”它的核心是计算规则和状态流转。工资单从生成、试算、提交、审核、发放到归档每一步都要有状态和操作日志。我在表设计阶段就专门留了一个salary_log表来记录所有审核和变更动作这后来在客户对账的时候帮了大忙。2. 技术选型为什么偏偏是 Node.js Vue2.1 后端选型的心路历程客户一开始问我能不能用 Spring Boot我承认 Java 社区很成熟Spring Boot 也确实稳。但考虑实际情况这家企业内部系统并发极低核心场景是多人同时操作、I/O 密集而非 CPU 密集业务逻辑以增删改查和计算为主。Node.js 的事件驱动模型在这种场景下完全够用而且轻得多。更现实的一点是这家企业没有专门的 Java 团队前端倒是有人写过 Vue。如果上 Spring Boot前后端代码各一种语言小团队维护起来等于摊了两份技术债。统一用 JavaScript/TypeScript人力盘活、知识复用新人也更容易上手。我当时给客户算了一笔账用 Node.js 开发同样的接口量能省下差不多三分之一的开发时间。当然Node.js 不是没有短板。如果你后面要做大量 CPU 密集计算比如跑复杂的工资税优算法或者海量数据的聚合单线程模型就会有瓶颈。但对于几百人的员工规模读一版工资表也就几万行数据库索引建好响应时间基本在几十毫秒以内。这个体量的项目选 Node.js 完全撑得住。2.2 Vue 在前端承担的角色前端选 Vue 的理由可能更直白组件化开发让页面复用度特别高一个“员工基本信息表单”组件在新增、编辑、详情三个地方都能用响应式数据绑定让工资试算的交互特别好做前端改一个数值页面自动重新汇总不需要手写 DOM 操作。Vue 生态里的三个标配我这次全用上了Vue Router负责页面路由和路由守卫实现登录拦截和动态权限路由。Pinia替代 Vuex 做状态管理集中维护用户信息、权限标识和全局配置。Element Plus组件库表格、表单、对话框、日期选择器这些企业后台常用组件开箱即用省下大量样式时间。我用 Vite 作为构建工具比起旧版的 Vue CLI冷启动速度快了不止一个档次。开发的时候保存代码页面一两秒就能热更新那种“等一下、再等一下”的频率明显下降了。2.3 系统整体架构设计整个系统的架构并不复杂走的是典型的前后端分离 集中式数据库路线前端Vue 3 单页应用部署时构建出静态文件由 Nginx 托管。后端Node.js 使用 Express 框架提供 RESTful API按模块拆分路由。数据库MySQL 5.7存员工、部门、工资单、工资项、操作日志等业务数据。认证方式JWT Token后端签发和校验前端存在内存和 localStorage并在 Axios 拦截器里统一注入请求头。这里有一个我特别坚持的设计前后端通过接口契约沟通。开发前先用 Apifox 定义好所有接口的请求和响应结构前端按 mock 数据开发后端按真实逻辑实现。两边同时开工到了联调阶段基本上没有“字段对不上”这种扯皮事。3. 开发环境搭建与踩坑实录3.1 Node.js 安装与环境变量配置环境这块看着简单但根据我这些年带新人的经验十个新手有八个卡在 Node.js 安装和环境配置上。这里把标准操作整理一遍。Windows 下直接去 Node.js 官网下载 LTS 版本安装包一路 Next 就行。安装完成后打开命令行验证node -v npm -v如果提示“node 不是内部或外部命令”说明环境变量没配好。手动加上两个路径一个是 Node.js 的安装目录比如D:\Program Files\nodejs\另一个是全局模块目录%APPDATA%\npm。配置完记得重启终端。国内开发者大概率会遇到 npm 下载依赖慢的问题建议第一件事就是把镜像源切到国内npm config set registry https://registry.npmmirror.com另外一个新手极其容易踩的坑是npm.ps1 无法加载文件的报错典型提示是这样的npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本这不是 Node.js 装坏了而是 Windows PowerShell 的默认执行策略限制了脚本运行。解决方案有两个要么用管理员身份给当前用户放行要么以后都用 cmd 而不是 PowerShell 跑命令。放行命令Set-ExecutionPolicy -Scope CurrentUser RemoteSigned我自己的习惯是直接设置RemoteSigned既保证本地脚本可以运行又不影响系统级策略比较折中。3.2 用 Vite 创建 Vue 项目创建 Vue 项目我强烈建议用官方的脚手架命令很简单npm create vuelatest这个脚手架会问你需不需要 TypeScript、Vue Router、Pinia、ESLint按需勾选就行。创建完项目后安装依赖npm install npm install element-plus npm install axios项目目录我会做一点规划不是脚手架默认结构拿来就用src/views按业务模块分页面比如employee、salary、report。src/components通用组件比如员工选择器、部门树、导出按钮。src/api接口封装一个模块对应一个文件全部导出函数。src/storePinia 的 store 文件。src/router路由配置和守卫逻辑。这里要特别提一下Vue Devtools 插件。调试 Vue 项目的状态和组件层级时这个浏览器扩展能帮你省下大量console.log的时间。它支持查看组件 props、响应式数据、Pinia 的 store、Vue Router 的路由记录基本是目前调试 Vue 3 项目的必备工具。3.3 MySQL 表结构设计的几个关键点工资系统的表设计没有高深的东西但有几个细节我特别留意。核心表大致如下表名说明关键字段employee员工档案id, name, department_id, position, base_salary, hire_date, statusdepartment部门表id, name, parent_idsalary_item工资项配置id, name, type(收入/扣款), calc_type(固定/按比例), valuemonthly_salary月度工资单id, employee_id, month, total_amount, status, audit_by, paid_atsalary_detail工资明细id, salary_id, item_id, item_name, amountsalary_log操作日志id, salary_id, action, operator_id, remark设计时的三个原则工资明细单列存把每一个工资项的金额拆到独立行方便后面做对账和追溯。不推荐把几十个工资项设计成几十个字段那会让表非常臃肿而且工资项配置是动态的。金额字段用 DECIMAL 而不是 FLOAT/DOUBLEMySQL 里 DECIMAL(10,2) 可以精确存储两位小数不会出现浮点误差。这个在工资系统里是底线问题差一分钱客户都要找你。状态字段用 TINYINT比如 0草稿、1待审核、2已审核、3已发放、4已作废。每个状态流转写进日志表保证全程可追溯。4. 后端核心模块实现4.1 JWT 登录认证与权限控制后端我用的 Express登录接口的流程是前端提交用户名密码后端校验通过后返回 JWT Token。密码存储使用bcryptjs做哈希绝不存明文。const jwt require(jsonwebtoken); const bcrypt require(bcryptjs); // 登录成功签发 token const token jwt.sign( { userId: user.id, role: user.role }, process.env.JWT_SECRET, { expiresIn: 12h } );用户权限我用了一个非常实用的设计角色 接口清单。每个角色在数据库里对应一组允许访问的接口标识请求进入时中间件校验function checkPermission(action) { return (req, res, next) { const { role, permissions } req.user; if (!permissions.includes(action)) { return res.status(403).json({ message: 没有操作权限 }); } next(); }; }其中permissions是登录成功之后从库里查出、挂在用户对象上的。这种方案比单纯判断角色灵活得多因为以后如果需要“财务可以修改工资项但主管不行”这种细粒度控制直接在权限配置里加一项就行不用改代码。4.2 工资计算引擎的实现思路工资计算是这套系统的灵魂我把它设计成了可配置的“规则脚本”而不是写死的一堆 if else。工资总额的计算逻辑大致是应发工资 基本工资 岗位津贴 绩效奖金 加班费 餐补 补贴项 实发工资 应发工资 - 社保个人部分 - 公积金个人部分 - 个税 - 其他扣款后端在生成月度工资单时会遍历每个员工的工资项配置按类型计算for (const item of salaryItems) { let amount 0; if (item.calc_type fixed) { amount item.value; } else if (item.calc_type by_salary) { amount Math.round(employee.base_salary * item.value); } else if (item.calc_type by_attendance) { amount Math.round(attendanceCount * item.value); } // 写入 detail... }工资计算最怕浮点丢精度。JavaScript 的0.1 0.2不等于0.3这是老生常谈但工资系统里可不止发生在加减法上。我的处理方式是统一使用整数分来运算也就是说所有金额在计算过程中都乘以 100转成整数最后再除以 100。或者引入一个decimal.js这样的库。实测下来用整数分是最简单不引入额外依赖的方法。另一个容易坑到人的点是个税的前后端一致性。前端试算展示一个预估值后端正式计算是最终值这两个值必须用同一套算法。我的做法是把个税计算函数单独抽出来后端实现一份前端也封装一份同样的工具函数避免联调的时候两边各算各的。4.3 报表统计与 Excel 导出功能Excel 导出我用的库是exceljs它对样式控制比老牌的node-xlsx细腻很多可以设置表头合并、单元格边框、列宽导出的表格客户直接能拿去存档不需要二次调整。const ExcelJS require(exceljs); const workbook new ExcelJS.Workbook(); const sheet workbook.addWorksheet(月度工资表); sheet.columns [ { header: 工号, key: employeeNo, width: 15 }, { header: 姓名, key: name, width: 15 }, { header: 基本工资, key: baseSalary, width: 15 }, ]; // 填充数据 await workbook.xlsx.writeFile(monthly_salary.xlsx);这里有个小坑如果导出接口直接返回文件流给前端临时文件必须及时清理不然跑上一段时间服务器磁盘就被 Excel 文件塞满了。我后来改成接口直接返回 Buffer前端拿到文件流让浏览器下载服务端不落盘彻底规避了这个隐患。5. 前端核心页面实现5.1 权限控制与动态路由前端权限控制是工资系统里相对繁琐的一部分。我的做法是登录成功拿到用户信息和权限列表后把可访问的路由动态添加到 Vue Router 里。路由表先分成两部分一部分是所有角色都能访问的基础路由剩下的是需要权限的动态路由。// 路由守卫 router.beforeEach((to, from, next) { const token localStorage.getItem(token); if (!token to.path ! /login) { next(/login); } else { next(); } });这样处理之后你在地址栏里直接输入一个没有权限的路径会被前端拦截根本渲染不了对应页面。当然后端接口的权限校验依然要做前端路由守卫只是提升体验和减少无意义的请求。除了路由控制我还写了一个按钮级权限的自定义指令v-permission比如工资“审核”按钮只有财务角色才能显示。这个细节客户很满意因为他们原来的 Excel 流程里任何人拿到文件都能看全部工资现在连界面上都不会露出不该看到的操作入口。5.2 核心业务页面拆解员工管理页面是系统里最常规的 CRUD 页面但它有一个设计细节值得说列表按部门树联动过滤。左侧是一棵部门树右侧是员工表格点击部门节点自动按当前部门及其子部门过滤员工。实现上后端接口接收一个departmentId参数在 SQL 里递归查子部门。MySQL 8.0 支持递归 CTE写起来很顺手WITH RECURSIVE sub_depts AS ( SELECT id FROM department WHERE id ? UNION ALL SELECT d.id FROM department d INNER JOIN sub_depts s ON d.parent_id s.id ) SELECT * FROM employee WHERE department_id IN (SELECT id FROM sub_depts);月度工资计算页面是交互最复杂的页面。先选月份点“生成工资单”后端开始批量为该月所有在职员工生成工资单记录生成之后前端表格立即刷新出每人应发、实发金额的试算结果薪资项可以点击展开查看明细。前端做了一件比较讨巧的事情不把试算结果提交到后端而是就地用本地计算的方式做“前端试算”等用户确认无误后再点“确认提交”把所有结果一次性交给后端。这么做的好处是人事可以随便调整绩效值实时看计算结果只有最终确认那一步才会真的写入数据库。统计报表页用了 ECharts 做数据可视化主要是三个图月度应发工资总额柱状图、部门人力成本饼图、年度薪资增长趋势折线图。数据来源是后端聚合好的报表接口一次请求返回所有图表所需数据。5.3 状态管理与请求封装Vue 3 项目我用 Pinia 管理全局状态一个典型的userStoreexport const useUserStore defineStore(user, { state: () ({ token: localStorage.getItem(token) || , userInfo: null, permissions: [], }), actions: { setLogin(data) { this.token data.token; this.userInfo data.userInfo; this.permissions data.permissions; localStorage.setItem(token, data.token); }, logout() { this.token ; this.userInfo null; this.permissions []; localStorage.removeItem(token); }, }, });请求封装的核心在 Axios 拦截器里。请求拦截器统一注入 Token响应拦截器统一处理 HTTP 401token 过期跳登录页和业务错误码弹出错误提示。这一层做扎实之后业务代码里请求接口只需要一行调用错误处理完全不用业务侧操心。6. 常见问题排查与开发技巧实录6.1 npm 脚本执行权限报错这个问题的出现频率实在太高了几乎每带一个新人就会遇到一次。报错信息基本是这种npm : 无法加载文件 D:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本根本原因是 PowerShell 默认的Restricted策略不允许执行.ps1脚本文件npm 的启动脚本正是.ps1。处理办法是打开 PowerShell执行Set-ExecutionPolicy -Scope CurrentUser RemoteSigned这里科普一下RemoteSigned的含义本地创建的脚本可以运行从网上下载的脚本需要签名。日常开发这样设置足够安全不要图省事直接设成Unrestricted。如果你不想动 PowerShell 的安全策略另一个很实用的办法是命令行工具改用 cmd命令提示符cmd 不受 PowerShell 执行策略影响直接用npm命令没有任何问题。我之前遇到客户那就是这样妥协的后面反正也不影响开发。6.2 Node 版本带来的兼容性问题Node.js 版本迭代很快很多老项目依赖库和新版本 Node 之间存在兼容性问题。最常见的一幕就是执行npm install报 ERESOLVE 错误比如npm ERR! ERESOLVE unable to resolve dependency tree这个错误多数情况是依赖版本冲突不是代码写错了。一个迅速排查的思路是先删掉node_modules和package-lock.json再重新安装如果还不行就用 npm 的 legacy 模式npm install --legacy-peer-deps我在实际开发中更推荐另一个做法用 nvm-windows 做 Node 版本的灵活切换。一个项目用 Node 16另一个项目用 Node 18随时切换互不干扰。说实话装上 nvm 之后我基本没有再手动安装过 Node。6.3 前后端联调时的 CORS 和代理问题前后端分离开发的时候前端跑在localhost:5173Vite 默认端口后端跑在localhost:3000只要前端发请求跨域就出现了。后端虽然可以配置 CORS 中间件放行但更标准、更接近生产环境的做法是前端开发环境通过 Vite 代理转发请求。在 Vite 项目根目录的vite.config.js里配置export default defineConfig({ server: { proxy: { /api: { target: http://localhost:3000, changeOrigin: true, }, }, }, });前端请求/api/salary/listVite 自动转发到http://localhost:3000/api/salary/list同一个源下通信没有跨域没烦恼。生产环境则用 Nginx 起一个反向代理把/api指到 Node 服务逻辑一模一样。这里还送大家一个经验联调阶段接口字段命名风格必须统一。后端返回employee_name前端偏用employeeName两边的转换就够你喝一壶。我们的约定是后端统一返回小驼峰命名数据库字段的下划线映射工作全部后端消化前端拿到什么就是什么不折腾。6.4 工资数据的精度与安全细节精度问题我再强调一次工资系统所有的金额字段在后端和数据库层都不能出现浮点类型这个在前文讲过但是值得单独拿出来再提醒一遍。我见过有同事在 MySQL 里把金额字段建成了DOUBLE工资算到后期对不上账排查了两个小时才发现是精度问题。用DECIMAL(10,2)是最稳妥的选择。安全方面有三个细节容易被新手忽略登录接口必须做防暴力破解连续失败次数达到 N 次锁定一段时间。工资明细查询接口要做数据权限校验不能让员工传一个employeeId就把别人的工资看走了。导出 Excel 的文件名不要直接用员工姓名拼路径避免路径穿越和中文乱码。7. 最后分享几点真实体会这套系统从需求梳理到上线前后花了大约三周时间。我个人比较满意的地方并不是界面有多炫酷而是把每个月财务最头疼的“对账”这件事彻底消掉了——现在工资单一旦审核任何人改不了每次操作都有日志财务月底再也不用拿着 Excel 一遍一遍做 sum。如果你也想动手复刻一套类似的系统我的建议是从小的边界开始先跑通员工管理 工资项配置 月度工资生成这一个闭环再去加报表、权限、审核这些外围功能。技术栈就按 Node.js Vue 3 MySQL 这套来对新人友好上线也轻快。最后再分享一个小技巧数据库备份一定要自动化。我后来给这套系统加了一个每天凌晨的定时任务自动备份数据库并保留最近 30 天的备份文件。工资数据这东西丢了可没人赔得起。
最近给一家小型企业重新做了一套员工工资管理系统技术栈最终敲定的是Node.js Vue 前后端分离。说实话这套组合在中小团队的内网系统里相当能打后端 Node.js 扛住接口和业务逻辑前端 Vue 负责交互页面的快速迭代两边又都是 JavaScript团队协作的沟通成本低到可以忽略。系统做完之后员工档案管理、工资项配置、月度算薪、审核发放、历史明细查询、报表导出整个流程都能在一个系统里跑通。如果你正好在做技术选型或者想拿一个真实项目练手 Vue 和 Node.js这篇文章值得你耐心看完。我打算把整个项目从需求梳理、技术选型、环境搭建、后端接口、前端页面到常见坑位完整拆开讲一遍。里面大部分内容是我实际编码和排障过程中的记录属于那种“网上查得到但不会有人系统讲过”的经验。1. 这个工资管理系统到底要解决什么问题1.1 传统工资管理方式的痛点在没有这套系统之前这家企业的工资核算基本就是靠三样东西Excel 表格、微信聊天记录和财务的个人记忆。每个月算薪的时候人事把考勤记录导出来发给财务财务再对着员工基础工资表手动核算加班费、绩效、社保扣款每一项都得手工处理。这种模式的毛病特别典型。第一Excel 文件在多人之间传来传去版本容易错乱经常出现两个人手里的工资表对不上数。第二公式嵌套稍微复杂一点就有人不小心拖错单元格错误还特别难排查往往是工资都发出去了才发现问题。第三工资数据是极其敏感的信息但用聊天工具传文件全程没有访问控制和操作留痕风控上完全不可控。所以客户提需求的时候核心诉求其实就一句话把每个月算工资这个“手工流水线”变成一条可追溯、权限分明的系统流程。要求倒不复杂但非常看重明细留痕和审批闭环。1.2 核心功能模块拆解我把需求梳理成下面几个模块后面所有开发都是围绕这个清单展开的员工档案管理维护员工基本信息、入职日期、部门岗位、薪资标准支持离职员工归档。部门与岗位管理树形结构工资计算时按部门进行汇总和权限过滤。考勤与工时数据接入支持导入 Excel 考勤表也能通过接口对接考勤机数据。工资项配置自定义工资组成比如基本工资、绩效奖金、餐补、交通补贴、社保、公积金、个税。月度工资计算按月份生成工资单系统根据配置的工资项自动汇总计算。审核与发放工资单生成后需要主管和财务两级审核确认后标记为已发放。历史记录与明细查询员工可查看个人历史工资明细管理员可查看全员记录。报表统计与导出月度工资总额、部门人力成本、年度薪资趋势等统计支持导出。多级权限控制员工、部门主管、财务、系统管理员四种角色数据权限按部门和操作权限双重隔离。这里有个容易被忽略的点工资系统不像普通 CRUD 系统那样“能增删改查就行”它的核心是计算规则和状态流转。工资单从生成、试算、提交、审核、发放到归档每一步都要有状态和操作日志。我在表设计阶段就专门留了一个salary_log表来记录所有审核和变更动作这后来在客户对账的时候帮了大忙。2. 技术选型为什么偏偏是 Node.js Vue2.1 后端选型的心路历程客户一开始问我能不能用 Spring Boot我承认 Java 社区很成熟Spring Boot 也确实稳。但考虑实际情况这家企业内部系统并发极低核心场景是多人同时操作、I/O 密集而非 CPU 密集业务逻辑以增删改查和计算为主。Node.js 的事件驱动模型在这种场景下完全够用而且轻得多。更现实的一点是这家企业没有专门的 Java 团队前端倒是有人写过 Vue。如果上 Spring Boot前后端代码各一种语言小团队维护起来等于摊了两份技术债。统一用 JavaScript/TypeScript人力盘活、知识复用新人也更容易上手。我当时给客户算了一笔账用 Node.js 开发同样的接口量能省下差不多三分之一的开发时间。当然Node.js 不是没有短板。如果你后面要做大量 CPU 密集计算比如跑复杂的工资税优算法或者海量数据的聚合单线程模型就会有瓶颈。但对于几百人的员工规模读一版工资表也就几万行数据库索引建好响应时间基本在几十毫秒以内。这个体量的项目选 Node.js 完全撑得住。2.2 Vue 在前端承担的角色前端选 Vue 的理由可能更直白组件化开发让页面复用度特别高一个“员工基本信息表单”组件在新增、编辑、详情三个地方都能用响应式数据绑定让工资试算的交互特别好做前端改一个数值页面自动重新汇总不需要手写 DOM 操作。Vue 生态里的三个标配我这次全用上了Vue Router负责页面路由和路由守卫实现登录拦截和动态权限路由。Pinia替代 Vuex 做状态管理集中维护用户信息、权限标识和全局配置。Element Plus组件库表格、表单、对话框、日期选择器这些企业后台常用组件开箱即用省下大量样式时间。我用 Vite 作为构建工具比起旧版的 Vue CLI冷启动速度快了不止一个档次。开发的时候保存代码页面一两秒就能热更新那种“等一下、再等一下”的频率明显下降了。2.3 系统整体架构设计整个系统的架构并不复杂走的是典型的前后端分离 集中式数据库路线前端Vue 3 单页应用部署时构建出静态文件由 Nginx 托管。后端Node.js 使用 Express 框架提供 RESTful API按模块拆分路由。数据库MySQL 5.7存员工、部门、工资单、工资项、操作日志等业务数据。认证方式JWT Token后端签发和校验前端存在内存和 localStorage并在 Axios 拦截器里统一注入请求头。这里有一个我特别坚持的设计前后端通过接口契约沟通。开发前先用 Apifox 定义好所有接口的请求和响应结构前端按 mock 数据开发后端按真实逻辑实现。两边同时开工到了联调阶段基本上没有“字段对不上”这种扯皮事。3. 开发环境搭建与踩坑实录3.1 Node.js 安装与环境变量配置环境这块看着简单但根据我这些年带新人的经验十个新手有八个卡在 Node.js 安装和环境配置上。这里把标准操作整理一遍。Windows 下直接去 Node.js 官网下载 LTS 版本安装包一路 Next 就行。安装完成后打开命令行验证node -v npm -v如果提示“node 不是内部或外部命令”说明环境变量没配好。手动加上两个路径一个是 Node.js 的安装目录比如D:\Program Files\nodejs\另一个是全局模块目录%APPDATA%\npm。配置完记得重启终端。国内开发者大概率会遇到 npm 下载依赖慢的问题建议第一件事就是把镜像源切到国内npm config set registry https://registry.npmmirror.com另外一个新手极其容易踩的坑是npm.ps1 无法加载文件的报错典型提示是这样的npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本这不是 Node.js 装坏了而是 Windows PowerShell 的默认执行策略限制了脚本运行。解决方案有两个要么用管理员身份给当前用户放行要么以后都用 cmd 而不是 PowerShell 跑命令。放行命令Set-ExecutionPolicy -Scope CurrentUser RemoteSigned我自己的习惯是直接设置RemoteSigned既保证本地脚本可以运行又不影响系统级策略比较折中。3.2 用 Vite 创建 Vue 项目创建 Vue 项目我强烈建议用官方的脚手架命令很简单npm create vuelatest这个脚手架会问你需不需要 TypeScript、Vue Router、Pinia、ESLint按需勾选就行。创建完项目后安装依赖npm install npm install element-plus npm install axios项目目录我会做一点规划不是脚手架默认结构拿来就用src/views按业务模块分页面比如employee、salary、report。src/components通用组件比如员工选择器、部门树、导出按钮。src/api接口封装一个模块对应一个文件全部导出函数。src/storePinia 的 store 文件。src/router路由配置和守卫逻辑。这里要特别提一下Vue Devtools 插件。调试 Vue 项目的状态和组件层级时这个浏览器扩展能帮你省下大量console.log的时间。它支持查看组件 props、响应式数据、Pinia 的 store、Vue Router 的路由记录基本是目前调试 Vue 3 项目的必备工具。3.3 MySQL 表结构设计的几个关键点工资系统的表设计没有高深的东西但有几个细节我特别留意。核心表大致如下表名说明关键字段employee员工档案id, name, department_id, position, base_salary, hire_date, statusdepartment部门表id, name, parent_idsalary_item工资项配置id, name, type(收入/扣款), calc_type(固定/按比例), valuemonthly_salary月度工资单id, employee_id, month, total_amount, status, audit_by, paid_atsalary_detail工资明细id, salary_id, item_id, item_name, amountsalary_log操作日志id, salary_id, action, operator_id, remark设计时的三个原则工资明细单列存把每一个工资项的金额拆到独立行方便后面做对账和追溯。不推荐把几十个工资项设计成几十个字段那会让表非常臃肿而且工资项配置是动态的。金额字段用 DECIMAL 而不是 FLOAT/DOUBLEMySQL 里 DECIMAL(10,2) 可以精确存储两位小数不会出现浮点误差。这个在工资系统里是底线问题差一分钱客户都要找你。状态字段用 TINYINT比如 0草稿、1待审核、2已审核、3已发放、4已作废。每个状态流转写进日志表保证全程可追溯。4. 后端核心模块实现4.1 JWT 登录认证与权限控制后端我用的 Express登录接口的流程是前端提交用户名密码后端校验通过后返回 JWT Token。密码存储使用bcryptjs做哈希绝不存明文。const jwt require(jsonwebtoken); const bcrypt require(bcryptjs); // 登录成功签发 token const token jwt.sign( { userId: user.id, role: user.role }, process.env.JWT_SECRET, { expiresIn: 12h } );用户权限我用了一个非常实用的设计角色 接口清单。每个角色在数据库里对应一组允许访问的接口标识请求进入时中间件校验function checkPermission(action) { return (req, res, next) { const { role, permissions } req.user; if (!permissions.includes(action)) { return res.status(403).json({ message: 没有操作权限 }); } next(); }; }其中permissions是登录成功之后从库里查出、挂在用户对象上的。这种方案比单纯判断角色灵活得多因为以后如果需要“财务可以修改工资项但主管不行”这种细粒度控制直接在权限配置里加一项就行不用改代码。4.2 工资计算引擎的实现思路工资计算是这套系统的灵魂我把它设计成了可配置的“规则脚本”而不是写死的一堆 if else。工资总额的计算逻辑大致是应发工资 基本工资 岗位津贴 绩效奖金 加班费 餐补 补贴项 实发工资 应发工资 - 社保个人部分 - 公积金个人部分 - 个税 - 其他扣款后端在生成月度工资单时会遍历每个员工的工资项配置按类型计算for (const item of salaryItems) { let amount 0; if (item.calc_type fixed) { amount item.value; } else if (item.calc_type by_salary) { amount Math.round(employee.base_salary * item.value); } else if (item.calc_type by_attendance) { amount Math.round(attendanceCount * item.value); } // 写入 detail... }工资计算最怕浮点丢精度。JavaScript 的0.1 0.2不等于0.3这是老生常谈但工资系统里可不止发生在加减法上。我的处理方式是统一使用整数分来运算也就是说所有金额在计算过程中都乘以 100转成整数最后再除以 100。或者引入一个decimal.js这样的库。实测下来用整数分是最简单不引入额外依赖的方法。另一个容易坑到人的点是个税的前后端一致性。前端试算展示一个预估值后端正式计算是最终值这两个值必须用同一套算法。我的做法是把个税计算函数单独抽出来后端实现一份前端也封装一份同样的工具函数避免联调的时候两边各算各的。4.3 报表统计与 Excel 导出功能Excel 导出我用的库是exceljs它对样式控制比老牌的node-xlsx细腻很多可以设置表头合并、单元格边框、列宽导出的表格客户直接能拿去存档不需要二次调整。const ExcelJS require(exceljs); const workbook new ExcelJS.Workbook(); const sheet workbook.addWorksheet(月度工资表); sheet.columns [ { header: 工号, key: employeeNo, width: 15 }, { header: 姓名, key: name, width: 15 }, { header: 基本工资, key: baseSalary, width: 15 }, ]; // 填充数据 await workbook.xlsx.writeFile(monthly_salary.xlsx);这里有个小坑如果导出接口直接返回文件流给前端临时文件必须及时清理不然跑上一段时间服务器磁盘就被 Excel 文件塞满了。我后来改成接口直接返回 Buffer前端拿到文件流让浏览器下载服务端不落盘彻底规避了这个隐患。5. 前端核心页面实现5.1 权限控制与动态路由前端权限控制是工资系统里相对繁琐的一部分。我的做法是登录成功拿到用户信息和权限列表后把可访问的路由动态添加到 Vue Router 里。路由表先分成两部分一部分是所有角色都能访问的基础路由剩下的是需要权限的动态路由。// 路由守卫 router.beforeEach((to, from, next) { const token localStorage.getItem(token); if (!token to.path ! /login) { next(/login); } else { next(); } });这样处理之后你在地址栏里直接输入一个没有权限的路径会被前端拦截根本渲染不了对应页面。当然后端接口的权限校验依然要做前端路由守卫只是提升体验和减少无意义的请求。除了路由控制我还写了一个按钮级权限的自定义指令v-permission比如工资“审核”按钮只有财务角色才能显示。这个细节客户很满意因为他们原来的 Excel 流程里任何人拿到文件都能看全部工资现在连界面上都不会露出不该看到的操作入口。5.2 核心业务页面拆解员工管理页面是系统里最常规的 CRUD 页面但它有一个设计细节值得说列表按部门树联动过滤。左侧是一棵部门树右侧是员工表格点击部门节点自动按当前部门及其子部门过滤员工。实现上后端接口接收一个departmentId参数在 SQL 里递归查子部门。MySQL 8.0 支持递归 CTE写起来很顺手WITH RECURSIVE sub_depts AS ( SELECT id FROM department WHERE id ? UNION ALL SELECT d.id FROM department d INNER JOIN sub_depts s ON d.parent_id s.id ) SELECT * FROM employee WHERE department_id IN (SELECT id FROM sub_depts);月度工资计算页面是交互最复杂的页面。先选月份点“生成工资单”后端开始批量为该月所有在职员工生成工资单记录生成之后前端表格立即刷新出每人应发、实发金额的试算结果薪资项可以点击展开查看明细。前端做了一件比较讨巧的事情不把试算结果提交到后端而是就地用本地计算的方式做“前端试算”等用户确认无误后再点“确认提交”把所有结果一次性交给后端。这么做的好处是人事可以随便调整绩效值实时看计算结果只有最终确认那一步才会真的写入数据库。统计报表页用了 ECharts 做数据可视化主要是三个图月度应发工资总额柱状图、部门人力成本饼图、年度薪资增长趋势折线图。数据来源是后端聚合好的报表接口一次请求返回所有图表所需数据。5.3 状态管理与请求封装Vue 3 项目我用 Pinia 管理全局状态一个典型的userStoreexport const useUserStore defineStore(user, { state: () ({ token: localStorage.getItem(token) || , userInfo: null, permissions: [], }), actions: { setLogin(data) { this.token data.token; this.userInfo data.userInfo; this.permissions data.permissions; localStorage.setItem(token, data.token); }, logout() { this.token ; this.userInfo null; this.permissions []; localStorage.removeItem(token); }, }, });请求封装的核心在 Axios 拦截器里。请求拦截器统一注入 Token响应拦截器统一处理 HTTP 401token 过期跳登录页和业务错误码弹出错误提示。这一层做扎实之后业务代码里请求接口只需要一行调用错误处理完全不用业务侧操心。6. 常见问题排查与开发技巧实录6.1 npm 脚本执行权限报错这个问题的出现频率实在太高了几乎每带一个新人就会遇到一次。报错信息基本是这种npm : 无法加载文件 D:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本根本原因是 PowerShell 默认的Restricted策略不允许执行.ps1脚本文件npm 的启动脚本正是.ps1。处理办法是打开 PowerShell执行Set-ExecutionPolicy -Scope CurrentUser RemoteSigned这里科普一下RemoteSigned的含义本地创建的脚本可以运行从网上下载的脚本需要签名。日常开发这样设置足够安全不要图省事直接设成Unrestricted。如果你不想动 PowerShell 的安全策略另一个很实用的办法是命令行工具改用 cmd命令提示符cmd 不受 PowerShell 执行策略影响直接用npm命令没有任何问题。我之前遇到客户那就是这样妥协的后面反正也不影响开发。6.2 Node 版本带来的兼容性问题Node.js 版本迭代很快很多老项目依赖库和新版本 Node 之间存在兼容性问题。最常见的一幕就是执行npm install报 ERESOLVE 错误比如npm ERR! ERESOLVE unable to resolve dependency tree这个错误多数情况是依赖版本冲突不是代码写错了。一个迅速排查的思路是先删掉node_modules和package-lock.json再重新安装如果还不行就用 npm 的 legacy 模式npm install --legacy-peer-deps我在实际开发中更推荐另一个做法用 nvm-windows 做 Node 版本的灵活切换。一个项目用 Node 16另一个项目用 Node 18随时切换互不干扰。说实话装上 nvm 之后我基本没有再手动安装过 Node。6.3 前后端联调时的 CORS 和代理问题前后端分离开发的时候前端跑在localhost:5173Vite 默认端口后端跑在localhost:3000只要前端发请求跨域就出现了。后端虽然可以配置 CORS 中间件放行但更标准、更接近生产环境的做法是前端开发环境通过 Vite 代理转发请求。在 Vite 项目根目录的vite.config.js里配置export default defineConfig({ server: { proxy: { /api: { target: http://localhost:3000, changeOrigin: true, }, }, }, });前端请求/api/salary/listVite 自动转发到http://localhost:3000/api/salary/list同一个源下通信没有跨域没烦恼。生产环境则用 Nginx 起一个反向代理把/api指到 Node 服务逻辑一模一样。这里还送大家一个经验联调阶段接口字段命名风格必须统一。后端返回employee_name前端偏用employeeName两边的转换就够你喝一壶。我们的约定是后端统一返回小驼峰命名数据库字段的下划线映射工作全部后端消化前端拿到什么就是什么不折腾。6.4 工资数据的精度与安全细节精度问题我再强调一次工资系统所有的金额字段在后端和数据库层都不能出现浮点类型这个在前文讲过但是值得单独拿出来再提醒一遍。我见过有同事在 MySQL 里把金额字段建成了DOUBLE工资算到后期对不上账排查了两个小时才发现是精度问题。用DECIMAL(10,2)是最稳妥的选择。安全方面有三个细节容易被新手忽略登录接口必须做防暴力破解连续失败次数达到 N 次锁定一段时间。工资明细查询接口要做数据权限校验不能让员工传一个employeeId就把别人的工资看走了。导出 Excel 的文件名不要直接用员工姓名拼路径避免路径穿越和中文乱码。7. 最后分享几点真实体会这套系统从需求梳理到上线前后花了大约三周时间。我个人比较满意的地方并不是界面有多炫酷而是把每个月财务最头疼的“对账”这件事彻底消掉了——现在工资单一旦审核任何人改不了每次操作都有日志财务月底再也不用拿着 Excel 一遍一遍做 sum。如果你也想动手复刻一套类似的系统我的建议是从小的边界开始先跑通员工管理 工资项配置 月度工资生成这一个闭环再去加报表、权限、审核这些外围功能。技术栈就按 Node.js Vue 3 MySQL 这套来对新人友好上线也轻快。最后再分享一个小技巧数据库备份一定要自动化。我后来给这套系统加了一个每天凌晨的定时任务自动备份数据库并保留最近 30 天的备份文件。工资数据这东西丢了可没人赔得起。
