WMS Next（WMSFORNEW）实战笔记：多仓、序列号与扫码作业

仓储系统最容易出现的问题，不是功能不够，而是「流程和实物对不上」。收货时少扫一件、拣货时拿错批次、发货后才发现库存没扣，最后都要靠盘点擦屁股。所以这篇笔记重点不在功能清单，而在一条闭环：单据驱动作业，扫码校验实物，流水可追溯。

阅读前提：你已经有一台能跑 Docker 的 Linux 服务器，并且了解仓库、库位、物料、批次、序列号这些基本概念。文中的域名、密码、授权码都是占位值。

一、这套 WMS 的定位

WMS Next 是一套私有化部署的仓储管理系统。它把库存拆成三层： 库位级数量 + 批次（效期）+ 序列号（一物一码）。所有变动都写入库存流水，既能看「这个库位有多少」，也能追「这个序列号去过哪里」。

能力	说明
多仓与库位	仓库 → 库区 → 库位三级模型，支持容量、冻结、混放、专属商品
序列号/批次	一物一码或按批次管理，状态从创建、在库、拣货到发运全程可追
三种扫码	USB 扫码枪（键盘楔）、手机/PDA 摄像头、PDA 原生广播
作业闭环	收货 → 上架 → 拣货 → 发运；支持预占、FIFO、作业锁
标签打印	单品标、外箱标、库位标，对接打印代理，重打有审计
可选集成	ERPNext 主数据同步与单据回写；电商平台订单适配

二、架构与组件

后端是 Go 单体服务（Gin + GORM），前端是 Vue 3 + Element Plus，数据落在 MariaDB，Redis 负责缓存、作业锁和会话类数据。整体不复杂，适合一台 4C8G 的机器起步。

浏览器 / PDA / 扫码枪
        │  HTTPS + JWT
        ▼
┌─────────────────────────────┐
│  Go 单体服务（Gin + GORM）   │
│  主数据 / 库存 / 作业 / 标签  │
│  盘点 / 报表 / 审计 / 集成    │
└──────┬────────┬────────┬─────┘
       │        │        │
   MariaDB    Redis   print-server
    主库      锁/缓存    标签打印
       │
   ERPNext / 电商平台（可选）

部署时至少有四个容器：MariaDB、Redis、后端、前端 Nginx。打印服务和授权服务是可选依赖；不打印标签、不启用联网授权时可以先不接。

三、部署准备

建议的起步配置：

Linux 服务器，4 核 8G 内存，100G 以上磁盘（看序列号量）。
Docker 24+ 与 Docker Compose v2。
一个域名和 HTTPS 证书；手机摄像头扫码必须走 HTTPS。
如果要用 ERPNext 对接，提前准备 API Key/Secret 和公司、仓库映射。

把发布包解压到服务器，例如 /opt/wms，然后进入 deploy 目录：

cd /opt/wms/deploy
cp .env.example .env
vi .env

至少修改下面这些值，不要直接使用示例密码：

APP_NAME=VisiLog WMS Next
MARIADB_PASSWORD=换成强密码
JWT_SECRET=换成随机长字符串
ADMIN_PASSWORD=首次登录密码
WEB_PORT=9103
BACKEND_PORT=9102
LICENSE_ENFORCE=true
LICENSE_KEY=你的授权码

安全提醒：不要把手写密码、JWT_SECRET、授权码提交到 Git 仓库。生产环境建议只开放 443（或反向代理端口），MariaDB 和 Redis 不要暴露到公网。

四、启动与初始化

首次部署推荐用一键脚本：

cd /opt/wms/deploy
./deploy.sh up --build

# 查看状态和日志
./deploy.sh status
./deploy.sh logs backend

启动成功后，浏览器打开 https://你的域名/，用 admin 和 ADMIN_PASSWORD 登录。第一时间做三件事：

修改 admin 密码，并给每个操作员建独立账号，不要共用。
建仓库和库位，确认库位编码规则（例如 A-01-02-03）。
建一个测试物料，生成一张单品标签，先把打印链路跑通。

五、主数据：仓库、库位、物料、条码

仓库与库位

仓库是最大的容器，下面可以建库区和库位。库位支持容量、冻结、混放和专属商品。如果仓库刚上线，建议先用「批量生成库位」：按前缀-货架-层-位的规则一次生成，单次上限 2000 个，已存在的会自动跳过。

物料与多条码

物料档案里要确认：编号、名称、规格、单位、是否启用批次、是否启用序列号、默认仓库。同一商品可以挂多个条码（EAN13、EAN8、UPC、CODE128、CODE39），并指定一个主条码。扫码时系统会按条码反查商品，所以条码不要重复。

供应商与客户

客商档案主要用于收货、发运和 ERPNext 映射。编码建议和 ERP 保持一致，后面做数据同步会省很多事。

六、入库：预到货 → 收货 → 上架

推荐流程是「先建预到货单，再收货，最后上架」。这样收货时不用临时找供应商和物料，也能提前知道今天要到什么。

