[Feature] External build order (#9312)

* Add BuildOrder reference to PurchaseOrderLineItem

* Add setting to enable / disable external build orders

* Fix for supplier part detail

* Update forms

* Filter build list by "external" status

* Add "external" attribute to BuildOrder

* Filter by external build when selecting against purchase order line item

* Add frontend elements

* Prevent creation of build outputs

* Tweak related model field

- Send filters when fetching initial data

* Fix migrations

* Fix some existing typos

* Add build info when receiving line items

* Logic fix

* Bump API version

* Updated relationship

* Add external orders tab for order

* Display table of external purchase orders against a build order

* Fix permissions

* Tweak field definition

* Add unit tests

* Tweak api_version.py

* Playwright testing

* Fix discrepancy in 'building' filter

* Add basic documentation

( more work required )

* Tweak docs macros

* Migration fix

* Adjust build page tabs

* Fix imports

* Fix broken import

* Update playywright tests

* Bump API version

* Handle DB issues

* Improve filter

* Cleaner code

* Fix column ordering bug

* Add filters to build output table

* Documentation

* Tweak unit test

* Add "scheduled_for_production" field

* Add helper function to part model

* Cleanup

docs/docs/manufacturing/build.md

@@ -36,6 +36,8 @@ The build calendar allows the user to navigate month-by-month and display the fi
 
 ## Build Order Details
 
+Select an individual build order from the build order table to navigate to the Build Order detail page. The build order detail page provides a comprehensive overview of the build order, including all relevant information and actions.
+
 ### Build Order Reference
 
 Each Build Order is uniquely identified by its *Reference* field. Read more about [reference fields](../settings/reference.md).
@@ -181,6 +183,10 @@ Build order notes (which support markdown formatting) are displayed in the *Note
 
 {{ image("build/build_notes.png", title="Notes") }}
 
+## External Build Orders
+
+InvenTree supports the creation of *external build orders*, which are used to manage the manufacturing of parts by an external supplier. Read more about [external build orders](./external.md).
+
 ## Create Build Order
 
 To create a build order for your part, you have two options:
@@ -266,6 +272,7 @@ The following [global settings](../settings/global.md) are available for adjusti
 | Name | Description | Default | Units |
 | ---- | ----------- | ------- | ----- |
 {{ globalsetting("BUILDORDER_REFERENCE_PATTERN") }}
+{{ globalsetting("BUILDORDER_EXTERNAL_BUILDS") }}
 {{ globalsetting("BUILDORDER_REQUIRE_RESPONSIBLE") }}
 {{ globalsetting("BUILDORDER_REQUIRE_ACTIVE_PART") }}
 {{ globalsetting("BUILDORDER_REQUIRE_LOCKED_PART") }}

docs/docs/manufacturing/external.md

@@ -0,0 +1,72 @@
+---
+title: External Manufacturing
+---
+
+## External Manufacturing
+
+In some cases, it may be necessary to outsource the manufacturing of certain components or assemblies to an external supplier. InvenTree provides a simple interface for managing external manufacturing processes, allowing users to create and track orders with external suppliers.
+
+In the context of InvenTree, an *external build order* is a request to an external supplier to manufacture a specific assembly or component. This order is linked to a specific BOM and build order, ensuring that the correct components are produced.
+
+In conjunction with the external [Build Order](./build.md), a [Purchase Order](../purchasing/purchase_order.md) is required to manage the procurement of the manufactured items. The purchase order is used to track the order with the external supplier, including details such as pricing, delivery dates, and payment terms.
+
+When items are received from the external supplier (against the Purchase Order), they are automatically allocated to the external build order.
+
+### Stock Allocation
+
+Stock item can be allocated against an external build order as per the normal build order process. The external manufacturer may be expected to provide all of the components required to complete the build order, or they may only be responsible for a subset of the components. In either case, it is important to ensure that the correct stock items are allocated to the external build order. The allocation process is flexible, allowing users to specify which components should be included in the order.
+
+In the case of partial allocation, the user simply selects the stock items that should be included in the order.
+
+### Fulfillment
+
+The fulfillment process for external build orders is slightly different from the standard build order process. Instead of manually creating build outputs for the build order, these outputs are generated when the linked Purchase Order items are received.
+The Build Order and Purchase Order processes are closely linked, allowing users to easily manage the entire manufacturing process from start to finish. This includes tracking the progress of the external manufacturing process, managing stock allocations, and ensuring that the correct components are delivered on time.
+
+### Extra Requirements
+
+To successfully manage external build orders, the "assembly" (the part which is being manufactured) must be a *purchaseable* part, and it must have a linked Supplier Part which is associated with the external supplier.
+
+This ensures that external build orders are only created for parts that can be purchased from the supplier, and that the supplier is provided with the correct order codes and descriptions.
+
+The external suppiler must also be marked as a "manufacturer" in the InvenTree system.
+
+## Enable External Manufacturing
+
+By default, external manufacturing is disabled in InvenTree. To enable this feature, enable the {{ globalsetting("BUILDORDER_EXTERNAL_BUILDS", short=True) }} setting.
+
+## External Build Order Process
+
+The process for managing external build orders in InvenTree is as follows:
+
+### Create Build Order
+
+Create a new build order, specifying the assembly part and the quantity to be manufactured. When creating the new build order, select the "External" option to indicate that this is an external build order. The Build detail page will indicate that this is an external build order:
+
+{{ image("build/external_build_detail.png", "External build order detail") }}
+
+Additionally, the *Incomplete Outputs* panel will indicate that the build order is linked to an external purchase order, and that the outputs will be generated when the purchase order items are received.
+
+{{ image("build/external_build_fulfilment.png", "External build order fulfillment") }}
+
+### Create Purchase Order
+
+Once the build order has been created, a purchase order provides the link between the build order and the incoming goods (which will fulfil the build order).
+
+Create a purchase order against the external supplier which will be responsible for manufacturing the assembly. This assumes that there is already a [supplier part](../purchasing/supplier.md#supplier-parts) which links the assembled part to the external supplier.
+
+### Add Items to Purchase Order
+
+Once the purchase order has been created, add the assembly part to the purchase order. When adding the line item to the purchase order, ensure that the "Build Order" field is set to the external build order that was created earlier. This links the purchase order to the build order, allowing InvenTree to automatically allocate the received items to the build order when they are received.
+
+{{ image("build/external_build_select_build.png", "Link items to build order") }}
+
+### Receive Items
+
+Follow the normal process for receiving items against the purchase order. When the items are received from the external supplier, they will be marked as "build outputs" against the external build order.
+
+{{ image("build/external_build_receive_items.png", "Receive items against purchase order") }}
+
+The received items will now be registered as "incomplete outputs" against the external build order:
+
+{{ image("build/external_build_incomplete.png", "Incomplete build outputs") }}

docs/main.py

@@ -318,8 +318,14 @@ def define_env(env):
             json.dump(data, f, indent=4)
 
     @env.macro
-    def rendersetting(key: str, setting: dict):
-        """Render a provided setting object into a table row."""
+    def rendersetting(key: str, setting: dict, short: bool = False):
+        """Render a provided setting object into a table row.
+
+        Arguments:
+            key: The name of the setting to extract information for.
+            setting: The setting object to render.
+            short: If True, return a short version of the setting (default: False)
+        """
         name = setting['name']
         description = setting['description']
         default = setting.get('default')
@@ -328,37 +334,44 @@ def define_env(env):
         default = f'`{default}`' if default else ''
         units = f'`{units}`' if units else ''
 
-        return (
-            f'| <div title="{key}">{name}</div> | {description} | {default} | {units} |'
-        )
+        if short:
+            return f'<span title="{key}"><strong>{name}</strong></span>'
+
+        return f'| <div title="{key}"><strong>{name}</strong></div> | {description} | {default} | {units} |'
 
     @env.macro
-    def globalsetting(key: str):
+    def globalsetting(key: str, short: bool = False):
         """Extract information on a particular global setting.
 
         Arguments:
             key: The name of the global setting to extract information for.
+            short: If True, return a short version of the setting (default: False)
         """
         global GLOBAL_SETTINGS
         setting = GLOBAL_SETTINGS[key]
 
-        observe_setting(key, 'global')
+        # Settings are only 'observed' if they are displayed in full
+        if not short:
+            observe_setting(key, 'global')
 
-        return rendersetting(key, setting)
+        return rendersetting(key, setting, short=short)
 
     @env.macro
-    def usersetting(key: str):
+    def usersetting(key: str, short: bool = False):
         """Extract information on a particular user setting.
 
         Arguments:
             key: The name of the user setting to extract information for.
+            short: If True, return a short version of the setting (default: False)
         """
         global USER_SETTINGS
         setting = USER_SETTINGS[key]
 
-        observe_setting(key, 'user')
+        # Settings are only 'observed' if they are displayed in full
+        if not short:
+            observe_setting(key, 'user')
 
-        return rendersetting(key, setting)
+        return rendersetting(key, setting, short=short)
 
     @env.macro
     def tags_and_filters():

docs/mkdocs.yml

@@ -167,6 +167,7 @@ nav:
     - Build Orders: manufacturing/build.md
     - Build Outputs: manufacturing/output.md
     - Allocating Stock: manufacturing/allocate.md
+    - External Manufacturing: manufacturing/external.md
     - Example Build Order: manufacturing/example.md
   - Purchasing:
     - Purchasing: purchasing/index.md