SwiftFlow WMS 仓储管理系统 - 需求与系统规格说明书 (PRD)

文档版本	状态	编写日期	关联系统
v1.0.0	评审定稿	2026-10-22	QL361 ERP (只读逆向对接) / SwiftFlow 后端与多端

---

1. 项目概述与业务背景

1.1 项目目标

SwiftFlow 是一套基于 Monorepo（单仓库） 架构的现代化、高并发、精细化仓储管理系统（WMS）。 系统以后端 Gleam (基于 Erlang BEAM 虚拟机) 为核心引擎，实现对商品生命周期、批次保质期、四级库位、扫码作业及多仓库存的精细化管控。

1.2 核心业务边界与定位

• 上游数据源：QL361（成都企链科技来肯企汇云 ERP，访问入口：https://22beta.ql361.com/desktop.html）。
• 交互边界（严格只读）：
  • 系统定位为只读对接 QL361。绝不向 QL361 进行数据反向写入，彻底避免逆向写入带来的业务风险或数据冲突。
  • 所有仓储出入库作业、库位流转、实际库存扣减、波次打单均在 SwiftFlow 本地闭环处理。
  • 核心功能：抓取 QL361 商品资料、采购进货单（入库源）、销售订单（出库源）。

---

2. 总体架构与多端定位

flowchart TD
    QL[QL361 云平台\n22beta.ql361.com] -->|逆向只读 API 抓取| SYNC[shared/ql361api\nGleam 逆向会话与数据抓取引擎]
    SYNC -->|标准化清洗数据| BACKEND[backend/ Gleam 后端核心\n业务逻辑 / RBAC / 状态机]
    
    subgraph MultiTerminal [多端协同体系]
        BACKEND <-->|RESTful / WebSocket| WEB[web/ Vite Web 端\n管理控制台 / 数据大屏 / 报表]
        BACKEND <-->|RESTful / 本地外设通讯| DESK[desktop/ 桌面端 (Win/macOS)\n电子秤通信 / 标签与面单批量高速打印]
        BACKEND <-->|RESTful / 扫码接口| MOB[mobile/ APP 端 (iOS/Android)\n工业 PDA 红外扫码 / 移动扫码作业]
        BACKEND <-->|RESTful / 扫码接口| MINI[miniapp/ 微信小程序端\n便捷出入库 / 移动库存查询]
    end

2.1 终端职责划分矩阵

终端	运行形态	面向角色	核心职责	特色技术需求
Web 端 (web/)	浏览器 (Vite SPA)	系统管理员、仓管主管、审单员	全局基础配置、RBAC 授权、波次策略调度、多仓报表、QL361 同步监控	现代化响应式后台、图表可视化
桌面客户端 (desktop/)	Windows & macOS	打包复核员、发货操作员	功能与 Web 端一致，重点强化发货工作台：高速打包复核、打单发货	直接连接本地硬件外设（热敏打印机、串口/USB 电子秤）
APP 移动端 (mobile/)	移动终端 (iOS/Android)	库内作业员（上架、拣选、盘点、移库）	移动库内作业，执行入库验货、库位绑定、按路径波次拣货、盘点录入	支持手机摄像头扫码与工业级 PDA 红外扫描头（广播监听）
小程序端 (miniapp/)	微信小程序	仓库作业员、现场主管	轻量作业端，临时扫码收发货、退货验收、快速库存与库位查询	微信原生扫码与蓝牙便携打印机支持

---

3. QL361 逆向 API 对接规范 (shared/ql361api)

3.1 会话管理与认证机制

• 认证凭证：系统初次部署配置管理员账号与密码，存储于安全环境变量。
• 登录维持器：由 Gleam 原生 HTTP 客户端实现：
  • 模拟登录请求，提取并持久化维护 Session Cookie / Token。
  • 心跳保活与失效探测：在调用 API 遇到 401 Unauthorized 或 Session 过期标识时，自动触发重登流程与会话更新。
• 并发控制：内置请求速率限制器（Rate Limiter），避免对目标网站造成突发高频压力。

3.2 同步策略模型

1. 后台轮询调度（Polling）：
   • 定时拉取（例如默认每 3~5 分钟）：抓取最新的“待发货销售订单”与“待入库采购单”。
   • 抓取商品增量：检测是否有新增 SKU，自动同步基础信息。
2. 操作驱动主动查询（On-demand）：
   • 管理员在 Web/桌面端可随时点击“立即同步 QL361 订单”。
   • 扫码作业若扫描到本地未缓存的新条码，触发实时 API 查验。

