Merge pull request #4366 from bcgov/461-explicit-crv-status-for-manual-handling

461 explicit crv status for manual handling

Author: Sepehr-Sobhani

bc_obps/compliance/migrations/0040_alter_compliancereportversion_status.py

@@ -0,0 +1,47 @@
+# Generated by Django 5.1.15 on 2026-03-24 20:17
+
+from django.db import migrations, models
+
+
+def migrate_manual_handling_status(apps, schema_editor):
+    ComplianceReportVersion = apps.get_model('compliance', 'ComplianceReportVersion')
+    ComplianceReportVersion.objects.filter(
+        status="No obligation or earned credits",
+        manual_handling_record__isnull=False,
+    ).update(status="Requires manual handling")
+
+
+def reverse_migrate_manual_handling_status(apps, schema_editor):
+    ComplianceReportVersion = apps.get_model('compliance', 'ComplianceReportVersion')
+    ComplianceReportVersion.objects.filter(
+        status="Requires manual handling",
+        manual_handling_record__isnull=False,
+    ).update(status="No obligation or earned credits")
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('compliance', '0039_V5_6_0'),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name='compliancereportversion',
+            name='status',
+            field=models.CharField(
+                choices=[
+                    ('Obligation not met', 'Obligation Not Met'),
+                    ('Obligation fully met', 'Obligation Fully Met'),
+                    ('Obligation pending invoice creation', 'Obligation Pending Invoice Creation'),
+                    ('Earned credits', 'Earned Credits'),
+                    ('No obligation or earned credits', 'No Obligation Or Earned Credits'),
+                    ('Requires manual handling', 'Requires Manual Handling'),
+                    ('Superceded', 'Superceded'),
+                ],
+                db_comment='The status of this compliance report version. Options: [Obligation not met, Obligation fully met, Earned credits, No obligation or earned credits, Requires manual handling]',
+                max_length=100,
+            ),
+        ),
+        migrations.RunPython(migrate_manual_handling_status, reverse_migrate_manual_handling_status, elidable=True),
+    ]

bc_obps/compliance/models/compliance_report_version.py

@@ -14,6 +14,7 @@ class ComplianceStatus(models.TextChoices):
         OBLIGATION_PENDING_INVOICE_CREATION = "Obligation pending invoice creation"
         EARNED_CREDITS = "Earned credits"
         NO_OBLIGATION_OR_EARNED_CREDITS = "No obligation or earned credits"
