models.py

# pyright: reportUninitializedInstanceVariable=false
import datetime
import typing
from warnings import deprecated

from django.contrib.gis.db import models as gis_models
from django.contrib.gis.geos import GEOSGeometry
from django.db import models
from django.db.models import Case, CharField, ExpressionWrapper, Q, When
from django.db.models.expressions import Value
from django.db.models.functions import Concat, Lower
from django.utils.translation import gettext_lazy
from django_choices_field import IntegerChoicesField
from pyfirebase_mapswipe import models as firebase_models

from apps.common.models import (
    ArchivableResource,
    AssetMimetypeEnum,
    AssetTypeEnum,
    CommonAsset,
    FirebasePushResource,
    UserResource,
)
from apps.contributor.models import ContributorTeam
from main.db import Model
from main.fields import OverwritableFileField
from utils.fields import validate_percentage

if typing.TYPE_CHECKING:
    from apps.tutorial.models import Tutorial  # noqa: F401


class ProjectAssetInputTypeEnum(models.IntegerChoices):
    """Enum representing the types of project input asset."""

    AOI_GEOMETRY = 100, "AOI Geometry"
    OBJECT_IMAGE = 200, "Image with object annotations"
    COVER_IMAGE = 201, "Image for project cover"

    @classmethod
    def get_display(cls, value: typing.Self | int) -> str:
        if value in cls:
            return str(cls(value).label)
        return "Unknown"


class ProjectAssetExportTypeEnum(models.IntegerChoices):
    """Enum representing the types of project export asset."""

    # Common?
    AGGREGATED_RESULTS = 100, "Aggregated Results (CSV)"
    AGGREGATED_RESULTS_WITH_GEOMETRY = 101, "Aggregated Results (with Geometry) (GEOJSON)"
    GROUPS = 104, "Groups (CSV)"
    HISTORY = 105, "History (CSV)"
    RESULTS = 106, "Results (CSV)"
    TASKS = 107, "Tasks (CSV)"
    USERS = 108, "Users (CSV)"
    AREA_OF_INTEREST = 109, "Area of Interest (GEOJSON)"
    # FIND / COMPARE
    HOT_TASKING_MANAGER_GEOMETRIES = 200, "HOT Tasking Manager Geometries (GEOJSON)"
    MODERATE_TO_HIGH_AGREEMENT_YES_MAYBE_GEOMETRIES = 201, "Moderate to High Agreement Yes Maybe Geometries (GEOJSON)"

    @classmethod
    def get_display(cls, value: typing.Self | int) -> str:
        if value in cls:
            return str(cls(value).label)
        return "Unknown"

    @staticmethod
    def get_mimetype(export_type: "ProjectAssetExportTypeEnum"):
        if export_type == ProjectAssetExportTypeEnum.AGGREGATED_RESULTS:
            return AssetMimetypeEnum.GZIP
        if export_type == ProjectAssetExportTypeEnum.AGGREGATED_RESULTS_WITH_GEOMETRY:
            return AssetMimetypeEnum.GZIP
        if export_type == ProjectAssetExportTypeEnum.GROUPS:
            return AssetMimetypeEnum.GZIP
        if export_type == ProjectAssetExportTypeEnum.HISTORY:
            return AssetMimetypeEnum.CSV
        if export_type == ProjectAssetExportTypeEnum.RESULTS:
            return AssetMimetypeEnum.GZIP
        if export_type == ProjectAssetExportTypeEnum.TASKS:
            return AssetMimetypeEnum.GZIP
        if export_type == ProjectAssetExportTypeEnum.USERS:
            return AssetMimetypeEnum.GZIP
        if export_type == ProjectAssetExportTypeEnum.AREA_OF_INTEREST:
            return AssetMimetypeEnum.GEOJSON
        if export_type == ProjectAssetExportTypeEnum.MODERATE_TO_HIGH_AGREEMENT_YES_MAYBE_GEOMETRIES:
            return AssetMimetypeEnum.GEOJSON
        if export_type == ProjectAssetExportTypeEnum.HOT_TASKING_MANAGER_GEOMETRIES:
            return AssetMimetypeEnum.GEOJSON
        typing.assert_never(export_type)


