feat: 多系统新增扫码中间件与 AGV 对接,优化拧紧与退库流程

新增扫码中间件支持网络型扫码枪键盘注入,AGV 对接从 WMS 迁至 MES 统一管理;新增拧紧不合格人工处置与 PLC 对账机制,优化退库单关联与工位终端功能,同时清理旧 AGV 任务表,完善数据库与配置项。
This commit is contained in:
SunYF
2026-10-14 17:24:59 +08:00
parent 8e6048c64b
commit f65a52d9e1
170 changed files with 15415 additions and 10572 deletions
+2 -414
View File
@@ -9,7 +9,6 @@ import (
"bj_power_wms/ent"
"bj_power_wms/ent/inventory"
"bj_power_wms/ent/material"
"bj_power_wms/ent/ordermaterialledger"
"bj_power_wms/ent/outbounddetail"
"bj_power_wms/ent/outboundorder"
"bj_power_wms/internal/svc"
@@ -17,419 +16,6 @@ import (
"github.com/zeromicro/go-zero/core/logx"
)
// deductStockRequest 出库扣减请求
// createOutboundHandler 创建出库单(等价于扣减库存,走同一套约束)
func createOutboundHandler(ctx *svc.ServiceContext) http.HandlerFunc {
return deductStockHandler(ctx)
}
type deductStockRequest struct {
OrderNo string `json:"orderNo"`
MaterialCode string `json:"materialCode"`
BatchNo string `json:"batchNo"`
SnList []string `json:"snList"`
Qty int `json:"qty"`
Operator string `json:"operator"`
Reviewer string `json:"reviewer"`
TargetDock string `json:"targetDock"`
ZoneCode string `json:"zoneCode"`
ShelfNo string `json:"shelfNo"`
LayerNo string `json:"layerNo"`
PositionNo string `json:"positionNo"`
Remark string `json:"remark"`
OutboundNo string `json:"outboundNo"` // 可选:留空自动生成;填了必须唯一(如 OB20260921-001)
// OutboundType 出库类型:workorder(备料出库,默认) / refill(工位叫料·补料出库)
OutboundType string `json:"outboundType"`
// NeedAgv 是否需要 AGV 配送到接驳台(备料/补料一般为 true)
NeedAgv bool `json:"needAgv"`
// OverReason 超物料清单领用原因(损耗/报废/返修/其他)。
// 超领不硬卡:net_out > 需求时,填了原因即放行并留痕;未填仍 409 拦截。
OverReason string `json:"overReason"`
// IdempotencyKey 幂等键(安全审计 C2):调用方(如 MES 备料自动出库网络超时重试)
// 传入稳定唯一键,同一键重复提交直接复用已生成的出库单,避免重复扣减库存。
// 留空则按 OutboundNo 规则(手填校验唯一 / 留空自动生成)处理。
IdempotencyKey string `json:"idempotencyKey"`
}
// deductStockHandler 出库扣减
// body: { orderNo, materialCode, batchNo?, snList?[], qty, operator, targetDock? }
// 强约束:累计出库 ≤ 工单物料清单需求量;等于时领料完结。
//
// 事务保证:出库单 + 库存行扣减(inventory) + 出库明细 + 工单台账 原子提交,
// 任一环节失败整体回滚,杜绝"出库单生成了但库存没扣"或"台账没更新"的中间态。
// 扣减本身用条件原子更新(AddQuantity(-qty) WHERE quantity>=qty),即使并发也不会出现负库存。
func deductStockHandler(ctx *svc.ServiceContext) http.HandlerFunc {
return func(w http.ResponseWriter, r *http.Request) {
var req deductStockRequest
if err := parseJSON(r, &req); err != nil {
fail(w, http.StatusBadRequest, "参数错误: "+err.Error())
return
}
if req.OrderNo == "" || req.MaterialCode == "" {
fail(w, http.StatusBadRequest, "orderNo 和 materialCode 必填")
return
}
// 1. 工单台账强约束:累计出库 ≤ 总需求
ledger, err := ctx.EntClient.OrderMaterialLedger.Query().
Where(
ordermaterialledger.OrderNoEQ(req.OrderNo),
ordermaterialledger.MaterialCodeEQ(req.MaterialCode),
).
Only(ctx0())
if err != nil {
fail(w, http.StatusBadRequest, "工单物料台账不存在,请先在 MES 同步工单物料清单后再领料;如无需挂靠工单(退料/样品/报废/发货),请改用「通用出库」: "+req.OrderNo+"/"+req.MaterialCode)
return
}
if ledger.Status == "领料完结" {
fail(w, http.StatusConflict, "工单领料已完结,禁止再出库")
return
}
// 物料档案:sn_mode 守卫 + 出库单冗余类型/序列号方式
m, merr := ctx.EntClient.Material.Query().
Where(material.CodeEQ(req.MaterialCode)).
Only(ctx0())
if merr != nil {
fail(w, http.StatusBadRequest, "物料不存在: "+req.MaterialCode)
return
}
// sn_mode 守卫(2026-09-30 解耦定稿):物料档案未设置序列号(是/否),禁止出库
if m.SnMode == snModeUnset {
fail(w, http.StatusBadRequest, "请先在物料档案设置序列号(是/否)")
return
}
// 实际扣减数量
actualQty := req.Qty
if req.BatchNo == "" && len(req.SnList) == 0 {
fail(w, http.StatusBadRequest, "batchNo 或 snList 至少提供一个")
return
}
// 盘点冻结守卫(问题2):盘点期间该批库存禁止出库,避免差异混入业务变动。
if !assertNotFrozenTargets(ctx, w, req.BatchNo, req.SnList) {
return
}
// C2 幂等键(安全审计):调用方传入幂等键(如 MES 自动出库超时重试),
// 同一键重复提交直接复用已生成的出库单,避免重复扣减库存。
outboundNo := strings.TrimSpace(req.IdempotencyKey)
if outboundNo != "" {
if exist, e := ctx.EntClient.OutboundOrder.Query().
Where(outboundorder.OutboundNoEQ(outboundNo)).Only(ctx0()); e == nil && exist != nil {
// 幂等复用:该出库请求此前已处理,直接返回既有单据与状态,不再扣减。
ok(w, map[string]any{
"outboundNo": outboundNo,
"qty": exist.Quantity,
"orderNo": req.OrderNo,
"outboundType": exist.OutboundType,
"status": exist.Status,
"idempotent": true,
"message": "幂等复用:该出库请求此前已处理",
})
return
}
} else if obNo := strings.TrimSpace(req.OutboundNo); obNo != "" {
if err := validateUniqueNo(ctx, "OB", obNo); err != nil {
fail(w, http.StatusBadRequest, err.Error())
return
}
outboundNo = obNo
} else {
no, err := nextDailyNo(ctx, "OB")
if err != nil {
fail(w, http.StatusInternalServerError, "生成出库单号失败: "+err.Error())
return
}
outboundNo = no
}
// 开启事务:出库单 + 库存扣减 + 明细 + 台账 原子提交
tx, err := ctx.EntClient.Tx(ctx0())
if err != nil {
fail(w, http.StatusInternalServerError, "开启事务失败: "+err.Error())
return
}
committed := false
defer func() {
if !committed {
_ = tx.Rollback()
}
}()
// 1.5 出库库位兜底(客户诉求 一.9「出库相同」):未填的层级按
// 「批次在库记录 → 首个 SN 在库记录」补全,保证出库单留痕到具体货位。
// 条9 强校验:只要显式填了任一库位层级,SN/批次所在货位必须与所填一致。
specZone, specShelf, specLayer, specPos := req.ZoneCode, req.ShelfNo, req.LayerNo, req.PositionNo
locSpecified := specZone != "" || specShelf != "" || specLayer != "" || specPos != ""
req.ZoneCode, req.ShelfNo, req.LayerNo, req.PositionNo =
outboundLocationFallback(ctx, req.BatchNo, req.SnList, req.ZoneCode, req.ShelfNo, req.LayerNo, req.PositionNo)
// 2. 创建出库单(出库即扣库存 → 初始状态「已出库」;叫AGV到位后置「已送达」)
obType := req.OutboundType
if obType != "refill" {
obType = "workorder"
}
pw := "" // 产品工号:从源库存取,出库单创建后回填(五页带出)
ob, err := tx.OutboundOrder.Create().
SetOutboundNo(outboundNo).
SetOutboundType(obType).
SetStatus("已出库").
SetNeedAgv(req.NeedAgv).
SetNillableOrderNo(strPtr(req.OrderNo)).
SetMaterialCode(req.MaterialCode).
SetManageMode(m.ManageMode).
SetSnMode(m.SnMode).
SetNillableBatchNo(strPtr(req.BatchNo)).
SetNillableZoneCode(strPtr(req.ZoneCode)).
SetNillableShelfNo(strPtr(req.ShelfNo)).
SetNillableLayerNo(strPtr(req.LayerNo)).
SetNillablePositionNo(strPtr(req.PositionNo)).
SetQuantity(0).
SetNillableOperator(strPtr(req.Operator)).
SetNillableReviewer(strPtr(req.Reviewer)).
SetNillableTargetDock(strPtr(req.TargetDock)).
SetNillableRemark(strPtr(req.Remark)).
Save(ctx0())
if err != nil {
// 并发幂等:另一条相同幂等键/单号的请求已抢先落库,复用其单号返回。
if isDuplicateOutboundNo(err) {
if exist, e2 := ctx.EntClient.OutboundOrder.Query().
Where(outboundorder.OutboundNoEQ(outboundNo)).Only(ctx0()); e2 == nil && exist != nil {
ok(w, map[string]any{
"outboundNo": outboundNo,
"qty": exist.Quantity,
"orderNo": req.OrderNo,
"outboundType": exist.OutboundType,
"status": exist.Status,
"idempotent": true,
"message": "幂等复用:该出库请求此前已处理",
})
return
}
}
fail(w, http.StatusInternalServerError, "创建出库单失败: "+err.Error())
return
}
// 3. 扣减批次(原子:quantity>=qty 才减,避免超扣/负数;locked_qty 同步回收)
if req.BatchNo != "" {
bq := tx.Inventory.Query().
Where(inventory.SnModeEQ(snModeBatch), inventory.BatchNoEQ(req.BatchNo), inventory.MaterialCodeEQ(req.MaterialCode),
inventory.StatusIn("在库", "锁定")) // 条9 前置:仅允许对在库/锁定库存行出库(必须有有效库存行)
// 条9:指定了库位时按该库位的批次行校验可用量
if locSpecified {
if specZone != "" {
bq = bq.Where(inventory.ZoneCodeEQ(specZone))
}
if specShelf != "" {
bq = bq.Where(inventory.ShelfNoEQ(specShelf))
}
if specLayer != "" {
bq = bq.Where(inventory.LayerNoEQ(specLayer))
}
if specPos != "" {
bq = bq.Where(inventory.PositionNoEQ(specPos))
}
}
b, err := bq.Only(ctx0())
if err != nil {
// 区分「批次不存在」「批次不属于所选物料」「不在指定库位」三种情况给出明确中文错误
if locSpecified {
if exist, e2 := tx.Inventory.Query().
Where(inventory.SnModeEQ(snModeBatch), inventory.BatchNoEQ(req.BatchNo), inventory.MaterialCodeEQ(req.MaterialCode)).
Exist(ctx0()); e2 == nil && exist {
fail(w, http.StatusBadRequest, "SN/批次不在指定库位: "+req.BatchNo)
return
}
}
if exist, e2 := tx.Inventory.Query().
Where(inventory.SnModeEQ(snModeBatch), inventory.BatchNoEQ(req.BatchNo)).
Exist(ctx0()); e2 == nil && exist {
fail(w, http.StatusBadRequest, "批次不属于所选物料: "+req.BatchNo+" / "+req.MaterialCode)
return
}
fail(w, http.StatusBadRequest, "批次不存在: "+req.BatchNo)
return
}
pw = b.ProductWorkNo // 取源库存产品工号,回填出库单
avail := b.Quantity - b.LockedQty
if avail < req.Qty {
fail(w, http.StatusConflict, "批次库存不足: "+req.BatchNo+" 可用 "+itoa(avail))
return
}
// 质量门禁(P0-2,客户口径):仅「合格」批次可领料上线;未检(待检)/不合格/待退 一律拦截
if b.QualityStatus != QStatusPass {
fail(w, http.StatusConflict, "批次 "+req.BatchNo+" 质量状态为「"+qualityLabel(b.QualityStatus)+"」,仅合格品可领料上线(请先完成质量检验)")
return
}
aff, err := tx.Inventory.Update().
Where(inventory.ID(b.ID), inventory.QuantityGTE(req.Qty)).
AddQuantity(-req.Qty).
AddLockedQty(-min(req.Qty, b.LockedQty)).
Save(ctx0())
if err != nil || aff == 0 {
fail(w, http.StatusConflict, "批次扣减失败(库存不足或并发冲突): "+req.BatchNo)
return
}
if _, err = tx.OutboundDetail.Create().
SetOutboundNo(outboundNo).
SetBatchNo(req.BatchNo).
SetMaterialCode(req.MaterialCode).
SetQuantity(req.Qty).
SetNillableOrderNo(strPtr(req.OrderNo)).
Save(ctx0()); err != nil {
fail(w, http.StatusInternalServerError, "创建出库明细失败: "+err.Error())
return
}
actualQty = req.Qty
}
// 4. 扣减 SN(原子:仅 在库/锁定 的 SN 可出库 → 置出库)
// 质量门禁(P0-2,客户口径):仅「合格」SN 可出库(未检/不合格/待退 拦截;退货/报废走「通用出库」)
if len(req.SnList) > 0 {
for _, sn := range req.SnList {
// 条9:校验 SN 属于所选物料;填了库位时所在货位须与所填一致
invRow, e := tx.Inventory.Query().
Where(inventory.SnModeEQ(snModeSN), inventory.SnCodeEQ(sn)).
Only(ctx0())
if e != nil {
fail(w, http.StatusBadRequest, "SN 不存在: "+sn)
return
}
if invRow.MaterialCode != req.MaterialCode {
fail(w, http.StatusBadRequest, "SN 不属于所选物料: "+sn)
return
}
if locSpecified && !locationMatches(invRow, specZone, specShelf, specLayer, specPos) {
fail(w, http.StatusBadRequest, "SN/批次不在指定库位: "+sn)
return
}
if pw == "" {
pw = invRow.ProductWorkNo
}
aff, err := tx.Inventory.Update().
Where(inventory.SnModeEQ(snModeSN), inventory.SnCodeEQ(sn), inventory.MaterialCodeEQ(req.MaterialCode), inventory.StatusIn("在库", "锁定"),
inventory.QualityStatusEQ(QStatusPass)).
SetStatus("出库").
SetNillableZoneCode(strPtr(req.ZoneCode)).
Save(ctx0())
if err != nil {
fail(w, http.StatusInternalServerError, "SN 出库失败: "+sn+" "+err.Error())
return
}
if aff == 0 {
fail(w, http.StatusBadRequest, "SN 不可出库(不存在、非在库/锁定,或质量状态非「合格」): "+sn)
return
}
if _, err = tx.OutboundDetail.Create().
SetOutboundNo(outboundNo).
SetSnCode(sn).
SetMaterialCode(req.MaterialCode).
SetQuantity(1).
SetNillableOrderNo(strPtr(req.OrderNo)).
Save(ctx0()); err != nil {
fail(w, http.StatusInternalServerError, "创建出库明细失败: "+err.Error())
return
}
}
actualQty = len(req.SnList)
}
// 4.5 回填产品工号(从源库存取,五页带出展示/筛选)
if pw != "" {
if _, e := tx.OutboundOrder.UpdateOneID(ob.ID).SetNillableProductWorkNo(strPtr(pw)).Save(ctx0()); e != nil {
fail(w, http.StatusInternalServerError, "回填产品工号失败: "+e.Error())
return
}
}
// 5. 更新出库单实际数量
if _, err = tx.OutboundOrder.UpdateOneID(ob.ID).
SetQuantity(actualQty).Save(ctx0()); err != nil {
fail(w, http.StatusInternalServerError, "更新出库单失败: "+err.Error())
return
}
// 6. 更新工单台账:累计出库(在事务内重读台账,避免并发重复累计)
ledgerNow, err := tx.OrderMaterialLedger.Query().
Where(
ordermaterialledger.OrderNoEQ(req.OrderNo),
ordermaterialledger.MaterialCodeEQ(req.MaterialCode),
).Only(ctx0())
if err != nil {
fail(w, http.StatusInternalServerError, "重读台账失败: "+err.Error())
return
}
newOutQty := ledgerNow.OutQty + actualQty
// 超量拦截按「净领用」判定(out_qty − returned_qty):退料会回补缺口。
// 否则「出库100 → 退料20 → 再补料20」累计 120 > 需求 100,会被 409 永久拦死。
netOut := newOutQty - ledgerNow.ReturnedQty
overQty := 0
if netOut > ledgerNow.TotalQty {
// 超物料清单领用不硬卡:损耗/报废/返修会真实超出物料清单需求,硬卡会停线。
// 规则:填了超领原因即放行并留痕(可统计、可预警);未填仍拦截。
if req.OverReason == "" {
fail(w, http.StatusConflict, "出库数量超过工单物料清单需求: 净领用 "+itoa(netOut)+" > 需求 "+itoa(ledgerNow.TotalQty)+
"(已发出 "+itoa(ledgerNow.OutQty)+" − 已退回 "+itoa(ledgerNow.ReturnedQty)+" + 本次 "+itoa(actualQty)+");"+
"如确需超领(损耗/报废/返修),请填写超领原因后重试")
return
}
overQty = netOut - ledgerNow.TotalQty
}
status := ledgerNow.Status
if netOut >= ledgerNow.TotalQty {
status = "领料完结"
} else if status == "领料完结" {
// 退料回补后净额回落 → 状态回归「进行中」,允许再次补料
status = "进行中"
}
// 台账 completed_at = 最后一笔领料完结出库时间(客户诉求 问题记录 L238-240:台账增加完成时间筛选)
// 台账 out_qty 用原子自增(AddOutQty)替代「读改写绝对赋值」,消除并发丢失更新
//(C1:原 newOutQty = ledgerNow.OutQty + actualQty 再 SetOutQty 在并发下会少计)。
ledgerUpd := tx.OrderMaterialLedger.UpdateOneID(ledgerNow.ID).
AddOutQty(actualQty).
SetStatus(status)
if status == "领料完结" && ledgerNow.Status != "领料完结" {
ledgerUpd.SetCompletedAt(time.Now().Unix())
}
if _, err = ledgerUpd.Save(ctx0()); err != nil {
fail(w, http.StatusInternalServerError, "更新台账失败: "+err.Error())
return
}
// 7. 提交事务
if err = tx.Commit(); err != nil {
fail(w, http.StatusInternalServerError, "提交事务失败: "+err.Error())
return
}
committed = true
ctx.EventLog.Write(ctx0(), "outbound.create", r.Header.Get("X-Username"), "outbound", outboundNo,
"备料出库 工单 "+req.OrderNo+" 物料 "+req.MaterialCode+" ×"+itoa(actualQty),
map[string]any{"orderNo": req.OrderNo, "qty": actualQty, "overQty": overQty, "overReason": req.OverReason})
if overQty > 0 {
// 超领留痕:可统计、可预警(某工位频繁超领即异常信号)
ctx.EventLog.Write(ctx0(), "material.over", r.Header.Get("X-Username"), "order_material_ledger", req.OrderNo,
"超物料清单领用 "+req.MaterialCode+" 超 "+itoa(overQty)+" 原因:"+req.OverReason,
map[string]any{"orderNo": req.OrderNo, "materialCode": req.MaterialCode,
"overQty": overQty, "reason": req.OverReason, "netOut": netOut, "total": ledgerNow.TotalQty})
}
logx.Infof("deduct stock: order=%s material=%s qty=%d over=%d", req.OrderNo, req.MaterialCode, actualQty, overQty)
ok(w, map[string]any{
"outboundNo": outboundNo,
"qty": actualQty,
"orderNo": req.OrderNo,
"outboundType": obType,
"ledgerOut": newOutQty,
"ledgerReturned": ledgerNow.ReturnedQty,
"ledgerNet": netOut,
"ledgerTotal": ledgerNow.TotalQty,
"overQty": overQty,
"status": status,
})
}
}
// queryOutboundHandler 出库单查询
// 客户诉求 L96-108:按 归属单号 / 名称图号 / 日期范围 / 目标工位 查询,多条件取交集;
@@ -1076,6 +662,8 @@ func outboundCategoryLabel(v string) string {
return "发货"
case "supplier_return":
return "退货"
case "call":
return "叫料配送"
case "other":
return "其他"
default: