feat(outbound): 备选库位可见性，让「物理覆盖」不再盲扫

问题 ---- 预占会把货锁定在某个库位，但工人到现场可能进不去/找不到该库位，需要改扫同物料的其它批次。后端执行端已支持按 base_id 校验、允许换批次，但系统从不告诉他「还有哪些库位有货」—— 工人只能凭记忆或挨个翻。后端：新增 GET /api/v1/outbound/alternatives -------------------------------------------- 入参 base_id（必填）、source_table/stock_id（可选，用于标注推荐行）返回该物料全部可用库存行 + 合计可用量，推荐行置顶、其余按可用量降序。为什么不复用 stock/list 或 bom-match-stock 的查询模式：那两处按 stock_quantity > 0 过滤，会把「有货但已被别单全部预占」的库位也列出来，工人跑过去才发现拿不到。实测库中有 14 行处于该状态。本接口按 available_quantity > 0 过滤，只给真正能拿的库位。前端：计划清单库位列加图标 + popover ------------------------------------ [推荐] Y1/2/1 可用 5 ← 本单锁定行（来自 items_json 的 stock_id） [备选] Y2/3/4 可用 10 [备选] Z1/1/1 可用 2 三处取舍： · trigger="click" 而非 hover —— 车间用扫码枪/触摸屏，hover 在触屏不可用 · @show 时才发请求 —— 计划清单可能几十行，渲染即请求会打出一片并发 · 附提示文案「现场取不到推荐库位时可直接扫备选库位条码出库」注：历史单据的 items_json 无 stock_id，此时所有库位显示为「备选」（不影响可用性，仅少了推荐标记）；预占改造后新提交的单可正确标注。实测：造 3 批次 Y1/2/1(5) Y2/3/4(10) Z1/1/1(2)，预占首个后其 available=0，接口正确排除该库位，返回两个备选、合计可用 12。
2026-09-10 14:59:17 +08:00
parent b57c21a4cd
commit 209b29c10f
3 changed files with 231 additions and 4 deletions
--- a/inventory-backend/app/api/v1/outbound.py
+++ b/inventory-backend/app/api/v1/outbound.py
@ -351,6 +351,99 @@ def _allocate_bom_requirements(requirements, company_limit,
    }), 200


+# ==============================================================================
+# 备选库位查询 (GET /api/v1/outbound/alternatives)
+#
+# 场景：申请单已把货预占在某个库位，但工人到现场发现该库位进不去/找不到，
+# 需要改扫同物料的其它批次。改造前系统不告诉他「还有哪些库位有货」，
+# 工人只能凭记忆或挨个翻 —— 这个接口就是为「物理覆盖」提供可见性。
+#
+# 与 bom-match-stock 查询模式的区别：
+#   · 该模式按 stock_quantity > 0 过滤，会把「有货但已被别单全部预占」的
+#     库位也列出来，工人跑过去才发现拿不到货；
+#   · 本接口按 available_quantity > 0 过滤，只给**真正能拿**的库位，
+#     并额外标注哪一条是本单锁定的推荐行。
+# ==============================================================================
+@outbound_bp.route('/alternatives', methods=['GET'])
+@jwt_required()
+def get_stock_alternatives():
+    """
+    查询某物料的全部可替代库位（available_quantity > 0）。
+
+    Query: base_id（必填）、source_table / stock_id（可选，用于标注推荐行）
+    Returns: { items: [{stock_id, source_table, warehouse_location,
+                        available_quantity, is_locked, typeLabel, sku, batch_number}] }
+    """
+    try:
+        base_id = request.args.get('base_id', type=int)
+        if not base_id:
+            return jsonify({'code': 400, 'msg': 'base_id 不能为空'}), 400
+
+        prefer_table = (request.args.get('source_table') or '').strip()
+        try:
+            prefer_stock_id = int(request.args.get('stock_id') or 0)
+        except (TypeError, ValueError):
+            prefer_stock_id = 0
+
+        from app.utils.decorators import get_current_company_filter
+        from app.models.base import MaterialBase
+        from app.models.inbound.buy import StockBuy
+        from app.models.inbound.semi import StockSemi
+        from app.models.inbound.product import StockProduct
+        from sqlalchemy.orm import joinedload
+
+        company_limit = get_current_company_filter()
+        items = []
+
+        for model, source_table, label in (
+            (StockBuy, 'stock_buy', '采购件'),
+            (StockSemi, 'stock_semi', '半成品'),
+            (StockProduct, 'stock_product', '成品'),
+        ):
+            q = model.query.filter(
+                model.base_id == base_id,
+                model.available_quantity > 0,   # ★ 只给真正能拿的
+            )
+            if company_limit is not None:
+                q = q.filter(model.base.has(MaterialBase.company_name == company_limit))
+            try:
+                rows = q.options(joinedload(model.base)).all()
+            except Exception as e:
+                current_app.logger.error(
+                    f"[alternatives] {source_table} 查询失败: {type(e).__name__}: {e}"
+                )
+                continue
+
+            for s in rows:
+                items.append({
+                    'stock_id': s.id,
+                    'source_table': source_table,
+                    'typeLabel': label,
+                    'sku': s.sku or '',
+                    'batch_number': getattr(s, 'batch_number', '') or getattr(s, 'serial_number', '') or '',
+                    'warehouse_location': getattr(s, 'warehouse_location', '') or '',
+                    'available_quantity': float(s.available_quantity or 0),
+                    # ★ 该行是否就是本单锁定的推荐批次
+                    'is_locked': (prefer_stock_id and s.id == prefer_stock_id
+                                  and source_table == prefer_table),
+                })
+
+        # 排序：推荐行置顶，其余按可用量降序（工人优先看到货最多的库位）
+        items.sort(key=lambda x: (not x['is_locked'], -x['available_quantity']))
+
+        return jsonify({
+            'code': 200, 'msg': 'success',
+            'data': {
+                'items': items,
+                'total_available': round(sum(i['available_quantity'] for i in items), 4),
+            }
+        }), 200
+
+    except Exception as e:
+        traceback.print_exc()
+        return jsonify({'code': 500, 'msg': f'查询备选库位失败: {str(e)}'}), 500
+
+
 # ==============================================================================
 # BOM 匹配库存接口 (POST /api/v1/outbound/bom-match-stock)
 #