chore: add service to start report for reporting year

chore: cleanup

chore: cleanup

chore: add registration purpose to startReport schema

chore: cleanup

chore: cleanup

chore: cleanup

chore: cleanup

chore: cleanup

Author: shon-button

bc_obps/common/tests/endpoints/auth/constants.py

@@ -41,6 +41,7 @@
             "kwargs": {"operation_id": MOCK_UUID},
         },
         {"method": "get", "endpoint_name": "list_current_users_operations"},
+        {"method": "get", "endpoint_name": "list_previous_reportable_operations"},
         {
             "method": "get",
             "endpoint_name": "get_initial_activity_data",
@@ -174,6 +175,7 @@
             "endpoint_name": "register_create_operation_information",
         },
         {"method": "post", "endpoint_name": "start_report"},
+        {"method": "post", "endpoint_name": "create_report_for_reporting_year"},
         {
             "method": "post",
             "endpoint_name": "save_report",

bc_obps/registration/api/__init__.py

@@ -44,3 +44,4 @@
 from . import transfer_events
 from ._transfer_events import transfer_id
 from .router import router  # django_ninja router object  # noqa: F401
+from ._operations.reportable import list_previous_reportable_operations

bc_obps/registration/api/_operations/reportable.py

@@ -0,0 +1,28 @@
+from typing import List, Literal, Tuple
+from django.http import HttpRequest
+from common.api.utils import get_current_user_guid
+from registration.schema import OperationReportableOut, Message
+from service.error_service.custom_codes_4xx import custom_codes_4xx
+from service.operation_service import OperationService
+from registration.api.router import router
+from common.permissions import authorize
+from registration.constants import OPERATION_TAGS
+
+##### GET #####
+
+
+@router.get(
+    "/operations/reportable/previous",
+    response={200: List[OperationReportableOut], custom_codes_4xx: Message},
+    tags=OPERATION_TAGS,
+    auth=authorize("approved_industry_user"),
+    description="""
+    Returns the reporting year/operation combinations for which the current user is eligible to create a report
+    """,
+)
+def list_previous_reportable_operations(
+    request: HttpRequest,
+) -> Tuple[Literal[200], list[dict]]:
+    return 200, OperationService.list_previous_reportable_operations(
+        get_current_user_guid(request),
+    )

bc_obps/registration/schema/operation.py

@@ -316,3 +316,9 @@ class OperationUpdateStatusOut(ModelSchema):
     class Meta:
         model = Operation
         fields = ["id", "status"]
+
+
+class OperationReportableOut(Schema):
+    operation_id: UUID
+    operation_name: str
+    reporting_year: int

bc_obps/reporting/api/__init__.py

@@ -1,6 +1,7 @@
 # ruff: noqa: F401
 from .router import router
 from .reports import start_report
+from .reports import create_report_for_reporting_year
 from .build_form_schema import build_form_schema
 from .reporting_dashboard import get_dashboard_operations_list
 from .activity_data import get_initial_activity_data

bc_obps/reporting/api/reports.py

@@ -8,7 +8,7 @@
 from reporting.api.permissions import check_operation_ownership
 from reporting.constants import EMISSIONS_REPORT_TAGS
 from reporting.schema.generic import Message
-from reporting.schema.report import StartReportIn, CreateReportVersionIn
+from reporting.schema.report import StartReportIn, CreateReportVersionIn, CreateReportForReportingYearIn
 from service.report_service import ReportService
 from service.report_version_service import ReportVersionService, ReportVersionData
 from service.reporting_year_service import ReportingYearService
@@ -23,6 +23,7 @@
     approved_industry_user_report_composite_auth,
 )
 from reporting.models import ReportingYear, ReportVersion
