大宗物料销售出库项目需求 v4.0

版本演进

技术决策录（v4.0 代码审查后确认）

以下决策基于对现有 mes-warehouse 模块、数据库、小程序前端的全面审查后确认：

一、项目背景与目标

1.1 背景

当前 MES 大宗物料系统已完成入库功能（扫码→称重→临时表→存盘→同步U8），但出库环节空白。结算中心仍在使用老旧的销售出库流程，效率低下且数据追溯困难。

1.2 目标

开发大宗物料销售出库功能，使结算中心、装卸工、成品库人员、地磅室能在 MES 中完成从创建登记单到最终生成 U8 销售出库单的完整出库流程。同时支持工作量统计，为工资核算提供数据支持。

1.3 核心设计原则

二、系统定位与设计原则

2.1 系统定位

┌──────────────────────────────────────────────────────┐
│              用友U8 ERP（主数据源 / 财务核算系统）     │
│                                                      │
│  库存管理 ←→ 销售发货单 ←→ 销售出库单 ←→ 财务核算    │
│                      ▲               ▲               │
│                      │ 读取          │ 写入           │
│                      │               │               │
│  ┌───────────────────┴───────────────┴─────────────┐ │
│  │          MES大宗物料系统（现场操作终端）         │ │
│  │                                                  │ │
│  │  ┌──────────┐ ┌──────────┐ ┌────────┐ ┌──────┐ │ │
│  │  │ 销售出库 │ │ 库提拆件 │ │ 订单   │ │工作量│ │ │
│  │  │ 主流程   │ │ 子系统   │ │ 完善   │ │统计  │ │ │
│  │  └──────────┘ └──────────┘ └────────┘ └──────┘ │ │
│  │  ┌──────────┐                                   │ │
│  │  │ 库位管理 │                                   │ │
│  │  └──────────┘                                   │ │
│  └─────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────┘

MES的职责：从U8读取库存、发货单、客户、产品等参考数据；连接地磅获取实时重量；扫合格证实现单品级出库追溯；业务完成后将结果写回U8。

MES不做的事：不维护独立的库存主数据；不做财务核算；不做采购管理。

三、角色与权限模型

3.1 角色总览

3.2 权限矩阵

3.3 核心规则

3.4 角色说明

四、核心设计理念

4.1 「扫码认领制」

4.2 「一票到底」模式

一张纸质登记单 = 一个二维码 = 全流程通行证

同一张纸质登记单在司机/装卸工手中物理流转，各站点人员扫码即操作。系统完全不感知「谁拿着纸质单」，只感知「谁扫了二维码在操作」。

4.3 「逐件计工」模式

v3.1 的问题：certificate_operator 在表头上，只能记录一个人，无法处理多人协作装同一车。

解决方案：建立独立的扫码记录表，每扫一个合格证 = 一条记录。

登记单 20260501-A3F7K2

扫描记录表 dzwl_outbound_scan_record：
┌────┬──────┬──────────┬──────────────┬──────┐
│ 序号│ 人员 │ 合格证码  │ 入库重量(t)   │ 时间 │
├────┼──────┼──────────┼──────────────┼──────┤
│  1 │ 张三 │ ZS001    │    2.500     │ 09:15│ ← 张三工作量
│  2 │ 张三 │ ZS002    │    3.200     │ 09:17│ ← 张三工作量
│  3 │ 李四 │ ZS003    │    2.800     │ 09:22│ ← 李四工作量
│  4 │ 李四 │ ZS004    │    3.100     │ 09:25│ ← 李四工作量
│  5 │ 王五 │ ZS005    │    2.200     │ 09:30│ ← 王五工作量
└────┴──────┴──────────┴──────────────┴──────┘

五、核心业务流程

5.1 兼容三种流转模式

5.2 模式B流程详解（司机全程自助）

