做连锁超市生鲜配货管理系统有几个东西是绕不过去的生鲜非标品怎么管、多门店的订货需求怎么汇总、每隔一天甚至每天一次的高频配货怎么保证不出错。这些问题用 Excel 和微信群解决门店少了还行门店一多分分钟变成一场灾难。所以当我拿到这个“vue nodejs ElementUi 的华联连锁超市生鲜配货管理系统”的需求时第一反应就是这其实不是一套简单的增删改查而是一套围绕“损耗、时效、协同”三个关键词设计的业务系统。这篇文章我会从需求拆解、技术选型、库表设计、核心模块实现到部署运维把我踩过的坑和验证过的方案一次性讲清楚。技术栈是 Vue 2 Node.jsExpress Element UI MySQL整体都比较主流哪怕你只负责其中一个端这篇文章也能帮你少走不少弯路。1. 整体设计与核心需求拆解1.1 生鲜配货的业务链路到底长什么样生鲜配货和普通商品配货最大的区别在于生鲜有自己的“生命时钟”。蔬菜水果放一天可能就折价一半冷鲜肉对温度极其敏感水产更是必须全程冷链。所以生鲜配货系统的业务链路本质上是在跟时间和损耗赛跑。标准链路是门店提交配货申请 → 总部或配送中心汇总审核 → 生成配货单 → 仓库按单拣货 → 复核装车 → 司机配送 → 门店验收签收 → 系统回写入库。听起来不复杂但每个环节都有“坑”。拿“门店提交配货申请”这一步来说门店店长不是一次只申请一种商品而是几十上百种品项一次提交不是所有品项都有历史订单可参考新品和季节性商品经常只能靠经验填量不是所有门店的库存口径都一致有的门店早上盘一次点有的门店晚上才盘。这些业务细节直接决定了后面数据库怎么设计、接口怎么定义、前端表单怎么组织。这套系统我做的时候把业务拆成几个核心对象门店Store、商品Goods、配货申请单DistributionOrder、配货明细DistributionOrderItem、门店库存StoreInventory、系统用户User。后面所有功能的开发都围绕这几个对象展开。1.2 技术选型为什么偏偏是 Vue Node.js Element UI这个项目选型其实没什么值得纠结的但我还是想说说我的判断逻辑毕竟技术选型决定了后面几个月写代码的体验。前端选 Vue 2 Element UI是因为这个组合在后台管理系统领域太成熟了。Element UI 的开箱即用组件表格、表单、日期选择器、弹窗、分页几乎把后台系统 80% 的通用交互都覆盖了。对于生鲜配货系统来说最核心的交互不是炫酷的图表而是“多条件下单”、“表格快速录入”、“配货单明细核对”这类强表单场景Element UI 在这方面的表现非常稳定。Node.js 做后端主要是看重它和前端同语言带来的心智统一。前端写 JavaScript后端也写 JavaScript处理 JSON 数据的时候不需要任何序列化转换接口联调效率高很多。再加上 Express 框架非常轻量对于这种单体业务系统来说完全够用。可能有朋友会问为什么不用 Java 或者 PHP说实话技术上没有对错只有合不合适。Java 在复杂事务和安全性上有优势PHP 在传统 cms 场景很顺手但这个项目的核心是中小规模连锁超市的内部管理系统Node.js 的异步 I/O 模型处理并发请求并不差开发效率却高很多。尤其前端本来就是 Vue 写出来的后端再用 Node.js整个项目从部署到维护一个人就能完整 hold 住。1.3 系统模块划分与角色权限设计系统做得好不好用很大程度上取决于角色和权限设计。这套系统我在设计初期就明确了四种角色系统管理员维护门店、商品、用户等基础数据配置系统参数。总部配货管理员审核门店申请、生成配货单、查看全部门店配货记录。门店店长/订货员维护自己门店的配货申请、确认收货、查看门店库存。仓库发货员查看待拣货清单、更新发货状态、打印配货单。这四类角色不是随便定的是顺着业务链路一条一条捋出来的。每个角色对应的权限边界必须清楚门店只能操作自己的数据总部可以看全局仓库只关心发货环节。这个权限划分既能保证业务推进顺畅也能在出问题的时候快速定位责任环节。权限控制的实现我采用了前端路由守卫加后端中间件双重校验。前端根据角色动态生成菜单后端每个接口校验 token 中的角色信息两边都不松口。别觉得这是重复劳动前端控制是为了体验后端控制才是安全底线。2. 数据库设计与后端核心接口实现2.1 数据库设计把所有业务关系理清楚数据库设计是这套系统里最需要耐心的一步。我第一次画表的时候潦草了结果后面写业务逻辑时反复改表结构返工成本极高。这里把最终稳定的表结构分享出来。门店表store核心字段包括门店ID、门店编码、门店名称、地址、联系人、联系电话、状态营业/停业、创建时间。商品表goods则包含商品ID、商品编码、商品名称、分类蔬菜/水果/肉禽/水产/乳品/熟食、规格单位、参考进价、参考售价、保质期天数、是否称重商品、状态、创建时间。配货模块是我重点设计的。配货申请单主表distribution_order字段包括配货单号、申请门店ID、单据状态待审核/已审核/已发货/已收货/已取消、申请日期、期望送达日期、申请人ID、审核人ID、审核时间、备注。配货单明细表distribution_order_item包含ID、配货单ID、商品ID、申请数量、审核数量、实发数量、验收数量、单价、金额、备注。门店库存表store_inventory字段为ID、门店ID、商品ID、在库数量、在途数量、安全库存、最后盘点时间、更新时间。最后是用户表user包含用户ID、用户名、密码bcrypt加密存储、真实姓名、手机号、角色ID关联角色表、所属门店ID、状态、创建时间。注意到“配货单号”我单独设计成了业务字段而不是直接用自增ID。因为门店和仓库的员工经常要在电话里沟通配货单号一个像”PS20250101001”这样的单号比数字ID好记得多也方便按日期检索。2.2 RESTful API 设计前后端联调的基本盘RESTful API 设计看似简单但真正做得好的项目不多。核心原则是资源用名词操作用 HTTP 方法。这套系统最重要的几个 API 如下GET /api/stores 门店列表分页、条件查询 POST /api/stores 新增门店 PUT /api/stores/:id 修改门店信息 GET /api/goods 商品列表按分类/关键词查询 POST /api/goods 新增商品 POST /api/distribution/apply 门店提交配货申请 GET /api/distribution/list 配货单列表多条件查询 GET /api/distribution/:orderNo 配货单详情主表明细 PUT /api/distribution/:orderNo/audit 审核配货单 PUT /api/distribution/:orderNo/ship 发货 PUT /api/distribution/:orderNo/receive 门店收货确认 GET /api/inventory/store/:storeId 查询某门店的库存 PUT /api/inventory/:id/adjust 库存调整报损/盘盈配货单列表接口的设计要特别注意因为它是整个系统里查询频率最高、条件组合最复杂的接口。我最终的查询条件设计是配货单号模糊搜索、门店ID精确匹配、单据状态精确匹配、申请日期区间查询、分页参数。排序默认按申请时间倒序这个默认值看着简单但实际中如果不加用户会觉得列表“乱乱的”。2.3 Node.js 后端关键代码生成配货单的核心逻辑配货单的生成是整个系统业务规则最密集的部分也是我花心思最多的地方。核心流程是总部审核通过门店的申请后系统要自动为配货单生成唯一的单号并将明细状态从“待审核”更新为“已审核”。生成单号的逻辑我放在服务层用了一个比较稳妥的方式取当前日期再加当天流水号。// 生成配货单号: PS 年月日 三位流水号 async function generateOrderNo(date new Date()) { const yyyy date.getFullYear(); const mm String(date.getMonth() 1).padStart(2, 0); const dd String(date.getDate()).padStart(2, 0); const prefix PS${yyyy}${mm}${dd}; const count await DistributionOrder.count({ where: { orderNo: { [Op.like]: ${prefix}% } } }); return ${prefix}${String(count 1).padStart(3, 0)}; }审核接口的业务逻辑是这样的接收订单号后先检查订单状态必须是“待审核”否则直接返回错误然后逐条检查商品是否存在、是否停用接着计算总金额最后用事务将主表和明细表一起更新。exports.auditOrder async (ctx) { const { orderNo } ctx.params; const t await sequelize.transaction(); try { const order await DistributionOrder.findOne({ where: { orderNo, status: 待审核 }, transaction: t }); if (!order) { throw new Error(订单不存在或状态不允许审核); } const items await DistributionOrderItem.findAll({ where: { distributionOrderId: order.id }, transaction: t }); // 校验商品是否有效 for (const item of items) { const goods await Goods.findByPk(item.goodsId, { transaction: t }); if (!goods || goods.status ! normal) { throw new Error(商品[${item.goodsName}]不存在或已停用); } } await order.update({ status: 已审核, totalAmount: items.reduce((sum, i) sum Number(i.amount), 0), auditTime: new Date() }, { transaction: t }); await t.commit(); ctx.body { code: 0, message: 审核成功 }; } catch (err) { await t.rollback(); ctx.body { code: 1, message: err.message }; } };采购入库的时候要记得生成库存流水这样每一笔库存变动都有据可查。库存流水表inventory_log字段包括ID、门店ID、商品ID、变动类型入库/出库/报损/盘点、变动数量、关联单号、操作人ID、操作时间、备注。2.4 数据库事务别让数据不一致毁掉整个系统做管理系统的人最容易犯的错误就是忽略数据库事务。配货单审核、发货、收货这些操作每一步都涉及主表和明细表的同时更新如果不加事务一旦某一步失败就会出现“主表已审核明细还是待审核”这种莫名其妙的数据不一致问题。Node.js 中使用 Sequelize 操作 MySQL事务代码其实很简单。把所有需要原子性执行的操作包在同一个 transaction 里全部成功后统一 commit任何一步出错就 rollback保证数据要么全变要么全不变。另外一个常见的坑不要把业务校验放在数据库事务外面。比如审核的时候先查了订单状态然后才开启事务更新的时候发现状态已经被别人改过了。正确做法是先开启事务再在事务里查询并锁定该行记录防止并发情况下超卖或重复审核。// 在事务内加行锁防止并发重复审核 const order await DistributionOrder.findOne({ where: { orderNo, status: 待审核 }, transaction: t, lock: t.LOCK.UPDATE });很多新手程序员对事务不以为然觉得“我逻辑简单不会出问题”。但当系统真正上线多个门店同时在早高峰提交配货申请的时候并发问题就会接踵而至。3. 前端实现与 Vue Element UI 项目搭建3.1 前端工程化和项目结构设计Vue 前端这块项目的可维护性很多时候从目录结构就能看出来。我把目录统一规划为src/ -- api/ # 接口请求统一封装 -- assets/ # 静态资源 -- components/ # 通用组件 -- router/ # 路由配置 -- store/ # Vuex 状态管理 -- utils/ # 工具函数 -- views/ -- store/ # 门店管理模块 -- goods/ # 商品管理模块 -- distribution/ # 配货管理模块 -- inventory/ # 库存管理模块 -- dashboard/ # 数据看板 -- login/ # 登录页面每个业务模块下再细分 list、detail、edit 等页面文件。这样做的核心目的是不同角色进入系统后根据菜单权限动态加载路由前端代码就能天然地按照业务模块隔离。3.2 axios 请求封装与 token 身份认证axios 封装是前端每个项目的必做项。生鲜配货系统的接口调用频率很高而且接口返回格式统一我更倾向于在请求层统一处理错误提示而不是在每个页面里 try...catch 一遍。// utils/request.js import axios from axios; import { Message } from element-ui; import router from /router; const service axios.create({ baseURL: process.env.VUE_APP_BASE_API, timeout: 15000 }); service.interceptors.request.use(config { const token localStorage.getItem(token); if (token) { config.headers[Authorization] Bearer ${token}; } return config; }); service.interceptors.response.use( response { const res response.data; if (res.code ! 0) { Message.error(res.message || 请求失败); return Promise.reject(new Error(res.message)); } return res.data; }, error { if (error.response error.response.status 401) { Message.error(登录状态已过期请重新登录); localStorage.removeItem(token); router.push(/login); } else { Message.error(网络异常请稍后重试); } return Promise.reject(error); } ); export default service;之所以要把拦截器写得这么“啰嗦”是因为在实际业务中门店店长和仓库员工大多不是技术人员给他们弹一个”401”或者”服务器错误”是没有意义的。统一拦截、统一提示、统一跳转才能保证系统的可用性。3.3 配货申请页复杂表单的交互实现配货申请页是整个前端最复杂的页面。门店的配货申请往往涉及几十个品项每个品项都有申请数量、备注等字段。技术上我用 Element UI 的表格组件来实现品项填写的交互。每次新增一条商品就向表格的数据源 push 一条记录。el-table :dataform.items border el-table-column label商品编码 propgoodsCode width120/el-table-column el-table-column label商品名称 propgoodsName min-width160/el-table-column el-table-column label单位 propunit width80/el-table-column el-table-column label参考进价 propprice width100/el-table-column el-table-column label申请数量 width140 template slot-scope{ row } el-input-number v-modelrow.applyQuantity :min1 :max9999 sizesmall / /template /el-table-column el-table-column label备注 min-width180 template slot-scope{ row } el-input v-modelrow.remark sizesmall placeholder选填如要新鲜一点的 / /template /el-table-column el-table-column label操作 width80 template slot-scope{ $index } el-button typedanger sizemini clickremoveItem($index)删除/el-button /template /el-table-column /el-table有几个交互细节很重要。第一商品选择的弹窗必须支持按分类筛选和关键词搜索几十种商品靠翻页找是不现实的第二一旦用户填写了申请数量校验规则要立即触发提示数量是否超出安全库存或历史日均销量的合理范围第三提交前必须二次确认因为一次配货申请可能涉及几万块的生鲜货值点错一个按钮后果很严重。3.4 Element UI 表格固定列变透明的坑与修复这个坑我必须单独拿出来讲因为很多读者就是搜到这个问题才点进来的。Element UI 的表格在设置fixed固定列之后偶尔会出现一个诡异的现象固定列区域变成半透明底下的文字透上来完全没法看。原本清晰的表格变成视觉灾难。这个问题的根源是表格渲染时固定列和滑动区域各自生成了独立的层而两个层在滚动渲染的过程中出现了样式污染。解决办法也很直接在全局样式里强制给固定列加上不透明的背景.el-table__fixed, .el-table__fixed-right { background-color: #fff !important; box-shadow: none !important; }但是如果你的表格有斑马纹stripe效果这个方案就不够了因为斑马纹本身的底色会在滚动时错位。这种情况处理起来麻烦一些我的临时方案是去掉表格斑马纹就纯白底色加分隔线反而更干净。如果你一定要保留斑马纹就不要用fixed列而是用多个表格拼合的方式或者在数据量可控的情况下关闭fixed直接用横向滚动。说实话配货单明细几十行数据横向滚动完全够用固定列更多是心理上的舒适不是功能上的必须。4. 项目搭建过程中的坑与排查实录4.1 npm 脚本执行权限问题npm.ps1 无法加载这个错很多用 Windows 系统做 Node.js 开发的朋友第一次运行npm run dev就会遇到一串红字报错npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本。这个问题的原因是 Windows 默认的 PowerShell 执行策略是Restricted禁止运行任何.ps1脚本文件而新版 Node.js 安装器安装的 npm 命令本质上就是一个 .ps1 脚本文件所以被系统拦截了。解决方案有两个。最简单粗暴的是以管理员身份打开 PowerShell运行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser执行之后输入Y确认然后再重新打开终端运行 npm 命令就正常了。RemoteSigned表示本地创建的脚本可以运行从网上下载的脚本必须有可信签名才能运行这个策略比完全放开安全得多。网上有人建议直接用Set-ExecutionPolicy Unrestricted我不建议这么做太危险。还有人说可以删除 npm.ps1 改用 npm.cmd治标不治本同一个终端下很多构建工具还是会去调 .ps1 脚本。所以安全又有效的方案就是RemoteSigned。4.2 Node.js 版本与安装环境配置的细节Node.js 的版本选择我建议不要追新。很多朋友一上来就装最新版 Node.js 20结果老项目跑不起来新项目依赖装不上各种报错。从我的实践经验看开发 Vue 2 Element UI 项目Node.js 14 到 16 这两个大版本是比较稳的选择。Node.js 17 及以上版本对 OpenSSL 的处理方式变了经常导致老项目在启动或构建时出现error:0308010C:digital envelope routines::unsupported这样的报错。这个报错的解决办法其实也简单设置环境变量NODE_OPTIONS--openssl-legacy-provider就能绕过但与其折腾这个不如直接装一个稳定版本。安装 Node.js 的时候还要注意环境变量的配置。Windows 下如果你用安装包默认路径安装装完系统会自动把C:\Program Files\nodejs加进 PATH一般没问题。但如果你在安装过程中改了路径就要手动去系统环境变量里把 Node.js 的安装目录加进 PATH否则命令行里永远找不到node命令。如果公司电脑没有管理员权限可以用免安装版。去 Node.js 官网下载 zip 包解压后把 bin 目录加进 PATH再自己配一下 npm 的全局缓存路径就能正常使用。这个方式还特别适合在腾讯云、阿里云的 Windows 服务器上部署——不需要图形界面解压就能跑。4.3 跨域问题处理前后端分离的联调拦路虎前后端分离开发的时候本地联调必须处理跨域问题。如果前端跑在 8080 端口后端跑在 3000 端口前端直接发请求是会被浏览器拦截的。最优雅的解决办法是在 Vue CLI 的 devServer 里配置代理让前端把请求代理到后端接口从而绕过浏览器的跨域策略。在vue.config.js中这样配置module.exports { devServer: { proxy: { /api: { target: http://localhost:3000, changeOrigin: true, pathRewrite: { ^/api: /api } } } } };上线部署的时候则让 Nginx 把/api前缀的请求反向代理到 Node.js 服务这样前后端在同一个域名下自然没有跨域问题。记住一个原则跨域问题的最终解决是靠服务器端代理不要在 Node.js 里粗暴地设置Access-Control-Allow-Origin: *除非你真的不在乎安全问题。4.4 Element UI 表格大数据量渲染卡顿的优化生鲜配货系统里有一个非常具体的性能问题总部查看全部门店配货记录时表格一次性渲染几百上千条数据Element UI 的表格会出现明显卡顿滚动不流畅输入框还有延迟。这个问题本质上是 DOM 节点太多导致的。优化方案有三种第一接口层做分页每次只查20条这是最简单也最有效的方式。真实业务里几乎没人会一页看完所有配货记录都是从近到远筛选查询。第二如果一定要跨页面操作数据用懒加载。Element UI 的 Table 可以配合el-table的row-key和load方法实现树形懒加载子级数据在点开时才请求。第三减少列的渲染数量。配货单列表没必要把所有字段都展示出来把“金额”、“备注”这些低频字段放进详情弹窗里列表更清爽渲染压力也小。我实际项目里三种方案组合使用列表页分页一页20条详情用抽屉组件异步加载所有金额和备注类信息都在详情里展示。上线后测试接口响应在 200ms 内页面滚动流畅不卡顿。4.5 生成配货单时的并发重复问题前面也提到过生鲜配货单的高频使用场景就是每天早晨。几十家门店可能会集中在同一时间段提交配货申请后台审核也集中在这个时间段。这就带来一个并发问题如果多个门店同时对同一个商品提交申请可能导致库存超卖或者配货重复。解决方式是采用数据库的乐观锁加唯一索引。在门店配货申请表中对“门店配货日期配货状态”建立唯一索引ALTER TABLE distribution_order ADD UNIQUE KEY uk_store_date (store_id, apply_date, status);同时在商品库存表上增加一个版本号字段version更新库存时校验版本号是否一致UPDATE store_inventory SET quantity quantity - #{buyNum}, version version 1 WHERE store_id #{storeId} AND goods_id #{goodsId} AND version #{oldVersion}这两层保障加在一起基本杜绝了并发重复配货的问题。这也是很多新手做管理系统时最容易忽略的一个点——在“看起来没多少人用”的系统里并发问题往往不会出现在测试环境只有在真实业务高峰期才会突然爆发。5. 库存管理与生鲜损耗的关键设计5.1 库存变动的正负记账模型生鲜库存管理的难点在于“账实相符”。蔬菜水果每天有自然损耗员工操作也可能出现盘点差异如果只存一个库存数字时间一长账面数字必然失真。我在设计库存模块时采用了正负记账的流水模式。每一次库存变化都记录一条流水库存表上的数字永远等于“所有流水的汇总值”而不是被直接改来改去的值。这样财务对账、损耗分析、库存追溯都有据可查。每一个入库或出库操作都必须要关联一个业务单号。比如门店验收关联配货单号报损关联报损单号盘点调整关联盘点单号。这样一旦某个库存数字对不上通过流水可以反查到具体是哪一笔操作、哪个单号、哪个人做的。5.2 库存预警让系统自动算好安全库存生鲜库存管理有个特殊的地方库存过高损耗就高库存过低门店断货影响销售。所以安全库存的设置非常关键。我用的安全库存公式是安全库存 日均销量 × 配送周期天数 × 安全系数1.2 到 1.5。看懂了这一条就能理解为什么订货系统要引入“昨天卖了多少”这个维度的数据。系统做了两级预警一是安全库存预警库存低于安全库存量时系统自动提示补货二是保质期预警对即将到保质期的商品系统自动标记高风险并提出促销建议。这两级预警都通过滚动消息的形式推送给相关角色让库存管理从“被动等”变成“主动看”。5.3 生鲜损耗率的统计与分析生鲜行业有个经典指标叫损耗率公式是损耗率 损耗成本 ÷ 期初库存成本。系统开发完成后最让我感到有价值的不是配货功能而是损耗分析看板。通过对比各个门店的损耗率可以快速定位管理不善的门店。比如 A 门店的蔬菜损耗率是 8%B 门店是 3%同样的商品同样的配货周期差异只能来自门店内部的库存周转效率和上架管理。总部可以通过这个看板做很多事情调整配货数量、优化配送频次、提醒门店改善保鲜条件。这套系统的数据分析功能我用 ECharts 做了折线图和饼图——按门店维度展示损耗率对比按月维度展示损耗趋势。这部分功能不算复杂但业务价值非常高。6. 经验总结做这套系统我最后悔和最庆幸的事整个项目做下来最深的感觉是写代码本身不累累的是前端联调、细节排查和业务沟通。最后悔的事是没有在一开始就把业务规则文档写清楚。比如类似“配货单能否部分收货”这种业务决策前期不定义清楚开发中途才发现需求来回拉扯架构上就会留下补丁。最庆幸的事是坚持用了数据库事务和库存流水表。这两个设计看似额外花了一些开发时间但在系统上线后帮了大忙。库存对不上账的时候只需要顺着流水表查基本半小时内就能找到问题环节。反而是那些号称“简单一点不用搞那么复杂”的功能后期全是填不完的坑。如果后续要扩展这套系统我建议的方向是对接第三方物流平台的轨迹查询让门店能看到配货车辆实时位置增加移动端适配让店长在手机上就能完成配货申请引入简单的销量预测算法基于历史数据和节假日标签自动推荐配货量。生鲜配货系统的核心价值永远不是技术本身而是帮助连锁超市把每一棵菜的损耗降到最低、把每一辆车的装载率提到最高。这个目标无论技术怎么演进方向都不会变。
Vue+Node.js生鲜配货管理系统实战：从设计到部署全流程
做连锁超市生鲜配货管理系统有几个东西是绕不过去的生鲜非标品怎么管、多门店的订货需求怎么汇总、每隔一天甚至每天一次的高频配货怎么保证不出错。这些问题用 Excel 和微信群解决门店少了还行门店一多分分钟变成一场灾难。所以当我拿到这个“vue nodejs ElementUi 的华联连锁超市生鲜配货管理系统”的需求时第一反应就是这其实不是一套简单的增删改查而是一套围绕“损耗、时效、协同”三个关键词设计的业务系统。这篇文章我会从需求拆解、技术选型、库表设计、核心模块实现到部署运维把我踩过的坑和验证过的方案一次性讲清楚。技术栈是 Vue 2 Node.jsExpress Element UI MySQL整体都比较主流哪怕你只负责其中一个端这篇文章也能帮你少走不少弯路。1. 整体设计与核心需求拆解1.1 生鲜配货的业务链路到底长什么样生鲜配货和普通商品配货最大的区别在于生鲜有自己的“生命时钟”。蔬菜水果放一天可能就折价一半冷鲜肉对温度极其敏感水产更是必须全程冷链。所以生鲜配货系统的业务链路本质上是在跟时间和损耗赛跑。标准链路是门店提交配货申请 → 总部或配送中心汇总审核 → 生成配货单 → 仓库按单拣货 → 复核装车 → 司机配送 → 门店验收签收 → 系统回写入库。听起来不复杂但每个环节都有“坑”。拿“门店提交配货申请”这一步来说门店店长不是一次只申请一种商品而是几十上百种品项一次提交不是所有品项都有历史订单可参考新品和季节性商品经常只能靠经验填量不是所有门店的库存口径都一致有的门店早上盘一次点有的门店晚上才盘。这些业务细节直接决定了后面数据库怎么设计、接口怎么定义、前端表单怎么组织。这套系统我做的时候把业务拆成几个核心对象门店Store、商品Goods、配货申请单DistributionOrder、配货明细DistributionOrderItem、门店库存StoreInventory、系统用户User。后面所有功能的开发都围绕这几个对象展开。1.2 技术选型为什么偏偏是 Vue Node.js Element UI这个项目选型其实没什么值得纠结的但我还是想说说我的判断逻辑毕竟技术选型决定了后面几个月写代码的体验。前端选 Vue 2 Element UI是因为这个组合在后台管理系统领域太成熟了。Element UI 的开箱即用组件表格、表单、日期选择器、弹窗、分页几乎把后台系统 80% 的通用交互都覆盖了。对于生鲜配货系统来说最核心的交互不是炫酷的图表而是“多条件下单”、“表格快速录入”、“配货单明细核对”这类强表单场景Element UI 在这方面的表现非常稳定。Node.js 做后端主要是看重它和前端同语言带来的心智统一。前端写 JavaScript后端也写 JavaScript处理 JSON 数据的时候不需要任何序列化转换接口联调效率高很多。再加上 Express 框架非常轻量对于这种单体业务系统来说完全够用。可能有朋友会问为什么不用 Java 或者 PHP说实话技术上没有对错只有合不合适。Java 在复杂事务和安全性上有优势PHP 在传统 cms 场景很顺手但这个项目的核心是中小规模连锁超市的内部管理系统Node.js 的异步 I/O 模型处理并发请求并不差开发效率却高很多。尤其前端本来就是 Vue 写出来的后端再用 Node.js整个项目从部署到维护一个人就能完整 hold 住。1.3 系统模块划分与角色权限设计系统做得好不好用很大程度上取决于角色和权限设计。这套系统我在设计初期就明确了四种角色系统管理员维护门店、商品、用户等基础数据配置系统参数。总部配货管理员审核门店申请、生成配货单、查看全部门店配货记录。门店店长/订货员维护自己门店的配货申请、确认收货、查看门店库存。仓库发货员查看待拣货清单、更新发货状态、打印配货单。这四类角色不是随便定的是顺着业务链路一条一条捋出来的。每个角色对应的权限边界必须清楚门店只能操作自己的数据总部可以看全局仓库只关心发货环节。这个权限划分既能保证业务推进顺畅也能在出问题的时候快速定位责任环节。权限控制的实现我采用了前端路由守卫加后端中间件双重校验。前端根据角色动态生成菜单后端每个接口校验 token 中的角色信息两边都不松口。别觉得这是重复劳动前端控制是为了体验后端控制才是安全底线。2. 数据库设计与后端核心接口实现2.1 数据库设计把所有业务关系理清楚数据库设计是这套系统里最需要耐心的一步。我第一次画表的时候潦草了结果后面写业务逻辑时反复改表结构返工成本极高。这里把最终稳定的表结构分享出来。门店表store核心字段包括门店ID、门店编码、门店名称、地址、联系人、联系电话、状态营业/停业、创建时间。商品表goods则包含商品ID、商品编码、商品名称、分类蔬菜/水果/肉禽/水产/乳品/熟食、规格单位、参考进价、参考售价、保质期天数、是否称重商品、状态、创建时间。配货模块是我重点设计的。配货申请单主表distribution_order字段包括配货单号、申请门店ID、单据状态待审核/已审核/已发货/已收货/已取消、申请日期、期望送达日期、申请人ID、审核人ID、审核时间、备注。配货单明细表distribution_order_item包含ID、配货单ID、商品ID、申请数量、审核数量、实发数量、验收数量、单价、金额、备注。门店库存表store_inventory字段为ID、门店ID、商品ID、在库数量、在途数量、安全库存、最后盘点时间、更新时间。最后是用户表user包含用户ID、用户名、密码bcrypt加密存储、真实姓名、手机号、角色ID关联角色表、所属门店ID、状态、创建时间。注意到“配货单号”我单独设计成了业务字段而不是直接用自增ID。因为门店和仓库的员工经常要在电话里沟通配货单号一个像”PS20250101001”这样的单号比数字ID好记得多也方便按日期检索。2.2 RESTful API 设计前后端联调的基本盘RESTful API 设计看似简单但真正做得好的项目不多。核心原则是资源用名词操作用 HTTP 方法。这套系统最重要的几个 API 如下GET /api/stores 门店列表分页、条件查询 POST /api/stores 新增门店 PUT /api/stores/:id 修改门店信息 GET /api/goods 商品列表按分类/关键词查询 POST /api/goods 新增商品 POST /api/distribution/apply 门店提交配货申请 GET /api/distribution/list 配货单列表多条件查询 GET /api/distribution/:orderNo 配货单详情主表明细 PUT /api/distribution/:orderNo/audit 审核配货单 PUT /api/distribution/:orderNo/ship 发货 PUT /api/distribution/:orderNo/receive 门店收货确认 GET /api/inventory/store/:storeId 查询某门店的库存 PUT /api/inventory/:id/adjust 库存调整报损/盘盈配货单列表接口的设计要特别注意因为它是整个系统里查询频率最高、条件组合最复杂的接口。我最终的查询条件设计是配货单号模糊搜索、门店ID精确匹配、单据状态精确匹配、申请日期区间查询、分页参数。排序默认按申请时间倒序这个默认值看着简单但实际中如果不加用户会觉得列表“乱乱的”。2.3 Node.js 后端关键代码生成配货单的核心逻辑配货单的生成是整个系统业务规则最密集的部分也是我花心思最多的地方。核心流程是总部审核通过门店的申请后系统要自动为配货单生成唯一的单号并将明细状态从“待审核”更新为“已审核”。生成单号的逻辑我放在服务层用了一个比较稳妥的方式取当前日期再加当天流水号。// 生成配货单号: PS 年月日 三位流水号 async function generateOrderNo(date new Date()) { const yyyy date.getFullYear(); const mm String(date.getMonth() 1).padStart(2, 0); const dd String(date.getDate()).padStart(2, 0); const prefix PS${yyyy}${mm}${dd}; const count await DistributionOrder.count({ where: { orderNo: { [Op.like]: ${prefix}% } } }); return ${prefix}${String(count 1).padStart(3, 0)}; }审核接口的业务逻辑是这样的接收订单号后先检查订单状态必须是“待审核”否则直接返回错误然后逐条检查商品是否存在、是否停用接着计算总金额最后用事务将主表和明细表一起更新。exports.auditOrder async (ctx) { const { orderNo } ctx.params; const t await sequelize.transaction(); try { const order await DistributionOrder.findOne({ where: { orderNo, status: 待审核 }, transaction: t }); if (!order) { throw new Error(订单不存在或状态不允许审核); } const items await DistributionOrderItem.findAll({ where: { distributionOrderId: order.id }, transaction: t }); // 校验商品是否有效 for (const item of items) { const goods await Goods.findByPk(item.goodsId, { transaction: t }); if (!goods || goods.status ! normal) { throw new Error(商品[${item.goodsName}]不存在或已停用); } } await order.update({ status: 已审核, totalAmount: items.reduce((sum, i) sum Number(i.amount), 0), auditTime: new Date() }, { transaction: t }); await t.commit(); ctx.body { code: 0, message: 审核成功 }; } catch (err) { await t.rollback(); ctx.body { code: 1, message: err.message }; } };采购入库的时候要记得生成库存流水这样每一笔库存变动都有据可查。库存流水表inventory_log字段包括ID、门店ID、商品ID、变动类型入库/出库/报损/盘点、变动数量、关联单号、操作人ID、操作时间、备注。2.4 数据库事务别让数据不一致毁掉整个系统做管理系统的人最容易犯的错误就是忽略数据库事务。配货单审核、发货、收货这些操作每一步都涉及主表和明细表的同时更新如果不加事务一旦某一步失败就会出现“主表已审核明细还是待审核”这种莫名其妙的数据不一致问题。Node.js 中使用 Sequelize 操作 MySQL事务代码其实很简单。把所有需要原子性执行的操作包在同一个 transaction 里全部成功后统一 commit任何一步出错就 rollback保证数据要么全变要么全不变。另外一个常见的坑不要把业务校验放在数据库事务外面。比如审核的时候先查了订单状态然后才开启事务更新的时候发现状态已经被别人改过了。正确做法是先开启事务再在事务里查询并锁定该行记录防止并发情况下超卖或重复审核。// 在事务内加行锁防止并发重复审核 const order await DistributionOrder.findOne({ where: { orderNo, status: 待审核 }, transaction: t, lock: t.LOCK.UPDATE });很多新手程序员对事务不以为然觉得“我逻辑简单不会出问题”。但当系统真正上线多个门店同时在早高峰提交配货申请的时候并发问题就会接踵而至。3. 前端实现与 Vue Element UI 项目搭建3.1 前端工程化和项目结构设计Vue 前端这块项目的可维护性很多时候从目录结构就能看出来。我把目录统一规划为src/ -- api/ # 接口请求统一封装 -- assets/ # 静态资源 -- components/ # 通用组件 -- router/ # 路由配置 -- store/ # Vuex 状态管理 -- utils/ # 工具函数 -- views/ -- store/ # 门店管理模块 -- goods/ # 商品管理模块 -- distribution/ # 配货管理模块 -- inventory/ # 库存管理模块 -- dashboard/ # 数据看板 -- login/ # 登录页面每个业务模块下再细分 list、detail、edit 等页面文件。这样做的核心目的是不同角色进入系统后根据菜单权限动态加载路由前端代码就能天然地按照业务模块隔离。3.2 axios 请求封装与 token 身份认证axios 封装是前端每个项目的必做项。生鲜配货系统的接口调用频率很高而且接口返回格式统一我更倾向于在请求层统一处理错误提示而不是在每个页面里 try...catch 一遍。// utils/request.js import axios from axios; import { Message } from element-ui; import router from /router; const service axios.create({ baseURL: process.env.VUE_APP_BASE_API, timeout: 15000 }); service.interceptors.request.use(config { const token localStorage.getItem(token); if (token) { config.headers[Authorization] Bearer ${token}; } return config; }); service.interceptors.response.use( response { const res response.data; if (res.code ! 0) { Message.error(res.message || 请求失败); return Promise.reject(new Error(res.message)); } return res.data; }, error { if (error.response error.response.status 401) { Message.error(登录状态已过期请重新登录); localStorage.removeItem(token); router.push(/login); } else { Message.error(网络异常请稍后重试); } return Promise.reject(error); } ); export default service;之所以要把拦截器写得这么“啰嗦”是因为在实际业务中门店店长和仓库员工大多不是技术人员给他们弹一个”401”或者”服务器错误”是没有意义的。统一拦截、统一提示、统一跳转才能保证系统的可用性。3.3 配货申请页复杂表单的交互实现配货申请页是整个前端最复杂的页面。门店的配货申请往往涉及几十个品项每个品项都有申请数量、备注等字段。技术上我用 Element UI 的表格组件来实现品项填写的交互。每次新增一条商品就向表格的数据源 push 一条记录。el-table :dataform.items border el-table-column label商品编码 propgoodsCode width120/el-table-column el-table-column label商品名称 propgoodsName min-width160/el-table-column el-table-column label单位 propunit width80/el-table-column el-table-column label参考进价 propprice width100/el-table-column el-table-column label申请数量 width140 template slot-scope{ row } el-input-number v-modelrow.applyQuantity :min1 :max9999 sizesmall / /template /el-table-column el-table-column label备注 min-width180 template slot-scope{ row } el-input v-modelrow.remark sizesmall placeholder选填如要新鲜一点的 / /template /el-table-column el-table-column label操作 width80 template slot-scope{ $index } el-button typedanger sizemini clickremoveItem($index)删除/el-button /template /el-table-column /el-table有几个交互细节很重要。第一商品选择的弹窗必须支持按分类筛选和关键词搜索几十种商品靠翻页找是不现实的第二一旦用户填写了申请数量校验规则要立即触发提示数量是否超出安全库存或历史日均销量的合理范围第三提交前必须二次确认因为一次配货申请可能涉及几万块的生鲜货值点错一个按钮后果很严重。3.4 Element UI 表格固定列变透明的坑与修复这个坑我必须单独拿出来讲因为很多读者就是搜到这个问题才点进来的。Element UI 的表格在设置fixed固定列之后偶尔会出现一个诡异的现象固定列区域变成半透明底下的文字透上来完全没法看。原本清晰的表格变成视觉灾难。这个问题的根源是表格渲染时固定列和滑动区域各自生成了独立的层而两个层在滚动渲染的过程中出现了样式污染。解决办法也很直接在全局样式里强制给固定列加上不透明的背景.el-table__fixed, .el-table__fixed-right { background-color: #fff !important; box-shadow: none !important; }但是如果你的表格有斑马纹stripe效果这个方案就不够了因为斑马纹本身的底色会在滚动时错位。这种情况处理起来麻烦一些我的临时方案是去掉表格斑马纹就纯白底色加分隔线反而更干净。如果你一定要保留斑马纹就不要用fixed列而是用多个表格拼合的方式或者在数据量可控的情况下关闭fixed直接用横向滚动。说实话配货单明细几十行数据横向滚动完全够用固定列更多是心理上的舒适不是功能上的必须。4. 项目搭建过程中的坑与排查实录4.1 npm 脚本执行权限问题npm.ps1 无法加载这个错很多用 Windows 系统做 Node.js 开发的朋友第一次运行npm run dev就会遇到一串红字报错npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本。这个问题的原因是 Windows 默认的 PowerShell 执行策略是Restricted禁止运行任何.ps1脚本文件而新版 Node.js 安装器安装的 npm 命令本质上就是一个 .ps1 脚本文件所以被系统拦截了。解决方案有两个。最简单粗暴的是以管理员身份打开 PowerShell运行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser执行之后输入Y确认然后再重新打开终端运行 npm 命令就正常了。RemoteSigned表示本地创建的脚本可以运行从网上下载的脚本必须有可信签名才能运行这个策略比完全放开安全得多。网上有人建议直接用Set-ExecutionPolicy Unrestricted我不建议这么做太危险。还有人说可以删除 npm.ps1 改用 npm.cmd治标不治本同一个终端下很多构建工具还是会去调 .ps1 脚本。所以安全又有效的方案就是RemoteSigned。4.2 Node.js 版本与安装环境配置的细节Node.js 的版本选择我建议不要追新。很多朋友一上来就装最新版 Node.js 20结果老项目跑不起来新项目依赖装不上各种报错。从我的实践经验看开发 Vue 2 Element UI 项目Node.js 14 到 16 这两个大版本是比较稳的选择。Node.js 17 及以上版本对 OpenSSL 的处理方式变了经常导致老项目在启动或构建时出现error:0308010C:digital envelope routines::unsupported这样的报错。这个报错的解决办法其实也简单设置环境变量NODE_OPTIONS--openssl-legacy-provider就能绕过但与其折腾这个不如直接装一个稳定版本。安装 Node.js 的时候还要注意环境变量的配置。Windows 下如果你用安装包默认路径安装装完系统会自动把C:\Program Files\nodejs加进 PATH一般没问题。但如果你在安装过程中改了路径就要手动去系统环境变量里把 Node.js 的安装目录加进 PATH否则命令行里永远找不到node命令。如果公司电脑没有管理员权限可以用免安装版。去 Node.js 官网下载 zip 包解压后把 bin 目录加进 PATH再自己配一下 npm 的全局缓存路径就能正常使用。这个方式还特别适合在腾讯云、阿里云的 Windows 服务器上部署——不需要图形界面解压就能跑。4.3 跨域问题处理前后端分离的联调拦路虎前后端分离开发的时候本地联调必须处理跨域问题。如果前端跑在 8080 端口后端跑在 3000 端口前端直接发请求是会被浏览器拦截的。最优雅的解决办法是在 Vue CLI 的 devServer 里配置代理让前端把请求代理到后端接口从而绕过浏览器的跨域策略。在vue.config.js中这样配置module.exports { devServer: { proxy: { /api: { target: http://localhost:3000, changeOrigin: true, pathRewrite: { ^/api: /api } } } } };上线部署的时候则让 Nginx 把/api前缀的请求反向代理到 Node.js 服务这样前后端在同一个域名下自然没有跨域问题。记住一个原则跨域问题的最终解决是靠服务器端代理不要在 Node.js 里粗暴地设置Access-Control-Allow-Origin: *除非你真的不在乎安全问题。4.4 Element UI 表格大数据量渲染卡顿的优化生鲜配货系统里有一个非常具体的性能问题总部查看全部门店配货记录时表格一次性渲染几百上千条数据Element UI 的表格会出现明显卡顿滚动不流畅输入框还有延迟。这个问题本质上是 DOM 节点太多导致的。优化方案有三种第一接口层做分页每次只查20条这是最简单也最有效的方式。真实业务里几乎没人会一页看完所有配货记录都是从近到远筛选查询。第二如果一定要跨页面操作数据用懒加载。Element UI 的 Table 可以配合el-table的row-key和load方法实现树形懒加载子级数据在点开时才请求。第三减少列的渲染数量。配货单列表没必要把所有字段都展示出来把“金额”、“备注”这些低频字段放进详情弹窗里列表更清爽渲染压力也小。我实际项目里三种方案组合使用列表页分页一页20条详情用抽屉组件异步加载所有金额和备注类信息都在详情里展示。上线后测试接口响应在 200ms 内页面滚动流畅不卡顿。4.5 生成配货单时的并发重复问题前面也提到过生鲜配货单的高频使用场景就是每天早晨。几十家门店可能会集中在同一时间段提交配货申请后台审核也集中在这个时间段。这就带来一个并发问题如果多个门店同时对同一个商品提交申请可能导致库存超卖或者配货重复。解决方式是采用数据库的乐观锁加唯一索引。在门店配货申请表中对“门店配货日期配货状态”建立唯一索引ALTER TABLE distribution_order ADD UNIQUE KEY uk_store_date (store_id, apply_date, status);同时在商品库存表上增加一个版本号字段version更新库存时校验版本号是否一致UPDATE store_inventory SET quantity quantity - #{buyNum}, version version 1 WHERE store_id #{storeId} AND goods_id #{goodsId} AND version #{oldVersion}这两层保障加在一起基本杜绝了并发重复配货的问题。这也是很多新手做管理系统时最容易忽略的一个点——在“看起来没多少人用”的系统里并发问题往往不会出现在测试环境只有在真实业务高峰期才会突然爆发。5. 库存管理与生鲜损耗的关键设计5.1 库存变动的正负记账模型生鲜库存管理的难点在于“账实相符”。蔬菜水果每天有自然损耗员工操作也可能出现盘点差异如果只存一个库存数字时间一长账面数字必然失真。我在设计库存模块时采用了正负记账的流水模式。每一次库存变化都记录一条流水库存表上的数字永远等于“所有流水的汇总值”而不是被直接改来改去的值。这样财务对账、损耗分析、库存追溯都有据可查。每一个入库或出库操作都必须要关联一个业务单号。比如门店验收关联配货单号报损关联报损单号盘点调整关联盘点单号。这样一旦某个库存数字对不上通过流水可以反查到具体是哪一笔操作、哪个单号、哪个人做的。5.2 库存预警让系统自动算好安全库存生鲜库存管理有个特殊的地方库存过高损耗就高库存过低门店断货影响销售。所以安全库存的设置非常关键。我用的安全库存公式是安全库存 日均销量 × 配送周期天数 × 安全系数1.2 到 1.5。看懂了这一条就能理解为什么订货系统要引入“昨天卖了多少”这个维度的数据。系统做了两级预警一是安全库存预警库存低于安全库存量时系统自动提示补货二是保质期预警对即将到保质期的商品系统自动标记高风险并提出促销建议。这两级预警都通过滚动消息的形式推送给相关角色让库存管理从“被动等”变成“主动看”。5.3 生鲜损耗率的统计与分析生鲜行业有个经典指标叫损耗率公式是损耗率 损耗成本 ÷ 期初库存成本。系统开发完成后最让我感到有价值的不是配货功能而是损耗分析看板。通过对比各个门店的损耗率可以快速定位管理不善的门店。比如 A 门店的蔬菜损耗率是 8%B 门店是 3%同样的商品同样的配货周期差异只能来自门店内部的库存周转效率和上架管理。总部可以通过这个看板做很多事情调整配货数量、优化配送频次、提醒门店改善保鲜条件。这套系统的数据分析功能我用 ECharts 做了折线图和饼图——按门店维度展示损耗率对比按月维度展示损耗趋势。这部分功能不算复杂但业务价值非常高。6. 经验总结做这套系统我最后悔和最庆幸的事整个项目做下来最深的感觉是写代码本身不累累的是前端联调、细节排查和业务沟通。最后悔的事是没有在一开始就把业务规则文档写清楚。比如类似“配货单能否部分收货”这种业务决策前期不定义清楚开发中途才发现需求来回拉扯架构上就会留下补丁。最庆幸的事是坚持用了数据库事务和库存流水表。这两个设计看似额外花了一些开发时间但在系统上线后帮了大忙。库存对不上账的时候只需要顺着流水表查基本半小时内就能找到问题环节。反而是那些号称“简单一点不用搞那么复杂”的功能后期全是填不完的坑。如果后续要扩展这套系统我建议的方向是对接第三方物流平台的轨迹查询让门店能看到配货车辆实时位置增加移动端适配让店长在手机上就能完成配货申请引入简单的销量预测算法基于历史数据和节假日标签自动推荐配货量。生鲜配货系统的核心价值永远不是技术本身而是帮助连锁超市把每一棵菜的损耗降到最低、把每一辆车的装载率提到最高。这个目标无论技术怎么演进方向都不会变。