+from common.api.utils.current_user_utils import get_current_user_guid
 
 
 @router.post(
@@ -38,6 +39,30 @@ def start_report(request: HttpRequest, payload: StartReportIn) -> Tuple[Literal[
     return 201, report_version_id
 
 
+@router.post(
+    "/create-report-for-reporting-year",
+    response={201: int, custom_codes_4xx: Message},
+    tags=EMISSIONS_REPORT_TAGS,
+    description="""
+    Creates a report for a given operation and reporting year
+
+    Allows a new report creation for a selected year when the authenticated
+    user's operator owned the operation during any portion of the reporting year
+    """,
+    auth=authorize("approved_industry_user"),
+)
+def create_report_for_reporting_year(
+    request: HttpRequest,
+    payload: CreateReportForReportingYearIn,
+) -> Tuple[Literal[201], int]:
+    report_version_id = ReportService.create_report_for_reporting_year(
+        user_guid=get_current_user_guid(request),
+        data=payload,
+    )
+
+    return 201, report_version_id
+
+
 @router.post(
     "/report-version/{version_id}/change-report-type",
     response={201: int, custom_codes_4xx: Message},

bc_obps/reporting/schema/report.py

@@ -17,3 +17,13 @@ class CreateReportVersionIn(Schema):
     """
 
     operation_id: UUID
+
+
+class CreateReportForReportingYearIn(Schema):
+    """
+    Schema for the start report for selected reporting year endpoint request
+    """
+
+    operation_id: UUID
+    reporting_year: int
+    registration_purpose: str

bc_obps/service/operation_designated_operator_timeline_service.py

@@ -62,3 +62,62 @@ def get_operation_designated_operator_for_reporting_year(
             start_date=timeline.start_date,
             end_date=timeline.end_date,
         )
+
+    @classmethod
+    def get_operation_designated_operators_for_reporting_years(
+        cls,
+        operation_ids: set[UUID],
+        reporting_years: set[int],
+    ) -> dict[tuple[UUID, int], OperationDesignatedOperatorTimelinePlus]:
+        """
+        Bulk version of get_operation_designated_operator_for_reporting_year
+
+        It is intended for scenarios where many operation/reporting year
+        combinations need to be evaluated, such as determining the list of reportable operations
+
+        Returns a lookup keyed by (operation_id, reporting_year)
+        """
+
+        if not operation_ids or not reporting_years:
+            return {}
+
+        min_year = min(reporting_years)
+        max_year = max(reporting_years)
+
+        timelines = (
+            OperationDesignatedOperatorTimeline.objects.select_related(
+                "operation",
+                "operator",
+            )
+            .filter(
+                operation_id__in=operation_ids,
+                start_date__year__lte=max_year,
+            )
+            .filter(Q(end_date__year__gt=min_year) | Q(end_date__isnull=True))
+            .order_by("operation__name", "start_date")
+        )
+
+        lookup: dict[tuple[UUID, int], OperationDesignatedOperatorTimelinePlus] = {}
+
+        for timeline in timelines:
+            start_date = timeline.start_date
+            end_date = timeline.end_date
+
+            if start_date is None:
+                continue
+
+            for reporting_year in reporting_years:
+                if start_date.year > reporting_year:
+                    continue
+
+                if end_date is not None and end_date.year <= reporting_year:
+                    continue
+
+                lookup[(timeline.operation_id, reporting_year)] = OperationDesignatedOperatorTimelinePlus(
+                    operation=timeline.operation,
+                    operator=timeline.operator,
+                    start_date=start_date,
+                    end_date=end_date,
+                )
+
+        return lookup

bc_obps/service/operation_service.py

@@ -50,7 +50,11 @@
 from django.db.models import Q
 from django.utils import timezone
 from registration.models.operation_designated_operator_timeline import OperationDesignatedOperatorTimeline
+from reporting.models.reporting_year import ReportingYear
+from service.reporting_year_service import ReportingYearService
 from django.conf import settings
+from service.operation_designated_operator_timeline_service import OperationDesignatedOperatorTimelineService
+from reporting.models.report import Report
 
 
 class OperationService:
@@ -749,3 +753,157 @@ def handle_change_of_registration_purpose(
             payload.regulated_products = []
 
         return payload
+
+    @classmethod
+    def _get_previous_reporting_years(cls) -> QuerySet[ReportingYear]:
+        """
+        Returns reporting years that are eligible for the Start Past Report workflow
+
+        Only reporting years prior to the current reporting year are returned
+        """
+
+        current_reporting_year = ReportingYearService.get_current_reporting_year()
+
+        return ReportingYear.objects.filter(reporting_year__lt=current_reporting_year.reporting_year).order_by(
+            "-reporting_year"
+        )
+
+    @staticmethod
+    def _build_reportable_operation_row(
+        timeline: OperationDesignatedOperatorTimeline,
+        reporting_year: ReportingYear,
+    ) -> dict[str, UUID | str | int]:
+        """
+        Builds a reportable operation response row
+        """
+        return {
+            "operation_id": timeline.operation.id,
+            "operation_name": timeline.operation.name,
+            "reporting_year": reporting_year.reporting_year,
+        }
+
+    @classmethod
+    def list_previous_reportable_operations(
+        cls,
+        user_guid: UUID,
+    ) -> list[dict]:
+        """
+        Returns the reporting year/operation  combinations for which the current user is eligible to create a report
+
+        An reporting year/operation  combination is eligible if:
+        1. The operation was designated to the user's operator for that reporting year, or
+        2. The operation is currently registered to the user's operator as a fallback
+
+        Existing reports are excluded
+        """
+
+        user_operator = UserDataAccessService.get_user_operator_by_user(user_guid)
+
+        reporting_years = cls._get_previous_reporting_years()
+        year_values = {reporting_year.reporting_year for reporting_year in reporting_years}
+
+        # Find all registered operation timelines associated with the user's operator
+        timelines = list(
+            OperationDesignatedOperatorTimeline.objects.select_related("operation")
+            .filter(
+                operator_id=user_operator.operator_id,
+                operation__status=Operation.Statuses.REGISTERED,
+            )
+            .order_by("operation__name", "start_date")
+        )
+
+        # Find all currently registered operations for fallback handling
+        current_registered_operations = list(
+            Operation.objects.filter(
+                operator_id=user_operator.operator_id,
+                status=Operation.Statuses.REGISTERED,
+            ).order_by("name")
+        )
+
+        all_operation_ids = {timeline.operation.id for timeline in timelines} | {
+            operation.id for operation in current_registered_operations
+        }
+
+        # Bulk fetch existing reports
+        existing_reports = set(
+            Report.objects.filter(
+                operation_id__in=all_operation_ids,
+                reporting_year_id__in=year_values,
+            ).values_list(
+                "operation_id",
+                "reporting_year_id",
+            )
+        )
+
+        # Bulk fetch designated operator timelines
+        designations_lookup = (
+            OperationDesignatedOperatorTimelineService.get_operation_designated_operators_for_reporting_years(
+                operation_ids=all_operation_ids,
+                reporting_years=year_values,
+            )
+        )
+
+        reportable_operations: list[dict] = []
+        added_operation_years: set[tuple[UUID, int]] = set()
+
+        # Add combinations that are valid based on historical designated operator timelines
+        for timeline in timelines:
+            for reporting_year in reporting_years:
+                operation_year = (
+                    timeline.operation.id,
+                    reporting_year.reporting_year,
+                )
+
+                if operation_year in added_operation_years:
+                    continue
+
+                if operation_year in existing_reports:
+                    continue
+
+                designated_operator_timeline = designations_lookup.get(operation_year)
+
+                if not designated_operator_timeline:
+                    continue
+
+                if designated_operator_timeline.operator.id != user_operator.operator_id:
+                    continue
+
+                reportable_operations.append(
+                    {
+                        **cls._build_reportable_operation_row(
+                            timeline,
+                            reporting_year,
+                        ),
+                        "is_current_registered_fallback": False,
+                    }
+                )
+
+                added_operation_years.add(operation_year)
+
+        # Fallback: include current registered operations for operation/year combinations not already returned by the historical designation logic
+        for operation in current_registered_operations:
+            for reporting_year in reporting_years:
+                operation_year = (
+                    operation.id,
+                    reporting_year.reporting_year,
+                )
+
+                if operation_year in added_operation_years:
+                    continue
+
+                if operation_year in existing_reports:
+                    continue
+
+                reportable_operations.append(
+                    {
+                        "operation_id": operation.id,
+                        "operation_name": operation.name,
+                        "reporting_year": reporting_year.reporting_year,
+                        "registration_purpose": operation.registration_purpose,
+                        "is_current_registered_fallback": True,
+                    }
+                )
+
+                added_operation_years.add(operation_year)
+
+        return reportable_operations