feat(locations): add viewsets, serializers, managers and routers for country, state and city models

Author: tyronejosee

apps/locations/managers.py

@@ -0,0 +1,15 @@
+"""Managers for Locations App."""
+
+from apps.utilities.managers import BaseManager
+
+
+class CountryManager(BaseManager):
+    """Manager for Country Model."""
+
+
+class StateManager(BaseManager):
+    """Manager for State Model."""
+
+
+class CityManager(BaseManager):
+    """Manager for City Model."""

apps/locations/models.py

@@ -3,13 +3,16 @@
 from django.db import models
 
 from apps.utilities.models import BaseModel
+from .managers import CountryManager, StateManager, CityManager
 
 
 class Country(BaseModel):
     """Model definition for Country."""
 
     name = models.CharField(max_length=100, unique=True)
 
+    objects = CountryManager()
+
     class Meta:
         ordering = ["pk"]
         verbose_name = "country"
@@ -28,6 +31,8 @@ class State(BaseModel):
     name = models.CharField(max_length=100, unique=True)
     country_id = models.ForeignKey(Country, on_delete=models.CASCADE)
 
+    objects = StateManager()
+
     class Meta:
         ordering = ["pk"]
         verbose_name = "state"
@@ -46,6 +51,8 @@ class City(BaseModel):
     name = models.CharField(max_length=100, unique=True)
     state_id = models.ForeignKey(State, on_delete=models.CASCADE)
 
+    objects = CityManager()
+
     class Meta:
         ordering = ["pk"]
         verbose_name = "city"

apps/locations/routers.py

@@ -0,0 +1,16 @@
+"""Routers for Locations App."""
+
+from django.urls import include
+from django.urls import path
+from rest_framework.routers import DefaultRouter
+
+from .viewsets import CountryViewSet, StateViewSet, CityViewSet
+
+router = DefaultRouter()
+router.register(r"countries", CountryViewSet, basename="country")
+router.register(r"states", StateViewSet, basename="state")
+router.register(r"cities", CityViewSet, basename="city")
+
+urlpatterns = [
+    path("api/v1/", include(router.urls)),
+]

apps/locations/serializers.py

@@ -18,19 +18,54 @@ class Meta:
         ]
 
 
+class CountryWriteSerializer(ModelSerializer):
+    """Serializer for Country model (Create/update)."""
+
+    class Meta:
+        model = Country
+        fields = [
+            "name",
+        ]
+
+
+class CountryMinimalSerializer(ModelSerializer):
+    """Serializer for Country model (Minimal)."""
+
+    class Meta:
+        model = Country
+        fields = [
+            "id",
+            "name",
+        ]
+
+
 class StateReadSerializer(ModelSerializer):
     """Serializer for State model (List/retrieve)."""
 
+    country_id = CountryMinimalSerializer()
+
     class Meta:
         model = State
         fields = [
             "id",
             "name",
+            "country_id",
             "created_at",
             "updated_at",
         ]
 
 
+class StateWriteSerializer(ModelSerializer):
+    """Serializer for State model (Create/update)."""
+
+    class Meta:
+        model = State
+        fields = [
+            "name",
+            "country_id",
+        ]
+
+
 class StateMinimalSerializer(ModelSerializer):
     """Serializer for State model (Minimal)."""
 
@@ -45,7 +80,7 @@ class Meta:
 class CityReadSerializer(ModelSerializer):
     """Serializer for City model (List/retrieve)."""
 
-    state_id = StateReadSerializer()
+    state_id = StateMinimalSerializer()
 
     class Meta:
         model = City
@@ -58,6 +93,17 @@ class Meta:
         ]
 
 
+class CityWriteSerializer(ModelSerializer):
+    """Serializer for City model (Create/update)."""
+
+    class Meta:
+        model = City
+        fields = [
+            "name",
+            "state_id",
+        ]
+
+
 class CityMinimalSerializer(ModelSerializer):
     """Serializer for City model (Minimal)."""
 

