[Feature] SalesOrder Auto-Allocate (#12000)

* Add basic auto-allocate functionality

- backend code
- background task
- API endpoint

* Add new endpoint enum

* add frontend components

* Tweak auto-allocate output

* Allow specifying of individual line items

* Tweak error boundary

* Enable bulk-delete of allocated items against sales order

* Refactor stock sorting options

* Allow user to select how to handle serialized stock

* Backport new functionality to BuildOrder allocation

* Refactor sorting options to use enumerated values

* Implement functional unit tests for new feature

* Update API and CHANGELOG

* Additional unit test

* Add playwright testing

* Documentation

* Update docs for build auto-allocate

* Fix dependencies

* Adjust build line filtering

* Fix serializer

docs/docs/manufacturing/allocate.md

@@ -80,7 +80,16 @@ The *Deallocate Stock* button can be used to remove all allocations of untracked
 
 ## Automatic Stock Allocation
 
-To speed up the allocation process, the *Auto Allocate* button can be used to allocate untracked stock items to the build. Automatic allocation of stock items does not work in every situation, as a number of criteria must be met.
+To speed up the allocation process, the *Auto Allocate* button can be used to automatically allocate stock items to the build.
+
+!!! info "Background Task"
+    Auto-allocation runs as a background task. The UI will display a progress indicator while the task is running.
+
+#### Selecting Lines to Allocate
+
+By default, auto-allocation processes **all eligible BOM line items** in the build order. To restrict allocation to a subset of lines, select the desired rows in the allocation table before pressing the button — the dialog will indicate how many lines are selected.
+
+#### Auto Allocation Options
 
 The *Automatic Allocation* dialog is presented as shown below:
 
@@ -90,12 +99,16 @@ The *Automatic Allocation* dialog is presented as shown below:
 
 Select the master location where stock items are to be allocated from. Leave this input blank to allocate stock items from any available location.
 
+**Exclude Location**
+
+Exclude stock from a specific location (and all of its sub-locations). Useful for reserving stock in a particular area.
+
 **Interchangeable Stock**
 
 Set this option to *True* to signal that stock items can be used interchangeably. This means that in the case where multiple stock items are available, the auto-allocation routine does not care which stock item it uses.
 
 !!! warning "Take Care"
-    If the *Interchangeable Stock* option is enabled, and there are multiple stock items available, the results of the automatic allocation algorithm may somewhat unexpected.
+    If the *Interchangeable Stock* option is enabled, and there are multiple stock items available, the results of the automatic allocation algorithm may be somewhat unexpected.
 
 !!! info "Example"
     Let's say that we have 5 reels of our *C_100nF_0603* capacitor, each with 4,000 parts available. If we do not mind which of these reels the stock should be taken from, we enable the *Interchangeable Stock* option in the dialog above. In this case, the stock will be allocated from one of these reels, and eventually subtracted from stock when the build is completed.
@@ -104,6 +117,32 @@ Set this option to *True* to signal that stock items can be used interchangeably
 
 Set this option to *True* to allow substitute parts (as specified by the BOM) to be allocated, if the primary parts are not available.
 
+**Optional Items**
+
+Set this option to *True* to include optional BOM line items in the auto-allocation. By default, optional items are not automatically allocated.
+
+**Item Type**
+
+Controls which category of BOM line items is considered for auto-allocation:
+
+| Option | Description |
+| --- | --- |
+| Untracked Items | Only untracked (non-serialized) BOM lines are allocated *(default)* |
+| Tracked Items | Only tracked BOM lines are allocated |
+| All Items | Both tracked and untracked BOM lines are allocated |
+
+**Stock Priority**
+
+Controls the order in which matching stock items are consumed:
+
+| Option | Description |
+| --- | --- |
+| Oldest stock first (FIFO) | Stock items updated least recently are consumed first *(default)* |
+| Newest stock first (LIFO) | Stock items updated most recently are consumed first |
+| Smallest quantity first | Stock items with the lowest available quantity are consumed first |
+| Largest quantity first | Stock items with the highest available quantity are consumed first |
+| Soonest expiry date first | Stock items expiring earliest are consumed first; items with no expiry date are used last |
+
 ## Allocating Tracked Stock
 
 Allocation of tracked stock items is slightly more complex. Instead of being allocated against the *Build Order*, tracked stock items must be allocated against an individual *Build Output*.

docs/docs/sales/sales_order.md

@@ -110,6 +110,79 @@ After shipments were created, user can either:
 
 During the allocation process, user is required to select the desired shipment that will contain the stock items.
 
+### Auto Allocate Stock
+
+To speed up the allocation process, use the *Auto Allocate Stock* button ({{ icon("wand") }}) available in the *Line Items* tab. This automatically finds available stock and creates the required allocations with minimal user interaction.
+
+!!! info "Background Task"
+    Auto-allocation runs as a background task. The UI will display a progress indicator while the task is running.
+
+#### Selecting Lines to Allocate
+
+By default, auto-allocation processes **all unallocated line items** on the order. To restrict allocation to a subset of lines, select the desired rows in the *Line Items* table before pressing the button — the dialog will indicate how many lines are selected.
+
+#### Auto Allocation Options
+
+The auto-allocation dialog provides the following options:
+
+**Source Location**
+
+Restrict stock to a specific location (and all of its sub-locations). Leave blank to consider stock from any location.
+
+**Exclude Location**
+
+Exclude stock from a specific location (and all of its sub-locations). Useful for reserving stock in a particular area.
+
+**Shipment**
+
+Optionally assign all new allocations to a specific pending shipment. Only shipments that have not yet been completed are shown.
+
+**Interchangeable Stock**
+
+When enabled (default), stock may be drawn from multiple stock items or locations to fulfil a single line item. When disabled, a line item is only allocated if a single stock item can cover the entire remaining quantity.
+
+!!! warning "Take Care"
+    Enabling *Interchangeable Stock* means the auto-allocation routine will combine stock from different batches or locations. Review the resulting allocations if traceability is important.
+
+**Stock Priority**
+
+Controls the order in which matching stock items are consumed:
+
+| Option | Description |
+| --- | --- |
+| Oldest stock first (FIFO) | Stock items updated least recently are consumed first *(default)* |
+| Newest stock first (LIFO) | Stock items updated most recently are consumed first |
+| Smallest quantity first | Stock items with the lowest available quantity are consumed first |
+| Largest quantity first | Stock items with the highest available quantity are consumed first |
+| Soonest expiry date first | Stock items expiring earliest are consumed first; items with no expiry date are used last |
+
+**Serialized Stock**
+
+Controls whether serialized stock items are included in the auto-allocation:
+
+| Option | Description |
+| --- | --- |
+| Allow any stock | Both serialized and unserialized stock items are considered *(default)* |
+| Serialized stock only | Only stock items that carry a serial number are allocated |
+| Unserialized stock only | Only stock items without a serial number are allocated |
+
+#### Allocation Behaviour
+
+The auto-allocation routine performs the following steps for each eligible line item:
+
+1. Skips line items for *virtual* parts.
+2. Skips line items that are already fully allocated.
+3. Queries available stock for the line's part, applying any location and serialized-stock filters.
+4. Sorts the candidates according to the chosen *Stock Priority*.
+5. Greedily allocates from each stock item in turn until the remaining quantity for the line is satisfied.
+
+#### Removing Allocations
+
+Individual or multiple allocations can be removed from the *Allocated Stock* tab. Select the allocations to remove and use the *Delete* action.
+
+!!! warning "Shipped Allocations Protected"
+    Allocations that belong to a completed (shipped) shipment cannot be deleted.
+
 ### Check Shipment
 
 Shipments can be marked as "checked" to indicate that the items in the shipment has been verified. To mark a shipment as "checked", open the shipment actions menu, and select the "Check" action: