@blamejs/blamejs-shop 0.4.13 → 0.4.15

package/lib/admin.js

@@ -37,6 +37,7 @@ var loyaltyEarnRulesModule = require("./loyalty-earn-rules");
 var loyaltyRedemptionModule = require("./loyalty-redemption");
 var trustBadgesModule = require("./trust-badges");
 var cartModule = require("./cart");   // ABANDONED_* window/limit constants for the /admin/carts console
+var inventoryWriteoffsModule = require("./inventory-writeoffs");   // WRITEOFF_REASONS enum for the /admin/inventory/writeoffs console
 var textGuard = require("./text-guard");
 var { AsyncLocalStorage } = require("node:async_hooks");   // allow:non-shop-require — Node-core per-request context (no npm dep); the framework itself composes it in db-role-context / log. No b.* request-context primitive exists to wrap it.
 
@@ -574,6 +575,10 @@ function mount(router, deps) {
   var searchSuggestions = deps.searchSuggestions || null; // featured-suggestion curation + popular-searches view disabled when absent
   var trustBadges     = deps.trustBadges     || null; // trust-badge authoring console disabled when absent
   var preorder        = deps.preorder        || null; // pre-order campaign console (define/launch/close) disabled when absent
+  var inventoryLocations = deps.inventoryLocations || null; // stock-location CRUD + per-location levels console disabled when absent
+  var inventoryReceive   = deps.inventoryReceive   || null; // inbound-stock receive console disabled when absent
+  var stockTransfers     = deps.stockTransfers     || null; // location→location transfer console (dispatch/receive FSM) disabled when absent
+  var inventoryWriteoffs = deps.inventoryWriteoffs || null; // reason-coded write-off / shrinkage console disabled when absent
   // Read-only activity log at /admin/audit. Defaults ON — the framework
   // audit chain is always booted by createApp, so the screen always has a
   // data source (unlike the optional primitives above, which default off).
@@ -593,7 +598,7 @@ function mount(router, deps) {
   // `reports` is always present in the nav (read-only sales summary needs no
   // extra dep); its route mounts unconditionally and renders an unconfigured
   // notice when the salesReports primitive isn't wired.
-  var navAvailable = { analytics: !!deps.analytics, returns: !!returns, reviews: !!reviews, productQa: !!productQa, subscriptions: !!deps.subscriptions, preorder: !!deps.preorder, webhooks: !!deps.webhooks, collections: !!deps.collections, customers: !!deps.customers, customerSegments: !!customerSegments, giftcards: !!deps.giftcards, announcementBar: !!deps.announcementBar, promoBanners: !!deps.promoBanners, blog: !!deps.blog, knowledgeBase: !!deps.knowledgeBase, customerSurveys: !!deps.customerSurveys, storefrontPages: !!deps.storefrontPages, businessHours: !!deps.businessHours, taxRates: !!deps.taxRates, shippingZones: !!deps.shippingZones, deliveryEstimate: !!deps.deliveryEstimate, autoDiscount: !!deps.autoDiscount, discountAllocation: !!deps.discountAllocation, quantityDiscounts: !!deps.quantityDiscounts, loyalty: !!deps.loyalty, pickLists: !!pickLists, salesTaxFilings: !!salesTaxFilings, shippingLabels: !!shippingLabels, supportTickets: !!supportTickets, complianceExport: !!complianceExport, orderExchanges: !!orderExchanges, orderRatings: !!orderRatings, clickAndCollect: !!clickAndCollect, giftOptions: !!giftOptions, searchRanking: !!searchRanking, searchSuggestions: !!searchSuggestions, trustBadges: !!trustBadges, orderExport: !!orderExport, auditLog: auditLog, errorLog: !!errorLog, carts: !!cart };
+  var navAvailable = { analytics: !!deps.analytics, returns: !!returns, reviews: !!reviews, productQa: !!productQa, subscriptions: !!deps.subscriptions, preorder: !!deps.preorder, webhooks: !!deps.webhooks, collections: !!deps.collections, customers: !!deps.customers, customerSegments: !!customerSegments, giftcards: !!deps.giftcards, announcementBar: !!deps.announcementBar, promoBanners: !!deps.promoBanners, blog: !!deps.blog, knowledgeBase: !!deps.knowledgeBase, customerSurveys: !!deps.customerSurveys, storefrontPages: !!deps.storefrontPages, businessHours: !!deps.businessHours, taxRates: !!deps.taxRates, shippingZones: !!deps.shippingZones, deliveryEstimate: !!deps.deliveryEstimate, autoDiscount: !!deps.autoDiscount, discountAllocation: !!deps.discountAllocation, quantityDiscounts: !!deps.quantityDiscounts, loyalty: !!deps.loyalty, pickLists: !!pickLists, salesTaxFilings: !!salesTaxFilings, shippingLabels: !!shippingLabels, supportTickets: !!supportTickets, complianceExport: !!complianceExport, orderExchanges: !!orderExchanges, orderRatings: !!orderRatings, clickAndCollect: !!clickAndCollect, giftOptions: !!giftOptions, searchRanking: !!searchRanking, searchSuggestions: !!searchSuggestions, trustBadges: !!trustBadges, orderExport: !!orderExport, auditLog: auditLog, errorLog: !!errorLog, carts: !!cart, inventoryLocations: !!inventoryLocations, inventoryReceive: !!inventoryReceive, stockTransfers: !!stockTransfers, inventoryWriteoffs: !!inventoryWriteoffs };
 
   try { b.audit.registerNamespace(AUDIT_NAMESPACE); } catch (_e) { /* idempotent */ }
 
@@ -5273,6 +5278,406 @@ function mount(router, deps) {
     });
   }
 
