PhoenixKit Warehouse

Warehouse module for PhoenixKit.

A drop-in PhoenixKit module — add it to a host app's deps and it is auto-discovered, adding a Warehouse section to the admin panel. Like every PhoenixKit module it has no endpoint, router, or Ecto repo of its own; it borrows the host's via phoenix_kit.

Status: implemented. Stock keeping, the document set and their posting rules below are in use; see CHANGELOG.md for the release history.

Scope

Stock per item and location

• One stock row per catalogue item and location (a PhoenixKit Locations record of the configured warehouse location type): quantity (never negative, enforced by a database check) and an optional unit_value.
• A default warehouse setting decides where a document lands when none is chosen. The admin UI also has a stock list, per-item minimums with a deficit view, and a turnover report (inflow and outflow per item over a date range).

Documents

Documents are created as drafts and take effect when posted (a transfer ships and then is received). Each has a number drawn from its own sequence, and a draft can be soft-deleted. Most also have a storage folder for attachments and a comment thread.

Posting semantics worth knowing:

• Posting is atomic and a compare-and-swap on status: the document row is locked and re-checked as a draft inside the transaction, so a repeated or stale post cannot apply stock twice.
• Every posted line records the previous quantity it replaced or changed. For an inventory document that quantity is read inside the posting transaction under a row lock, so the audit trail stays exact when other documents post concurrently.
• After posting, a goods receipt or goods issue keeps its lines; only the note and the storage folder can still be corrected.

Programmatic posting

For callers that are not a person at a form (a shop, a POS, an integration), GoodsIssues.create_and_post/2, GoodsReceipts.create_and_post/2 and Inventories.create_and_post/2 create and post in one transaction: a call refused by validation or the stock check leaves no draft and consumes no document number. A failure after the insert (a database error while posting) rolls the draft back too, but the number sequence has advanced.

• Each takes the document attributes and the posting user's UUID.
• Duplicate item lines are refused ({:error, {:duplicate_lines, uuids}}) rather than merged or dropped. A goods issue reports every short line at once ({:error, {:insufficient_stock, [%{item_uuid, requested, available}]}}).
• All three accept an external_ref, the document's number in the outside system. It is unique per document type among posted, non-deleted documents, and a repeat returns {:ok, :already_posted, existing_document} without writing anything, so a retried delivery is harmless. The lines of the repeat are not compared with the existing document's.

Linking documents to host records

Documents link to host-owned records (orders, sub-orders, ...) through source_refs and the generic PhoenixKitWarehouse.SourceKinds registry, so the package has no dependency on any specific "order" concept. Kinds come from the host's config :phoenix_kit_warehouse, :source_kinds list and from any registered PhoenixKit module that exports warehouse_source_kinds/0; the two are merged by kind, and the host's definition wins on a conflict.

Admin API tools (shop API)

On a host that runs PhoenixKit core with the shop API and has switched the admin API on (Settings -> API), this module offers five tools to API keys. A key sees a tool only while the Warehouse module is enabled and only if the key's scopes and its owner's warehouse permission allow it. The three write tools are offered only on a core that can hold a dangerous call for confirmation; on an older core only the two read tools are.

How they behave, in short:

• A product is named by a ref: exactly one of id (the catalogue item UUID), sku or external_id. Only live (not trashed) catalogue items are accepted; sku and external_id need a catalogue release with the shop API support. Refs of every kind resolve inside one catalogue: catalogue_id is required when the shop has more than one active catalogue (otherwise the only active one is used; the refusal lists the catalogue ids to choose from as allowed); a deleted catalogue is refused, an archived one can be read but not written. An ambiguous ref is reported with the candidates it matches, at the top level of its row error.

• Each write tool creates and posts one document in one transaction. If any line is wrong nothing is posted and every problem is reported at once; a product on two lines is refused (duplicate_line); issue_stock reports every short line (insufficient_stock) and posts nothing. The answer is 422 insufficient_stock with posted: false and context.lines[{id, ref, sku, requested, available}]: id is the product, ref the one you sent, requested and available decimal strings in the product's unit (the unit that get_stock answers).

• Through the HTTP/MCP executor the closed input schema refuses malformed shapes first, with context.errors[{path, message}] and no row code; the row errors with a code are for what the schema lets through.

• A call with more lines than core's api_confirm_batch_over setting (50 unless the host changed it) is held for confirmation: the first call answers a preview and a confirm_token, the same call with the token posts it. This holds for a retry of a posted external_ref too.

• dry_run: true (a control field every write tool takes) answers what the call would do (would_post, would_skip, or the same refusal a real call gives) and writes nothing. A stocktake is worth previewing: the from of each line is the current stock.

• Every posted line answers the stock before (from) and after (to). A confirmation code is bound to what the preview showed, including the current stock of every line: any other document that moves one of those products before the code is used invalidates it (409), and the call is previewed again.

• A posting that Postgres aborts to break a lock cycle with another document (a deadlock) is answered 500 internal_error with posted: false and a retry-after of 1 second; nothing was changed and the same call can be sent again. A call that carried a confirmation code (above the confirmation threshold) has spent it: send it again without the code.

