Merge pull request #76 from dev-lymar/docs/dev-documentation-editing

Docs/dev documentation editing

README.md

@@ -11,19 +11,58 @@
 [![pytest](https://img.shields.io/badge/pytest-8.0.2-0A9EDC?style=flat&logo=pytest&logoColor=white)](https://docs.pytest.org/)
 [![Ruff](https://img.shields.io/badge/Ruff-0.3-FCC21B?style=flat&logo=ruff&logoColor=white"/)](https://github.com/astral-sh/ruff)
 [![SimpleJWT](https://img.shields.io/badge/SimpleJWT-5.3.1-orange?style=flat&logo=jwt&logoColor=white)](https://github.com/jazzband/djangorestframework-simplejwt)
+[![pre-commit](https://img.shields.io/badge/precommit-0.2-FAB040?style=flat&logo=precommit&logoColor=white)](https://pre-commit.com/)
+[![Flake8](https://img.shields.io/badge/flake8-checked-blueviolet?style=flat)](https://flake8.pycqa.org/en/latest/)
+[![mypy](https://img.shields.io/badge/mypy-checked-blue?style=flat)](https://mypy-lang.org/)
 
 # Melnichanka
 
 ## Table of Contents
 
-- [How to run the project](#how-to-run-the-project)
 - [Project Description](#project-description)
+- [How to run the project](#how-to-run-the-project)
 - [Usage](#usage)
 - [Documentation](#documentation)
 - [Testing](#testing)
 - [Contributing](#contributing)
 - [License](#license)
 
+## Project Description
+
+***Melnichanka: Simplifying Shipment Application Submissions***
+
+Melnichanka is a web application designed to streamline the process of submitting shipment
+applications. It automates the generation of necessary documents based on user input, covering
+details such as goods, brands, factories, and packages.
+
+***Key Benefits:***
+
+- Efficiency: Automates document generation to save time and resources.
+- Accuracy: Reduces errors associated with manual data entry.
+- Accessibility: User-friendly interface ensures ease of use, suitable for all levels of technical
+  proficiency.
+- Convenience: Simplifies the submission process, even for users with minimal technical experience.
+
+***Technological Foundation:***
+
+- Built with Django: Utilizes the robust Django framework for Python, ensuring reliability and
+  flexibility.
+- Containerized with Docker: Deployed using Docker and Docker Compose, enabling easy scalability
+  and
+  deployment.
+
+***Target Audience:***
+
+Designed for companies needing to submit shipment applications regularly.
+Ideal for organizations seeking to enhance efficiency, minimize errors, and optimize resource
+allocation.
+
+***Conclusion:***
+
+Melnichanka empowers companies by automating the creation of shipment documents, enabling them to
+focus on core business activities. It stands as a powerful tool for improving operational
+efficiency and streamlining document submission processes.
+
 ## How to run the project
 
 1. Install [`Docker`](https://www.docker.com/)
@@ -43,6 +82,10 @@ git clone https://github.com/KroshkaByte/Melnichanka.git
 cd Melnichanka
 ```
 
+- [Configure .env](#environment-configuration)
+
+<p>
+
 - Start the project from root directory:
 
 ```sh
@@ -51,36 +94,30 @@ docker-compose up -d --build
 
 - Open your web browser and navigate to http://localhost:80 to access the application.
 
-## Project Description
-
-Melnichanka is a web application designed to facilitate the process of submitting shipment
-applications to consignees. The application generates a package of documents required for shipment
-based on user input, including information about goods, brands, factories, and packages.
+#### Environment Configuration
 
-The application is intended to be used by companies that need to submit shipment applications on a
-regular basis. By using Melnichanka, companies can streamline the process of generating the
-necessary documents, reduce errors, and save time and resources.
+You need to manually update this secret in your `.env` file each time it changes.
 
-The application includes a user-friendly interface that allows users to easily enter data and
-generate documents. The interface is designed to be intuitive and easy to use, even for users with
-little or no technical experience.
+Additionally, create a `.env` file in the root directory based on the provided `.env.example`. Fill
+in your own data and rename the file to `.env`.
 
-Melnichanka is built using modern web technologies, including `Django`, a popular web framework for
-Python. The application is containerized using Docker and Docker Compose, making it easy to deploy
-and scale.
+Please note that the Django secret key used in the `.env.example` is just an example. You can
+generate a new key using the following command:
 
-Overall, Melnichanka is a powerful and flexible tool that can help companies save time and
-resources when submitting shipment applications. By automating the process of generating documents,
-Melnichanka can help companies reduce errors, improve efficiency, and focus on their core business.
+   ```sh
+   from django.core.management.utils import get_random_secret_key
+
+   print(get_random_secret_key())
+   ```
 
 ## Usage
 
 To use Melnichanka, follow these steps:
 
 - Enter the required information about the goods, brands, factories, and packages.
 - Click the `Generate Documents` button to generate the package of documents required for shipment.
-- Review the generated documents and make any necessary edits.
-- Download the documents in the desired format (e.g., PDF, Word, Excel).
+- Verify all the data and create an archive with documents.
+- Download the archive of documents in Excel format.
 - Submit the documents to the consignee as required.
 
 ## Database Pre-population

clients/models.py

@@ -5,7 +5,11 @@
 
 
 class DirectorPosition(models.Model):
-    director_position = models.CharField(max_length=40)
+    """
+    Model representing a director's position.
+    """
+
+    director_position = models.CharField(max_length=40, verbose_name="Должность директора")
 
     class Meta:
         verbose_name = "Должность директора"
@@ -16,7 +20,11 @@ def __str__(self) -> str:
 
 
 class Client(models.Model):
-    # Основная информация
+    """
+    Model representing a client organization.
+    """
+
+    # Main Information
     client_name = models.CharField(
         max_length=100, verbose_name="Наименование организации", db_index=True
     )
@@ -31,7 +39,7 @@ class Client(models.Model):
     destination_city = models.ForeignKey(
         City, on_delete=models.PROTECT, verbose_name="Город доставки", db_index=True
     )
-    # ЖД реквизиты
+    # Railway Details
     railway_station = models.ForeignKey(
         RailwayStation,
         on_delete=models.PROTECT,
@@ -40,19 +48,19 @@ class Client(models.Model):
         blank=True,
         null=True,
     )
-    # Остальные данные
+    # Other Data
     receiver_name = models.CharField(max_length=100, blank=True, verbose_name="Имя получателя")
     receiver_id = models.PositiveIntegerField(
         blank=True, null=True, verbose_name="Номер получателя"
     )
     receiver_okpo = models.PositiveIntegerField(blank=True, null=True, verbose_name="ОКПО")
     receiver_adress = models.CharField(max_length=200, blank=True, verbose_name="Адрес получателя")
     special_marks = models.CharField(max_length=200, blank=True, verbose_name="Особые отметки")
-    # Номер приложения
+    # Application Number
     last_application_number = models.CharField(
         max_length=50, blank=True, verbose_name="Номер приложения"
     )
-    # Пользователь который создал запись
+    # User who created the record
     user = models.ForeignKey(
         CustomUser,
         verbose_name="Пользователь",

clients/permissions.py

@@ -3,10 +3,11 @@
 
 class ClientAccessPermission(permissions.BasePermission):
     """
-    Класс разрешений для доступа к записям клиентов.
-    Проверяет, что пользователь аутентифицирован для просмотра записей.
-    Также проверяет, что пользователь является автором записи
-    или администратором для выполнения изменений или удаления записей.
+    Permission class for accessing client records.
+
+    Checks that the user is authenticated to view records.
+    Additionally, verifies that the user is either the author of the record
+    or an administrator to perform changes or deletions on records.
     """
 
     def has_permission(self, request, view):

clients/serializers.py

@@ -4,12 +4,36 @@
 
 
 class DirectorPositionSerializer(serializers.ModelSerializer[DirectorPosition]):
+    """
+    Serializer for the DirectorPosition model.
+
+    Serializes the 'id' and 'director_position' fields of DirectorPosition.
+    """
+
     class Meta:
         model = DirectorPosition
         fields = ["id", "director_position"]
 
 
 class ClientSerializer(serializers.ModelSerializer[Client]):
+    """
+    Serializer for the Client model.
+
+    Serializes all fields of the Client model
+    including nested serialization of 'director_position'.
+    Adds 'destination_city' and 'railway_station' as CharField serializers.
+    Sets the current authenticated user as the value for the 'user' field using HiddenField.
+
+    Fields:
+    - id: IntegerField
+    - director_position: Nested serialization using DirectorPositionSerializer
+    - destination_city: CharField for destination city name
+    - railway_station: CharField for railway station name
+    - user: HiddenField that defaults to the current authenticated user
+
+    Note: 'user' field is automatically populated with the current user making the request.
+    """
+
     director_position = DirectorPositionSerializer()
     destination_city: serializers.CharField = serializers.CharField()
     railway_station: serializers.CharField = serializers.CharField()

clients/views.py

@@ -7,15 +7,25 @@
 from .serializers import ClientSerializer, DirectorPositionSerializer
 
 
-# Базовый класс  для получения данных по записям клиентов
 class ClientAPIView(generics.ListCreateAPIView[Client]):
+    """
+    API view for retrieving a list of clients and creating a new client record.
+
+    Retrieves a list of clients with related director position, destination city,
+    and railway station. Caches the client list for 15 minutes if not already cached.
+    """
+
     queryset = Client.objects.select_related(
         "director_position", "destination_city", "railway_station"
     ).all()
     serializer_class = ClientSerializer
     permission_classes = (IsAuthenticated,)
 
     def get_queryset(self):
+        """
+        Get the queryset of clients. If cached, return cached data; otherwise, fetch from database
+        and cache for 15 minutes.
+        """
         cached_clients = cache.get("clients_list")
         if cached_clients:
             return cached_clients
@@ -25,22 +35,40 @@ def get_queryset(self):
             return clients
 
 
-# Изменение данных записи клиента
 class ClientAPIUpdateView(generics.RetrieveUpdateAPIView[Client]):
+    """
+    API view for updating a client record.
+
+    Retrieves and updates a specific client record based on its primary key.
+    Requires ClientAccessPermission for authorization.
+    """
+
     queryset = Client.objects.all()
     serializer_class = ClientSerializer
     permission_classes = (ClientAccessPermission,)
 
 
-# Удаление данных записи клиента
 class ClientAPIDeleteView(generics.DestroyAPIView[Client]):
+    """
+    API view for deleting a client record.
+
+    Deletes a specific client record based on its primary key.
+    Requires ClientAccessPermission for authorization.
+    """
+
     queryset = Client.objects.all()
     serializer_class = ClientSerializer
     permission_classes = (ClientAccessPermission,)
 
 
-# Передача списка позиций директора для фронтенда
 class DirectorPositionListView(generics.ListAPIView[DirectorPosition]):
+    """
+    API view for retrieving a list of director positions.
+
+    Retrieves a list of all available director positions.
+    Requires authentication (IsAuthenticated).
+    """
+
     queryset = DirectorPosition.objects.all()
     serializer_class = DirectorPositionSerializer
     permission_classes = (IsAuthenticated,)