docs(development): Add model history

ref: #601 #605

docs/projects/centurion_erp/development/core/model_history.md

@@ -0,0 +1,76 @@
+---
+title: Model History
+description: Centurion ERP Model History development documentation
+date: 2025-02-15
+template: project.html
+about: https://github.com/nofusscomputing/centurion_erp
+---
+
+Model History is a core feature that is intended to be used to keep an audit history of **ALL** changes to a model.
+
+
+## Adding History to a Model
+
+Most of the work has already been done, all that is required to add history to a model is the creation of the following:
+
+- Model
+
+- Function `` added to audit model
+
+
+### Model
+
+The model must inherit from `core.models.model_history.ModelHistory`. This model requires a `models.ForeignKey` field named `model` be added to the new history model that will be receiving the history feature. The foriegn key relationship is to the model that will be receiving the history. There is also a requirement to add a function called `get_serialized_model` that returns the serialized model, using the "base" serializer. The model that is serialized is the model the history is for,
+
+As history can be broken up into parent-child relationships, if the model in question is a child model. The history model that will then be inherited from is the parent model history class. As this class will already contain the field `model`, the child history class must add field `child_model` which like the field `model` is also a `models.ForeignKey`.
+
+Like the parent history model, A serializer is required. In this case the serializer function is to be called `get_serialized_child_model` that returns the serialized child model. Again like the parent history model using the "base" serializer. The model that is serialized is the child model the history is for,
+
+
+#### Example model
+
+This example is for adding history to the Device Model
+
+``` py title="models/device_history.py"
+
+--8<-- "app/itam/models/device_history.py"
+
+```
+
+This example is for adding history to the child model DeviceSoftware
+
+``` py title="models/device_software_history.py"
+
+--8<-- "app/itam/models/device_software_history.py"
+
+```
+
+!!! tip
+    Take note of the inheritence and the fact that children don't override parent objects.
+
+!!! danger "Requirement"
+    Ensure that for the `model` and `child_model` fields that they are called with `related_name = history`. This ensures that **ALL** models that have history, will have an attribute called `history` that is available when working with that model.
+
+
+## Audit Model
+
+For history to save, there is a requirement to add a function to the model being audited. This function is to be called `save_history`. The sole purpose of this function is to call the super class (History class) function of the same name, although this time passing the history model.
+
+Example of the required function, in this case for the `Device` model.
+
+``` py
+
+
+def save_history(self, before: dict, after: dict) -> bool:
+
+    from itam.models.device_history import DeviceHistory
+
+    history = super().save_history(
+        before = before,
+        after = after,
+        history_model = DeviceHistory
+    )
+
+    return history
+
+```

mkdocs.yml

@@ -149,6 +149,8 @@ nav:
 
       - projects/centurion_erp/development/models.md
 
+      - projects/centurion_erp/development/core/model_history.md
+
       - projects/centurion_erp/development/core/model_notes.md
 
       - projects/centurion_erp/development/templates.md