class ProjectTypeEnum(models.IntegerChoices):
    """Enum representing the types of project."""

    FIND = 1, "Find Features"
    """ Find project type. Previously known as Classification / Build Area. """

    VALIDATE = 2, "Validate Footprints"
    """ Validate project type. Previously known as Footprint """

    VALIDATE_IMAGE = 10, "Assess Images"
    """ Validate image project type. """

    COMPARE = 3, "Compare Dates"
    """ Compare project type. Previously known as Change Detection. """

    COMPLETENESS = 4, "Check Completeness"
    """ Completeness project type. """

    # MEDIA = 5, "Media"
    # DIGITIZATION = 6, "Digitization"
    STREET = 7, "View Streets"
    """ Street project type. """

    # TODO(thenav56): Confirm if we have more/less

    @classmethod
    def get_display(cls, value: typing.Self | int) -> str:
        if value in cls:
            return str(cls(value).label)
        return "Unknown"

    def to_firebase(self) -> firebase_models.FbEnumProjectType:
        match self:
            case ProjectTypeEnum.FIND:
                return firebase_models.FbEnumProjectType.FIND
            case ProjectTypeEnum.COMPARE:
                return firebase_models.FbEnumProjectType.COMPARE
            case ProjectTypeEnum.COMPLETENESS:
                return firebase_models.FbEnumProjectType.COMPLETENESS
            case ProjectTypeEnum.VALIDATE:
                return firebase_models.FbEnumProjectType.VALIDATE
            case ProjectTypeEnum.VALIDATE_IMAGE:
                return firebase_models.FbEnumProjectType.VALIDATE_IMAGE
            case ProjectTypeEnum.STREET:
                return firebase_models.FbEnumProjectType.STREET


# TODO(tnagorra): Reset the values later
class ProjectStatusEnum(models.IntegerChoices):
    """Enum representing the status of a project."""

    DRAFT = 10, "Draft"
    """Background processes and validations will not be triggered for a "Draft" project."""

    READY_TO_PROCESS = 20, "Ready to Process"
    """Background processes and validations will be triggered
    once a project is "Ready to Process".
    """

    DISCARDED = 80, "Discarded"
    """Discarded projects are not visible to the contributors.
    "Discarded" projects cannot be "un-discarded".
    """

    PROCESSING_FAILED = 30, "Processing Failed"
    """If there are validation errors or issues with background processes,
    then processing of project has failed
    """

    PROCESSED = 40, "Processed"
    """If there are no validation errors or issues with background processes,
    then the project is "Processed"
    These projects are not be yet visible to the contributors.
    """

    READY_TO_PUBLISH = 45, "Ready to Publish"
    """Background processes and syncing to firebase will be triggered
    once a project is "Ready to Publish".
    """

    PUBLISHING_FAILED = 46, "Publishing Failed"
    """If there are errors or issues with background processes,
    then publishing of project has failed
    """

    PUBLISHED = 50, "Published"
    """"Published" project is be visible to the contributors."""

    PAUSED = 60, "Paused"
    """Paused projects are visible to the contributors.
    "Paused" projects can be "un-paused" again.
    """

    WITHDRAWN = 70, "Withdrawn"
    """Withdrawn projects are not visible to the contributors.
    "Withdrawn" projects cannot be "un-widthdrawn" again.
    """

    FINISHED = 75, "Finished"
    """Finished projects are not visible to the contributors.
    "Finished" projects cannot be "un-finished" again.
    """


class ProjectProgressStatusEnum(models.IntegerChoices):
    """Enum representing the state of project's progress."""

    ON_GOING = 1, "On going"
    COMPLETED = 2, "Completed"


class ProjectProcessingStatusEnum(models.IntegerChoices):
    """Enum representing the granular status of a project that is being processed."""

    PREPARING = 10, "Preparing"
    VALIDATING_GEOMETRY = 20, "Validating Geometry"
    GENERATING_GROUPS_AND_TASKS = 30, "Generating groups and tasks"
    ANALYZING_GROUPS_AND_TASK = 40, "Analyzing groups and tasks"
    GENERATING_TASKS_GEOJSON = 50, "Generating GeoJSON from tasks"
    COMPLETED = 60, "Processing Completed"


