Calculate number of spares #417

inventory_management_system_api/core/database.py

@@ -39,7 +39,8 @@ def start_session_transaction(action_description: str) -> Generator[ClientSessio
 
     Also handles write conflicts.
 
-    :param action_description: Description of what the transaction is doing so it can be used in any raised errors.
+    :param action_description: Description of what the contents of the transaction is doing so it can be used in any
+                               raised errors.
     :raises WriteConflictError: If there a write conflict during the transaction.
     :returns: MongoDB session that has a transaction started on it.
     """

inventory_management_system_api/repositories/catalogue_item.py

@@ -137,7 +137,7 @@ def has_child_elements(self, catalogue_item_id: CustomObjectId, session: ClientS
         item = self._items_collection.find_one({"catalogue_item_id": catalogue_item_id}, session=session)
         return item is not None
 
-    def list_ids(self, catalogue_category_id: str, session: ClientSession = None) -> List[ObjectId]:
+    def list_ids(self, catalogue_category_id: Optional[str] = None, session: ClientSession = None) -> List[ObjectId]:
         """
         Retrieve a list of all catalogue item ids with a specific catalogue_category_id from a MongoDB
         database. Performs a projection to only include _id. (Required for mass updates of properties
@@ -148,17 +148,23 @@ def list_ids(self, catalogue_category_id: str, session: ClientSession = None) ->
         :return: A list object catalogue item ObjectId's or an empty list if no catalogue items are returned by
                  the database.
         """
-        logger.info(
-            "Finding the id's of all catalogue items within the catalogue category with ID '%s' in the database",
-            catalogue_category_id,
-        )
+
+        query = {}
+        if catalogue_category_id:
+            catalogue_category_id = CustomObjectId(catalogue_category_id)
+            query["catalogue_category_id"] = catalogue_category_id
+
+        message = "Retrieving IDs of all catalogue items from the database"
+        if not query:
+            logger.info(message)
+        else:
+            logger.info("%s matching the provided catalogue category ID filter", message)
+            logger.debug("Provided catalogue category ID filter: %s", catalogue_category_id)
 
         # Using distinct has a 16MB limit
         # https://stackoverflow.com/questions/29771192/how-do-i-get-a-list-of-just-the-objectids-using-pymongo
         # For 100000 documents, using list comprehension takes about 0.85 seconds vs 0.50 seconds for distinct
-        return self._catalogue_items_collection.find(
-            {"catalogue_category_id": CustomObjectId(catalogue_category_id)}, {"_id": 1}, session=session
-        ).distinct("_id")
+        return self._catalogue_items_collection.find(query, {"_id": 1}, session=session).distinct("_id")
 
     def insert_property_to_all_matching(
         self, catalogue_category_id: str, property_in: PropertyIn, session: ClientSession = None
@@ -211,3 +217,32 @@ def update_names_of_all_properties_with_id(
             array_filters=[{"elem._id": CustomObjectId(property_id)}],
             session=session,
         )
+
+    def update_number_of_spares(
+        self,
+        catalogue_item_id: Optional[ObjectId],
+        number_of_spares: Optional[int],
+        session: Optional[ClientSession] = None,
+    ) -> None:
+        """
+        Updates the `number_of_spares` field using a given catalogue item id filter.
+
+        :param catalogue_item_id: The ID of the catalogue item to update or `None` if updating all.
+        :param number_of_spares: New number of spares to update to. A value of `None` can be used to write lock
+                                 the involved documents when updating within a transaction as the actual value will be
+                                 assigned later but the documents should be write locked immediately.
+        :param session: PyMongo ClientSession to use for database operations.
+        """
+
+        if catalogue_item_id is not None:
+            self._catalogue_items_collection.update_one(
+                {"_id": catalogue_item_id},
+                {"$set": {"number_of_spares": number_of_spares}},
+                session=session,
+            )
+        else:
+            self._catalogue_items_collection.update_many(
+                {},
+                {"$set": {"number_of_spares": number_of_spares}},
+                session=session,
+            )

inventory_management_system_api/repositories/item.py

@@ -182,3 +182,22 @@ def update_names_of_all_properties_with_id(
         )
 
     # pylint:enable=duplicate-code
+
+    def count_with_usage_status_ids_in(
+        self,
+        catalogue_item_id: ObjectId,
+        usage_status_ids: List[CustomObjectId],
+        session: Optional[ClientSession] = None,
+    ) -> int:
+        """
+        Counts the number of items within a catalogue item with a `usage_status_id` contained within the given list.
+
+        :param catalogue_item_id: ID of the catalogue item for which items should be counted.
+        :param usage_status_ids: List of usage status IDs which should be included in the count.
+        :param session: PyMongo ClientSession to use for database operations.
+        :return: Number of items counted.
+        """
+
+        return self._items_collection.count_documents(
+            {"catalogue_item_id": catalogue_item_id, "usage_status_id": {"$in": usage_status_ids}}, session=session
+        )

inventory_management_system_api/repositories/setting.py

@@ -92,15 +92,34 @@ def get(self, out_model_type: Type[SettingOutBaseT], session: ClientSession = No
         :return: Retrieved setting or `None` if not found.
         """
 
+        # First obtain the setting document
+        setting = self._settings_collection.find_one({"_id": out_model_type.SETTING_ID}, session=session)
+
+        # Now ensure the setting is actually assigned and doesn't just have a write `_lock` and `_id` fields
+        if setting is None or (len(setting.keys()) == 2 and "_lock" in setting):
+            return None
+
         if out_model_type is SparesDefinitionOut:
             # The spares definition contains a list of usage statuses - use an aggregate query here to obtain
             # the actual usage status entities instead of just their stored ID
 
-            result = list(self._settings_collection.aggregate(SPARES_DEFINITION_GET_AGGREGATION_PIPELINE))
-            setting = result[0] if len(result) > 0 else None
-        else:
-            setting = self._settings_collection.find_one({"_id": out_model_type.SETTING_ID}, session=session)
+            setting = list(
+                self._settings_collection.aggregate(SPARES_DEFINITION_GET_AGGREGATION_PIPELINE, session=session)
+            )[0]
+
+        return out_model_type(**setting)
+
+    def write_lock(self, out_model_type: Type[SettingOutBaseT], session: ClientSession) -> None:
+        """
+        Updates a field `_lock` inside a setting in the database to lock the document from further updates in other
+        transactions.
+
+        Will add the setting document if it doesn't already exist. To ensure it can still be locked if it hasn't
+        ever been assigned a value before. (The get handles this case ensuring it still returns `None`.)
 
-        if setting is not None:
-            return out_model_type(**setting)
-        return None
+        :param out_model_type: The output type of the setting's model. Also contains the ID for lookup.
+        :param session: PyMongo ClientSession to use for database operations.
+        """
+        self._settings_collection.update_one(
+            {"_id": out_model_type.SETTING_ID}, {"$set": {"_lock": None}}, upsert=True, session=session
+        )

inventory_management_system_api/routers/v1/catalogue_item.py

@@ -16,12 +16,13 @@
     MissingMandatoryProperty,
     MissingRecordError,
     NonLeafCatalogueCategoryError,
+    WriteConflictError,
 )
 from inventory_management_system_api.schemas.catalogue_item import (
+    CATALOGUE_ITEM_WITH_CHILD_NON_EDITABLE_FIELDS,
     CatalogueItemPatchSchema,
     CatalogueItemPostSchema,
     CatalogueItemSchema,
-    CATALOGUE_ITEM_WITH_CHILD_NON_EDITABLE_FIELDS,
 )
 from inventory_management_system_api.services.catalogue_item import CatalogueItemService
 
@@ -107,6 +108,12 @@ def create_catalogue_item(
         message = "Adding a catalogue item to a non-leaf catalogue category is not allowed"
         logger.exception(message)
         raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=message) from exc
+    # pylint: disable=duplicate-code
+    except WriteConflictError as exc:
+        message = str(exc)
+        logger.exception(message)
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=message) from exc
+    # pylint: enable=duplicate-code
 
 
 @router.patch(

inventory_management_system_api/routers/v1/item.py

@@ -14,6 +14,7 @@
     InvalidPropertyTypeError,
     MissingMandatoryProperty,
     MissingRecordError,
+    WriteConflictError,
 )
 from inventory_management_system_api.schemas.item import ItemPatchSchema, ItemPostSchema, ItemSchema
 from inventory_management_system_api.services.item import ItemService
