From 75b5f48f9e12a2683e7db2cd046139b4cd46e523 Mon Sep 17 00:00:00 2001
From: Jon <jonathon.lockwood@networkedweb.com>
Date: Sat, 15 Feb 2025 22:04:17 +0930
Subject: [PATCH] docs(development): Add model history

ref: #601 #605
---
 .../development/core/model_history.md         | 76 +++++++++++++++++++
 mkdocs.yml                                    |  2 +
 2 files changed, 78 insertions(+)
 create mode 100644 docs/projects/centurion_erp/development/core/model_history.md

diff --git a/docs/projects/centurion_erp/development/core/model_history.md b/docs/projects/centurion_erp/development/core/model_history.md
new file mode 100644
index 00000000..f6a97454
--- /dev/null
+++ b/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
+
+```
diff --git a/mkdocs.yml b/mkdocs.yml
index 68d3eaab..ef30067d 100644
--- a/mkdocs.yml
+++ b/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