Pricing app

CONTRIBUTING.md

@@ -77,6 +77,7 @@ The following Django apps are defined in `src/backend/InvenTree/`:
 | `machine/` | Support for external machines and devices |
 | `order/` | Purchase orders and sales orders |
 | `part/` | Parts catalogue and categories |
+| `pricing/` | Pricing calculation and caching |
 | `stock/` | Stock items and locations |
 | `report/` | Report templates and generation |
 | `plugin/` | Plugin system |

docs/docs/concepts/pricing.md

@@ -23,6 +23,17 @@ Throughout this documentation (and within InvenTree) the concepts of *cost* and
 | Price | The theoretical amount of money required to pay for something. |
 | Cost | The actual amount of money paid. |
 
+## Cost Tracking
+
+While *price* (as defined [above](#terminology)) is primarily tracked at the [Part](../part/pricing.md) level, *cost* - the actual amount paid - is tracked at the [Stock Item](../stock/costs.md) level, via one or more *cost entries* recorded against each stock item. These entries are automatically combined into a cached cost summary for the item, which in turn feeds into part-level purchase cost calculations.
+
+Refer to the following pages for details specific to each level:
+
+| Level | Documentation | Description |
+| --- | --- | --- |
+| Part | [Part Pricing](../part/pricing.md) | Cached price *ranges*, aggregated from multiple sources (BOM, supplier, internal, purchase history, variants, sale history) |
+| Stock Item | [Stock Item Costs](../stock/costs.md) | Individual *cost entries* recorded against a specific stock item, and the calculated cost summary derived from them |
+
 ## Line Items
 
 Orders (Purchase Orders, Sales Orders, and Return Orders) are made up of *line items*, each linking a *Quantity* to a *Unit Price*. A line item's *Line Total* is calculated as follows:

docs/docs/part/pricing.md

@@ -13,7 +13,7 @@ Pricing information can be determined from multiple sources:
 | --- | --- | ---|
 | Internal Price | How much a part costs to make | [Part](../part/index.md) |
 | Supplier Price | The price to theoretically purchase a part from a given supplier (with price-breaks) | [Supplier](../purchasing/supplier.md) |
-| Purchase Cost | Historical cost information for parts purchased | [Purchase Order](../purchasing/purchase_order.md) |
+| Purchase Cost | Historical cost information for parts purchased | [Purchase Order](../purchasing/purchase_order.md) / [Stock Item Costs](../stock/costs.md) |
 | BOM Price | Total price for an assembly (total price of all component items) | [Part](../part/index.md) |
 
 ### Override Pricing
@@ -71,7 +71,7 @@ If the **Internal Price Override** setting is enabled, then internal pricing dat
 
 ### Purchase History
 
-If the Part is designated as *purchaseable*, then historical purchase cost information is displayed (and used to calculate overall pricing). Purchase history data is collected from *completed* [purchase orders](../purchasing/purchase_order.md).
+If the Part is designated as *purchaseable*, then historical purchase cost information is displayed (and used to calculate overall pricing). Purchase history data is collected from *completed* [purchase orders](../purchasing/purchase_order.md), and reflects the calculated unit cost of each associated [stock item](../stock/costs.md).
 
 {{ image("part/pricing_purchase_history.png", "Purchase History") }}
 

docs/docs/part/stocktake.md

@@ -22,7 +22,7 @@ In particular, an individual *Stocktake* record tracks the following information
 
 ### Value Range of Stock on Hand
 
-The total value range of stock on hand is calculated based on the provided pricing data. For stock items which have a recorded *cost* (e.g. *purchase price*), this value is used. If no direct pricing information is available for a particular stock item, the price range of the part itself is used.
+The total value range of stock on hand is calculated based on the provided pricing data. For stock items which have a [recorded cost](../stock/costs.md), this value is used. If no direct cost information is available for a particular stock item, the price range of the part itself is used.
 
 !!! info "Value Range"
     Value data is provided as a *range* of values, accounting for any variability in available pricing data.

docs/docs/purchasing/purchase_order.md

@@ -127,7 +127,7 @@ Serial numbers are *not* required to receive a trackable part - if left blank, a
 
 ### Item Value Currency
 
-The unit cost of the purchase order line item is transferred across to the created stock item. By default, the same currency is used for the stock item as was used for the purchase order line item.
+The unit cost of the purchase order line item is transferred across to the created stock item, recorded as a [purchase cost entry](../stock/costs.md#cost-types). By default, the same currency is used for the stock item as was used for the purchase order line item.
 
 However, if the [Convert Currency](#purchase-order-settings) setting is enabled, the currency of the stock item will be converted to the [default currency](../concepts/pricing.md#default-currency) of the system. This may be useful when ordering stock in a different currency, to ensure that the unit cost of the stock item is converted to the base currency at the time of receipt.
 
@@ -140,9 +140,9 @@ Rather than receiving the bundle as a single opaque stock quantity, InvenTree al
 1. Create a part to represent the bundle itself, and mark it as an [assembly](../part/index.md#assembly)
 2. Link a [supplier part](./supplier.md#supplier-parts) to the bundle part, representing how it is purchased from the supplier
 3. Define a [Bill of Materials](../manufacturing/bom.md) for the bundle part, listing each of the individual components and the quantity contained within a single bundle
-4. Create and receive a purchase order against the bundle's supplier part, as normal - a single stock item is created for the bundle, retaining the purchase price and source purchase order of the order as a whole
+4. Create and receive a purchase order against the bundle's supplier part, as normal - a single stock item is created for the bundle, retaining the [unit cost](../stock/costs.md) and source purchase order of the order as a whole
 
-Once the individual components are actually required, the received bundle stock item can be [disassembled](../stock/disassemble.md) into its component parts. The purchase price and traceability data (batch code, source purchase order) of the original bundle are automatically apportioned across the newly generated component stock items.
+Once the individual components are actually required, the received bundle stock item can be [disassembled](../stock/disassemble.md) into its component parts. The unit cost and traceability data (batch code, source purchase order) of the original bundle are automatically apportioned across the newly generated component stock items.
 
 !!! tip "Pack Size vs Bundled Items"
     A supplier part with a [pack size](./supplier.md#supplier-part-pack-size) greater than one still represents multiple units of the *same* part - the pack size simply determines how many physical units are added to stock per unit ordered. A *bundled* item is different: a single supplier part represents an assortment of *different* components, which must be disassembled before the individual components can be used or sold separately.

docs/docs/stock/adjust.md

@@ -60,6 +60,9 @@ then the merge would not be possible.
 
 If the conditions are met, the process of merging will add up the stock quantity for all items involved in the merge and create a new stock item with the final calculated quantity.
 
+!!! info "Cost Merging"
+    If any of the merged items have a [recorded unit cost](./costs.md), the resulting stock item is assigned a new *purchase* [cost entry](./costs.md#cost-types), calculated as a quantity-weighted average of the cost of the merged items. If none of the merged items have recorded cost data, no cost entry is created.
+
 To merge stock items, check two or more items in a stock table and click on the {{ icon("packages", title="Stock Actions") }} icon above the table, then click on {{ icon("arrow-merge", title="Merge") }} menu option.
 
 In the Merge Stock Items form, user can decide to allow mismatched suppliers or status to be merged together (disabled by default).

docs/docs/stock/costs.md

@@ -0,0 +1,98 @@
+---
+title: Stock Item Costs
+---
+
+## Stock Item Costs
+
+!!! info "Pricing Support"
+    Refer to the [Pricing Support](../concepts/pricing.md) documentation for a general introduction to cost and pricing concepts in InvenTree.
+
+Each [stock item](./index.md) can have one or more *cost entries* recorded against it, representing the various contributions to its overall unit cost. These entries are automatically combined into a single cached *cost summary*, which is displayed throughout the InvenTree interface (for example in stock tables, and on the stock item detail page).
+
+### Cost Entries
+
+A *cost entry* records a single contribution to a stock item's unit cost, tagged with a [cost type](#cost-types), along with a *minimum* and *maximum* cost value (and their associated currency).
+
+!!! info "Unit Cost, not Total Cost"
+    Cost entries always represent a **per-unit** cost, not the total value of the stock item. To determine the total value of a stock item, multiply its unit cost by its quantity - see [Stock Value](#stock-value) below.
+
+Only one cost entry may exist per *(stock item, cost type)* pair - adding a new entry of the same type as an existing one updates that entry in place, rather than creating a duplicate.
+
+#### Cost Types
+
+| Cost Type | Description |
+| --- | --- |
+| Purchase | Cost taken directly from a purchase (e.g. a received purchase order line item) |
+| Landed | Purchase cost plus additional landed costs (freight, duty, handling, etc) |
+| Material | Cost of BOM components consumed by a build order, from allocated stock which itself has a recorded cost |
+| Material (Estimated) | Cost of BOM components consumed by a build order, from allocated stock with no recorded cost - estimated from the component part's price range instead |
+| Manufacturing | Reserved for manufacturing *process* cost (e.g. labor, overhead) added during a build - distinct from Material, which is the cost of the components consumed |
+| Manual | Cost manually entered (or overridden) by a user |
+| System | Cost calculated automatically by the pricing system (e.g. a pricing plugin) |
+
+!!! warning "Manufacturing Process Cost"
+    *Manufacturing* process cost (labor, overhead) is not yet calculated anywhere - the cost type exists, but nothing populates it yet. Only *Material* cost (see [How Cost Entries are Created](#how-cost-entries-are-created) below) is currently recorded automatically from build orders - see [Known Limitations](#known-limitations) below.
+
+### Cost Summary
+
+The cost summary for a stock item is automatically (re)calculated as the sum of all of its cost entries, and cached for fast retrieval. It is not itself directly editable - it always reflects the current state of the underlying cost entries, and is recalculated automatically whenever an entry is added, updated, or removed.
+
+If a stock item has no cost entries recorded against it, no cost summary is available for that item (rather than a summary reporting a zero cost).
+
+!!! tip "Currency Conversion"
+    While individual cost entries retain their own original currency, the cost summary is always calculated in the [default currency](../concepts/pricing.md#default-currency). If a currency conversion rate is not available for one of the entries, that entry is excluded from the summary rather than being included unconverted - the summary will never mix currencies.
+
+### Viewing and Editing Cost Entries
+
+Cost entries for a stock item can be viewed - and added, edited, or deleted - from the *Stock Item Cost* tab on the stock item detail page.
+
+| Column | Description |
+| --- | --- |
+| Cost Type | The [cost type](#cost-types) of the entry |
+| Minimum Cost | The minimum unit cost |
+| Maximum Cost | The maximum unit cost |
+| Date | The date the entry was last updated |
+| Notes | Optional notes describing the entry |
+
+!!! info "Permissions"
+    Viewing, adding, editing and deleting cost entries requires the appropriate [Pricing permission role](../settings/permissions.md#roles), assigned via user groups.
+
+### Displayed Cost Information
+
+Cost summary information is displayed in a number of places throughout the InvenTree interface:
+
+- The stock item detail page displays the *Unit Price* (unit cost) and *Stock Value* for the item, if cost data is available
+- Stock tables can optionally display *Unit Price* and *Stock Value* columns - these are hidden by default, and only visible to users with the *Pricing* view permission
+
+#### Stock Value
+
+The *Stock Value* of a stock item is calculated as:
+
+```
+Stock Value = Unit Cost * Quantity
+```
+
+This value is not itself stored - it is calculated on the fly, from the cached cost summary and the item's current quantity.
+
+### How Cost Entries are Created
+
+Cost entries can be created (or updated) in a number of ways:
+
+- **Manually**: a user with the appropriate permission can add, edit, or delete cost entries directly, via the *Stock Item Cost* tab described [above](#viewing-and-editing-cost-entries)
+- **Purchase order receipt**: [receiving a line item](../purchasing/purchase_order.md#receive-line-items) against a purchase order automatically records a *Purchase* cost entry against each created stock item, based on the line item's unit price - see [Item Value Currency](../purchasing/purchase_order.md#item-value-currency)
+- **Stock disassembly**: [disassembling](./disassemble.md#automatic-cost-allocation) a stock item automatically apportions its unit cost across the generated component stock items, recorded as a *Purchase* cost entry against each
+- **Stock merge**: [merging](./adjust.md#merge-stock) two or more stock items automatically calculates a new *Purchase* cost entry for the merged item, as a quantity-weighted average of the cost of the merged items
+- **Direct stock item creation / update**: the [Stock API](../api/index.md) accepts a `purchase_price` (and `purchase_price_currency`) value when creating or updating a stock item, which is recorded as a *Purchase* cost entry - this is a write-only convenience field, rather than a stored property of the stock item itself
+- **Build order completion**: completing a [build order](../manufacturing/build.md) automatically records *Material* (or *Material (Estimated)*, if the allocated stock has no recorded cost) cost entries against each completed build output, based on the cost of the BOM components allocated to it - both stock directly allocated to a specific output, and stock allocated to the build order as a whole (apportioned evenly, per unit, across every completed output)
+
+### Known Limitations
+
+- **No cost history**: only the most recent value for each *(stock item, cost type)* pair is retained - there is no historical ledger of cost changes over time for a given stock item
+- **Manufacturing process cost**: only the *cost of components* consumed by a build order is recorded automatically (as *Material* / *Material (Estimated)*) - manufacturing *process* cost (labor, overhead) is not yet calculated anywhere, even though the *Manufacturing* cost type exists for this purpose. This is planned for a future release.
+- **Consumable and virtual BOM lines**: build order material cost does not yet account for consumable or virtual BOM lines - see the "Manufacturing Costs" section of `dev/todo/pricing.md` for the follow-up plan
+- **CSV import**: bulk cost data cannot currently be imported via the stock item CSV import process
+
+### Related Documentation
+
+- [Pricing Support](../concepts/pricing.md) - general pricing and currency concepts
+- [Part Pricing](../part/pricing.md) - part-level pricing, which incorporates stock item cost data into purchase history calculations