@blamejs/blamejs-shop 0.4.23 → 0.4.25

package/lib/stock-transfers.js

@@ -118,6 +118,70 @@ var TRANSFER_STATUSES = Object.freeze([
 var TRANSFER_ROLES    = Object.freeze(["origin", "destination"]);
 var TRANSFER_ORDER_KEY = ["opened_at:desc", "id:desc"];
 
+// The transfer lifecycle, modelled on b.fsm — the same composition the order
+// and quote primitives use (lib/order.js#_getOrderFsm, lib/quotes.js). The FSM
+// is the single source of truth for which (status, event) pairs are legal:
+// every status-changing verb replays the machine from the row's current status
+// and asks whether the edge is allowed before it touches the database, so an
+// illegal transition is refused identically regardless of which surface fired
+// it. Each event name maps 1:1 to the verb that fires it:
+//
+//   ship       open                 -> shipped     (markShipped)
+//   transit    shipped|in_transit   -> in_transit  (markInTransit; self-edge
+//                                                    keeps the scan-beat log)
+//   receive    shipped|in_transit   -> received    (markReceived)
+//   reconcile  received             -> reconciled  (reconcile; credits dest)
+//   except     open|shipped|in_transit|received
+//                                   -> exception   (markException)
+//
+// Terminal states (reconciled, exception) declare no outgoing edge, so the
+// machine itself refuses a double-reconcile / re-ship-after-exception without
+// a hand-written status check.
+var TRANSFER_TRANSITIONS = Object.freeze([
+  { from: "open",       to: "shipped",    on: "ship" },
+  { from: "shipped",    to: "in_transit", on: "transit" },
+  { from: "in_transit", to: "in_transit", on: "transit" },
+  { from: "shipped",    to: "received",   on: "receive" },
+  { from: "in_transit", to: "received",   on: "receive" },
+  { from: "received",   to: "reconciled", on: "reconcile" },
+  { from: "open",       to: "exception",  on: "except" },
+  { from: "shipped",    to: "exception",  on: "except" },
+  { from: "in_transit", to: "exception",  on: "except" },
+  { from: "received",   to: "exception",  on: "except" },
+]);
+
+var _transferFsm = null;
+function _getTransferFsm() {
+  if (_transferFsm) return _transferFsm;
+  // b.fsm emits audit events under the 'fsm' namespace — register it
+  // (idempotent) so the audit sink keeps the events instead of dropping them
+  // with a noisy warning, exactly as the order/quote FSMs do.
+  try { b.audit.registerNamespace("fsm"); } catch (_e) { /* idempotent; ignore */ }
+  _transferFsm = b.fsm.define({
+    name:    "stock_transfer",
+    initial: "open",
+    states: {
+      open:       {}, shipped:    {}, in_transit: {},
+      received:   {}, reconciled: {}, exception:  {},
+    },
+    transitions: TRANSFER_TRANSITIONS.map(function (t) {
+      return { from: t.from, to: t.to, on: t.on };
+    }),
+  });
+  return _transferFsm;
+}
+
+// Validate one status-changing edge through the FSM. Returns true when the
+// edge is legal from `fromStatus`, false otherwise. The verbs below use this
+// to decide whether to issue the atomic claim-guard UPDATE — they keep
+// throwing a TypeError on an illegal transition so the admin route's
+// `e instanceof TypeError -> 400` mapping (admin.js#_transferAction) stays
+// intact rather than surfacing a wrong-state as a 500.
+function _canTransfer(fromStatus, event) {
+  var fsm = _getTransferFsm();
+  return fsm.restore({ state: fromStatus, history: [], context: {} }).can(event);
+}
+
 // ---- validators ---------------------------------------------------------
 
 function _id(s, label) {
@@ -419,15 +483,21 @@ function create(opts) {
       if (!transfer) {
         throw new TypeError("stock-transfers.markShipped: transfer " + id + " not found");
       }
-      if (transfer.status !== "open") {
+      if (!_canTransfer(transfer.status, "ship")) {
         throw new TypeError("stock-transfers.markShipped: transfer is " + transfer.status +
           ", only open transfers can be shipped");
       }
-      await query(
+      // Claim the open -> shipped transition atomically — the WHERE status
+      // clause makes a concurrent double-ship a no-op for the loser.
+      var claim = await query(
         "UPDATE stock_transfers SET status = 'shipped', shipped_at = ?1, " +
-        "carrier = ?2, tracking_number = ?3 WHERE id = ?4",
+        "carrier = ?2, tracking_number = ?3 WHERE id = ?4 AND status = 'open'",
         [shippedAt, carrier, tracking, id],
       );
+      if (Number(claim.rowCount || 0) !== 1) {
+        throw new TypeError("stock-transfers.markShipped: transfer " + id +
+          " is no longer open (shipped by a concurrent call)");
+      }
       await _writeEvent(id, "ship", transfer.from_location, {
         carrier: carrier, tracking_number: tracking,
       }, shippedAt);
@@ -448,13 +518,17 @@ function create(opts) {
       if (!transfer) {
         throw new TypeError("stock-transfers.markInTransit: transfer " + id + " not found");
       }
-      if (transfer.status !== "shipped" && transfer.status !== "in_transit") {
+      if (!_canTransfer(transfer.status, "transit")) {
         throw new TypeError("stock-transfers.markInTransit: transfer is " + transfer.status +
           ", only shipped or in_transit transfers can record an in_transit scan");
       }
+      // Only the shipped -> in_transit edge flips status; the in_transit
+      // self-edge is an idempotent scan-beat that just appends an event. Claim
+      // the shipped -> in_transit flip with a WHERE status clause so two
+      // concurrent first-scans don't both believe they advanced the row.
       if (transfer.status === "shipped") {
         await query(
-          "UPDATE stock_transfers SET status = 'in_transit' WHERE id = ?1",
+          "UPDATE stock_transfers SET status = 'in_transit' WHERE id = ?1 AND status = 'shipped'",
           [id],
         );
       }
@@ -495,7 +569,7 @@ function create(opts) {
       if (!transfer) {
         throw new TypeError("stock-transfers.markReceived: transfer " + id + " not found");
       }
-      if (transfer.status !== "shipped" && transfer.status !== "in_transit") {
+      if (!_canTransfer(transfer.status, "receive")) {
         throw new TypeError("stock-transfers.markReceived: transfer is " + transfer.status +
           ", only shipped or in_transit transfers can be received");
       }
@@ -514,20 +588,44 @@ function create(opts) {
             " was not on the original transfer");
         }
       }
-      // Walk every shipped line; write quantity_received (defaulting
-      // to 0 for SKUs the operator didn't scan).
-      for (var u = 0; u < transfer.lines.length; u += 1) {
-        var line = transfer.lines[u];
-        var got  = Object.prototype.hasOwnProperty.call(rxMap, line.sku) ? rxMap[line.sku] : 0;
+      // Claim the (shipped|in_transit) -> received transition atomically
+      // BEFORE writing the per-line received quantities. Two concurrent
+      // receives both pass the read above, but only one UPDATE matches the
+      // expected status — the loser refuses, so a single set of
+      // quantity_received values lands and reconcile can't later credit twice.
+      var priorStatus = transfer.status;
+      var claim = await query(
+        "UPDATE stock_transfers SET status = 'received', received_at = ?1 " +
+        "WHERE id = ?2 AND status IN ('shipped', 'in_transit')",
+        [receivedAt, id],
+      );
+      if (Number(claim.rowCount || 0) !== 1) {
+        throw new TypeError("stock-transfers.markReceived: transfer " + id +
+          " is no longer shipped or in_transit (received by a concurrent call)");
+      }
+      // Walk every shipped line; write quantity_received (defaulting to 0 for
+      // SKUs the operator didn't scan). Each write is idempotent (the same
+      // quantity lands on a retry), so if a line throws the terminal claim is
+      // rolled back to its prior status — the transfer stays eligible for
+      // markReceived rather than stranding with partial / default quantities a
+      // later reconcile would then credit against.
+      try {
+        for (var u = 0; u < transfer.lines.length; u += 1) {
+          var line = transfer.lines[u];
+          var got  = Object.prototype.hasOwnProperty.call(rxMap, line.sku) ? rxMap[line.sku] : 0;
+          await query(
+            "UPDATE stock_transfer_lines SET quantity_received = ?1 WHERE id = ?2",
+            [got, line.id],
+          );
+        }
+      } catch (e) {
         await query(
-          "UPDATE stock_transfer_lines SET quantity_received = ?1 WHERE id = ?2",
-          [got, line.id],
+          "UPDATE stock_transfers SET status = ?1, received_at = NULL " +
+          "WHERE id = ?2 AND status = 'received'",
+          [priorStatus, id],
         );
+        throw e;
       }
-      await query(
-        "UPDATE stock_transfers SET status = 'received', received_at = ?1 WHERE id = ?2",
-        [receivedAt, id],
-      );
       await _writeEvent(id, "receive", transfer.to_location, {
         received_lines: input.received_lines,
       }, receivedAt);
@@ -546,48 +644,74 @@ function create(opts) {
       if (!transfer) {
         throw new TypeError("stock-transfers.reconcile: transfer " + id + " not found");
       }
-      if (transfer.status !== "received") {
+      // Refuse an illegal transition with a TypeError (kept for the route's
+      // 400 mapping). The status read here is only a fast-fail / clear-message
+      // path; the conditional claim-guard below is what actually serializes
+      // two concurrent reconciles.
+      if (!_canTransfer(transfer.status, "reconcile")) {
         throw new TypeError("stock-transfers.reconcile: transfer is " + transfer.status +
           ", only received transfers can be reconciled");
       }
       var ts = _now();
+      // Claim the received -> reconciled transition atomically BEFORE crediting
+      // the destination. Two concurrent reconciles both pass the read above,
+      // but only one UPDATE matches `status = 'received'` — the loser gets
+      // rowCount 0 and refuses, so the destination shelf is credited exactly
+      // once. (Without this guard both calls would credit, minting phantom
+      // inventory at the destination.)
+      var claim = await query(
+        "UPDATE stock_transfers SET status = 'reconciled', reconciled_at = ?1 " +
+        "WHERE id = ?2 AND status = 'received'",
+        [ts, id],
+      );
+      if (Number(claim.rowCount || 0) !== 1) {
+        throw new TypeError("stock-transfers.reconcile: transfer " + id +
+          " is no longer received (already reconciled by a concurrent call) — refusing to double-credit");
+      }
       var discrepancies = [];
-      // Credit the destination one line at a time. A failure here
-      // leaves the operator with a known-bad state: the receiving
-      // shelf is partially credited and the transfer is still
-      // 'received'. The operator can retry — every adjustStock that
-      // already landed shows up in the audit log so the second
-      // attempt won't double-credit because the FSM gate refuses
-      // reconcile on non-'received' status.
-      for (var i = 0; i < transfer.lines.length; i += 1) {
-        var line = transfer.lines[i];
-        var rx   = line.quantity_received == null ? 0 : line.quantity_received;
-        if (rx > 0) {
-          await locations.adjustStock({
-            sku: line.sku,
-            location_code: transfer.to_location,
-            delta: rx,
-            reason: "stock-transfer:reconcile:" + id,
-          });
+      // Credit the destination one line at a time. The claim above flipped the
+      // status, so a concurrent call can't reach this loop for the same
+      // transfer. Each line is skipped once its discrepancy column is stamped,
+      // so a retry (after the compensation below rolls the claim back) re-credits
+      // ONLY the lines that hadn't landed yet — no double-credit on the lines
+      // that already succeeded. If any line throws, the terminal claim is rolled
+      // back to 'received' so the transfer stays eligible for another reconcile
+      // that finishes the remaining credits, rather than stranding it.
+      try {
+        for (var i = 0; i < transfer.lines.length; i += 1) {
+          var line = transfer.lines[i];
+          if (line.discrepancy != null) continue;   // already credited on a prior attempt
+          var rx   = line.quantity_received == null ? 0 : line.quantity_received;
+          if (rx > 0) {
+            await locations.adjustStock({
+              sku: line.sku,
+              location_code: transfer.to_location,
+              delta: rx,
+              reason: "stock-transfer:reconcile:" + id,
+            });
+          }
+          var diff = line.quantity_shipped - rx;
+          await query(
+            "UPDATE stock_transfer_lines SET discrepancy = ?1 WHERE id = ?2",
+            [diff, line.id],
+          );
+          if (diff !== 0) {
+            discrepancies.push({
+              sku:               line.sku,
+              quantity_shipped:  line.quantity_shipped,
+              quantity_received: rx,
+              discrepancy:       diff,
+            });
+          }
         }
-        var diff = line.quantity_shipped - rx;
+      } catch (e) {
         await query(
-          "UPDATE stock_transfer_lines SET discrepancy = ?1 WHERE id = ?2",
-          [diff, line.id],
+          "UPDATE stock_transfers SET status = 'received', reconciled_at = NULL " +
+          "WHERE id = ?1 AND status = 'reconciled'",
+          [id],
         );
-        if (diff !== 0) {
-          discrepancies.push({
-            sku:               line.sku,
-            quantity_shipped:  line.quantity_shipped,
-            quantity_received: rx,
-            discrepancy:       diff,
-          });
-        }
+        throw e;
       }
-      await query(
-        "UPDATE stock_transfers SET status = 'reconciled', reconciled_at = ?1 WHERE id = ?2",
-        [ts, id],
-      );
       await _writeEvent(id, "reconcile", transfer.to_location, {
         discrepancies: discrepancies,
       }, ts);
@@ -612,15 +736,23 @@ function create(opts) {
       if (!transfer) {
         throw new TypeError("stock-transfers.markException: transfer " + id + " not found");
       }
-      if (transfer.status === "reconciled" || transfer.status === "exception") {
+      if (!_canTransfer(transfer.status, "except")) {
         throw new TypeError("stock-transfers.markException: transfer is " + transfer.status +
           ", terminal states cannot transition to exception");
       }
       var ts = _now();
-      await query(
-        "UPDATE stock_transfers SET status = 'exception', exception_reason = ?1 WHERE id = ?2",
+      // Claim the non-terminal -> exception transition atomically. The WHERE
+      // status clause refuses if a concurrent reconcile / exception already
+      // moved the row to a terminal state.
+      var claim = await query(
+        "UPDATE stock_transfers SET status = 'exception', exception_reason = ?1 " +
+        "WHERE id = ?2 AND status IN ('open', 'shipped', 'in_transit', 'received')",
         [reason, id],
       );
+      if (Number(claim.rowCount || 0) !== 1) {
+        throw new TypeError("stock-transfers.markException: transfer " + id +
+          " is no longer in a non-terminal state (settled by a concurrent call)");
+      }
       await _writeEvent(id, "exception", null, { reason: reason }, ts);
       return await _getHydrated(id);
     },