• external_ref carries your own document number: sending it again answers skipped with the existing document and moves no stock. On issue_stock source: {"kind": "external", "ref": ...} is the same reference (do not send both). The retry is answered from the posted document before the lines are checked (a product trashed or a default warehouse changed since does not matter). What a retry is compared on: the lines (the product and the quantity of each, and for a receipt the unit_value of each), an explicit location_id, an explicit catalogue_id, an explicit reason, and the shop order of the source. A location_id or catalogue_id left out is not compared (the default warehouse may have moved), and neither is note. A request that differs is refused as 422 validation_failed with posted: false, the posted document and context.errors[{path, code, message}]; it is never answered skipped, so a client that reads only the status cannot take a different request for one that went through. Nothing is posted. The lines of a retry are checked as in a first call: a line that a first call would refuse (a wrong quantity, an id that names no product, a product twice) is refused with the same errors, not answered skipped. The codes:

  • external_ref_lines_differ: the lines are not the posted ones.
  • external_ref_basis_differs: a stated location_id, catalogue_id, reason or shop order (source) is not the posted document's (the message names which).

  When a product no longer resolves (trashed since), its ref must match a stored product identity. Quantities, receipt unit values and duplicate products are still checked. A matching retry is answered skipped with an external_ref_lines_unverified effect, which a client must check. New documents retain product external_id refs in their lines for this comparison. For older documents without that snapshot, use the product UUID if its external ID no longer resolves; an unknown external ID is refused.

• issue_stock takes a required reason (sale, damage, production, other) and may link the write-off to a shop order with source: {"kind": "shop_order", "id": ...} (needs the E-commerce module, enabled, which registers that source kind). An issue with neither an external_ref nor an external source is not protected against a repeated request: if a call is repeated after a crash between the posting and the answer, the stock can be written off twice. Send a stable reference whenever a retry is possible.

• Quantities are decimal strings (or numbers) from 0 to 1000000000 with at most 6 decimal places; receipts and issues need more than zero, a stocktake accepts 0.

• Stock is written only to active warehouse locations; without location_id the default warehouse is used, and without one the call fails and names the setting.

• Each posted document writes one Activity entry (warehouse.goods_receipt.posted, warehouse.goods_issue.posted, warehouse.inventory.posted) with via: api, the key prefix, the request id and, for an operation released from the approval queue, the approver. These entries follow the module's :inventory_activity_logging switch: a host that switched that log off gets no module entry for API documents either (core's own api.request entry is separate and does not name the document), and a failed write of an entry never fails a document. The document itself still records its number, its external_ref, its posting time and the key owner as its creator.

• The tools follow this module's own enabled state, not the shop's "Stock tracking" switch.

Other modules

Requires phoenix_kit_catalogue (the items), phoenix_kit_locations (the warehouses), phoenix_kit_billing (currency formatting) and phoenix_kit_comments (document comment threads). A plan source for core's mix phoenix_kit.media.reorganize is included.

Installation

Add to your host app's mix.exs:

{:phoenix_kit_warehouse, "~> 0.3"}

Then fetch deps, apply the module's tables, and enable it in Admin → Modules:

mix deps.get
mix phoenix_kit.update

Removing this module

There is deliberately no automated uninstall. PhoenixKitWarehouse.Migrations.down/1 never drops any of the 8 phoenix_kit_warehouse_* tables or a row in them, for any target version — a host that merely removes this dependency from mix.exs has not consented to deleting live stock balances and document history, and a migration whose result depended on which packages happen to be compiled in would be nondeterministic (it would break core's manifest, chain hash, and squash verification). Removing the data is therefore a deliberate, manual operator step, in FK-safe order (children before parents):

-- Only after removing :phoenix_kit_warehouse from mix.exs, and only if you
-- actually want every stock balance and document gone for good.
DROP TABLE phoenix_kit_warehouse_goods_issues;
DROP TABLE phoenix_kit_warehouse_goods_receipts;
DROP TABLE phoenix_kit_warehouse_supplier_orders;
DROP TABLE phoenix_kit_warehouse_internal_orders;
DROP TABLE phoenix_kit_warehouse_inventory_documents;
DROP TABLE phoenix_kit_warehouse_stock;
DROP TABLE phoenix_kit_warehouse_transfers;
DROP TABLE phoenix_kit_warehouse_min_stock;
-- The document-number sequences are not OWNED BY their columns, so
-- dropping the tables leaves them behind.
DROP SEQUENCE phoenix_kit_warehouse_goods_issues_number_seq;
DROP SEQUENCE phoenix_kit_warehouse_goods_receipts_number_seq;
DROP SEQUENCE phoenix_kit_warehouse_supplier_orders_number_seq;
DROP SEQUENCE phoenix_kit_warehouse_internal_orders_number_seq;
DROP SEQUENCE phoenix_kit_warehouse_inventory_documents_number_seq;
DROP SEQUENCE phoenix_kit_warehouse_transfers_number_seq;

If you want to keep the tables (e.g. you plan to reinstall the module later) but stop this chain from tracking them, clear the version marker instead — it lives only on the anchor table:

COMMENT ON TABLE phoenix_kit_warehouse_stock IS NULL;

Development

See AGENTS.md for architecture, conventions, testing, and the release checklist.

License

MIT — see LICENSE.