apps/locations/viewsets.py

@@ -0,0 +1,124 @@
+"""ViewSets for Promotions App."""
+
+from rest_framework.viewsets import ModelViewSet
+from rest_framework.permissions import AllowAny
+
+from apps.users.permissions import IsAdministrator
+from apps.utilities.mixins import ListCacheMixin, LogicalDeleteMixin
+from .models import Country, State, City
+from .serializers import (
+    CountryReadSerializer,
+    CountryWriteSerializer,
+    CountryMinimalSerializer,
+    StateReadSerializer,
+    StateWriteSerializer,
+    StateMinimalSerializer,
+    CityReadSerializer,
+    CityWriteSerializer,
+    CityMinimalSerializer,
+)
+
+
+class CountryViewSet(ListCacheMixin, LogicalDeleteMixin, ModelViewSet):
+    """
+    ViewSet for managing Country instances.
+
+    Endpoints:
+    - GET /api/v1/countries/
+    - POST /api/v1/countries/
+    - GET /api/v1/countries/{id}/
+    - PUT /api/v1/countries/{id}/
+    - PATCH /api/v1/countries/{id}/
+    - DELETE /api/v1/countries/{id}/
+    """
+
+    permission_classes = [IsAdministrator]
+    serializer_class = CountryWriteSerializer
+    search_fields = ["name"]
+
+    def get_queryset(self):
+        return Country.objects.get_available()
+
+    def get_serializer_class(self):
+        if self.action == "list":
+            return CountryMinimalSerializer
+        elif self.action == "retrieve":
+            return CountryReadSerializer
+        return super().get_serializer_class()
+
+    def get_permissions(self):
+        if self.action in ["list", "retrieve"]:
+            return [AllowAny()]
+        return super().get_permissions()
+
+
+class StateViewSet(ListCacheMixin, LogicalDeleteMixin, ModelViewSet):
+    """
+    ViewSet for managing State instances.
+
+    Endpoints:
+    - GET /api/v1/states/
+    - POST /api/v1/states/
+    - GET /api/v1/states/{id}/
+    - PUT /api/v1/states/{id}/
+    - PATCH /api/v1/states/{id}/
+    - DELETE /api/v1/states/{id}/
+    """
+
+    permission_classes = [IsAdministrator]
+    serializer_class = StateWriteSerializer
+    search_fields = ["name"]
+    # filterset_class = StateFilter # TODO: Add filter
+
+    def get_queryset(self):
+        return State.objects.get_available().select_related(
+            "country_id"
+        )  # TODO: Add manager
+
+    def get_serializer_class(self):
+        if self.action == "list":
+            return StateMinimalSerializer
+        elif self.action == "retrieve":
+            return StateReadSerializer
+        return super().get_serializer_class()
+
+    def get_permissions(self):
+        if self.action in ["list", "retrieve"]:
+            return [AllowAny()]
+        return super().get_permissions()
+
+
+class CityViewSet(ListCacheMixin, LogicalDeleteMixin, ModelViewSet):
+    """
+    ViewSet for managing City instances.
+
+    Endpoints:
+    - GET /api/v1/cities/
+    - POST /api/v1/cities/
+    - GET /api/v1/cities/{id}/
+    - PUT /api/v1/cities/{id}/
+    - PATCH /api/v1/cities/{id}/
+    - DELETE /api/v1/cities/{id}/
+    """
+
+    permission_classes = [IsAdministrator]
+    serializer_class = CityWriteSerializer
+    search_fields = ["name"]
+    # filterset_class = CityFilter # TODO: Add filter
+
+    def get_queryset(self):
+        return City.objects.select_related(
+            "state_id"
+        ).get_available()  # TODO: Add manager
+
+    def get_serializer_class(self):
+        if self.action == "list":
+            return CityMinimalSerializer
+        elif self.action == "retrieve":
+            return CityReadSerializer
+        return super().get_serializer_class()
+
+    def get_permissions(self):
+        if self.action in ["list", "retrieve"]:
+            return [AllowAny()]
+        return super().get_permissions()