步骤① 结算中心(PC)：创建登记单→打印纸质单→交给司机
步骤② 司机开车到地磅 → 将纸质单交给地磅室人员 → 地磅室人员扫二维码 → 称皮重 → 绑定 → 纸质单还给司机
步骤③ 司机开车到成品库 → 将纸质单交给成品库人员 → 逐件装车+扫合格证 → 多人协作各自计工 → 纸质单还给司机
步骤④ 司机开车回地磅 → 将纸质单交给地磅室人员 → 称毛重 → 确认出库 → 纸质单还给司机
步骤⑤ 司机到结算中心 → 交纸质单 → 结算中心审核 → 生成U8销售出库单 → 开出门证 → 完成

5.3 步骤详解

步骤①：结算中心创建登记单 + 打印纸质单

结算中心在MES PC端，进入「大宗物料→销售出库→登记单管理」，点击「新建登记单」。系统调用U8 API获取「已保存未出库」的U8发货单列表供筛选。选择发货单后系统自动拉取数据预填。不指定操作人。保存后系统自动：生成登记单号（格式：yyyyMMdd-6位随机码）、生成登记单二维码、计算装车路线、状态→待称皮重。

步骤②：称皮重

操作者打开小程序，扫码获取登记单。系统校验：二维码有效 + 状态=待称皮重 + 有操作角色。核对车牌号，引导车辆上磅，点击获取皮重（轮询磅秤API），稳定后点击绑定为皮重。自动记录操作人信息，状态→待装车。

步骤③：装车扫码

操作者引导车辆到成品库。扫纸质登记单二维码进入界面。逐件装车+立即扫合格证码，校验有效性/是否已出库/合同号。每扫一件插入一条扫描记录。支持多人协作，各自记录名下。

步骤④：称毛重 + 确认出库

装车完毕，车辆驶回地磅。核对已绑定列表，实时显示毛重并自动计算净重和差值。差值≤0.2吨时可确认出库：分配净重到每件产品、标记is_delivered、回写U8发货单、记录确认操作人、状态→待审核。

步骤⑤：审核

结算中心筛选「待审核」登记单，点击审核。系统执行：保存U8销售出库单→获取u8SaleOutId→审核U8销售出库单→状态→已完成→二维码失效→开具出门证。

5.4 称重技术方案

统一使用 IWeighService 直连地磅硬件（与入库称重完全一致）。