3.3 数据映射模型

QL361 实体	SwiftFlow WMS 本地实体	映射处理策略
商品档案 (Goods)	Product & Sku	映射商品名称、编码、条码、规格、单位；本地补充安全库存、默认库位等
销售订单 (Sales Order)	OutboundOrder (出库单)	仅抓取“已审核/待出库”状态订单，本地生成出库任务
采购进货单 (Purchase Order)	InboundOrder (入库单)	抓取“待收货”单据，本地生成入库验货任务

---

4. WMS 核心业务功能规范

4.1 仓储空间与库位管理

• 多仓库独立核算：支持多物理仓库（如：1 号总仓、2 号生鲜分仓、退货暂存仓），各仓库独立核算库存与作业流。
• 四级标准化库位编码： $$text{库位编码} = text{库区 (Area)} - text{货架 (Aisle)} - text{层 (Level)} - text{位 (Bin)}$$ 例如：A-01-02-03 表示 A 库区、01 号货架、第 2 层、03 号库位。 每个库位生成唯一条码（如 LOC-A010203），支持移动端扫码定位。

4.2 采购入库作业流程

1. 任务生成：由 QL361 采购单自动抓取生成，或手工新建到货单。
2. 移动端收货验货：
   • 作业员在 APP/小程序扫码点验到货数量。
   • 批次与保质期录入：强制录入生产批次号（Batch No）、生产日期、保质期到期日。
3. 上架推荐与确认：
   • 系统根据“同品集中”、“先进先出便利性”算法智能推荐目标库位。
   • 作业员至指定库位，依次扫描“库位条码”与“商品条码”，确认上架并生效可用库存。

4.3 销售出库作业流程（双模式支持）

flowchart TD
    ORDERS[QL361 待发货订单] --> AUDIT{出库模式分流}
    
    subgraph ModeA [模式一：一单一拣 / 边拣边打]
        AUDIT -->|急单 / 大件 / 散单| SINGLE[单订单拣货任务]
        SINGLE --> S_PICK[作业员扫码拣货 (推荐库位)]
        S_PICK --> S_PACK[直接复核称重打单]
    end
    
    subgraph ModeB [模式二：波次批量拣货 + 打包播种]
        AUDIT -->|高频同类订单| BATCH[波次生成引擎 (Wave)]
        BATCH --> B_PICK[生成汇总拣货单 + 路径优化]
        B_PICK --> B_STATION[运至打包分拣台 (播种墙)]
        B_STATION --> B_SEED[二次分播扫码复核]
        B_SEED --> B_PACK[称重校验 + 批量打印面单]
    end
    
    S_PACK --> OUT_FINISH[出库完成 / 扣减本地库存]
    B_PACK --> OUT_FINISH

• 批次出库策略 (FIFO)：
  • 系统在生成拣货建议时，根据商品保质期和入库时间，自动优先推荐最早批次的库位。
  • 移动端默认引导拣选该批次；若仓库现场由于破损或阻挡需要调整，作业员可选择并二次扫码确认实际拿取的批次。
• 复核打单与称重校验：
  • 桌面端直接集成电子秤，打包时自动读取重量。
  • 若实测重量超过预设公差阈值，系统报警拦截，杜绝漏发/错发。

4.4 库内管理与动态盘点

• 移库调拨：
  • 仓内移库：因理货或拣货补货需要，作业员扫原库位 -> 扫商品 -> 扫目标库位，即时完成转移。
  • 跨仓调拨：生成调拨出库与调拨入库流。
• 多维度盘点机制：
  • 动态盘点（动碰盘）：仅盘点当日有出入库流转的库位与 SKU。
  • 周期全盘 / 区域盘点：按库区锁库盘点。
  • 盲盘机制：作业端不展示系统库存账面数，作业员实盘录入，提交后系统比对生成差异报表，需主管审批确认方可生成损益调整单。
• 预警机制：
  • 安全库存下限预警（缺货预警）。
  • 临期商品红黄牌预警（按剩余保质期百分比或天数分级预警）。

4.5 售后退货与逆向物流

• 退货登记：支持关联原出库单退货，或按客户/条码进行无单退货登记。
• 退货质检分流：
  • 良品：推荐退货上架库位，重新计入可用库存。
  • 不良品 / 破损件：自动流转至不良品隔离库区，等待返厂或报废。

---