+        REQUIRES_MANUAL_HANDLING = "Requires manual handling"
         SUPERCEDED = "Superceded"
 
     compliance_report = models.ForeignKey(
@@ -47,7 +48,7 @@ class ComplianceStatus(models.TextChoices):
     status = models.CharField(
         max_length=100,
         choices=ComplianceStatus.choices,
-        db_comment="The status of this compliance report version. Options: [Obligation not met, Obligation fully met, Earned credits, No obligation or earned credits]",
+        db_comment="The status of this compliance report version. Options: [Obligation not met, Obligation fully met, Earned credits, No obligation or earned credits, Requires manual handling]",
     )
 
     is_supplementary = models.BooleanField(

bc_obps/compliance/service/compliance_dashboard_service.py

@@ -333,6 +333,10 @@ def _annotate_status(
                 When(
                     status=ComplianceReportVersion.ComplianceStatus.EARNED_CREDITS.value, then=Value("Earned credits")
                 ),
+                When(
+                    status=ComplianceReportVersion.ComplianceStatus.REQUIRES_MANUAL_HANDLING.value,
+                    then=Value("Supplementary report - action required"),
+                ),
                 default=F("status"),
                 output_field=CharField(),
             ),

bc_obps/compliance/service/supplementary_version_service.py

@@ -46,9 +46,9 @@ def handle(
 
 
 # Concrete strategy for:
-# - Detecting when a previous CRV is still under manual handling (pending), and
-# - Creating a new supplementary NO_OBLIG / earned-credits CRV
-#   with an associated manual-handling record to carry that flag forward.
+# - Detecting when a previous CRV has a manual-handling record, and
+# - Creating a new supplementary REQUIRES_MANUAL_HANDLING CRV
+#   carrying forward the handling_type/context from the previous record.
 class ManualHandler:
     @staticmethod
     def can_handle(
@@ -72,7 +72,7 @@ def handle(
         version_count: int,
     ) -> Optional[ComplianceReportVersion]:
         """
-        Create a new supplementary NO_OBLIGATION_OR_EARNED_CREDITS CRV and an
+        Create a new supplementary REQUIRES_MANUAL_HANDLING CRV and an
         associated manual-handling record when the previous CRV has a manual-handling record
 
         Assumptions:
@@ -95,7 +95,7 @@ def handle(
         compliance_report_version = ComplianceReportVersion.objects.create(
             compliance_report=compliance_report,
             report_compliance_summary=new_summary,
-            status=ComplianceReportVersion.ComplianceStatus.NO_OBLIGATION_OR_EARNED_CREDITS,
+            status=ComplianceReportVersion.ComplianceStatus.REQUIRES_MANUAL_HANDLING,
             is_supplementary=True,
             previous_version=previous_compliance_version,
         )
@@ -815,7 +815,8 @@ def _record_manual_handling(
         compliance_report_version_id: int,
     ) -> None:
         """
-        Create a related ComplianceReportVersionManualHandling record.
+        Create a related ComplianceReportVersionManualHandling record and set the
+        CRV status to REQUIRES_MANUAL_HANDLING.
         """
         crv = ComplianceReportVersion.objects.get(id=compliance_report_version_id)
 
@@ -826,6 +827,9 @@ def _record_manual_handling(
             context=ComplianceReportVersionManualHandling.Context.OBLIGATION_REFUND_POOL_CASH,
         )
 
+        crv.status = ComplianceReportVersion.ComplianceStatus.REQUIRES_MANUAL_HANDLING
+        crv.save(update_fields=['status'])
+
     @staticmethod
     def _create_earned_credits(compliance_report_version_id: int, tonnes: Decimal) -> None:
         """

bc_obps/compliance/tests/integration/test_manual_handling_supplementary.py

@@ -65,7 +65,7 @@ def test_decreased_obligation_paid_invoice_creates_manual_handling(
           → obligation fully paid AND leftover refund > 0 AND has_cash → manual handling
 
         Expected:
-        - New CRV with NO_OBLIGATION_OR_EARNED_CREDITS status
+        - New CRV with REQUIRES_MANUAL_HANDLING status
         - Previous CRV marked OBLIGATION_FULLY_MET
         - ManualHandling record created with handling_type=OBLIGATION,
           context=OBLIGATION_REFUND_POOL_CASH
@@ -102,7 +102,7 @@ def test_decreased_obligation_paid_invoice_creates_manual_handling(
             compliance_report=self.compliance_report,
             is_supplementary=True,
         )
-        assert supp_crv.status == ComplianceReportVersion.ComplianceStatus.NO_OBLIGATION_OR_EARNED_CREDITS
+        assert supp_crv.status == ComplianceReportVersion.ComplianceStatus.REQUIRES_MANUAL_HANDLING
         assert supp_crv.previous_version == self.initial_crv
 
         manual_handling = ComplianceReportVersionManualHandling.objects.get(compliance_report_version=supp_crv)

bc_obps/compliance/tests/service/test_compliance_dashboard_service.py

@@ -438,124 +438,58 @@ def test_get_compliance_report_versions_for_dashboard_sorts_and_filters(
     def test_get_compliance_report_versions_annotates_status_correctly(
         self,
     ):
-        # setup
         user_operator = make_recipe('registration.tests.utils.approved_user_operator')
 
-        # 1 - not met
-        test_data_1 = ComplianceTestHelper.build_test_data(
-            crv_status=ComplianceReportVersion.ComplianceStatus.OBLIGATION_NOT_MET
-        )
-        test_data_1.operation.operator = user_operator.operator
-        test_data_1.report.operator = user_operator.operator
-        test_data_1.operation.save()
-        test_data_1.report.save()
-
-        # # 2 - met
-        test_data_2 = ComplianceTestHelper.build_test_data(
-            crv_status=ComplianceReportVersion.ComplianceStatus.OBLIGATION_FULLY_MET
-        )
-        test_data_2.operation.operator = user_operator.operator
-        test_data_2.report.operator = user_operator.operator
-        test_data_2.operation.save()
-        test_data_2.report.save()
-
-        # # 3 - pending invoice creation
-        test_data_3 = ComplianceTestHelper.build_test_data(
-            crv_status=ComplianceReportVersion.ComplianceStatus.OBLIGATION_PENDING_INVOICE_CREATION
-        )
-        test_data_3.operation.operator = user_operator.operator
-        test_data_3.report.operator = user_operator.operator
-        test_data_3.operation.save()
-        test_data_3.report.save()
-
-        # # 4 - not requested
-        test_data_4 = ComplianceTestHelper.build_test_data(
-            crv_status=ComplianceReportVersion.ComplianceStatus.EARNED_CREDITS
-        )
-        test_data_4.operation.operator = user_operator.operator
-        test_data_4.report.operator = user_operator.operator
-        test_data_4.compliance_earned_credit.issuance_status = ComplianceEarnedCredit.IssuanceStatus.CREDITS_NOT_ISSUED
-        test_data_4.compliance_earned_credit.save()
-        test_data_4.operation.save()
-        test_data_4.report.save()
+        def build(crv_status):
+            td = ComplianceTestHelper.build_test_data(crv_status=crv_status)
+            td.operation.operator = user_operator.operator
+            td.report.operator = user_operator.operator
+            td.operation.save()
+            td.report.save()
+            return td
+
+        # Obligation statuses
+        td_not_met = build(ComplianceReportVersion.ComplianceStatus.OBLIGATION_NOT_MET)
+        td_fully_met = build(ComplianceReportVersion.ComplianceStatus.OBLIGATION_FULLY_MET)
+        td_pending_invoice = build(ComplianceReportVersion.ComplianceStatus.OBLIGATION_PENDING_INVOICE_CREATION)
+
+        # Earned credits — vary by issuance_status
+        earned_credit_cases = [
+            (ComplianceEarnedCredit.IssuanceStatus.CREDITS_NOT_ISSUED, "Earned credits - not requested"),
+            (ComplianceEarnedCredit.IssuanceStatus.ISSUANCE_REQUESTED, "Earned credits - issuance requested"),
+            (ComplianceEarnedCredit.IssuanceStatus.APPROVED, "Earned credits - approved"),
+            (ComplianceEarnedCredit.IssuanceStatus.DECLINED, "Earned credits - declined"),
+            (ComplianceEarnedCredit.IssuanceStatus.CHANGES_REQUIRED, "Earned credits - changes required"),
+        ]
+        earned_credit_data = []
+        for issuance_status, _ in earned_credit_cases:
+            td = build(ComplianceReportVersion.ComplianceStatus.EARNED_CREDITS)
+            td.compliance_earned_credit.issuance_status = issuance_status
+            td.compliance_earned_credit.save()
+            earned_credit_data.append(td)
+
+        # Earned credits — no issuance record
+        td_no_credit_record = build(ComplianceReportVersion.ComplianceStatus.EARNED_CREDITS)
+        td_no_credit_record.compliance_earned_credit.delete()
+
+        # Requires manual handling
+        td_manual = build(ComplianceReportVersion.ComplianceStatus.REQUIRES_MANUAL_HANDLING)
 
-        # # 5 - issuance requested
-        test_data_5 = ComplianceTestHelper.build_test_data(
-            crv_status=ComplianceReportVersion.ComplianceStatus.EARNED_CREDITS
-        )
-        test_data_5.operation.operator = user_operator.operator
-        test_data_5.report.operator = user_operator.operator
-        test_data_5.compliance_earned_credit.issuance_status = ComplianceEarnedCredit.IssuanceStatus.ISSUANCE_REQUESTED
-        test_data_5.compliance_earned_credit.save()
-        test_data_5.operation.save()
-        test_data_5.report.save()
-
-        # # 6 - approved
-        test_data_6 = ComplianceTestHelper.build_test_data(
-            crv_status=ComplianceReportVersion.ComplianceStatus.EARNED_CREDITS
-        )
-        test_data_6.operation.operator = user_operator.operator
-        test_data_6.report.operator = user_operator.operator
-        test_data_6.compliance_earned_credit.issuance_status = ComplianceEarnedCredit.IssuanceStatus.APPROVED
-        test_data_6.compliance_earned_credit.save()
-        test_data_6.operation.save()
-        test_data_6.report.save()
-
-        # # 7 - declined
-        test_data_7 = ComplianceTestHelper.build_test_data(
-            crv_status=ComplianceReportVersion.ComplianceStatus.EARNED_CREDITS
-        )
-        test_data_7.operation.operator = user_operator.operator
-        test_data_7.report.operator = user_operator.operator
-        test_data_7.compliance_earned_credit.issuance_status = ComplianceEarnedCredit.IssuanceStatus.DECLINED
-        test_data_7.compliance_earned_credit.save()
-        test_data_7.operation.save()
-        test_data_7.report.save()
-
-        # # 8 - changes required
-        test_data_8 = ComplianceTestHelper.build_test_data(
-            crv_status=ComplianceReportVersion.ComplianceStatus.EARNED_CREDITS
-        )
-        test_data_8.operation.operator = user_operator.operator
-        test_data_8.report.operator = user_operator.operator
-        test_data_8.compliance_earned_credit.issuance_status = ComplianceEarnedCredit.IssuanceStatus.CHANGES_REQUIRED
-        test_data_8.compliance_earned_credit.save()
-        test_data_8.operation.save()
-        test_data_8.report.save()
-
-        # # 9 - earned credits
-        test_data_9 = ComplianceTestHelper.build_test_data(
-            crv_status=ComplianceReportVersion.ComplianceStatus.EARNED_CREDITS
-        )
-        test_data_9.operation.operator = user_operator.operator
-        test_data_9.report.operator = user_operator.operator
-        test_data_9.operation.save()
-        test_data_9.report.save()
-        test_data_9.compliance_earned_credit.delete()
-
-        # checks
         result = ComplianceDashboardService.get_compliance_report_versions_for_dashboard(
             user_guid=user_operator.user_id,
             sort_field="id",
             sort_order="asc",
             filters=_NoopFilters(),
         )
 
-        assert result[0].id == test_data_1.compliance_report_version.id
-        assert result[0].display_status == "Obligation - not met"
-        assert result[1].id == test_data_2.compliance_report_version.id
-        assert result[1].display_status == "Obligation - met"
-        assert result[2].id == test_data_3.compliance_report_version.id
-        assert result[2].display_status == "Obligation - pending invoice creation"
-        assert result[3].id == test_data_4.compliance_report_version.id
-        assert result[3].display_status == "Earned credits - not requested"
-        assert result[4].id == test_data_5.compliance_report_version.id
-        assert result[4].display_status == "Earned credits - issuance requested"
-        assert result[5].id == test_data_6.compliance_report_version.id
-        assert result[5].display_status == "Earned credits - approved"
-        assert result[6].id == test_data_7.compliance_report_version.id
-        assert result[6].display_status == "Earned credits - declined"
-        assert result[7].id == test_data_8.compliance_report_version.id
-        assert result[7].display_status == "Earned credits - changes required"
-        assert result[8].id == test_data_9.compliance_report_version.id
-        assert result[8].display_status == "Earned credits"
+        expected = [
+            (td_not_met, "Obligation - not met"),
+            (td_fully_met, "Obligation - met"),
+            (td_pending_invoice, "Obligation - pending invoice creation"),
+            *zip(earned_credit_data, [status for _, status in earned_credit_cases]),
+            (td_no_credit_record, "Earned credits"),
+            (td_manual, "Supplementary report - action required"),
+        ]
+        for i, (td, expected_status) in enumerate(expected):
+            assert result[i].id == td.compliance_report_version.id
+            assert result[i].display_status == expected_status

bc_obps/compliance/tests/service/test_supplementary_version_service.py

@@ -732,7 +732,7 @@ def test_handle_creates_compliance_report_version(self):
         assert result.report_compliance_summary == new_summary
         assert result.is_supplementary is True
         assert result.previous_version == previous_crv
-        assert result.status == ComplianceReportVersion.ComplianceStatus.NO_OBLIGATION_OR_EARNED_CREDITS
+        assert result.status == ComplianceReportVersion.ComplianceStatus.REQUIRES_MANUAL_HANDLING
 
         # And a new manual-handling record carrying forward handling_type/context
         new_manual = ComplianceReportVersionManualHandling.objects.get(compliance_report_version=result)

bc_obps/compliance/tests/utils/compliance_test_helper.py

@@ -2,6 +2,7 @@
 from registration.models import Operation
 from reporting.models import ReportingYear, ReportVersion
 from compliance.models import CompliancePeriod, ComplianceReportVersion
+from compliance.models.compliance_report_version_manual_handling import ComplianceReportVersionManualHandling
 
 from model_bakery.baker import make_recipe
 
@@ -243,4 +244,17 @@ def build_test_data(
                 t.compliance_report_version.status = ComplianceReportVersion.ComplianceStatus.SUPERCEDED
                 t.compliance_report_version.save()
 
+            case ComplianceReportVersion.ComplianceStatus.REQUIRES_MANUAL_HANDLING:
+                if previous_data:
+                    t = SupplementaryComplianceTestInfrastructure(previous_data)
+                else:
+                    t = BaseComplianceTestInfrastructure(reporting_year)
+                t.compliance_report_version.status = ComplianceReportVersion.ComplianceStatus.REQUIRES_MANUAL_HANDLING
+                t.compliance_report_version.save()
+                ComplianceReportVersionManualHandling.objects.create(
+                    compliance_report_version=t.compliance_report_version,
+                    handling_type=ComplianceReportVersionManualHandling.HandlingType.OBLIGATION,
+                    context=ComplianceReportVersionManualHandling.Context.OBLIGATION_REFUND_POOL_CASH,
+                )
+
         return t

bciers/libs/utils/src/enums.ts

@@ -126,6 +126,7 @@ export enum ComplianceSummaryStatus {
   OBLIGATION_PENDING_INVOICE_CREATION = "Obligation pending invoice creation",
   EARNED_CREDITS = "Earned credits",
   NO_OBLIGATION_OR_EARNED_CREDITS = "No obligation or earned credits",
+  REQUIRES_MANUAL_HANDLING = "Requires manual handling",
 }
 
 export enum PenaltyStatus {