建预到货单：填写供应商、预计到货时间、物料和数量。
收货：在待收货列表打开单据，逐件扫序列号或按数量确认。库位可以留空，先入「未上架」暂存。
上架：把暂存的货移到正式库位。上架只改变库位，不改变总库存。

如果是临时到货、没有预到货单，也可以用「直接收货」。收货确认后库存立即增加，并写入库存流水。已入库的标签不能重复入库，系统会拦截。

七、出库：计划 → 拣货 → 发运

出库有两种方式：正式出库计划，或「直接出货」。前者适合有拣货、复核、发运分工的仓库；后者适合一人完成的小仓。

建出库计划：填写发运方式、凭证号、客户、物料和数量。
拣货：按库位和 FIFO 建议取货，逐件扫序列号。拣货会预占库存，但此时还不扣总库存。
发运：确认物流单号后发运，系统才正式扣减库存，并把序列号状态改为已发运。

关键设计：拣货下架不等于出库。只有发运成功才扣库存，这样「已拣未发」的货仍然算在库存里，不会被误卖。

八、标签与打印

标签是仓储扫码的入口。系统支持三类标签：

单品标签：约 30×10mm，二维码内容就是序列号，不印数量。
外箱标签：按数量生成，箱码本身也是序列号；支持打包、封箱、拆箱。
库位标签：100×70 或 A5，条码和二维码内容都是库位号。

打印通过 print-server 代理完成。先在 print-server 里添加打印机、创建 API Key，再把地址和 Key 填到 WMS 的环境变量里。标签重打会记录审计，避免重复贴标。

# print-server 相关环境变量示例
PRINT_PROXY_URL=http://print-server:8000
PRINT_PROXY_API_KEY=你的_API_Key
PRINT_NETWORK=print-server_default

九、盘点、调拨与包装

盘点

盘点分盲盘和明盘。盲盘不显示系统数量，适合复核；明盘显示系统数量，适合快速核对。盘点前先选范围（仓/区/位/商品），系统会生成快照；盘点完成后自动生成盘盈盘亏调整。

调拨

调拨用于库位之间或仓库之间移动库存。扫码可以预填商品和序列号，提交后两端库位数量同时变化，并留下调拨记录。

包装箱

装箱时扫单品或已有包装，生成新的外箱码；封箱后可以放行。拆箱时扫箱码载入，再扫内物拆出，支持一键拆空。箱码和序列号的关联关系会保留，方便追溯。

十、与 ERPNext 对接（可选）

如果 ERP 和 WMS 同时使用，可以让 WMS 负责现场作业，ERPNext 负责财务和主账。对接前先在 ERPNext 生成 API Key/Secret，并确认公司、仓库、物料的映射关系。

在 WMS 的「ERPNext 对接」页面填写地址、API Key、API Secret、公司、默认仓库。
测试连接，然后同步主数据：物料、条码、仓库、客户、供应商。
按需拉取采购订单/销售订单，或在 WMS 作业完成后回写单据。
观察 outbox 和同步日志，失败的记录会按指数退避重试。

回写采用 outbox 模式：本地事务提交后异步推送，失败不会阻塞现场作业。映射优先使用物料/仓库上的 ERP 字段，为空时再按名称匹配。

十一、权限、审计与授权

系统使用 JWT + RBAC。角色决定能看哪些菜单、能做哪些操作；审计日志记录谁在什么时候改了库存、重打了标签、导出了报表。

给收货员、拣货员、仓管、管理员分别建角色，不要共用 admin。
标签重打、库存调整、盘点完成这类高风险操作，建议只给主管。
如果启用了联网授权，系统会定时心跳；断网有只读宽限期，超期后锁定。

十二、常见问题

1. 手机摄像头扫不了码？

浏览器要求 HTTPS 才能调用摄像头。确认域名证书有效，并且不是自签名证书；如果通过 IP 访问，部分浏览器也会拒绝。

2. USB 扫码枪扫出来是乱码？

扫码枪一般工作在「键盘楔」模式，需要把输入法切到英文，并确认回车结束符已开启。如果扫的是中文条码，检查扫码枪的编码设置是否为 UTF-8。

3. 标签打印不出来？

先看 print-server 是否能单独打印测试页，再检查 WMS 的 PRINT_PROXY_URL 和 PRINT_PROXY_API_KEY。容器之间要加入同一个 Docker 网络。

4. 为什么已拣货的库存还在？

这是预期行为。拣货只是预占，发运成功才扣库存。如果希望拣货即扣减，需要调整业务配置，但一般不建议，否则「已拣未发」的货会被重复销售。

5. 怎么备份？

至少备份 MariaDB 数据卷和上传的标签/附件文件。可以使用 deploy 脚本的 ./deploy.sh backup，也可以直接用 mysqldump。备份后定期做一次恢复演练，确认备份真的能用。

6. 能不能先不启用授权？

开发环境可以把 LICENSE_ENFORCE=false，生产环境请按实际授权配置。授权只影响系统启动和功能范围，不影响数据本身。

注：本文基于 WMS Next 0.1.x 的菜单和接口整理，版本升级后个别路径可能变化。