class UploadHelper:
    """Utility class providing helper functions for generating upload paths."""

    @staticmethod
    def project_asset(instance: "ProjectAsset", filename: str):
        client_id = instance.client_id
        asset_type_str = AssetTypeEnum.get_string_for_filepath(instance.type_enum)
        return f"project/{instance.project_id}/asset/{asset_type_str}/{client_id}/{filename}"

    @deprecated("This is kept because it's referenced in migrations")
    @staticmethod
    def project_image(instance: "Project", filename: str):
        return f"project/{instance.pk}/image/{filename}"


class Organization(UserResource, ArchivableResource, FirebasePushResource):  # type: ignore[reportIncompatibleVariableOverride]
    """Model representing the organization requesting the project."""

    name = models.CharField[str, str](max_length=255)
    description = models.TextField[str | None, str | None](null=True, blank=True)
    abbreviation = models.CharField[str, str](max_length=50, null=True, blank=True)

    unique_name = models.GeneratedField(
        expression=Lower("name"),
        output_field=models.CharField(),
        db_persist=True,
        unique=True,
    )

    @typing.override
    def __str__(self) -> str:
        return self.name


class Geometry(Model):
    """Model representing an area."""

    geometry: GEOSGeometry | None = gis_models.GeometryField(dim=2, srid=4326)  # type: ignore[reportIncompatibleVariableOverride]
    centroid = gis_models.PointField(blank=True, null=True, spatial_index=True, srid=4326)
    bbox = gis_models.PolygonField(blank=True, null=True, spatial_index=True, srid=4326)
    total_area = models.FloatField[float | None, float | None](null=True, default=None)


