选题编号：0（项目全景）
拿到一套开源 WMS，难的从来不是启动
很多开发者第一次打开 JeeWMS 的仓库，部署其实很顺利：JDK 1.8+ 加 MySQL 5.7，跑起来就有登录页、有菜单、有数据。真正让人卡住的是下一步------菜单几十项，模块十几个，代码目录一大片，不知道该先看哪里。一套开源的 Java 仓库管理系统摆在面前，通常有三种卡点：业务从哪里流入、库存在哪一刻被改动、自己那个需求该改配置还是改代码。
这里不罗列功能清单，只给一份"阅读地图"：按单据流 → 域模型 → 调用链 → 配置边界 → 二次开发入口 五层，把一套 Java 仓库管理系统拆成可以按顺序读的结构。官方仓库地址是 gitee.com/erzhongxmu/... ------认准官方仓库 gitee.com/erzhongxmu/JEEWMS，注意辨别第三方镜像/fork。
同一套系统，三种读法
产品视角 关心"它能做什么"：WMS 仓储执行、OMS 订单协同、BMS 计费结算、TMS 运输管理四段能力，加上基础配置与权限域验证，适合选型阶段。业务视角 关心"我的流程怎么落进来"：收货、上架、拣货、复核、发货、盘点、退货各自对应哪些操作台与单据，适合实施阶段。代码视角关心"哪一层驱动哪一层"：什么被数据驱动、什么被配置驱动、什么必须动代码，适合二次开发阶段。
三种读法没有优劣，但顺序不能乱。跳过前两种直接读代码，最常见的后果是：改了一处，三个月后在另一个仓上线时全线报错。
第一层：单据流，系统的骨骼
单据是仓储系统里最稳定的东西。界面会改、报表会加、设备会换，但"入库要有一张收货单"几十年没变。所以读源码的第一站应该是单据，而不是数据库表。
| 业务链 | 起点单据 | 中间单据 | 终点状态 | 库存被改动的时点 |
|---|---|---|---|---|
| 入库链 | 采购/调拨到货通知 | 收货单 → 质检 → 上架单 | 入库完成 | 上架确认时 |
| 出库链 | 客户订单/发货通知 | 波次 → 拣货单 → 复核 → 出库单 | 发货完成 | 出库确认时 |
| 库内链 | 移库/补货/盘点任务 | 移库单 / 盘点单 | 任务关闭 | 移库确认 / 盘点差异过账时 |
| 逆向链 | 客户退货申请 | 退货收货单 → 质检 → 处置单 | 退货入库或报废 | 处置确认时 |
这张表最大的价值在最后一列：库存不是随时可以改的，它只在几个明确的"过账动作"上变化，其余环节产生的都是待处理状态。理解这一点就能解释现场大量"数量不对"的疑问------多数不是算错，而是单据停在中间环节没过账。
第二层：五个核心对象
单据跑起来之后，支撑它的是五个对象，这也是读数据模型时应该先抓住的骨架：
- 货主。厂内物流可能只有一个，3PL 下是多个，它是绝大多数数据的第一层隔离维度。
- 仓库 / 库区 / 库位。三级建模，库位是库存最小容器，也是作业指令的最小落点。
- 货品与批次。货品是静态主数据，批次是动态实例，冷链、汽车、医药类场景的追溯都挂在批次上。
- 库存与库存状态 。库存不是一个数字，而是"货主 + 货品 + 批次 + 库位 + 状态"的定位结果。状态最容易被忽略：可用、锁定、待检、冻结，状态不同能参与的业务就不同。
- 单据与单据行。头与行的分离是所有仓储系统的共同选择，它决定了批次、库位、状态这些信息挂在哪一层。
五个对象里，前三个是配置出来的，后两个是跑出来的。这条界线划清了，后面的问题就都清楚了。
第三层：一次出库的完整链路
把对象和单据串起来的方式，是跟着一次真实作业走一遍。以出库为例，从 PDA 扫码到库存扣减大致七步：
接收订单 → 订单分配（按货主、仓库、库存可用性）→ 生成波次 → 生成拣货任务 → PDA 拣货扫码（校验库位、货品、批次）→ 复核与出库确认 → 库存过账与状态回写。
第三、四步是能力分水岭：没有波次和任务层的系统，现场只能靠人记；有了任务层，作业才能被派发、追踪、计量，绩效分析也才有数据基础。
第五步是域验证的介入点：多货主多仓下，同一操作员在不同仓、不同货主的可见范围不同，所以这里的权限不是菜单权限，而是管到"仓、货主、人"三维的数据权限。这也是排查"为什么我看不到这张单"的第一站。
配置驱动与代码驱动的分界线
二次开发最贵的错误，是把本该配置的东西写进代码。判断标准可以简化成一张表：
| 层次 | 典型内容 | 改动方式 | 升级代价 |
|---|---|---|---|
| 配置层 | 仓库库位建模、货主货品主数据、计费规则、作业策略 | 界面配置 | 几乎为零 |
| 扩展层 | 自定义校验、接口适配、报表定义 | 按扩展点实现 | 低 |
| 模块层 | 新增业务能力、改造领域模型 | 新增模块或改内核 | 中到高 |
判断需求落在哪一层，问三句话就够了：这条规则会不会变 （会变就该进配置）；变的是参数还是流程 （参数进配置，流程进扩展）；同行业其他用户会不会也用得到（会，就该做成可配置或提回主线）。
二次开发入口地图
按这个分界，实际动手时会遇到的入口主要有四个：
- 计费规则：BMS 动态计费引擎支持按操作类型、货主、合同周期组合规则，多数需求改配置即可。
- 域验证：新增数据隔离维度需在权限层扩展，改动范围明确但影响所有查询。
- 接口适配：对接 SAP ECC、SAP HANA、用友 U8、百胜 E3 时，优先在接口层做转换，别把外部字段语义下沉到领域模型。
- PDA 端：移动端用 UNI-APP，一套代码适配多种硬件，与后端通过接口解耦。
一个务实原则：能在接口层解决的，不要下沉到领域模型；能在配置层解决的，不要写进代码。每一次下沉都会让未来的升级多一份冲突。
技术栈在全景里的位置
技术栈的作用可以一句话概括：Spring Cloud 微服务架构 + Vue 前端的组合，让"业务边界"和"部署边界"能够对齐。仓储执行、订单、计费、运输的负载特征完全不同，拆开之后可独立扩容，也可按模块分批上线。
持久层用 Hibernate / Minidao 分工，缓存层用 Redis + Ehcache 承担高频读取的字典与规则数据，现场扫码的响应速度很大程度取决于这一层命中率。数据库兼容多种关系型数据库，加多租户设计后一套系统可同时服务多个货主与仓库，私有化部署也不必牺牲数据隔离。
三处最容易误读的地方
第一，把库存表当成唯一真相。库存是"单据过账的结果"，不是可随意更新的数字。看到数量不对，先查单据状态，再查库存。
第二，把配置当成静态字典。配置有版本、会随合同和季节变。变更不留痕，事后就解释不了"上个月的数字为什么和这个月不一样"。
第三，把多租户理解成多套数据库。多租户的核心是数据隔离维度贯穿全链路，而不是把数据分到不同的库。前者是架构，后者只是部署方式。
授权与生态
项目在 Gitee 上获得 GVP 认证，采用 GPL-3.0 协议，二次开发前建议先弄清授权边界。生态只有三个官方仓库：主仓库 gitee.com/erzhongxmu/... ，PDA 移动端开源仓库 jeewmsapp（gitee.com/erzhongxmu/... ，UNI-APP 技术栈），以及 GitHub 只读镜像 github.com/erzhongxmu/... 。使用中遇到问题，可在 Gitee 仓库的 Issue 区交流反馈。
从信息化到智能化
仓储系统走到今天，"记录发生了什么"已经不够了，下一步是"预测该怎么做"。JeeWMS 背后是正在构建的工业互联网智能体（AI Agent）平台------用 AI 智能体贯穿 WMS 仓储、MES 制造执行、ERP 企业资源、CRM 客户关系等核心业务域，把仓储沉淀的领域经验与大模型能力结合，走向智能调度、智能排产与 AI 运维，让工业场景从信息化迈向智能化。JEEWMS 在其中承担仓储域核心与落地底座的角色。
这套全景越清晰，智能体可介入的点就越多------单据流提供事件、域模型提供语义、配置层提供可调参数，这是智能体真正能做事的前提，也是这个项目未来值得持续关注的原因。
结语
读一套开源仓库管理系统，顺序比速度重要。三个自检问题：能否画出四条单据链并指出每条链上库存被改动的那一刻？能否说清需求该进配置层还是代码层？能否从 PDA 扫码一路追到库存过账那段代码？ 三个都能回答，这套系统对你就不是黑盒了。