IaC / SwiftFlow

Artifact 3709f058d0772a77d93a8b7804a74eec29ac53a03445cb2d02d0ec4a1b071ef2:

• File docs/requirements.md — part of check-in [5bb18ed4d4] at 2026-10-23 03:34:10 on branch trunk — 把来肯对接和本地库落到可切换的后端。

  账号从环境读取，商品由人工增量同步，订单按五分钟轮询并缓存登录会话。开发期用 SQLite，同一套结构可切到 PostgreSQL。 (user: pluto size: 12775)

# 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. 总体架构与多端定位

```mermaid
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 销售出库作业流程（双模式支持）

```mermaid
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)}$$

```mermaid
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、微信小程序全端贯通发布。