简介：这份资源是基于 QCADOO 框架构建的开源 MES 生产制造管理系统，面向制造业信息化开发者、企业技术团队及工业软件学习者，可用于机加工、食品包装、制鞋、服装等离散制造场景的生产执行管理。压缩包共约 2000 个文件，整体 37.7MB，以 1090 个 Java 源码为核心业务实现，595 个 XML 承担配置与数据映射，118 个 JS 与 40 个 CSS 支撑前端交互与界面样式，另有 88 个 properties、54 个 jsp 及少量 sh、sql 脚本，构成较完整的工程结构。目前已有 150 人学习下载。读者可借此研究 QCADOO 插件化架构下的工单排产、物料追溯、设备状态采集等模块设计，理解开源 MES 从数据库脚本到前后端页面的组织方式，并作为二次开发或行业定制的基础参考，适合具备一定 Java 与 Web 基础的中高级开发者深入研读。
1. 车间主任凌晨两点还在对Excel，这套开源MES能不能救急
上周去一家做精密五金的朋友厂里，车间主任老周给我看他的手机——凌晨两点十七分，他还在群里发一张Excel截图，问夜班班长“这批活到底走到哪道工序了”。这不是段子，是很多年产值几千万、却还在用纸质流转卡加Excel排产的中小制造企业的日常。MES（Manufacturing Execution System，生产制造管理系统）这个词听着像大厂专属，动辄几十上百万的授权费确实劝退，但QCADOO这套开源MES把门槛拉到了“一台服务器加一个懂业务的实施”就能起步的位置。它解决的核心问题很朴素：工单下发、工序报工、物料追溯、设备状态、质量记录这几件事，从人脑和表格里搬到系统里，让计划层和执行层之间那层黑匣子变得透明。适合谁？适合有自己IT或愿意找外包做二次开发的中小工厂，也适合想拿一套真实业务系统练手的Java后端。不适合谁？指望装完就能用、完全不想碰代码和业务配置的纯小白。
2. QCADOO MES的技术底座：为什么选它而不是自己撸一套
2.1 从工单到报工，MES到底在管什么
先把业务链路捋清楚，不然拿到源码也不知道从哪下手。一个典型离散制造场景是这样的：销售订单转成生产工单，工单拆成多道工序（下料、CNC、去毛刺、检验、包装），每道工序有标准工时、指定工位、需要领用的物料。工人上班第一件事是在工位终端上“开工”，扫工单条码，系统记录开始时间；做完一批点“报工”，填合格数、不良数、不良原因；质检员再抽检录入结果。这些动作产生的数据，汇总成三张核心表：工单进度表、工序流转表、质量追溯表。MES的价值就在于这三张表是实时联动的——老周不用再问“走到哪了”，打开看板就是当前状态。
QCADOO这套系统的设计思路是“低代码配置+标准业务模块”。它没有把工序流程写死在代码里，而是通过工艺路线（Routing）配置来定义产品走哪几道工序、每道工序的先后约束。这意味着你换一个产品，不用改代码，在后台配一条新路线就行。常见做法是先用它自带的示例工艺路线跑通一遍，再照着改自己厂的。
2.2 技术栈拆解：Spring Boot + MyBatis + Vue的前后端分离
拿到源码包，先看目录结构。后端是标准的Spring Boot多模块Maven工程，我一般会先看pom.xml确认版本和依赖。数据库层用MyBatis做ORM，SQL写在XML里，这对需要频繁改查询条件、加自定义报表的工厂场景反而比JPA灵活——实施人员懂点SQL就能改。前端是Vue加Element UI，工位终端用浏览器就能打开，不用装客户端，这点对车间环境很友好。
# 克隆或解压后，先看后端模块划分 cd qcadoo-mes ls -1 # 常见输出： # mes-core 核心业务逻辑（工单、工序、物料） # mes-web 对外REST接口层 # mes-admin 后台管理配置 # mes-common 工具类与常量逻辑说明：模块拆分的意义在于二次开发时知道改哪里。比如要加工单字段，改mes-core的实体和mes-web的DTO；要加一个报表接口，在mes-web新建Controller即可，不用动核心逻辑。参数方面，重点看application.yml里的数据库连接和mybatis的mapper-locations配置，确保XML能被扫描到。
# application.yml 关键片段 spring: datasource: url: jdbc:mysql://127.0.0.1:3306/qcadoo_mes?useUnicode=true&characterEncoding=utf8 username: mes_user password: your_password mybatis: mapper-locations: classpath*:mapper/**/*.xml configuration: map-underscore-to-camel-case: true这里map-underscore-to-camel-case一定要开，否则数据库的work_order_no映射不到Java的workOrderNo，报工接口会返回一堆null，这是新手最常见的翻车点之一。
2.3 数据库初始化：先跑通再谈定制
源码包里一般带sql目录，里面有建表脚本和初始数据。我习惯先建库再按顺序执行，不要跳步。
-- 1. 建库，字符集必须utf8mb4，否则不良原因里的特殊符号会乱码 CREATE DATABASE qcadoo_mes DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; -- 2. 按顺序执行脚本（文件名以实际包内为准） -- source schema.sql; -- source init_data.sql; -- 3. 验证核心表是否建好 SHOW TABLES LIKE '%work_order%'; SHOW TABLES LIKE '%operation%';执行完检查work_order（工单）、operation（工序）、material（物料）三张表是否存在且有初始数据。如果init_data.sql里带了示例工艺路线，先别删，用它跑通第一个工单再清理。参数上注意MySQL版本，5.7和8.0在驱动类名上有区别，8.0用com.mysql.cj.jdbc.Driver，配错了启动直接报ClassNotFoundException。
3. 从零跑起来：环境、启动与第一个工单
3.1 环境准备与依赖版本对齐
在动手之前，把版本对齐这件事做扎实，能省掉后面一半的排查时间。我一般会列一张清单逐项确认，而不是装到哪算哪。
| 组件 | 建议版本 | 说明 |
|---|---|---|
| JDK | 8 或 11 | 看pom里java.version，别硬上17 |
| MySQL | 5.7 / 8.0 | 字符集utf8mb4 |
| Maven | 3.6+ | 用于拉依赖和打包 |
| Node.js | 14 / 16 | 前端Vue2项目，别用太新的 |
| Redis | 5.0+ | 部分会话或缓存依赖 |
版本对不齐的典型现象是：后端能启动但前端npm install报一堆node-sass编译错误。遇到这个，先确认Node版本，Vue2+Element UI的老项目在Node 18上大概率翻车，切回16通常就好了。
3.2 后端启动与接口自测
环境齐了之后，先单独把后端跑起来，不要前后端一起启，出问题不好定位。
# 在项目根目录，先跳过测试打包，避免测试用例依赖环境导致失败 mvn clean package -DskipTests # 启动（假设打出来的是mes-web的jar） java -jar mes-web/target/mes-web.jar --spring.profiles.active=dev逻辑说明：-DskipTests是实操习惯，源码包里的单元测试往往依赖特定数据库状态，先跳过保证能出包。--spring.profiles.active=dev指定用开发配置，连本地库。启动成功后，用curl打一下健康检查或工单列表接口，确认数据库连通。
# 自测工单列表接口（路径以实际Controller为准） curl -X GET "http://127.0.0.1:8080/api/workOrder/list?pageNum=1&pageSize=10" \ -H "Content-Type: application/json"如果返回500且日志里有Table 'xxx' doesn't exist，回去检查SQL脚本是否全部执行；如果返回401，说明接口有鉴权，先走登录拿token。参数上pageNum和pageSize是分页标配，别传0或负数，部分分页插件会直接抛异常。
3.3 前端启动与工位终端适配
后端通了再启前端。工位终端那台机器，我建议直接用浏览器全屏模式，省得装客户端。
cd mes-ui npm install # 开发模式启动，注意后端地址要配对 npm run dev前端一般有个配置文件（如.env.development）写着后端API地址，确认它指向你刚启动的后端端口。逻辑上，前端只是展示层，报工、开工这些动作最终都打到后端接口，所以后端不通前端一定白屏或报错。参数上，如果车间网络是内网，把前端打包后丢到Nginx，配一个反向代理到后端，比开发模式稳定得多。
# 生产打包 npm run build:prod # 产物在dist目录，丢给Nginx即可到这里，一个最小可用的MES就跑起来了。接下来才是真正花时间的部分：把示例工艺路线改成你自己厂的。
4. 避坑与排查：那些让我加班到深夜的配置
4.1 报工数量对不上：并发与事务的坑
现象：两个工位同时报工同一张工单，合格数加起来比工单总数还多。原因：报工接口在更新工单已完成数量时没有加锁或乐观锁校验，并发下读到的旧值互相覆盖。解决：在更新语句里加版本号或直接update ... set done_qty = done_qty + #{qty} where id = #{id} and done_qty + #{qty} <= plan_qty，用数据库行锁保证不超报。这是MES最核心的数据一致性问题，别指望前端拦，前端拦不住并发。
4.2 工序流转卡住：工艺路线配置的先后约束
现象：工单在第一道工序报工后，第二道工序在终端上死活点不了“开工”。原因：工艺路线里两道工序的前后置关系配错了，或者第二道工序没有绑定可用工位。解决：去后台检查routing_operation表里两道工序的sequence顺序，以及工位与工序的绑定关系。常见做法是先在测试环境把整条路线走一遍，确认每道工序都能开工再上线。
4.3 中文乱码：从数据库到前端的字符集链路
现象：不良原因里填的中文，存进库变成问号，或者前端显示乱码。原因：字符集链路某一环没统一，可能是建库时用了utf8（三字节，存不下某些字符）而不是utf8mb4，也可能是JDBC连接串没带characterEncoding=utf8。解决：建库、连接串、MyBatis配置三处统一成utf8mb4，缺一不可。这个坑我踩过不止一次，血泪经验是建库脚本第一行就写死字符集。
4.4 启动报驱动类找不到：MySQL版本与驱动不匹配
现象：java.lang.ClassNotFoundException: com.mysql.jdbc.Driver。原因：MySQL 8.0的驱动类名是com.mysql.cj.jdbc.Driver，老配置里写的是旧类名。解决：改application.yml里的driver-class-name，同时确认pom.xml里引的是mysql-connector-java对应版本。别小看这一行，能让你对着日志怀疑人生半小时。
4.5 前端打包后接口404：Nginx代理路径没对齐
现象：开发模式一切正常，打包丢到Nginx后所有接口404。原因：开发模式前端直连后端端口，生产环境走Nginx反向代理，代理的location路径和前端请求的baseURL不一致。解决：统一约定一个前缀（如/api），Nginx里location /api/ { proxy_pass http://后端; }，前端请求也带/api。参数上注意proxy_pass结尾有没有斜杠，带不带斜杠的转发路径规则不同，这是Nginx的经典玄学。
5. 二次开发与进阶：把开源MES改成自己厂的样子
5.1 加一个自定义报工字段的完整链路
开源系统不可能开箱即用，加字段是最高频的二次开发。以“给报工记录加一个设备编号”为例，走一遍完整链路。第一步改数据库，加列。
ALTER TABLE work_report ADD COLUMN equipment_code VARCHAR(64) DEFAULT NULL COMMENT '设备编号';第二步改后端实体和Mapper。实体类加字段，XML里insert和select补上这一列。
// WorkReport.java 实体加字段 private String equipmentCode; // getter/setter 略<!-- WorkReportMapper.xml insert里补列 --> <insert id="insert" parameterType="WorkReport"> INSERT INTO work_report (work_order_no, operation_id, qty, equipment_code) VALUES (#{workOrderNo}, #{operationId}, #{qty}, #{equipmentCode}) </insert>第三步前端表单加输入框，提交时带上这个字段。逻辑说明：改字段的顺序永远是“库→后端→前端”，反过来做会各种报错。参数上注意equipment_code的驼峰映射，开了map-underscore-to-camel-case就不用额外配resultMap。
5.2 用看板接口对接车间大屏
车间大屏是MES最直观的价值体现。常见做法是写一个聚合接口，把工单进度、设备状态、当日产量一次返回，前端用ECharts或DataV渲染。
// DashboardController.java 聚合看板数据 @GetMapping("/dashboard/overview") public Result overview() { Map<String, Object> data = new HashMap<>(); data.put("todayOutput", reportService.sumTodayOutput()); // 当日产量 data.put("runningOrders", orderService.countRunning()); // 在制工单数 data.put("passRate", qualityService.todayPassRate()); // 当日合格率 return Result.ok(data); }逻辑说明：看板接口要轻，别在循环里查库，能一次聚合就一次聚合。参数上todayOutput这类统计建议加时间范围参数，默认当天，方便大屏切换日/周视图。大屏机器一般只读不写，给它单独开一个只读账号，别用管理员账号，安全上也省心。
5.3 验证改造是否成功：三步回归法
改完代码别急着上线，我一般走三步回归。第一步，单元自测：用Postman或curl打新接口，确认返回结构正确。第二步，业务回归：新建一张工单，从开工到报工走完整条路线，确认新字段在每一步都正确落库。第三步，并发验证：模拟两个终端同时报工，确认数量不超报。这三步走完，基本能拦住大部分低级问题。从那以后我每次改MES核心表结构，都强制走一遍这三步，宁可多花半小时，也不想半夜被叫起来查数据。希望这套开源MES的拆解能帮到你，少走点我踩过的弯路。
本文还有配套的精品资源，点击获取