@@ -58,6 +59,12 @@ def create_item(item: ItemPostSchema, item_service: ItemServiceDep) -> ItemSchem
         message = "Unable to create item"
         logger.exception(message)
         raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=message) from exc
+    # pylint: disable=duplicate-code
+    except WriteConflictError as exc:
+        message = str(exc)
+        logger.exception(message)
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=message) from exc
+    # pylint: enable=duplicate-code
 
 
 @router.delete(
@@ -77,6 +84,12 @@ def delete_item(
         message = "Item not found"
         logger.exception(message)
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=message) from exc
+    # pylint: disable=duplicate-code
+    except WriteConflictError as exc:
+        message = str(exc)
+        logger.exception(message)
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=message) from exc
+    # pylint: enable=duplicate-code
 
 
 @router.get(path="", summary="Get items", response_description="List of items")
@@ -161,3 +174,9 @@ def partial_update_item(
         message = "Cannot change the catalogue item of an item"
         logger.exception(message)
         raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail=message) from exc
+    # pylint: disable=duplicate-code
+    except WriteConflictError as exc:
+        message = str(exc)
+        logger.exception(message)
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=message) from exc
+    # pylint: enable=duplicate-code

inventory_management_system_api/routers/v1/setting.py

@@ -7,7 +7,7 @@
 
 from fastapi import APIRouter, Depends, HTTPException, status
 