class Project(UserResource, FirebasePushResource):
    """Model representing the project."""

    Type = ProjectTypeEnum
    Status = ProjectStatusEnum
    ProcessingStatus = ProjectProcessingStatusEnum

    project_type: int = IntegerChoicesField(  # type: ignore[reportAssignmentType]
        choices_enum=ProjectTypeEnum,
    )

    requesting_organization = models.ForeignKey[Organization, Organization](
        Organization,
        on_delete=models.PROTECT,
        related_name="+",
        help_text=gettext_lazy("Which group, institution or community is requesting this project?"),
    )

    # Generate in manager dashboard based on topic, region, project number, requesting org
    topic = models.CharField[str, str](max_length=255)
    region = models.CharField[str, str](max_length=255)
    project_number = models.PositiveIntegerField[int, int]()

    # TODO(tnagorra): Max length is 25 in manager dashboard.
    look_for = models.CharField[str | None, str | None](
        null=True,
        blank=True,
        max_length=255,
        help_text=gettext_lazy("What should the users look for (e.g. buildings, cars, trees)"),
    )

    additional_info_url = models.CharField[str | None, str | None](
        null=True,
        blank=True,
        help_text=gettext_lazy("Provide an optional link to a resource with additional information on the project"),
    )  # NOTE: manual_url before

    # TODO(tnagorra): Max length is 10000 in manager dashboard.
    # TODO(tnagorra): This should be required.
    # NOTE: Markdown syntax is supported.
    description = models.TextField[str | None, str | None](
        null=True,
        blank=True,
    )  # NOTE: project_details before

    project_instruction = models.TextField[str | None, str | None](
        null=True,
        blank=True,
        help_text=gettext_lazy(
            "Provide project instruction",
        ),
    )

    image = models.ForeignKey["ProjectAsset | None", "ProjectAsset | None"](
        "project.ProjectAsset",
        related_name="+",
        blank=True,
        null=True,
        on_delete=models.SET_NULL,
    )

    # FIXME(tnagorra): We might need to rename this field
    tutorial = models.ForeignKey["Tutorial | None", "Tutorial | None"](
        "tutorial.Tutorial",
        null=True,  # NOTE: Validation makes sure active project have tutorial attached
        blank=True,
        on_delete=models.PROTECT,
        related_name="+",
        help_text=gettext_lazy("Tutorial used for this project."),
    )  # NOTE: tutorial_id before

    verification_number = models.PositiveSmallIntegerField[int, int](
        help_text=gettext_lazy("How many people do you want to see every tile before you consider it finished?"),
        default=3,
    )

    group_size = models.PositiveSmallIntegerField[int, int](
        help_text=gettext_lazy(
            "How big should a mapping session be? Group size refers to the number of tasks per mapping session.",
        ),
        default=10,
    )

    max_tasks_per_user = models.PositiveSmallIntegerField[int, int](
        help_text=gettext_lazy("How many tasks each user is allowed to work on for this project"),
        null=True,
        blank=True,
    )

    # TODO(tnagorra): Currently this field collects any data not stored by another fields, pulled from firebase.
    # Also, used in SQL queries
    project_type_specifics = models.JSONField(blank=True, null=True)

    aoi_geometry_input_asset = models.ForeignKey["ProjectAsset | None", "ProjectAsset | None"](
        "project.ProjectAsset",
        related_name="+",
        blank=True,
        null=True,
        on_delete=models.SET_NULL,
    )
    project_type_specific_output_asset = models.ForeignKey["ProjectAsset | None", "ProjectAsset | None"](
        "project.ProjectAsset",
        related_name="+",
        blank=True,
        null=True,
        on_delete=models.SET_NULL,
    )

    # TODO(tnagorra): remove centroid and bbox
    # Use centroid and bbox from aoi_geometry.centroid and aoi_geometry.bbox
    centroid = gis_models.PointField(blank=True, null=True, spatial_index=True, srid=4326)
    bbox = gis_models.PolygonField(blank=True, null=True, spatial_index=True, srid=4326)
    total_area = models.FloatField[float | None, float | None](null=True, default=None)

    # STATUS

    is_featured = models.BooleanField[bool, bool](default=False)
    status: int = IntegerChoicesField(  # type: ignore[reportAssignmentType]
        choices_enum=ProjectStatusEnum,
        default=ProjectStatusEnum.DRAFT,
    )
    processing_status: int | None = IntegerChoicesField(  # type: ignore[reportAssignmentType]
        choices_enum=ProjectProcessingStatusEnum,
        null=True,
        blank=True,
    )
    status_message = models.CharField[str | None, str | None](
        null=True,
        blank=True,
        max_length=510,
    )

    aoi_geometry = models.OneToOneField[Geometry | None, Geometry | None](
        Geometry,
        on_delete=models.CASCADE,
        null=True,
        blank=True,
        related_name="+",
    )

    # TEAM

    # NOTE: If any team is attached to the project, then project should only visible to the team members.
    team = models.ForeignKey[ContributorTeam | None, ContributorTeam | None](
        ContributorTeam,
        on_delete=models.SET_NULL,
        null=True,
        blank=True,
        related_name="+",
    )
    is_private = models.GeneratedField(
        expression=ExpressionWrapper(
            Q(team__isnull=False),
            output_field=models.BooleanField(),
        ),
        output_field=models.BooleanField(),
        db_persist=True,
        help_text=gettext_lazy(
            "If the project is private, then it is only visible to the team members.",
        ),
    )

    # CALCULATED FIELDS

    required_results = models.IntegerField[int, int](default=0)
    result_count = models.IntegerField[int, int](default=0)  # NOTE: All project have 0 in production database

    # -- After project is published

    progress_status: int = IntegerChoicesField(  # type: ignore[reportAssignmentType]
        choices_enum=ProjectProgressStatusEnum,
        default=ProjectProgressStatusEnum.ON_GOING,
    )

    # FIXME(tnagorra): Change this to float?
    progress = models.PositiveSmallIntegerField[int, int](
        default=0,
        validators=[validate_percentage],
        help_text=gettext_lazy("Percentage of the required contribution that has been completed"),
    )

    number_of_contributor_users = models.PositiveIntegerField[int, int](
        default=0,
        help_text=gettext_lazy("Number of users who made contributions to this project"),
    )
    number_of_results = models.PositiveIntegerField[int, int](
        default=0,
        help_text=gettext_lazy("Number of results contributed to this project"),
    )
    number_of_results_for_progress = models.PositiveIntegerField[int, int](
        default=0,
        help_text=gettext_lazy(
            "Number of results contributed to this project that can be used to calculate the progress of this project. "
            "Max no. of results per task that can be used to calculate progress is equal to the `verification number`",
        ),
    )
    last_contribution_date = models.DateField[datetime.date | None, datetime.date | None](
        null=True,
        blank=True,
        help_text=gettext_lazy("Last recent contribution date"),
    )

    slack_thread_ts = models.CharField[str | None, str | None](
        max_length=20,
        null=True,
        blank=True,
        help_text=gettext_lazy("Timestamp of the base slack message"),
    )

    slack_progress_notifications = models.PositiveIntegerField[int | None, int | None](
        null=True,
        blank=True,
        help_text=gettext_lazy("Stores the last progress checkpoint notified via Slack."),
    )

    # Type hints
    requesting_organization_id: int
    tutorial_id: int | None
    image_id: int | None
    team_id: int | None
    project_type_specific_output_id: int | None

    class Meta:  # type: ignore[reportIncompatibleVariableOverride]
        constraints = [
            # XXX: Changing this also requires changes in the serializers
            models.UniqueConstraint(
                "project_type",
                Lower("topic"),
                Lower("region"),
                "project_number",
                "requesting_organization",
                name="unique_project_name",
                violation_error_message=gettext_lazy(
                    "A project with the same type, topic, region, number and requesting organization already exists.",
                ),
            ),
        ]

    @typing.override
    def __str__(self) -> str:
        return self.generate_name()

    # NOTE: Defininig this function here to avoid circular dependency
    # FIXME(tnagorra): rename this to generate_name
    # Format: "{project_type} {topic} - {region} ({project_number}) {requesting_organization.name}"
    @staticmethod
    def generate_project_name(
        *,
        project_type: ProjectTypeEnum,
        topic: str,
        requesting_organization_name: str,
        region: str,
        project_number: int,
    ) -> str:
        return f"{project_type.label} - {topic} - {region} ({project_number}) {requesting_organization_name}"

    # FIXME(tnagorra): rename this to generated_name
    def generate_name(self) -> str:
        """Get generated name for the project based on topic, region and project number.

        Use select_related to avoid N+1 queries.
        """
        return Project.generate_project_name(
            project_type=self.project_type_enum,
            topic=self.topic,
            requesting_organization_name=self.requesting_organization.name,
            region=self.region,
            project_number=self.project_number,
        )

    @staticmethod
    def generate_name_query(prefix: str = ""):
        """Get a Django QuerySet expression to generate the project name."""
        project_type_label = Case(
            *[
                When(
                    **{f"{prefix}project_type": choice.value},
                    then=Value(choice.label),
                )
                for choice in ProjectTypeEnum
            ],
            default=models.Value("N/A"),
            output_field=CharField(),
        )

        return Concat(
            project_type_label,
            Value(" - "),
            models.F(f"{prefix}topic"),
            Value(" - "),
            models.F(f"{prefix}region"),
            Value(" ("),
            models.F(f"{prefix}project_number"),
            Value(") "),
            models.F(f"{prefix}requesting_organization__name"),
            output_field=models.CharField(),
        )

    def update_status(self, status: ProjectStatusEnum, commit: bool = True):
        self.status = status
        if commit:
            self.save(update_fields=("status",))

    def update_processing_status(self, status: ProjectProcessingStatusEnum, commit: bool = True):
        self.processing_status = status
        if commit:
            self.save(update_fields=("processing_status",))

    @property
    def project_type_enum(self):
        return ProjectTypeEnum(self.project_type)

    @property
    def status_enum(self):
        return ProjectStatusEnum(self.status)

    @property
    def progress_status_enum(self):
        return ProjectProgressStatusEnum(self.progress_status)