+  // ---- inventory-ops back-office --------------------------------------
+  //
+  // Per-location stock on top of the single-bucket catalog inventory. The
+  // catalog `inventory.stock_on_hand` stays the storefront source of truth;
+  // these screens keep it in step with the per-location detail so a
+  // multi-location operator's warehouse breakdown never diverges from the
+  // count the storefront sells against. A store that never defines a
+  // location keeps using /admin/inventory unchanged — the default location
+  // is implicit, zero config.
+
+  // Credit ALL THREE ledgers for an inbound receive of one (sku,
+  // location) line:
+  //   1. inventoryReceive.draft + apply — the batched-receipt record the
+  //      "Recent receipts" history reads, AND the storefront-aggregate
+  //      credit (apply composes catalog.inventory.restock, which fires the
+  //      low-stock observer). A unique reference is auto-generated so two
+  //      receives in the same millisecond don't collide on the UNIQUE
+  //      constraint.
+  //   2. inventoryLocations.adjustStock(+qty) — the per-location detail +
+  //      its reason-coded inventory_adjustments audit row.
+  //
+  // The location credit lands first: it's the verb that refuses an unknown
+  // / deactivated location (a credit never refuses on insufficiency), so a
+  // bad location is rejected before any receipt row is written. If the
+  // receipt record then fails (duplicate reference race, DB error) the
+  // location credit is reversed so the per-location detail doesn't sit
+  // ahead of the aggregate. Returns the location adjust result.
+  async function _receiveToLocation(sku, locationCode, qty, reason) {
+    var adj = await inventoryLocations.adjustStock({
+      sku: sku, location_code: locationCode, delta: qty,
+      reason: reason ? ("receive: " + reason) : "receive",
+    });
+    try {
+      var ref = "RCV-" + Date.now().toString(36).toUpperCase() + "-" +
+        b.uuid.v7().slice(0, 8);
+      var draft = await inventoryReceive.draft({
+        reference:   ref,
+        supplier:    reason ? reason.slice(0, 256) : "",
+        received_by: "admin-console",
+        notes:       locationCode ? ("location: " + locationCode) : "",
+        lines:       [{ sku: sku, qty_received: qty }],
+      });
+      // apply credits the storefront aggregate (restock → low-stock
+      // observer). restock is a no-op for an un-tracked SKU (no inventory
+      // row) — fine: an un-tracked SKU is unlimited in the storefront, so
+      // the per-location detail is the only ledger that needed the credit.
+      await inventoryReceive.apply(draft.id);
+    } catch (e) {
+      // Compensate the per-location credit so the detail doesn't disagree
+      // with the aggregate, then surface the original failure.
+      try {
+        await inventoryLocations.adjustStock({
+          sku: sku, location_code: locationCode, delta: -qty,
+          reason: "receive: rollback",
+        });
+      } catch (_e2) { /* drop-silent — the original error is the operator's signal */ }
+      throw e;
+    }
+    return adj;
+  }
+
+  // Debit BOTH ledgers for a write-off: the per-location detail (via the
+  // writeoffs primitive, which composes inventoryLocations.adjustStock and
+  // owns the reason-coded audit row) AND the storefront aggregate (catalog
+  // adjustOnHand, which fires the low-stock observer + refuses to eat into
+  // held stock).
+  //
+  // The aggregate mirror is applied BEFORE the write-off is committed as a
+  // real record so the two ledgers never silently diverge. adjustOnHand
+  // returns `{ adjusted: false }` (not a throw) when the debit would eat
+  // into stock already held for paid-but-unfulfilled orders — that's a real
+  // operational conflict (you're writing off units promised to a paid
+  // order), so we reverse the per-location debit and surface it as a
+  // refusal rather than committing a write-off that leaves the storefront
+  // count ahead of the physical shelf. A null result means the SKU is
+  // un-tracked in the catalog aggregate (no inventory row) — the
+  // per-location detail is then the only ledger, and the write-off stands.
+  async function _writeoffFromLocation(input) {
+    var row = await inventoryWriteoffs.recordWriteoff(input);
+    if (input.location_code) {
+      // The per-location debit already landed inside recordWriteoff. Mirror
+      // it onto the storefront aggregate.
+      var mirror = await catalog.inventory.adjustOnHand(input.sku, -input.quantity);
+      if (mirror && mirror.adjusted === false) {
+        // The aggregate refused — reverse the per-location debit AND the
+        // write-off record so neither ledger carries a half-applied move,
+        // then surface the conflict.
+        try {
+          await inventoryWriteoffs.reverseWriteoff({
+            id: row.id,
+            reason: "aggregate-conflict: would oversell held stock",
+          });
+        } catch (_e) { /* drop-silent — the thrown conflict is the operator's signal */ }
+        throw new TypeError("admin.inventory.writeoff: " + input.quantity +
+          " unit(s) of " + input.sku + " can't be written off — that would eat " +
+          "into stock already held for paid orders. Fulfil or cancel those orders first.");
+      }
+    }
+    return row;
+  }
+
+  if (inventoryLocations) {
+    // GET /admin/inventory/locations — location list with per-location
+    // levels for an optional ?sku= drill-down. JSON for the bearer token.
+    router.get("/admin/inventory/locations", _pageOrApi(true,
+      R(async function (req, res) {
+        var rows = await inventoryLocations.listLocations({});
+        _json(res, 200, { rows: rows });
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var sku = url && url.searchParams.get("sku");
+        var rows = await inventoryLocations.listLocations({});
+        var levels = null;
+        if (sku) {
+          try { levels = await inventoryLocations.stockForSku(sku); }
+          catch (e) { if (!(e instanceof TypeError)) throw e; levels = null; }
+        }
+        _sendHtml(res, 200, renderAdminInvLocations({
+          shop_name: deps.shop_name, nav_available: navAvailable,
+          locations: rows, sku: sku || "", levels: levels,
+          saved:  url && url.searchParams.get("saved"),
+          notice: url && url.searchParams.get("err") ? "That location couldn't be saved — check the fields and try again." : null,
+        }));
+      },
+    ));
+
+    // POST /admin/inventory/locations — defineLocation, or updateLocation
+    // when the code already exists (operator-friendly upsert). A bad shape
+    // is a plain TypeError → 400.
+    router.post("/admin/inventory/locations", _pageOrApi(false,
+      W("inventory.location.save", async function (req, res) {
+        var loc;
+        try { loc = await _saveInvLocationFromBody(req.body || {}); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        _json(res, 201, loc);
+        return loc;
+      }),
+      async function (req, res) {
+        try { await _saveInvLocationFromBody(req.body || {}); }
+        catch (e) { if (e instanceof TypeError) return _redirect(res, "/admin/inventory/locations?err=1"); throw e; }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".inventory.location.save", outcome: "success", metadata: { code: (req.body || {}).code } });
+        _redirect(res, "/admin/inventory/locations?saved=1");
+      },
+    ));
+
+    async function _saveInvLocationFromBody(body) {
+      var input = {
+        code:     body.code,
+        name:     body.name,
+        type:     body.type,
+        priority: body.priority == null || body.priority === "" ? undefined : (parseInt(body.priority, 10)),
+      };
+      if (input.priority !== undefined && !Number.isFinite(input.priority)) {
+        throw new TypeError("admin.inventory.location.save: priority must be an integer");
+      }
+      var existing = await inventoryLocations.getLocation(body.code);
+      if (existing) {
+        var patch = { name: input.name, type: input.type };
+        if (input.priority !== undefined) patch.priority = input.priority;
+        return inventoryLocations.updateLocation(body.code, patch);
+      }
+      return inventoryLocations.defineLocation(input);
+    }
+
+    // POST /admin/inventory/locations/:code/deactivate — soft-delete. The
+    // row survives so historical adjustments still resolve their location.
+    router.post("/admin/inventory/locations/:code/deactivate", _pageOrApi(false,
+      W("inventory.location.deactivate", async function (req, res) {
+        var code = req.params.code;
+        var existing;
+        try { existing = await inventoryLocations.getLocation(code); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        if (!existing) return _problem(res, 404, "inventory-location-not-found");
+        var row = await inventoryLocations.deactivateLocation(code);
+        _json(res, 200, row);
+        return row;
+      }),
+      async function (req, res) {
+        var code = req.params.code;
+        var existing;
+        try { existing = await inventoryLocations.getLocation(code); }
+        catch (e) { if (e instanceof TypeError) return _redirect(res, "/admin/inventory/locations?err=1"); throw e; }
+        if (!existing) return _redirect(res, "/admin/inventory/locations?err=1");
+        await inventoryLocations.deactivateLocation(code);
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".inventory.location.deactivate", outcome: "success", metadata: { code: code } });
+        _redirect(res, "/admin/inventory/locations?saved=1");
+      },
+    ));
+  }
+
+  if (inventoryReceive && inventoryLocations) {
+    // GET /admin/inventory/receive — the receive form + recent receipt
+    // history (the inventory-receive ledger). The form credits a single
+    // (sku, location) line; the history reads the batched-receipt records.
+    router.get("/admin/inventory/receive", _pageOrApi(true,
+      R(async function (req, res) {
+        var page = await inventoryReceive.list({ limit: 50 });
+        _json(res, 200, { rows: page.rows, next_cursor: page.next_cursor });
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var locs = await inventoryLocations.listLocations({ active_only: true });
+        var page = await inventoryReceive.list({ limit: 50 });
+        _sendHtml(res, 200, renderAdminInvReceive({
+          shop_name: deps.shop_name, nav_available: navAvailable,
+          locations: locs, receipts: page.rows || [],
+          saved:  url && url.searchParams.get("saved"),
+          notice: url && url.searchParams.get("err") ? "That receipt couldn't be recorded — check the SKU, location, and quantity." : null,
+        }));
+      },
+    ));
+
+    // POST /admin/inventory/receive — credit a single (sku, location) line
+    // to both ledgers. quantity must be a positive integer; the location
+    // must exist (adjustStock refuses an unknown one).
+    router.post("/admin/inventory/receive", _pageOrApi(false,
+      W("inventory.receive", async function (req, res) {
+        var body = req.body || {};
+        var qty = parseInt(body.quantity, 10);
+        if (!Number.isInteger(qty) || qty <= 0) return _problem(res, 400, "bad-request", "quantity must be a positive integer");
+        var out;
+        try { out = await _receiveToLocation(body.sku, body.location_code, qty, body.reason); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        _json(res, 201, out);
+        return out;
+      }),
+      async function (req, res) {
+        var body = req.body || {};
+        var qty = parseInt(body.quantity, 10);
+        if (!Number.isInteger(qty) || qty <= 0) return _redirect(res, "/admin/inventory/receive?err=1");
+        try { await _receiveToLocation(body.sku, body.location_code, qty, body.reason); }
+        catch (e) { if (e instanceof TypeError) return _redirect(res, "/admin/inventory/receive?err=1"); throw e; }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".inventory.receive", outcome: "success", metadata: { sku: body.sku, location_code: body.location_code, quantity: qty } });
+        _redirect(res, "/admin/inventory/receive?saved=1");
+      },
+    ));
+  }
+
+  if (stockTransfers && inventoryLocations) {
+    // GET /admin/inventory/transfers — the open-transfer queue + the open
+    // form. The queue shows non-terminal transfers with the FSM actions
+    // legal from each status.
+    router.get("/admin/inventory/transfers", _pageOrApi(true,
+      R(async function (req, res) {
+        var rows = await stockTransfers.listOpen({});
+        _json(res, 200, { rows: rows });
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var locs = await inventoryLocations.listLocations({ active_only: true });
+        var rows = await stockTransfers.listOpen({});
+        _sendHtml(res, 200, renderAdminInvTransfers({
+          shop_name: deps.shop_name, nav_available: navAvailable,
+          locations: locs, transfers: rows,
+          saved:  url && url.searchParams.get("saved"),
+          notice: url && url.searchParams.get("err") ? "That transfer action couldn't be completed — check stock at the source and the transfer state." : null,
+        }));
+      },
+    ));
+
+    // POST /admin/inventory/transfers — openTransfer for one (sku, qty)
+    // line. Debits the source immediately (stock leaves at dispatch).
+    router.post("/admin/inventory/transfers", _pageOrApi(false,
+      W("inventory.transfer.open", async function (req, res) {
+        var body = req.body || {};
+        var qty = parseInt(body.quantity, 10);
+        if (!Number.isInteger(qty) || qty <= 0) return _problem(res, 400, "bad-request", "quantity must be a positive integer");
+        var t;
+        try {
+          t = await stockTransfers.openTransfer({
+            from_location: body.from_location, to_location: body.to_location,
+            lines: [{ sku: body.sku, quantity: qty }], reason: body.reason,
+          });
+        } catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        _json(res, 201, t);
+        return t;
+      }),
+      async function (req, res) {
+        var body = req.body || {};
+        var qty = parseInt(body.quantity, 10);
+        if (!Number.isInteger(qty) || qty <= 0) return _redirect(res, "/admin/inventory/transfers?err=1");
+        try {
+          await stockTransfers.openTransfer({
+            from_location: body.from_location, to_location: body.to_location,
+            lines: [{ sku: body.sku, quantity: qty }], reason: body.reason,
+          });
+        } catch (e) { if (e instanceof TypeError) return _redirect(res, "/admin/inventory/transfers?err=1"); throw e; }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".inventory.transfer.open", outcome: "success", metadata: { sku: body.sku, from: body.from_location, to: body.to_location, quantity: qty } });
+        _redirect(res, "/admin/inventory/transfers?saved=1");
+      },
+    ));
+
+    // The FSM-action routes: ship → in-transit → receive → reconcile, plus
+    // exception. Each resolves the transfer first (unknown id → err) and
+    // calls the matching primitive verb; a wrong-state transition is a
+    // plain TypeError surfaced as an error redirect / 400.
+    function _transferAction(action, verb) {
+      router.post("/admin/inventory/transfers/:id/" + action, _pageOrApi(false,
+        W("inventory.transfer." + action, async function (req, res) {
+          var id = req.params.id;
+          var out;
+          try { out = await verb(id, req.body || {}); }
+          catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+          _json(res, 200, out);
+          return out;
+        }),
+        async function (req, res) {
+          var id = req.params.id;
+          try { await verb(id, req.body || {}); }
+          catch (e) { if (e instanceof TypeError) return _redirect(res, "/admin/inventory/transfers?err=1"); throw e; }
+          b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".inventory.transfer." + action, outcome: "success", metadata: { transfer_id: id } });
+          _redirect(res, "/admin/inventory/transfers?saved=1");
+        },
+      ));
+    }
+    _transferAction("ship", function (id, body) {
+      return stockTransfers.markShipped({ transfer_id: id, carrier: body.carrier || null, tracking_number: body.tracking_number || null });
+    });
+    _transferAction("in-transit", function (id, body) {
+      return stockTransfers.markInTransit({ transfer_id: id, location: body.location || null });
+    });
+    _transferAction("receive", function (id, body) {
+      // Single-line transfers from the open form: receive the full shipped
+      // qty unless the operator overrides quantity_received. Resolve the
+      // shipped line so a blank field receives everything (the happy path).
+      return (async function () {
+        var t = await stockTransfers.getTransfer(id);
+        if (!t) throw new TypeError("transfer not found");
+        var rx = t.lines.map(function (l) {
+          var got = body["rx_" + l.sku];
+          var q = got == null || got === "" ? l.quantity_shipped : parseInt(got, 10);
+          if (!Number.isInteger(q) || q < 0) throw new TypeError("quantity_received must be a non-negative integer");
+          return { sku: l.sku, quantity_received: q };
+        });
+        return stockTransfers.markReceived({ transfer_id: id, received_lines: rx });
+      })();
+    });
+    _transferAction("reconcile", function (id) {
+      return stockTransfers.reconcile({ transfer_id: id });
+    });
+    _transferAction("exception", function (id, body) {
+      return stockTransfers.markException({ transfer_id: id, reason: body.reason });
+    });
+  }
+
+  if (inventoryWriteoffs && inventoryLocations) {
+    // GET /admin/inventory/writeoffs — the write-off log + the record form.
+    router.get("/admin/inventory/writeoffs", _pageOrApi(true,
+      R(async function (req, res) {
+        var page = await inventoryWriteoffs.listWriteoffs({ limit: 50 });
+        _json(res, 200, { rows: page.rows, next_cursor: page.next_cursor });
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var locs = await inventoryLocations.listLocations({ active_only: true });
+        var page = await inventoryWriteoffs.listWriteoffs({ limit: 50 });
+        _sendHtml(res, 200, renderAdminInvWriteoffs({
+          shop_name: deps.shop_name, nav_available: navAvailable,
+          locations: locs, writeoffs: page.rows || [],
+          reasons: inventoryWriteoffsModule.WRITEOFF_REASONS,
+          saved:  url && url.searchParams.get("saved"),
+          notice: url && url.searchParams.get("err") ? "That write-off couldn't be recorded — check the SKU, location, quantity, and reason." : null,
+        }));
+      },
+    ));
+
+    // POST /admin/inventory/writeoffs — recordWriteoff against a location +
+    // mirror the debit onto the storefront aggregate.
+    router.post("/admin/inventory/writeoffs", _pageOrApi(false,
+      W("inventory.writeoff", async function (req, res) {
+        var body = req.body || {};
+        var qty = parseInt(body.quantity, 10);
+        if (!Number.isInteger(qty) || qty <= 0) return _problem(res, 400, "bad-request", "quantity must be a positive integer");
+        var row;
+        try {
+          row = await _writeoffFromLocation({
+            sku: body.sku, location_code: body.location_code, quantity: qty,
+            reason: body.reason, actor: body.actor || "admin-console", notes: body.notes || null,
+          });
+        } catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        _json(res, 201, row);
+        return row;
+      }),
+      async function (req, res) {
+        var body = req.body || {};
+        var qty = parseInt(body.quantity, 10);
+        if (!Number.isInteger(qty) || qty <= 0) return _redirect(res, "/admin/inventory/writeoffs?err=1");
+        try {
+          await _writeoffFromLocation({
+            sku: body.sku, location_code: body.location_code, quantity: qty,
+            reason: body.reason, actor: body.actor || "admin-console", notes: body.notes || null,
+          });
+        } catch (e) { if (e instanceof TypeError) return _redirect(res, "/admin/inventory/writeoffs?err=1"); throw e; }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".inventory.writeoff", outcome: "success", metadata: { sku: body.sku, location_code: body.location_code, quantity: qty, reason: body.reason } });
+        _redirect(res, "/admin/inventory/writeoffs?saved=1");
+      },
+    ));
+  }
+
   // ---- gift wraps -----------------------------------------------------
   //
   // The operator-defined gift-wrap catalog: define / update / archive a wrap