-from inventory_management_system_api.core.exceptions import InvalidObjectIdError, MissingRecordError
+from inventory_management_system_api.core.exceptions import InvalidObjectIdError, MissingRecordError, WriteConflictError
 from inventory_management_system_api.schemas.setting import SparesDefinitionPutSchema, SparesDefinitionSchema
 from inventory_management_system_api.services.setting import SettingService
 
@@ -37,6 +37,12 @@ def update_spares_definition(
         message = "A specified usage status does not exist"
         logger.exception(message)
         raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail=message) from exc
+    # pylint: disable=duplicate-code
+    except WriteConflictError as exc:
+        message = str(exc)
+        logger.exception(message)
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=message) from exc
+    # pylint: enable=duplicate-code
 
 
 @router.get(

inventory_management_system_api/services/catalogue_item.py

@@ -9,16 +9,19 @@
 from fastapi import Depends
 
 from inventory_management_system_api.core.custom_object_id import CustomObjectId
+from inventory_management_system_api.core.database import start_session_transaction
 from inventory_management_system_api.core.exceptions import (
     ChildElementsExistError,
     InvalidActionError,
     MissingRecordError,
     NonLeafCatalogueCategoryError,
 )
 from inventory_management_system_api.models.catalogue_item import CatalogueItemIn, CatalogueItemOut
+from inventory_management_system_api.models.setting import SparesDefinitionOut
 from inventory_management_system_api.repositories.catalogue_category import CatalogueCategoryRepo
 from inventory_management_system_api.repositories.catalogue_item import CatalogueItemRepo
 from inventory_management_system_api.repositories.manufacturer import ManufacturerRepo
+from inventory_management_system_api.repositories.setting import SettingRepo
 from inventory_management_system_api.schemas.catalogue_item import (
     CATALOGUE_ITEM_WITH_CHILD_NON_EDITABLE_FIELDS,
     CatalogueItemPatchSchema,
@@ -39,6 +42,7 @@ def __init__(
         catalogue_item_repository: Annotated[CatalogueItemRepo, Depends(CatalogueItemRepo)],
         catalogue_category_repository: Annotated[CatalogueCategoryRepo, Depends(CatalogueCategoryRepo)],
         manufacturer_repository: Annotated[ManufacturerRepo, Depends(ManufacturerRepo)],
+        setting_repository: Annotated[SettingRepo, Depends(SettingRepo)],
     ) -> None:
         """
         Initialise the `CatalogueItemService` with a `CatalogueItemRepo`, `CatalogueCategoryRepo`
@@ -47,10 +51,12 @@ def __init__(
         :param catalogue_item_repository: The `CatalogueItemRepo` repository to use.
         :param catalogue_category_repository: The `CatalogueCategoryRepo` repository to use.
         :param manufacturer_repository: The `ManufacturerRepo` repository to use.
+        :param setting_repository: The `SettingRepo` repository to use.
         """
         self._catalogue_item_repository = catalogue_item_repository
         self._catalogue_category_repository = catalogue_category_repository
         self._manufacturer_repository = manufacturer_repository
+        self._setting_repository = setting_repository
 
     def create(self, catalogue_item: CatalogueItemPostSchema) -> CatalogueItemOut:
         """
@@ -88,15 +94,26 @@ def create(self, catalogue_item: CatalogueItemPostSchema) -> CatalogueItemOut:
         supplied_properties = catalogue_item.properties if catalogue_item.properties else []
         supplied_properties = utils.process_properties(defined_properties, supplied_properties)
 
-        return self._catalogue_item_repository.create(
-            CatalogueItemIn(
-                **{
-                    **catalogue_item.model_dump(),
-                    "properties": supplied_properties,
-                },
-                number_of_spares=None,
+        # Perform actual creation in a transaction as we need to ensure they cannot be added when in the process of
+        # recalculating spares through the spares definition being set
+        with start_session_transaction("creating catalogue item") as session:
+            # Write lock the spares definition - if this fails it either means another catalogue item is being created
+            # (unlikely) or that the spares definition has been set and is still recalculating
+            self._setting_repository.write_lock(SparesDefinitionOut, session)
+
+            # Obtain the current spares definition as if there is one set, we know it has 0 items
+            spares_definition = self._setting_repository.get(SparesDefinitionOut, session=session)
+
+            return self._catalogue_item_repository.create(
+                CatalogueItemIn(
+                    **{
+                        **catalogue_item.model_dump(),
+                        "properties": supplied_properties,
+                    },
+                    number_of_spares=None if spares_definition is None else 0,
+                ),
+                session=session,
             )
-        )
 
     def get(self, catalogue_item_id: str) -> Optional[CatalogueItemOut]:
         """