5. RBAC 权限与多仓数据隔离模型

5.1 权限架构设计

系统采用严格的 RBAC (Role-Based Access Control) 模型，结合多仓数据范围约束： $$text{有效操作权限} = text{功能权限点 (Action)} cap text{管辖仓库范围 (Warehouse Scope)}$$

erDiagram
    USER ||--o{ USER_ROLE : has
    ROLE ||--o{ USER_ROLE : assigned_to
    ROLE ||--o{ ROLE_PERMISSION : contains
    PERMISSION ||--o{ ROLE_PERMISSION : belongs_to
    USER ||--o{ USER_WAREHOUSE : authorized_to
    WAREHOUSE ||--o{ USER_WAREHOUSE : assigned

5.2 预设系统角色与职责划分

角色编码	角色名称	访问终端权限	核心权限与职责
ROLE_SYS_ADMIN	超级管理员	Web / 桌面端	系统参数配置、多仓建立、QL361 账号配置、RBAC 授权、审计日志查看
ROLE_WH_MANAGER	仓库主管	Web / 桌面端 / 小程序	盘点任务发起与差异审批、损益确认、波次策略配置、员工绩效统计
ROLE_ORDER_CLERK	制单/调度员	Web / 桌面端	审核出入库任务、手动触发 QL361 订单同步、波次组单与异常单标记
ROLE_PACKER	打包复核员	桌面工作台 (Win/Mac)	播种分选、电子秤称重复核、面单打印、发货封箱
ROLE_OPERATOR	库内作业员	APP (iOS/Android) / 小程序	移动扫码收货、库位上架、波次拣选、移库理货、退货验收

5.3 多仓数据隔离规则

1. 行级数据过滤：所有与库存、单据、库位相关的数据库查询，后端上下文自动附加 warehouse_id IN (user_authorized_warehouses) 条件。
2. 跨仓防串单：移动端作业员在登录或开始作业前需选择“当前作业仓库”，无法扫描或操作其他仓库的库位与库存。

---

6. 软硬件与外设交互技术标准

6.1 扫码体系与 PDA 适配

• 双模扫码支持：
  1. 普通摄像头扫码：针对普通 iOS/Android 手机及微信小程序，采用内置高质量扫码解析库，优化暗光环境与褶皱条码识别。
  2. 工业级 PDA 广播模式 (Broadcast Receiver)：适配主流安卓仓储 PDA（如优博讯 Urovo、新大陆 Newland、斑马 Zebra 等）。在后台监听红外扫描头广播 Intent，实现毫秒级硬件扫码，无需调起任何相机界面，提高 10 倍作业效率。

6.2 桌面端硬件外设驱动

• 标签与电子面单打印：
  • 桌面客户端直接与本地/网络热敏打印机建立通信（支持 TSPL / CPCL / ZPL 指令或直接 PDF 栅格化打印）。
• 串口/USB 电子秤：
  • 桌面端后台守护监听串口数据，打包复核时自动提取稳定重量数值，实现“放箱即验重”。

---

7. 数据实体与核心表结构设计 (Gleam 模型设计)

7.1 核心数据实体清单

1. User / Role / Permission：RBAC 基础实体。
2. Warehouse / Location：多仓库及四级库位实体。
3. Product / ProductSku：商品主数据与条码。
4. Inventory / InventoryBatch：库存现存量与批次库存（记录保质期、批次号）。
5. InboundOrder / InboundItem：采购入库单及明细。
6. OutboundOrder / OutboundItem / Wave：销售出库单、明细及波次组。
7. StockMove / StockCheck：移库单与盘点单。
8. Ql361SyncLog：逆向抓取与同步日志。

---

8. 实施里程碑规划

• 阶段一 (M1) - 基础底座与 QL361 逆向引擎：
  • 完成 Gleam 后端基础架构与 RBAC 数据表设计。
  • 完成 shared/ql361api 模拟登录、商品增量抓取与销售订单拉取。
• 阶段二 (M2) - 核心库存与入库流程：
  • 多仓与四级库位管理。
  • 采购入库、批次号录入、移动端扫码上架。
• 阶段三 (M3) - 销售出库与波次打单：
  • 一单一拣与波次拣货路径算法。
  • 桌面端打包复核、电子秤对接与热敏面单打印。
• 阶段四 (M4) - 库内治理与全端联调：
  • 动态盘点、移库调拨、售后退货处理。
  • Web、桌面客户端、iOS/Android APP、微信小程序全端贯通发布。