一、项目背景与定位

1.1 背景

中小三方物流（3PL）普遍存在多货主隔离难、仓运配脱节、计费对账复杂、库存追溯弱、数字化成本高五大痛点。本方案基于开源项目 wms-ruoyi（RuoYi-Vue-Fast 架构） 快速扩展，打造多货主 WMS+TMS+OMS + 计费结算一体化平台，满足 3PL“一仓多客、仓运协同、按单计费、全程追溯” 核心需求。

1.2 定位

• 基础：复用 wms-ruoyi 成熟仓储能力（多仓库 / 库区、批次 / SN / 效期、条码打印、库存台账）。

• 扩展：新增多货主隔离、订单管理（OMS）、运输管理（TMS）、智能计费、货主门户、PDA 作业六大模块。

• 目标：低成本、快速落地，支撑10 + 货主、日单 500+、多仓协同、运配全程可视的中小 3PL 业务。

1.3 核心价值

• 多货主隔离：数据 / 权限 / 库存 / 报表完全隔离，避免货主间数据混淆。

• 仓运一体化：订单→仓储→运输→签收→结算全流程打通，减少人工对接。

• 智能计费：按货主合同自动计算仓储费、操作费、运输费、增值服务费。

• 全程追溯：批次 / SN / 入库 / 出库 / 运输 / 签收全链路追踪，满足货主审计需求。

• 降本增效：开源底座 + 低代码扩展，缩短实施周期、降低 license 成本。

---

二、业务架构设计（OWTB 模型）

采用 订单（OMS）+ 仓储（WMS）+ 运输（TMS）+ 计费（Billing） 一体化架构，覆盖 3PL 全业务链。

2.1 核心业务流程

1. 货主下单（OMS）：货主通过门户 / API 下达入库 / 出库 / 调拨 / 退货订单，系统自动校验库存 / 信用额度。

2. 仓储执行（WMS）：

   1. 入库：收货→质检→上架→库存入账→生成批次 / 条码。

   2. 出库：拣货→复核→打包→出库→库存扣减→联动 TMS 派单。

   3. 库内：移库→盘点→批次调整→库存冻结 / 解冻。

3. 运输配送（TMS）：运单生成→智能调度（运力匹配）→司机 APP 接单→在途跟踪→签收→回单上传。

4. 计费结算（Billing）：按合同规则自动计费→生成对账单→货主确认→收款→财务对账。

5. 数据看板（BI）：货主看板（库存 / 订单 / 费用）、运营看板（仓容 / 履约率 / 毛利）、司机看板（运单 / 轨迹 / 收入）。

2.2 多货主模型设计（核心）

• 货主隔离维度：

  • 数据隔离：所有业务表（订单 / 库存 / 单据）加 owner_id（货主 ID），查询自动过滤。

  • 权限隔离：RBAC + 数据权限，货主仅可见自身数据，管理员全局可见。

  • 库存隔离：wms_inventory 按 owner_id+warehouse_id+material_id 唯一，货主库存独立核算。

  • 配置隔离：货主独立配置条码模板、打印模板、计费规则、预警阈值。

• 货主档案：货主编码 / 名称 / 联系人 / 地址 / 结算方式 / 信用额度 / 合同附件 / 计费模板。

---

三、技术架构设计（基于 wms-ruoyi）

3.1 技术栈（复用 + 扩展）

后端（Java）

• 核心框架：Spring Boot 2.7.x + Spring Security + Redis + JWT（复用 wms-ruoyi）。

• ORM：MyBatis + 分页插件（复用）。

• 扩展组件：

  • 多租户隔离：自定义拦截器 + 数据权限插件（新增）。

  • 运输模块：TMS 服务（运单 / 调度 / 轨迹）（新增）。

  • 计费引擎：规则引擎（Groovy / 表达式解析）（新增）。

  • 消息推送：WebSocket + 短信 + 邮件（新增）。

  • 地图服务：高德 / 百度地图 API（轨迹 /geocoding）（新增）。

前端（Vue）

