Data Model
==========

``ArticleDetail`` (``\Shopware\Models\Article\Detail``) and its attributes
    In Shopware ERP's data model, Shopware's product variant entity ``ArticleDetail`` corresponds to a physical product.
    This means that all stock management activity always refers to ``\Shopware\Models\Article\Detail``, never
    ``\Shopware\Models\Article\Article``.

    The most relevant attribute properties on ``\Shopware\Models\Attribute\Article`` are:

    * ``pickwareStockManagementDisabled``, which can be used to prevent Shopware ERP from managing stock for individual
      products. Clients should never update this property directly, but call
      :ref:`StockLedgerService::startRecordingStockChangesForArticleDetail() <erp:Shopware\\Plugins\\ViisonPickwareERP\\Components\\StockLedger\\StockLedgerService::startRecordingStockChangesForArticleDetail()>`
      or
      :ref:`StockLedgerService::stopRecordingStockChangesForArticleDetail() <erp:Shopware\\Plugins\\ViisonPickwareERP\\Components\\StockLedger\\StockLedgerService::stopRecordingStockChangesForArticleDetail()>`,
      respectively, instead.
    * ``pickwareStockInitialized`` and ``pickwareStockInitializationTime``, which document whether (and when) the
      product's initial stock was recorded in the stock ledger. Again, clients should never write these properties
      directly, but call
      :ref:`StockInitializationService::initializeStocksOfArticleDetails() <erp:Shopware\\Plugins\\ViisonPickwareERP\\Components\\StockLedger\\StockInitializationService::initializeStocksOfArticleDetails()>`
      or one of the other methods of that service instead.

.. _warehouse-model:

:php:class:`erp:Shopware\\CustomModels\\ViisonPickwareERP\\Warehouse\\Warehouse`
    Represents a physical warehouse with a name, a shorthand code and contact information. Contains any number of bin
    locations.

    Exactly one warehouse must be marked as the default warehouse, which will be used as a fallback whenever stock
    changes have to be made but the relevant warehouse is unknown. There is also a default return shipment warehouse,
    which is where return shipments go when no explicit warehouse is given.

    A warehouse can be marked as having its stock available for sale. If yes, the physical stock of each product in the
    warehouse will be counted towards Shopware's quantity of "available stock" for the product.

.. _bin-location-model:

:php:class:`erp:Shopware\\CustomModels\\ViisonPickwareERP\\Warehouse\\BinLocation`
    Represents a named location within a warehouse which can hold any number of pieces of any number of products. Pieces
    of a product may reside on multiple bin locations within the same warehouse --- this is called *chaotic
    warehousing*.

    A bin location is identified by a bin location code which is unique inside its warehouse. For each warehouse,
    exactly one bin location with the code ``pickware_null_bin_location`` exists which contains all stock which is on an
    unspecified or unknown bin location within the warehouse.

:php:class:`erp:Shopware\\CustomModels\\ViisonPickwareERP\\Warehouse\\ArticleDetailBinLocationMapping`
    Describes the fact that a product (``ArticleDetail``) has or may have stock on a certain bin location.

    The current amount of stock for a single product on the mapped bin location is stored in the ``stock`` property. The
    property ``reservedStock`` holds the amount of stock which is reserved for ongoing picking processes.

    The column ``lastStocktake`` stores the last time when the product stock was counted manually on the bin location.

    At most one ``ArticleDetailBinLocationMapping`` per ``ArticleDetail``--``Warehouse`` pair may be marked as the default
    mapping for a product, which means that stock will be added to or taken from that bin location when no explicit bin
    location was given for a process that changes stock for that product.

:php:class:`erp:Shopware\\CustomModels\\ViisonPickwareERP\\StockLedger\\StockLedgerEntry`
    Every movement of stock creates an entry in Shopware ERP's *stock ledger*. These record the relative change in the
    per-warehouse stock of a product, as well as the previous and the new per-warehouse stock for the product.

    All stock ledger entries have a technical type which records the reason for the stock movement. Valid types are
    ``purchase``, ``sale``, ``return``, ``stocktake``, ``incoming``, ``outgoing``, ``relocation``, ``initialization``,
    ``write-off``, and ``manual`` (deprecated). Stock ledger entries may also include a comment which is usually entered
    by the user, but can also be provided by the system --- for example, when stock ledger entries are changed as part
    of a migration.

    The stock ledger entry also records the price the product was purchased at for inbound stock entries, as well as
    which purchase batch stock is theoretically removed from (from an accounting perspective) for outbound stock
    entries.

    Even more so than with all other ERP models, stock ledger entries should never be written directly (neither via SQL
    nor Doctrine), but always by calling the appropriate methods of :php:class:`Shopware\\Plugins\\ViisonPickwareERP\\Components\\StockLedger\\StockLedgerService`. Creating or updating
    stock ledger entries directly will almost certainly cause stock inconsistencies and other problems.

Stock Initialization
^^^^^^^^^^^^^^^^^^^^

`Stock initialization` is the process by which products for which stock was previously not managed by Shopware ERP are
put under stock management. For this, the likely physical stock of a product is computed based on the Shopware's
available stock counter and booked into the default warehouse. Then, the fact that the product is initialized along with
the timestamp of the initialization's stock ledger entry.