@@ -11946,6 +12351,10 @@ var ADMIN_NAV_ITEMS = [
   { key: "dashboard",    href: "/admin/dashboard",    label: "Dashboard" },
   { key: "products",     href: "/admin/products",     label: "Products" },
   { key: "inventory",    href: "/admin/inventory",    label: "Inventory" },
+  { key: "inventory-locations", href: "/admin/inventory/locations", label: "Stock locations", requires: "inventoryLocations" },
+  { key: "inventory-receive",   href: "/admin/inventory/receive",   label: "Receive stock",   requires: "inventoryReceive" },
+  { key: "inventory-transfers", href: "/admin/inventory/transfers", label: "Transfers",       requires: "stockTransfers" },
+  { key: "inventory-writeoffs", href: "/admin/inventory/writeoffs", label: "Write-offs",      requires: "inventoryWriteoffs" },
   { key: "orders",       href: "/admin/orders",       label: "Orders" },
   { key: "carts",        href: "/admin/carts",        label: "Abandoned carts", requires: "carts" },
   { key: "reports",      href: "/admin/reports",      label: "Reports" },
@@ -14687,6 +15096,236 @@ function renderAdminPickupLocations(opts) {
   return _renderAdminShell(opts.shop_name, "Pickup locations", body, "pickup-locations", opts.nav_available);
 }
 
+// Stock-location list + the define/update form + an optional per-SKU
+// levels drill-down. Location names and codes are operator free text —
+// escaped at the sink.
+function renderAdminInvLocations(opts) {
+  opts = opts || {};
+  var list = opts.locations || [];
+  var saved  = opts.saved  ? "<div class=\"banner banner--ok\">Stock location saved.</div>" : "";
+  var notice = opts.notice ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+
+  var rows = list.map(function (l) {
+    return "<tr>" +
+      "<td><code class=\"order-id\">" + _htmlEscape(l.code) + "</code></td>" +
+      "<td>" + _htmlEscape(l.name) + "</td>" +
+      "<td>" + _htmlEscape(l.type) + "</td>" +
+      "<td>" + _htmlEscape(String(l.priority)) + "</td>" +
+      "<td>" + (l.active ? "<span class=\"status-pill\">active</span>" : "<span class=\"meta\">inactive</span>") + "</td>" +
+      "<td>" +
+        (l.active
+          ? "<form method=\"post\" action=\"/admin/inventory/locations/" + encodeURIComponent(l.code) + "/deactivate\" class=\"form-inline\">" +
+              "<button class=\"btn btn--ghost btn--sm\" type=\"submit\">Deactivate</button></form>"
+          : "<span class=\"meta\">—</span>") +
+      "</td>" +
+      "</tr>";
+  }).join("");
+
+  var table = list.length
+    ? "<div class=\"panel\">" + _tableWrap("<table><thead><tr><th scope=\"col\">Code</th><th scope=\"col\">Name</th><th scope=\"col\">Type</th><th scope=\"col\">Priority</th><th scope=\"col\">Status</th><th scope=\"col\">Action</th></tr></thead><tbody>" + rows + "</tbody></table>") + "</div>"
+    : "<p class=\"empty\">No stock locations yet. A store with one warehouse needs no location — the default bucket is implicit. Add a location below once you ship from more than one place.</p>";
+
+  // Per-SKU levels drill-down.
+  var levelsBlock = "";
+  if (opts.levels) {
+    var lv = opts.levels;
+    var lvRows = (lv.by_location || []).map(function (r) {
+      return "<tr><td><code class=\"order-id\">" + _htmlEscape(r.code) + "</code></td><td>" + _htmlEscape(String(r.quantity)) + "</td></tr>";
+    }).join("");
+    levelsBlock =
+      "<div class=\"panel mt\"><h3 class=\"subhead\">Levels for " + _htmlEscape(opts.sku) + " — total " + _htmlEscape(String(lv.total)) + "</h3>" +
+        (lv.by_location && lv.by_location.length
+          ? _tableWrap("<table><thead><tr><th scope=\"col\">Location</th><th scope=\"col\">On hand</th></tr></thead><tbody>" + lvRows + "</tbody></table>")
+          : "<p class=\"empty\">No per-location stock recorded for this SKU.</p>") +
+      "</div>";
+  }
+  var lookup =
+    "<div class=\"panel mt\"><h3 class=\"subhead\">Per-location levels</h3>" +
+      "<form method=\"get\" action=\"/admin/inventory/locations\" class=\"form-inline\">" +
+        _setupField("SKU", "sku", opts.sku || "", "text", "Show the per-location breakdown for one SKU.", " maxlength=\"128\"") +
+        "<button class=\"btn btn--ghost btn--sm\" type=\"submit\">Look up</button>" +
+      "</form>" + levelsBlock +
+    "</div>";
+
+  var form =
+    "<div class=\"panel mt\"><h3 class=\"subhead\">Add / update a stock location</h3>" +
+      "<form method=\"post\" action=\"/admin/inventory/locations\">" +
+        _setupField("Code", "code", "", "text", "Stable identifier (alnum + . _ -). Re-using a code updates that location.", " maxlength=\"64\" required") +
+        _setupField("Name", "name", "", "text", "Operator-facing label (e.g. East warehouse).", " maxlength=\"128\" required") +
+        "<label class=\"form-field\"><span>Type</span>" +
+          "<select name=\"type\" required>" +
+            "<option value=\"warehouse\">warehouse</option>" +
+            "<option value=\"retail\">retail</option>" +
+            "<option value=\"dropship\">dropship</option>" +
+          "</select>" +
+          "<small>Drives default routing weight; override with priority.</small>" +
+        "</label>" +
+        _setupField("Priority", "priority", "", "number", "Lower picks first (default 100).", " min=\"0\"") +
+        "<div class=\"actions-row\"><button type=\"submit\" class=\"btn\">Save location</button></div>" +
+      "</form>" +
+    "</div>";
+
+  var body = "<section><h2>Stock locations</h2>" + saved + notice + table + lookup + form + "</section>";
+  return _renderAdminShell(opts.shop_name, "Stock locations", body, "inventory-locations", opts.nav_available);
+}
+
+// Receive inbound stock against a location. Credits both the per-location
+// detail and the storefront aggregate. Recent receipts (the batched
+// inventory-receive ledger) render below the form. Reference / supplier
+// are operator free text — escaped at the sink.
+function renderAdminInvReceive(opts) {
+  opts = opts || {};
+  var locs = opts.locations || [];
+  var receipts = opts.receipts || [];
+  var saved  = opts.saved  ? "<div class=\"banner banner--ok\">Stock received.</div>" : "";
+  var notice = opts.notice ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+
+  var locOptions = locs.map(function (l) {
+    return "<option value=\"" + _htmlEscape(l.code) + "\">" + _htmlEscape(l.name) + " (" + _htmlEscape(l.code) + ")</option>";
+  }).join("");
+
+  var form = locs.length
+    ? "<div class=\"panel\"><h3 class=\"subhead\">Receive stock</h3>" +
+        "<form method=\"post\" action=\"/admin/inventory/receive\">" +
+          _setupField("SKU", "sku", "", "text", "", " maxlength=\"128\" required") +
+          "<label class=\"form-field\"><span>Location</span><select name=\"location_code\" required>" + locOptions + "</select></label>" +
+          _setupField("Quantity", "quantity", "", "number", "Units received (positive).", " min=\"1\" required") +
+          _setupField("Reason / reference", "reason", "", "text", "Optional — PO number, supplier, note.", " maxlength=\"256\"") +
+          "<div class=\"actions-row\"><button type=\"submit\" class=\"btn\">Receive</button></div>" +
+        "</form></div>"
+    : "<p class=\"empty\">Add a stock location first, then receive stock against it.</p>";
+
+  var recRows = receipts.map(function (r) {
+    return "<tr>" +
+      "<td>" + _htmlEscape(String(r.reference || "")) + "</td>" +
+      "<td>" + _htmlEscape(String(r.supplier || "")) + "</td>" +
+      "<td><span class=\"status-pill\">" + _htmlEscape(String(r.status)) + "</span></td>" +
+      "<td>" + _htmlEscape(String(r.total_qty)) + "</td>" +
+      "<td>" + _htmlEscape(_fmtDate(r.received_at)) + "</td>" +
+      "</tr>";
+  }).join("");
+  var history = receipts.length
+    ? "<div class=\"panel mt\"><h3 class=\"subhead\">Recent receipts</h3>" +
+        _tableWrap("<table><thead><tr><th scope=\"col\">Reference</th><th scope=\"col\">Supplier</th><th scope=\"col\">Status</th><th scope=\"col\">Qty</th><th scope=\"col\">Received</th></tr></thead><tbody>" + recRows + "</tbody></table>") +
+      "</div>"
+    : "";
+
+  var body = "<section><h2>Receive stock</h2>" + saved + notice + form + history + "</section>";
+  return _renderAdminShell(opts.shop_name, "Receive stock", body, "inventory-receive", opts.nav_available);
+}
+
+// Location→location transfer console: the open form + the open-transfer
+// queue with the FSM action legal from each row's status. Reasons,
+// carriers, and tracking numbers are operator free text — escaped.
+function renderAdminInvTransfers(opts) {
+  opts = opts || {};
+  var locs = opts.locations || [];
+  var transfers = opts.transfers || [];
+  var saved  = opts.saved  ? "<div class=\"banner banner--ok\">Transfer updated.</div>" : "";
+  var notice = opts.notice ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+
+  var locOptions = locs.map(function (l) {
+    return "<option value=\"" + _htmlEscape(l.code) + "\">" + _htmlEscape(l.name) + " (" + _htmlEscape(l.code) + ")</option>";
+  }).join("");
+
+  function _transferActions(t) {
+    var blocks = [];
+    var act = function (action, label, extra) {
+      return "<form method=\"post\" action=\"/admin/inventory/transfers/" + encodeURIComponent(t.id) + "/" + action + "\" class=\"form-inline\">" +
+        (extra || "") + "<button class=\"btn btn--sm\" type=\"submit\">" + _htmlEscape(label) + "</button></form>";
+    };
+    if (t.status === "open") blocks.push(act("ship", "Mark shipped"));
+    if (t.status === "shipped" || t.status === "in_transit") {
+      blocks.push(act("receive", "Mark received"));
+    }
+    if (t.status === "received") blocks.push(act("reconcile", "Reconcile"));
+    if (t.status !== "reconciled" && t.status !== "exception") {
+      blocks.push(act("exception", "Exception",
+        "<input type=\"text\" name=\"reason\" placeholder=\"reason\" maxlength=\"280\" required>"));
+    }
+    return blocks.length ? blocks.join("") : "<span class=\"meta\">—</span>";
+  }
+
+  var rows = transfers.map(function (t) {
+    var lineSummary = (t.lines || []).map(function (l) {
+      return _htmlEscape(l.sku) + "×" + _htmlEscape(String(l.quantity_shipped));
+    }).join(", ");
+    return "<tr>" +
+      "<td><code class=\"order-id\">" + _htmlEscape(String(t.id).slice(0, 8)) + "</code></td>" +
+      "<td>" + _htmlEscape(t.from_location) + " → " + _htmlEscape(t.to_location) + "</td>" +
+      "<td>" + lineSummary + "</td>" +
+      "<td><span class=\"status-pill\">" + _htmlEscape(t.status) + "</span></td>" +
+      "<td>" + _transferActions(t) + "</td>" +
+      "</tr>";
+  }).join("");
+
+  var queue = transfers.length
+    ? "<div class=\"panel\">" + _tableWrap("<table><thead><tr><th scope=\"col\">ID</th><th scope=\"col\">Route</th><th scope=\"col\">Lines</th><th scope=\"col\">Status</th><th scope=\"col\">Actions</th></tr></thead><tbody>" + rows + "</tbody></table>") + "</div>"
+    : "<p class=\"empty\">No open transfers.</p>";
+
+  var form = locs.length >= 2
+    ? "<div class=\"panel mt\"><h3 class=\"subhead\">Open a transfer</h3>" +
+        "<form method=\"post\" action=\"/admin/inventory/transfers\">" +
+          "<label class=\"form-field\"><span>From</span><select name=\"from_location\" required>" + locOptions + "</select></label>" +
+          "<label class=\"form-field\"><span>To</span><select name=\"to_location\" required>" + locOptions + "</select></label>" +
+          _setupField("SKU", "sku", "", "text", "", " maxlength=\"128\" required") +
+          _setupField("Quantity", "quantity", "", "number", "Units to move (leaves the source immediately).", " min=\"1\" required") +
+          _setupField("Reason", "reason", "", "text", "Optional note.", " maxlength=\"280\"") +
+          "<div class=\"actions-row\"><button type=\"submit\" class=\"btn\">Open transfer</button></div>" +
+        "</form></div>"
+    : "<p class=\"empty\">Define at least two stock locations to transfer between them.</p>";
+
+  var body = "<section><h2>Stock transfers</h2>" + saved + notice + queue + form + "</section>";
+  return _renderAdminShell(opts.shop_name, "Transfers", body, "inventory-transfers", opts.nav_available);
+}
+
+// Reason-coded write-off log + record form. SKU, reason, notes, and actor
+// are operator free text — escaped at the sink.
+function renderAdminInvWriteoffs(opts) {
+  opts = opts || {};
+  var locs = opts.locations || [];
+  var list = opts.writeoffs || [];
+  var reasons = opts.reasons || [];
+  var saved  = opts.saved  ? "<div class=\"banner banner--ok\">Write-off recorded.</div>" : "";
+  var notice = opts.notice ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+
+  var locOptions = locs.map(function (l) {
+    return "<option value=\"" + _htmlEscape(l.code) + "\">" + _htmlEscape(l.name) + " (" + _htmlEscape(l.code) + ")</option>";
+  }).join("");
+  var reasonOptions = reasons.map(function (r) {
+    return "<option value=\"" + _htmlEscape(r) + "\">" + _htmlEscape(r) + "</option>";
+  }).join("");
+
+  var rows = list.map(function (w) {
+    return "<tr>" +
+      "<td>" + _htmlEscape(String(w.sku)) + "</td>" +
+      "<td>" + (w.location_code ? "<code class=\"order-id\">" + _htmlEscape(String(w.location_code)) + "</code>" : "<span class=\"meta\">—</span>") + "</td>" +
+      "<td>" + _htmlEscape(String(w.quantity)) + "</td>" +
+      "<td>" + _htmlEscape(String(w.reason)) + "</td>" +
+      "<td><span class=\"status-pill\">" + _htmlEscape(String(w.status)) + "</span></td>" +
+      "<td>" + _htmlEscape(_fmtDate(w.occurred_at)) + "</td>" +
+      "</tr>";
+  }).join("");
+  var table = list.length
+    ? "<div class=\"panel\">" + _tableWrap("<table><thead><tr><th scope=\"col\">SKU</th><th scope=\"col\">Location</th><th scope=\"col\">Qty</th><th scope=\"col\">Reason</th><th scope=\"col\">Status</th><th scope=\"col\">When</th></tr></thead><tbody>" + rows + "</tbody></table>") + "</div>"
+    : "<p class=\"empty\">No write-offs recorded.</p>";
+
+  var form = locs.length
+    ? "<div class=\"panel mt\"><h3 class=\"subhead\">Record a write-off</h3>" +
+        "<form method=\"post\" action=\"/admin/inventory/writeoffs\">" +
+          _setupField("SKU", "sku", "", "text", "", " maxlength=\"128\" required") +
+          "<label class=\"form-field\"><span>Location</span><select name=\"location_code\" required>" + locOptions + "</select></label>" +
+          _setupField("Quantity", "quantity", "", "number", "Units removed (positive).", " min=\"1\" required") +
+          "<label class=\"form-field\"><span>Reason</span><select name=\"reason\" required>" + reasonOptions + "</select></label>" +
+          _setupField("Notes", "notes", "", "text", "Optional.", " maxlength=\"4096\"") +
+          "<div class=\"actions-row\"><button type=\"submit\" class=\"btn btn--danger\">Record write-off</button></div>" +
+        "</form></div>"
+    : "<p class=\"empty\">Add a stock location first, then record write-offs against it.</p>";
+
+  var body = "<section><h2>Write-offs</h2>" + saved + notice + table + form + "</section>";
+  return _renderAdminShell(opts.shop_name, "Write-offs", body, "inventory-writeoffs", opts.nav_available);
+}
+
 // Pickup queue for one location: a location selector + status chips, the
 // scheduled/ready rows, and the FSM action forms (ready / picked-up /
 // no-show) legal from each row's status. The no_show reason is operator-