• 核心框架：Vue3 + Element Plus + Vite（复用 wms-ruoyi advance 分支）。

• 扩展模块：

  • 货主门户：独立登录 + 专属看板 + 订单管理 + 费用查询（新增）。

  • TMS 前端：运单管理 + 调度看板 + 轨迹地图 + 司机管理（新增）。

  • PDA 作业：Vue3+uniapp（兼容安卓），支持扫码 / 拍照 / 离线作业（新增）。

  • 可视化大屏：ECharts + 地图可视化，展示仓容 / 运单 / 履约率（新增）。

数据库（MySQL 8.0）

• 核心库：wms_ruoyi（原有表 + 新增货主 / 订单 / 运输 / 计费表）。

• 缓存：Redis 6.2+（库存缓存、会话缓存、分布式锁）。

• 存储：MinIO（单据附件、回单照片、轨迹文件）（新增）。

3.2 系统模块划分

1. 基础模块（复用 wms-ruoyi）

• 系统管理：用户 / 角色 / 菜单 / 权限 / 日志。

• 基础资料：仓库 / 库区 / 货架、物料 / 分类 / 单位、供应商 / 客户。

• 条码打印：入库单 / 出库单 / 物料标签 / 批次标签（Lodop + 网页打印）。

2. 多货主管理模块（新增）

• 货主档案：新增 / 编辑 / 禁用 / 合同管理。

• 货主配置：条码模板、打印模板、预警规则、计费规则。

• 数据权限：货主数据隔离、角色分配、菜单可见性。

3. OMS 订单管理模块（新增）

• 订单类型：入库订单、出库订单、调拨订单、退货订单。

• 订单生命周期：创建→审核→执行→完成→关闭→作废。

• 订单关联：订单→入库单 / 出库单→库存→运单→费用。

• 订单预警：超期未执行、库存不足、异常订单提醒。

4. WMS 仓储作业模块（复用 + 增强）

• 入库管理：采购入库、退货入库、货主入库（增强多货主支持）。

• 出库管理：销售出库、领料出库、货主出库（增强多货主支持）。

• 库内管理：移库、盘点、库存调整、批次管理、SN 管理（复用）。

• 库存管理：实时库存、库存明细、库存流水、库龄分析、库存预警（增强多货主隔离）。

5. TMS 运输管理模块（新增）

• 运力管理：承运商、车队、司机、车辆档案（证件 / 保险 / 状态）。

• 运单管理：运单创建、审核、派单、装车、在途、签收、回单。

• 智能调度：自动匹配司机 / 车辆、路线优化、配载计算（重量 / 体积）。

• 在途跟踪：GPS 轨迹、实时位置、温度监控（冷链）、异常上报。

• 回单管理：电子回单上传、审核、归档、对账凭证。

6. 计费结算模块（新增）

• 计费规则：按货主配置仓储费（按托 / 件 / 体积 / 天）、操作费（入库 / 出库 / 打包）、运输费（重量 / 体积 / 里程 / 阶梯价）、增值服务费（贴标 / 组装 / 质检）。

• 自动计费：定时任务按规则生成费用单，关联订单 / 运单 / 库存。

• 对账单管理：费用汇总、对账单生成、货主确认、开票管理。

• 财务结算：收款登记、核销、对账、毛利分析。

7. 货主门户模块（新增）

• 专属看板：库存汇总、订单状态、费用明细、履约率。

• 订单操作：下单、查询、取消、跟踪、导出。

• 库存查询：实时库存、批次 / 效期、库龄、流水。

• 费用管理：费用单查询、对账单确认、开票申请。

8. PDA 作业模块（新增）

• 入库作业：扫码收货、质检、上架、批次录入。

• 出库作业：扫码拣货、复核、打包、装车确认。

• 库内作业：移库、盘点、库存调整、条码打印。

• 运输作业：司机接单、扫码装车、在途打卡、签收、回单上传。

3.3 核心数据库模型（扩展设计）

原有核心表（复用，新增 owner_id）