class ProjectAsset(UserResource, CommonAsset):  # type: ignore[reportIncompatibleVariableOverride]
    """Model representing assets for a project."""

    # TODO(thenav56): add validation
    # Type specific nested types
    export_type: int | None = IntegerChoicesField(  # type: ignore[reportAssignmentType]
        choices_enum=ProjectAssetExportTypeEnum,
        blank=True,
        null=True,
    )
    input_type: int | None = IntegerChoicesField(  # type: ignore[reportAssignmentType]
        choices_enum=ProjectAssetInputTypeEnum,
        blank=True,
        null=True,
    )

    project = models.ForeignKey[Project, Project](
        Project,
        on_delete=models.CASCADE,
        related_name="+",
    )

    file = OverwritableFileField(
        upload_to=UploadHelper.project_asset,
        help_text=gettext_lazy("The file associated with the asset"),
        null=True,
        blank=True,
        max_length=255,
    )

    # This depends on the input_type
    asset_type_specifics = models.JSONField(default=dict)

    @property
    def input_type_enum(self):
        return ProjectAssetInputTypeEnum(self.input_type)

    # Type hints
    project_id: int
    id: int


class ProjectTaskGroup(FirebasePushResource):
    """Model representing a group of tasks within a project.

    Each project is divided into manageable task groups, and each group contains multiple tasks.
    Contributors submit data at the group level rather than for individual tasks.
    """

    firebase_id = models.CharField[str, str](max_length=30)

    project: Project = models.ForeignKey[Project, Project](  # type: ignore[reportAssignmentType]
        Project,
        on_delete=models.CASCADE,
        related_name="+",
    )

    number_of_tasks = models.IntegerField[int, int]()
    required_count = models.IntegerField[int, int]()

    finished_count = models.IntegerField[int, int](default=0)
    progress = models.PositiveSmallIntegerField[int, int](default=0, validators=[validate_percentage])

    # TODO(thenav56): Currently this field collects any data not stored by another fields, pulled from firebase.
    # Also, used in SQL queries
    # FIXME(thenav56): Refactor this
    project_type_specifics = models.JSONField()

    # NOTE: Used by Community Dashboard
    total_area = models.FloatField[float | None, float | None](null=True, default=None)
    time_spent_max_allowed = models.FloatField[float | None, float | None](null=True, default=None)

    # Type hints
    id: int
    project_id: int

    class Meta:  # type: ignore[reportIncompatibleVariableOverride]
        unique_together = (
            "project",
            "firebase_id",
        )

    @typing.override
    def __str__(self):
        return f"(project={self.project_id}, id={self.pk})"