config/urls.py

@@ -35,6 +35,7 @@
     # Apps urls
     path("", include("apps.restaurants.routers")),
     path("", include("apps.promotions.routers")),
+    path("", include("apps.locations.routers")),
     path("", include("apps.drivers.urls")),
     path("", include("apps.orders.urls")),
     path("", include("apps.blogs.urls")),

roadmap.md

@@ -131,29 +131,29 @@ TODO: Agregar permiso para Recursos humanos
 
 ## Locations [OK]
 
-- [ ] `GET /countries` Obtener la lista de todos los países.
-- [ ] `POST /countries` Registrar un nuevo país.
-- [ ] `GET /countries/{id}` Obtener los detalles de un país específico.
-- [ ] `PUT /countries/{id}` Actualizar los detalles de un país específico.
-- [ ] `DELETE /countries/{id}` Eliminar un país específico.
-
-- [ ] `GET /states` Obtener la lista de todos los estados.
-- [ ] `POST /states` Registrar un nuevo estado.
-- [ ] `GET /states/{id}` Obtener los detalles de un estado específico.
-- [ ] `PUT /states/{id}` Actualizar los detalles de un estado específico.
-- [ ] `DELETE /states/{id}` Eliminar un estado específico.
-
-- [ ] `GET /cities` Obtener la lista de todas las ciudades.
-- [ ] `POST /cities` Registrar una nueva ciudad.
-- [ ] `GET /cities/{id}` Obtener los detalles de una ciudad específica.
-- [ ] `PUT /cities/{id}` Actualizar los detalles de una ciudad específica.
-- [ ] `DELETE /api/v1/cities/{id}` Eliminar una ciudad específica.
+- [x] `GET /countries` Obtener la lista de todos los países.
+- [x] `POST /countries` Registrar un nuevo país.
+- [x] `GET /countries/{id}` Obtener los detalles de un país específico.
+- [x] `PUT /countries/{id}` Actualizar los detalles de un país específico.
+- [x] `DELETE /countries/{id}` Eliminar un país específico.
+
+- [x] `GET /states` Obtener la lista de todos los estados.
+- [x] `POST /states` Registrar un nuevo estado.
+- [x] `GET /states/{id}` Obtener los detalles de un estado específico.
+- [x] `PUT /states/{id}` Actualizar los detalles de un estado específico.
+- [x] `DELETE /states/{id}` Eliminar un estado específico.
+
+- [x] `GET /cities` Obtener la lista de todas las ciudades.
+- [x] `POST /cities` Registrar una nueva ciudad.
+- [x] `GET /cities/{id}` Obtener los detalles de una ciudad específica.
+- [x] `PUT /cities/{id}` Actualizar los detalles de una ciudad específica.
+- [x] `DELETE /api/v1/cities/{id}` Eliminar una ciudad específica.
 
 ## Users [OK]
 
-- [ ] `GET /users/reviews` Obtener todas las reseñas escritas por un usuario específico (IsClient).
-- [ ] `GET /users/orders` Obtener todas las reseñas escritas por un usuario específico (IsClient).
-- [ ] `GET /users/{id}/historical` Obtener el historial de cambios de un usuario específico (IsAdministrator).
+- [x] `GET /accounts/reviews` Obtener todas las reseñas escritas por un usuario específico (IsClient).
+- [x] `GET /accounts/orders` Obtener todas las reseñas escritas por un usuario específico (IsClient).
+- [x] `GET /accounts/{id}/historical` Obtener el historial de cambios de un usuario específico (IsAdministrator).
 
 TODO: Agregar reviews a restaurants y posts, limitar modelo de Review