Validation plugin (#370)

* Add new empty pages

* Add documentation on new plugin mixin class

* Add internal link

* Updated documentation on stock item tracking

docs/extend/plugins.md

@@ -107,3 +107,4 @@ Supported mixin classes are:
 - [ScheduleMixin](./plugins/schedule.md)
 - [SettingsMixin](./plugins/settings.md)
 - [UrlsMixin](./plugins/urls.md)
+- [ValidationMixin](./plugins/validation.md)

docs/extend/plugins/validation.md

@@ -0,0 +1,93 @@
+---
+title: Validation Mixin
+---
+
+## ValidationMixin
+
+The `ValidationMixin` class enables plugins to perform custom validation of various fields.
+
+Any of the methods described below can be implemented in a custom plugin to provide functionality as required.
+
+!!! info "More Info"
+    For more information on any of the methods described below, refer to the InvenTree source code.
+
+!!! info "Multi Plugin Support"
+    It is possible to have multiple plugins loaded simultaneously which support validation methods. For example when validating a field, if one plugin returns a null value (`None`) then the *next* plugin (if available) will be queried.
+
+### Part Name
+
+By default, part names are not subject to any particular naming conventions or requirements. However if custom validation is required, the `validate_part_name` method can be implemente to ensure that a part name conforms to a required convention.
+
+If the custom method determines that the part name is *objectionable*, it should throw a `ValidationError` which will be handled upstream by parent calling methods.
+
+### Part IPN
+
+Validation of the Part IPN (Internal Part Number) field is exposed to custom plugins via the `validate_part_IPN` method. Any plugins which extend the `ValidationMixin` class can implement this method, and raise a `ValidationError` if the IPN value does not match a required convention.
+
+### Batch Codes
+
+[Batch codes](../../stock/tracking.md#batch-codes) can be generated and/or validated by custom plugins.
+
+The `validate_batch_code` method allows plugins to raise an error if a batch code input by the user does not meet a particular pattern.
+
+The `generate_batch_code` method can be implemented to generate a new batch code.
+
+### Serial Numbers
+
+Requirements for serial numbers can vary greatly depending on the application. Rather than attempting to provide a "one size fits all" serial number implementation, InvenTree allows custom serial number schemes to be implemented via plugins.
+
+The default InvenTree [serial numbering system](../../stock/tracking.md#serial-numbers) uses a simple algorithm to validate and increment serial numbers. More complex behaviours can be implemented using the `ValidationMixin` plugin class and the following custom methods:
+
+#### Serial Number Validation
+
+Custom serial number validation can be implemented using the `validate_serial_number` method. A *proposed* serial number is passed to this method, which then has the opportunity to raise a `ValidationError` to indicate that the serial number is not valid.
+
+##### Example
+
+A plugin which requires all serial numbers to be valid hexadecimal values may implement this method as follows:
+
+```python
+def validate_serial_number(self, serial: str):
+    """Validate the supplied serial number"""
+
+    try:
+        # Attempt integer conversion
+        int(serial, 16)
+    except ValueError:
+        raise ValidationError("Serial number must be a valid hex value")
+```
+
+#### Serial Number Sorting
+
+While InvenTree supports arbitrary text values in the serial number fields, behind the scenes it attempts to "coerce" these values into an integer representation for more efficient sorting.
+
+A custom plugin can implement the `convert_serial_to_int` method to determine how a particular serial number is converted to an integer representation.
+
+!!! info "Not Required"
+    If this method is not implemented, or the serial number cannot be converted to an integer, then the sorting algorithm falls back to the text (string) value
+
+#### Serial Number Incrementing
+
+A core component of the InvenTree serial number system is the ability to *increment* serial numbers - to determine the *next* serial number value in a sequence. 
+
+For custom serial number schemes, it is important to provide a method to generate the *next* serial number given a current value. The `increment_serial_number` method can be implemented by a plugin to achieve this.
+
+!!! info "Invalid Increment"
+    If the provided number cannot be incremented (or an error occurs) the method should return `None`
+
+##### Example
+
+Continuing with the hexadecimal example as above, the method may be implemented as follows:
+
+```python
+def increment_serial_number(self, serial: str):
+    """Provide the next hexadecimal number in sequence"""
+
+    try:
+        val = int(serial, 16) + 1
+        val = hex(val).upper()[2:]
+    except ValueError:
+        val = None
+
+    return val
+```

docs/stock/tracking.md

@@ -0,0 +1,63 @@
+---
+title: Stock Tracking
+---
+
+## Stock Tracking
+
+It may be desirable to track individual stock items, or groups of stock items, with unique identifier values. Stock items may be *tracked* using either *Batch Codes* or *Serial Numbers*.
+
+Individual stock items can be assigned a batch code, or a serial number, or both, or neither, as requirements dictate.
+
+{% with id="batch_and_serial", url="stock/batch_and_serial.png", description="Batch and serial number" %}
+{% include 'img.html' %}
+{% endwith %}
+
+Out of the box, the default implementations for both batch codes and serial numbers are (intentionally) simplistic.
+
+As the particular requirements for serial number or batch code conventions may vary significantly from one application to another, InvenTree provides the ability for custom plugins to determine exactly how batch codes and serial numbers are implemented.
+
+### Batch Codes
+
+Batch codes can be used to specify a particular "group" of items, and can be assigned to any stock item without restriction. Batch codes are tracked even as stock items are split into separate items.
+
+Multiple stock items may share the same batch code without restriction, even across different parts.
+
+#### Generating Batch Codes
+
+Batch codes can be generated automatically based on a provided pattern. The default pattern simply uses the current datecode as the batch number, however this can be customized within a certain scope.
+
+{% with id="batch_code_pattern", url="stock/batch_code_template.png", description="Batch code pattern" %}
+{% include 'img.html' %}
+{% endwith %}
+
+#### Plugin Support
+
+To implement custom batch code functionality, refer to the details on the [Validation Plugin Mixin](../extend/plugins/validation.md#batch-codes).
+
+### Serial Numbers
+
+A serial "number" is used to uniquely identify a single, unique stock item. Note that while *number* is used throughout the documentation, these values are not required to be numeric.
+
+#### Uniqueness Requirements
+
+By default, serial numbers must be unique across any given [Part](../part/part.md) instance (including any variants of that part).
+
+However, it is also possible to specify that serial numbers must be globally unique across all types of parts. This is configurable in the settings display (see below):
+
+{% with id="serial_numbers_unique", url="stock/serial_numbers_unique.png", description="Serial number uniqueness" %}
+{% include 'img.html' %}
+{% endwith %}
+
+#### Generating Serial Numbers
+
+In the default implementation, InvenTree assumes that serial "numbers" are integer values in a simple incrementing sequence e.g. `{1, 2, 3, 4, 5, 6}`. When generating the *next* value for a serial number, the algorithm looks for the *most recent* serial number, and attempts to coerce that value into an integer, and then increment that value.
+
+While this approach is reasonably robust, it is definitely simplistic and is not expected to meet the requirements of every installation. For this reason, more complex serial number management is intented to be implemented using a custom plugin (see below).
+
+#### Plugin Support
+
+Custom serial number functionality, with any arbitrary requirements or level of complexity, can be implemented using the [Validation Plugin Mixin class](../extend/plugins/validation.md#serial-numbers). Refer to the documentation for this plugin for technical details.
+
+A custom plugin allows the user to determine how a "valid" serial number is defined, and (crucially) how any given serial number value is incremented to provide the next value in the sequence.
+
+Implementing custom methods for these two consideraions allows for complex serial number schema to be supported with minimal effort.

mkdocs.yml

@@ -88,6 +88,7 @@ nav:
   - Stock:
     - Stock Items: stock/stock.md
     - Stock Status: stock/status.md
+    - Stock Tracking: stock/tracking.md
     - Adjusting Stock: stock/adjust.md
     - Stock Expiry: stock/expiry.md
     - Stock Ownership: stock/owner.md
@@ -149,6 +150,7 @@ nav:
       - Schedule Mixin: extend/plugins/schedule.md
       - Settings Mixin: extend/plugins/settings.md
       - URL Mixin: extend/plugins/urls.md
+      - Validation Mixin: extend/plugins/validation.md
     - API: extend/api.md
     - Python Interface: extend/python.md
     - Themes: extend/themes.md