class ProjectTask(FirebasePushResource):
    """Model representing an individual task within a project group.

    Each task corresponds to a specific unit of work, typically a tile or area to be analyzed
    in the context of a larger mapping or data collection project.
    """

    firebase_id = models.CharField[str, str](max_length=30)

    task_group: ProjectTaskGroup = models.ForeignKey[ProjectTaskGroup, ProjectTaskGroup](  # type: ignore[reportAssignmentType]
        ProjectTaskGroup,
        on_delete=models.CASCADE,
        related_name="+",
    )

    # NOTE(tnagorra): The geometry is only necessary for validate project type
    # FIXME(thenav56): Existing gid_models.MultiPolygonField(srid=4326, blank=True, null=True)
    geometry: GEOSGeometry | None = gis_models.GeometryField(null=True, blank=True, default=None, dim=2, srid=4326)  # type: ignore[reportIncompatibleVariableOverride]

    # TODO(thenav56): Currently this field collects any data not stored by another fields, pulled from firebase.
    # Also, used in SQL queries
    # FIXME(thenav56): Refactor this
    project_type_specifics = models.JSONField()

    # Type hints
    id: int
    task_group_id: int

    # FIXME: Quick fix involves removing uniqueness constraint
    # As firebase_id for tasks are derived from user input,
    # we should discuss if we need db level uniqueness
    # class Meta:
    #     unique_together = (
    #         "task_group",
    #         "firebase_id",
    #     )

    @typing.override
    def __str__(self):
        return f"task_group_id={self.task_group_id}, id={self.pk}"