• wms_warehouse：仓库（不变）。

• wms_material：物料（不变）。

• wms_receipt：入库单（新增 owner_id）。

• wms_receipt_item：入库明细（新增 owner_id）。

• wms_shipment：出库单（新增 owner_id）。

• wms_shipment_item：出库明细（新增 owner_id）。

• wms_inventory：库存（新增 owner_id，联合主键 owner_id+warehouse_id+material_id+batch_no）。

• wms_inventory_history：库存流水（新增 owner_id）。

新增核心表

1. 货主表（wms_owner）

   owner_id BIGINT PK, -- 货主ID owner_code VARCHAR(32) UNIQUE, -- 货主编码 owner_name VARCHAR(64), -- 货主名称 contact VARCHAR(32), -- 联系人 phone VARCHAR(20), -- 联系电话 address VARCHAR(255), -- 地址 settle_type TINYINT, -- 结算方式：1月结 2周结 3现结 credit_limit DECIMAL(10,2), -- 信用额度 status TINYINT, -- 状态：1正常 0禁用 create_time DATETIME, update_time DATETIME

2. OMS 订单表（oms_order）

   order_id BIGINT PK, order_no VARCHAR(32) UNIQUE, -- 订单号 owner_id BIGINT, -- 货主ID order_type TINYINT, -- 1入库 2出库 3调拨 4退货 warehouse_id BIGINT, -- 仓库ID status TINYINT, -- 1暂存 2审核 3执行中 4完成 5作废 total_qty DECIMAL(10,2), -- 总数量 total_amount DECIMAL(10,2), -- 总金额 receiver_id BIGINT, -- 关联入库单ID shipment_id BIGINT, -- 关联出库单ID transport_id BIGINT, -- 关联运单ID create_by VARCHAR(32), create_time DATETIME, update_time DATETIME

3. TMS 运单表（tms_transport）

   transport_id BIGINT PK, transport_no VARCHAR(32) UNIQUE, -- 运单号 order_id BIGINT, -- 关联订单ID owner_id BIGINT, -- 货主ID carrier_id BIGINT, -- 承运商ID driver_id BIGINT, -- 司机ID vehicle_id BIGINT, -- 车辆ID from_address VARCHAR(255), -- 出发地 to_address VARCHAR(255), -- 目的地 weight DECIMAL(10,2), -- 重量 volume DECIMAL(10,2), -- 体积 freight DECIMAL(10,2), -- 运费 status TINYINT, -- 1待派单 2已派单 3运输中 4已签收 5已回单 sign_time DATETIME, -- 签收时间 receipt_photo VARCHAR(255), -- 回单照片 create_time DATETIME, update_time DATETIME

4. 计费规则表（bill_rule）

   rule_id BIGINT PK, owner_id BIGINT, -- 货主ID rule_type TINYINT, -- 1仓储费 2操作费 3运输费 4增值服务费 charge_unit VARCHAR(16), -- 计费单位：托/件/吨/方/天 price DECIMAL(10,2), -- 单价 min_charge DECIMAL(10,2), -- 最低收费 status TINYINT, create_time DATETIME

5. 费用单表（bill_fee）

   fee_id BIGINT PK, fee_no VARCHAR(32) UNIQUE, owner_id BIGINT, order_id BIGINT, -- 关联订单 transport_id BIGINT, -- 关联运单 rule_id BIGINT, -- 关联规则 fee_type TINYINT, qty DECIMAL(10,2), -- 计费数量 amount DECIMAL(10,2), -- 费用金额 status TINYINT, -- 1待确认 2已确认 3已开票 4已收款 confirm_time DATETIME, create_time DATETIME

---

四、核心功能详细设计

4.1 多货主隔离实现

• 数据层：所有业务表加 owner_id，Mapper 层自动拼接 where owner_id = #{ownerId}，避免硬编码。

• 权限层：基于若依数据权限插件，货主角色仅分配自身 owner_id 数据权限，管理员分配全部权限。

• 接口层：统一拦截器从 Token 中解析 owner_id，自动注入请求上下文，接口无需传参。