调用链路：小程序前端 → ExternalServiceController → WeighServiceImpl → 地磅硬件 (POST https://www.kingpipe.com:17601/process_number)

六、厂区引导方案

6.2 三级引导牌体系

第一级：厂区入口总导览

┌──────────────────────────────────────────────┐
│              XX钢管厂 物流路线导览             │
│                                              │
│   ┌──────┐     ┌────────┐     ┌──────┐      │
│   │ 地磅 │ →→→ │ 成品库 │ →→→ │ 地磅 │       │
│   │ ①号 │     │        │     │ ①号 │       │
│   └──────┘     └────────┘     └──────┘      │
│                                              │
│   成品库编号：A库=冷拔无缝管  B库=热轧无缝管   │
│              C库=毛管        D库=其他产品     │
└──────────────────────────────────────────────┘

6.3 引导牌编号体系

七、纸质登记单设计

7.1 打印规格

7.2 版式设计（横向布局）

┌──────┬──────────────────────────────────────────────────────────────────┐
│      │                      大宗物料出库登记单                          │
│      │                 No: 20260501-A3F7K2                           │
│      │                                                                  │
│ 二   │  车牌：鲁Q-XXXXX                                                   │
│ 维   │                                                                  │
│ 码   │  装车路线：                                                       │
│ 区   │  地磅①号 ─→ 成品库A(冷拔) ─→ 成品库B(热轧) ─→ 地磅①号 ─→ 结算中心│
│ 域   │                                                                  │
│ 48mm │  ───────────────────────────────────────────────────────────     │
│  ×   │  装车明细：                                                       │
│ 48mm │  ┌────┬──────┬──────────┬──────┬──────┬────────┬──────────────┐ │
│      │  │序号│品名  │ 规格型号  │ 钢号 │ 标准 │数量(吨)│库位(第X站)   │ │
│      │  ├────┼──────┼──────────┼──────┼──────┼────────┼──────────────┤ │
│      │  │ 1  │ 冷管 │ 60×5     │ 20#  │ 8163 │ 10.000 │A库 ← 第1站  │ │
│      │  │ 2  │ 热管 │ 89×6     │ 45#  │ 3087 │ 15.000 │B库 ← 第2站  │ │
│      │  │ 3  │ 冷管 │ 76×4.5   │ 20#  │ 8163 │  8.000 │A库 ← 第1站  │ │
│      │  └────┴──────┴──────────┴──────┴──────┴────────┴──────────────┘ │
│      │                                                                  │
│      │  装车顺序：先到A库装1、3号(共18.000吨) → 再到B库装2号           │
│      │                                                                  │
│      │  ───────────────────────────────────────────────────────────     │
│      │  JBC-MES大宗物料系统                                               │
└──────┴──────────────────────────────────────────────────────────────────┘

八、装车路线规划

8.1 路线规划逻辑

系统处理流程：从登记单表体获取所有待出库产品 → 查询各产品对应的库存位置（库位编码）→ 按库位分组 → 按库位与地磅的距离排序确定访问顺序 → 生成路线并打印在纸质登记单上。

8.2 库位数据来源

九、状态机设计

                   ┌─────────┐
                   │  草稿   │  (PC端新建未保存)
                   │  DRAFT  │
                   └────┬────┘
                        │ 保存 + 计算装车路线
                        ▼
                   ┌─────────┐
                   │ 待称皮重│  扫码认领→称皮重→记录tare_operator
                   │ PENDING │
                   │ _TARE   │
                   └────┬────┘
                        │
                        ▼
                   ┌─────────┐
                   │ 待装车  │  扫码认领→逐件装车扫码
                   │ TARE    │  每件→插入scan_record(含操作人)
                   │ _DONE   │  多人可协作，各自记录
                   └────┬────┘
                        │ 装车完毕→回车称毛重→校验差值→确认出库
                        │ 记录confirm_operator + 回写U8发货单
                        ▼
                   ┌─────────┐
                   │ 待审核  │  仅结算中心可审核
                   │ PENDING │
                   │ _REVIEW │
                   └────┬────┘
                        │ 审核 → 生成+审核U8销售出库单
                        ▼
                   ┌─────────┐
                   │ 已完成  │  二维码失效，纸质单归档
                   │ COMPLETE│
                   │ D       │
                   └─────────┘


   ┌─────────┐  任一环节结算中心可手动   ┌─────────┐
   │ 已作废  │ ◀────────────────────── │任意状态 │
   │ CANCELLE│                         │(除已完成)│
   │ D       │                         └─────────┘
   └─────────┘

十、异常处理机制

十一、功能模块清单

十二、模块A：销售出库主流程

12.1 PC端：登记单管理

路径：大宗物料 → 销售出库 → 登记单管理

12.1.1 登记单列表

筛选条件：登记单号、U8发货单号、客户、车牌号、状态、日期范围。列表字段：登记单号、发货单号、客户、车牌号、皮重、毛重、净重、称皮人、状态、创建时间。操作按钮：查看详情、打印纸质登记单、作废（非终态）、审核（待审核态）。

12.1.2 新建登记单

1. 「新建登记单」
2. 系统调用U8 API获取发货单列表（仅「已保存未完成出库」的U8发货单）
3. 选择发货单后，自动拉取预填表头（客户名称、销售部门、U8发货单号、发货日期、车牌号）和表体（存货编码、存货名称、规格型号、钢号、标准、发货数量）
4. 点击「保存」→ 生成登记单号 + 二维码 + 计算装车路线 → 状态：待称皮重
5. 可选择立即打印纸质登记单

12.1.3 审核登记单

1. 筛选「待审核」→ 查看详情，确认数据完整
2. 点击「审核」
3. 系统执行：调用U8 API /api/SaleOut/save 保存销售出库单 → 调用U8 API /api/saleout/Verify 审核出库单 → 状态→已完成 → 开具出门证

12.2 小程序端：登记单操作

路径：大宗物料 → 出库操作

入口：扫码认领 — 操作者打开小程序，扫描纸质登记单二维码，系统校验二维码有效性+登记单状态+操作者角色，通过后打开对应状态的操作界面。

十三、模块B：库提拆件子系统

13.1 业务场景

客户购买一件产品（多根钢管打包成一件）中的部分钢管。由成品库人员操作拆件。

13.2 拆件流程

原有入库件 (TrackNumber: 合格证1, is_split = 0)
  │
  │ 成品库人员拆为 2 件
  │
  ├──▶ 出库件 (给客户) → 库提出库(临时出库单) → 库提出库存盘 → U8产成品出库单
  │    新合格证: TrackNumber-S1
  │    重量: 原入库重的一部分
  │
  └──▶ 剩件 (回库) → 库提入库(临时入库单) → 库提入库存盘 → U8产成品入库单
       新合格证: TrackNumber-S2
       重量: 原入库重的一部分

原有入库件 → is_split = 1（标记已拆件）

13.3 四个子页面

库提出库：扫原有合格证码→填写拆出数量→生成新合格证码→生成临时出库单→打印新合格证。

库提出库存盘：筛选待存盘的临时出库记录→批量选择→存盘→调用U8 API生成产成品出库单。

库提入库：自动获取拆件后剩余信息→生成新合格证码→入库重量=原入库重-拆出重量→生成临时入库单→打印新合格证。

库提入库存盘：筛选待存盘→批量存盘→调用U8 API生成产成品入库单。

十四、模块C：订单管理完善

十五、模块D：出库工作量统计

15.1 数据来源

基于新表 dzwl_outbound_scan_record。称皮重和确认出库的操作人仍在表头，单独查询。

15.2 统计维度

15.4 工作量统计接口

十六、模块E：库位管理

在 dzwl_inbound_body 新增 warehouse_code VARCHAR(20)。入库时由成品库人员在下拉列表中选择，仓库编码与引导牌编号一致（A、B、C、D）。

十七、数据模型设计

17.1 表结构总览

17.2 dzwl_inbound_body（修改：新增字段）

17.3 dzwl_outbound_header（登记单表头，终版）

17.5 dzwl_outbound_scan_record（扫码记录表，新增—逐件计工核心）

十八、API接口设计

18.1 PC端接口

18.2 小程序端接口

18.3 扫码绑定合格证接口（核心）

POST /warehouse/outbound/{headerId}/scan-certificate

请求体：
{
  "trackNumber": "合格证码"
}

响应：
{
  "code": 200,
  "data": {
    "scanRecordId": 123,
    "productName": "冷拔无缝管",
    "specification": "60×5",
    "steelGrade": "20#",
    "batchNumber": "P20260501001",
    "inboundWeight": 2.500,
    "inboundPieces": 15,
    "warehouseCode": "A",
    "operatorName": "张三"
  }
}

十九、U8接口集成方案

19.1 两条通信渠道

19.2 创建登记单时「选U8发货单」

19.3 确认出库时「回写U8发货单」

调用 /api/Consignment/save，传入已有 dlid 即为更新。回写内容：实际称重重量 → iquantity。

19.4 审核登记单时「生成U8销售出库单」

第一步：POST /api/SaleOut/save → 返回 Data = U8出库单ID

第二步：审核销售出库单

POST http://www.kingpipe.com:9004/api/saleout/Verify?accnum={accNum}&id={u8SaleOutId}
Header: Auth = u8_integration.auth

19.6 U8接口快速参考

二十、与现有系统的衔接

20.1 与入库系统的关联

20.3 前端页面调整

二十一、远期规划与扩展点

二十二、专业建议与风险提示

22.1 并发扫码

同一登记单二维码被两人同时扫：先扫者进入操作（Redis锁30s过期），后扫者提示「该登记单正在被 XXX 操作中」。

22.4 U8依赖

U8不可用时 MES 本地不中断。待 U8 恢复后通过补同步机制将本地数据推送到 U8。

22.5 审核接口方案（已确认）

22.6 幂等性控制

审核登记单的接口应加 @Idempotent 注解，防止重复生成U8出库单。

二十三、附录

A. 术语对照

C. 接口文档清单

D. 后续待开发

• 退货功能
• 报表生成（含装车吨位日报/月报）
• 自助终端对接
• 车牌识别集成