4.2 智能计费引擎设计

• 规则配置：货主维度配置计费规则，支持固定单价、阶梯单价、按天计费、最低收费等模式。

• 自动计费：定时任务（每日凌晨）扫描完成的订单 / 运单，匹配货主规则，自动生成费用单。

• 费用核算：支持手动调整、费用减免、合并开票，满足货主特殊需求。

4.3 仓运协同流程设计

1. 出库单审核通过后，系统自动生成运单，关联出库单信息。

2. 调度员在 TMS 模块进行智能派单，分配司机 / 车辆。

3. 司机 APP 接收运单，扫码装车，系统自动扣减库存。

4. 运输途中实时上传 GPS 轨迹，异常情况（堵车 / 破损）及时上报。

5. 客户签收后，司机上传电子回单，系统自动更新运单状态。

6. 运单完成后，自动触发计费，生成运输费用单。

4.4 PDA 离线作业设计

• 离线缓存：PDA 作业数据（订单 / 库存 / 条码）本地缓存，断网时可正常作业。

• 自动同步：网络恢复后，自动上传作业数据，同步服务器库存 / 订单状态。

• 扫码适配：支持一维码 / 二维码扫描，兼容主流 PDA 设备（安卓）。

---

五、部署方案

5.1 部署架构

• 开发环境：本地部署（JDK17+MySQL8.0+Redis6.2+IDEA）。

• 测试 / 生产环境：Docker 容器化部署，Nginx 反向代理，前后端分离部署。

• 服务器配置（生产）：

  • 后端：2 核 4G×2（负载均衡）。

  • 数据库：4 核 8G×1（主从复制）。

  • Redis：2 核 4G×1（集群）。

  • 文件存储：2 核 4G×1（MinIO）。

5.2 实施步骤

1. 环境搭建：部署基础环境（JDK/MySQL/Redis），导入 wms-ruoyi 基础 SQL。

2. 代码扩展：基于 wms-ruoyi advance 分支，新增多货主 / OMS/TMS/ 计费模块代码。

3. 数据库扩展：执行新增表 SQL，配置多货主数据隔离。

4. 前端开发：开发货主门户、TMS 前端、PDA 作业页面。

5. 联调测试：单元测试→接口联调→业务流程测试→性能测试。

6. 上线部署：生产环境部署，数据迁移，用户培训，试运行。

---

六、风险与应对

6.1 技术风险

• 风险：多货主隔离不彻底，数据泄露。

• 应对：严格数据权限设计，代码审计，测试环境模拟多货主场景验证。

• 风险：高并发下库存超卖。

• 应对：库存操作加分布式锁，扣减前校验库存，事务回滚机制。

6.2 业务风险

• 风险：计费规则复杂，对账错误。

• 应对：规则配置可视化，自动计费日志可追溯，支持手动核对调整。

• 风险：仓运协同脱节，履约延迟。

• 应对：流程自动化，节点超时预警，异常工单及时提醒。

---

七、项目优势

1. 低成本落地：基于开源 wms-ruoyi，无需支付 WMS 授权费，二次开发成本低。

2. 快速迭代：若依框架低代码能力，代码生成器快速开发新模块，缩短实施周期。

3. 成熟稳定：复用 wms-ruoyi 经过验证的仓储核心能力，减少 bug 风险。

4. 高度可扩展：模块化设计，支持后续扩展WCS 自动化设备对接、RFID 盘点、跨境物流、财务系统对接等功能。

5. 全链路追溯：批次 / SN / 仓 / 运 / 费全流程追踪，满足 3PL 货主审计与合规需求。

---

八、总结

本方案基于wms-ruoyi开源项目，通过多货主隔离、OMS 订单、TMS 运输、智能计费、货主门户、PDA 作业六大模块扩展，构建了一套低成本、成熟稳定、高度可扩展的三方物流平台。方案覆盖 3PL “仓运配结算” 全业务链，解决行业核心痛点，适合中小三方物流企业快速数字化转型。