Merge pull request #4940 from bcgov/4759-penalty-and-faa-calculation-if-obligation-decreases-from-supp-report

4759 Add back-dating logic for decreased compliance obligations

Author: Sepehr-Sobhani

bc_obps/compliance/dataclass.py

@@ -182,13 +182,13 @@ class AdjustmentStrategy:
     Immutable, normalized contract consumed by `DecreasedObligationHandler._process_adjustment_after_commit(...)`
 
     - invoices: invoice-level adjustments to apply
-    - should_record_manual_handling: flag to create manual-handling record
+    - manual_handling_context: the manual-handling context to record, or None if manual handling is not required
     - earned_credits_tonnes: earned credits to create on the NEW CRV (tonnes)
     - should_create_earned_credits: whether to create an earned-credits record
     """
 
     invoices: List["InvoiceAdjustment"] = field(default_factory=list)
-    should_record_manual_handling: bool = False
+    manual_handling_context: Optional[str] = None
 
     earned_credits_tonnes: Decimal = Decimal("0")
     should_create_earned_credits: bool = False

bc_obps/compliance/migrations/0058_alter_compliancereportversionmanualhandling_context.py

@@ -0,0 +1,32 @@
+# Generated by Django 5.1.15 on 2026-07-14 23:49
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('compliance', '0057_V5_16_0'),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name='compliancereportversionmanualhandling',
+            name='context',
+            field=models.CharField(
+                choices=[
+                    (
+                        'obligation_refund_pool_cash',
+                        'Obligation is fully paid and the refund pool contains refundable cash.',
+                    ),
+                    ('earned_credits_previously_approved', 'Earned credits have been previously approved.'),
+                    (
+                        'credits_over_allowed_percentage',
+                        'A supplementary decrease pushed the applied compliance units over the allowed percentage.',
+                    ),
+                ],
+                db_comment='Reason for requiring manual handling',
+                max_length=100,
+            ),
+        ),
+    ]

bc_obps/compliance/models/compliance_report_version_manual_handling.py

@@ -29,6 +29,10 @@ class Context(models.TextChoices):
             "earned_credits_previously_approved",
             "Earned credits have been previously approved.",
         )
+        CREDITS_OVER_ALLOWED_PERCENTAGE = (
+            "credits_over_allowed_percentage",
+            "A supplementary decrease pushed the applied compliance units over the allowed percentage.",
+        )
 
     compliance_report_version = models.OneToOneField(
         ComplianceReportVersion,

bc_obps/compliance/service/bc_carbon_registry/apply_compliance_units_service.py

@@ -2,6 +2,7 @@
 from typing import Dict, List, Optional, Any
 from common.exceptions import UserError
 from compliance.dataclass import ComplianceUnitsPageData, BCCRUnit, TransferComplianceUnitsPayload, MixedUnit
+from compliance.models.compliance_obligation import ComplianceObligation
 from compliance.models.compliance_report_version import ComplianceReportVersion
 from compliance.service.bc_carbon_registry.account_service import BCCarbonRegistryAccountService
 from compliance.service.compliance_charge_rate_service import ComplianceChargeRateService
@@ -43,21 +44,32 @@ def _get_total_adjustments_for_report_version_by_reason(
         return total_adjustments
 
     @classmethod
-    def _calculate_apply_units_cap(cls, compliance_report_version_id: int) -> Decimal:
+    def _calculate_apply_units_cap(
+        cls, compliance_report_version_id: int, pending_supplementary_adjustment: Decimal = Decimal("0")
+    ) -> Decimal:
         """
         Retrieves the obligation for the given compliance report version ID and calculates the maximum
         allowable value for applied compliance units based on the max_credit_usage_percentage
         configured on the associated CompliancePeriod.
 
+        Args:
+            compliance_report_version_id: The ID of the compliance report version for which the credit usage cap is being checked
+            pending_supplementary_adjustment: A supplementary decrease that has not yet been posted to
+                eLicensing (signed, negative reduces the obligation). Lets callers compute the cap that
+                will apply *after* the decrease, before its adjustment row exists.
+
         Raises:
             UserError: If the obligation is missing or the fee_amount_dollars is not available.
         """
         obligation = ComplianceObligationService.get_obligation_for_report_version(compliance_report_version_id)
         if not obligation or not obligation.fee_amount_dollars:
             raise UserError("Unable to calculate unit cap: missing obligation or fee amount.")
-        total_supplementary_report_adjustments = cls._get_total_adjustments_for_report_version_by_reason(
-            compliance_report_version_id=compliance_report_version_id,
-            reason=ElicensingAdjustment.Reason.SUPPLEMENTARY_REPORT_ADJUSTMENT,
+        total_supplementary_report_adjustments = (
+            cls._get_total_adjustments_for_report_version_by_reason(
+                compliance_report_version_id=compliance_report_version_id,
+                reason=ElicensingAdjustment.Reason.SUPPLEMENTARY_REPORT_ADJUSTMENT,
+            )
+            + pending_supplementary_adjustment
         )
         crv = ComplianceReportVersion.objects.select_related('compliance_report__compliance_period').get(
             id=compliance_report_version_id
@@ -87,6 +99,37 @@ def _compute_compliance_unit_caps(cls, compliance_report_version_id: int) -> tup
 
         return compliance_unit_cap_limit, compliance_unit_cap_remaining
 
+    @classmethod
+    def is_credit_usage_over_cap(
+        cls, compliance_report_version_id: int, pending_supplementary_adjustment: Decimal = Decimal("0")
+    ) -> bool:
+        """
+        Returns True if the compliance units already applied to this report version now exceed the
+        allowed cap. This happens when a supplementary report decreases the obligation, shrinking the
+        cap (max_credit_usage_percentage of the reduced obligation) below the units already applied.
+
+        Args:
+            compliance_report_version_id: The ID of the compliance report version for which the credit usage cap is being checked
+            pending_supplementary_adjustment: A not-yet-posted supplementary decrease (signed, negative
+                reduces the obligation) to fold into the cap, so the check reflects the reduced obligation
+                before the adjustment row exists.
+
+        Raises:
+            UserError: If the obligation is missing or the fee_amount_dollars is not available.
+        """
+        obligation = ComplianceObligation.objects.filter(
+            compliance_report_version_id=compliance_report_version_id
+        ).first()
+        if not obligation or not obligation.fee_amount_dollars:
+            raise UserError("Unable to calculate unit cap: missing obligation or fee amount.")
+
+        cap_limit = cls._calculate_apply_units_cap(compliance_report_version_id, pending_supplementary_adjustment)
+        # Negative value (applications reduce the balance)
+        total_compliance_unit_adjustments = cls._get_total_adjustments_for_report_version_by_reason(
+            compliance_report_version_id=compliance_report_version_id, reason='Compliance Units Applied'
+        )
+        return (cap_limit + total_compliance_unit_adjustments) < Decimal("0")
+
     @classmethod
     def can_apply_compliance_units(cls, compliance_report_version_id: int) -> bool:
         """

bc_obps/compliance/service/compliance_adjustment_service.py

@@ -53,6 +53,7 @@ def create_adjustment_for_target_version(
         adjustment_total: Decimal,
         supplementary_compliance_report_version_id: int,
         reason: Optional[ElicensingAdjustment.Reason] = None,
+        date_adjustment_to_fee_date: bool = False,
     ) -> None:
         """
         Creates fee adjustment for a target compliance report version when triggered by a supplementary version.
@@ -62,6 +63,9 @@ def create_adjustment_for_target_version(
             adjustment_total: Total amount of the adjustment to be applied
             supplementary_compliance_report_version_id: ID of the supplementary compliance report version that triggered this adjustment
             reason: Reason for the adjustment
+            date_adjustment_to_fee_date: When True, date the adjustment to the target fee's date instead of
+                today, so a supplementary decrease applies from the start of the fee's accrual window (and
+                eLicensing accepts it, since the adjustment is never dated before the fee it adjusts).
         """
         from compliance.tasks import retryable_create_adjustment
 
@@ -71,6 +75,7 @@ def create_adjustment_for_target_version(
                 adjustment_total=adjustment_total,
                 supplementary_compliance_report_version_id=supplementary_compliance_report_version_id,
                 reason=reason,
+                date_adjustment_to_fee_date=date_adjustment_to_fee_date,
             )
         )
 
@@ -81,6 +86,7 @@ def create_adjustment(
         adjustment_total: Decimal,
         supplementary_compliance_report_version_id: int | None = None,
         reason: Optional[ElicensingAdjustment.Reason] = None,
+        date_adjustment_to_fee_date: bool = False,
     ) -> None:
         """
         Creates fee adjustment connecting with elicensing service.
@@ -90,6 +96,7 @@ def create_adjustment(
             adjustment_total: Total amount of the adjustment to be applied
             supplementary_compliance_report_version_id: ID of the supplementary compliance report version that triggered this adjustment
             reason: Reason for the adjustment
+            date_adjustment_to_fee_date: When True, date the adjustment to the fee's date instead of today.
         """
 
         # Get the compliance obligation from the compliance report version
@@ -123,7 +130,11 @@ def create_adjustment(
                 "feeObjectId": elicensing_line_item.object_id,
                 "adjustmentGUID": str(uuid.uuid4()),
                 "adjustmentTotal": float(adjustment_total),
-                "date": timezone.now().strftime("%Y-%m-%d"),
+                "date": (
+                    elicensing_line_item.fee_date.strftime("%Y-%m-%d")
+                    if date_adjustment_to_fee_date
+                    else timezone.now().strftime("%Y-%m-%d")
+                ),
                 "reason": reason,
                 "type": "Adjustment",
             }

bc_obps/compliance/service/supplementary_version_service/decreased_obligation_handler.py

@@ -88,7 +88,7 @@ def handle(
         # 3) Build a normalized strategy dict
         # The strategy object returned by the determination functions is the single contract used _process_adjustment_after_commit
         # invoices: list of InvoiceAdjustment entries, each with `version_id`, `applied`, `net_outstanding_after`, `mark_fully_met`, `should_void_invoice`.
-        # should_record_manual_handling: boolean flag.
+        # manual_handling_context: the manual-handling context to record, or None.
         # earned_credits_tonnes: earned credits to create on the NEW CRV
         # should_create_earned_credits: whether to create an earned-credits record
 
@@ -134,37 +134,43 @@ def _process_adjustment_after_commit(
         """
         Execute the "strategy" produced in handle():
 
-        For each invoice in strategy["invoices"]:
-          - Post a signed negative adjustment (reduces outstanding).
+        For each invoice in strategy.invoices:
+          - Post a signed negative adjustment (reduces outstanding), dated to the fee's date so the
+            reduction applies from the start of the fee's accrual window (works for regular and
+            supplementary obligations, and eLicensing accepts it since it is never dated before the fee).
           - If net outstanding hits zero, mark that previous CRV as FULLY_MET.
           - If fully met AND no prior CASH payments, void the invoice.
-          - If fully met AND no prior CASH payments AND credited emissions, create earned credits
 
+        Then act on the single outcome of the strategy already decided for the new supplementary CRV:
+        record manual handling (with the strategy's context) or create earned credits.
         """
-        for entry in strategy.invoices:
-            applied = entry.applied
+        for invoice in strategy.invoices:
+            applied = invoice.applied
             if applied != ZERO_DECIMAL:
                 reason = (
                     ElicensingAdjustment.Reason.SUPPLEMENTARY_REPORT_ADJUSTMENT_TO_VOID_INVOICE
-                    if entry.should_void_invoice
+                    if invoice.should_void_invoice
                     else ElicensingAdjustment.Reason.SUPPLEMENTARY_REPORT_ADJUSTMENT
                 )
                 ComplianceAdjustmentService.create_adjustment_for_target_version(
-                    target_compliance_report_version_id=entry.version_id,
+                    target_compliance_report_version_id=invoice.version_id,
                     adjustment_total=applied,
                     supplementary_compliance_report_version_id=compliance_report_version_id,
                     reason=reason,
+                    date_adjustment_to_fee_date=True,
                 )
 
-            if entry.mark_fully_met:
-                DecreasedObligationHandler._mark_previous_version_fully_met(entry.version_id)
-            if entry.should_void_invoice:
-                DecreasedObligationHandler._void_unpaid_invoices(entry.version_id)
+            if invoice.mark_fully_met:
+                DecreasedObligationHandler._mark_previous_version_fully_met(invoice.version_id)
+            if invoice.should_void_invoice:
+                DecreasedObligationHandler._void_unpaid_invoices(invoice.version_id)
 
-        if strategy.should_record_manual_handling:
-            DecreasedObligationHandler._record_manual_handling(compliance_report_version_id)
-
-        if strategy.should_create_earned_credits and strategy.earned_credits_tonnes > ZERO_DECIMAL:
+        # Act on the single outcome decided by the strategy builder.
+        if strategy.manual_handling_context:
+            DecreasedObligationHandler._record_manual_handling(
+                compliance_report_version_id, context=strategy.manual_handling_context
+            )
+        elif strategy.should_create_earned_credits and strategy.earned_credits_tonnes > ZERO_DECIMAL:
             DecreasedObligationHandler._create_earned_credits(
                 compliance_report_version_id,
                 strategy.earned_credits_tonnes,
@@ -271,18 +277,17 @@ def _build_adjustment_strategy(
             total_refund_vs_anchor, invoices, anchor_crv_id
         )
 
-        per_invoice, refund_pool = DecreasedObligationHandler._adjust_refund_to_invoices(invoices, refund_pool)
+        invoice_adjustments, refund_pool = DecreasedObligationHandler._adjust_refund_to_invoices(invoices, refund_pool)
 
         # --- Manual handling decision -------------------------------------------
         # Fully paid if no invoices OR all tracked invoices end at $0.
-        fully_paid_obligation = (len(per_invoice) == 0) or all(
-            e.net_outstanding_after == ZERO_DECIMAL for e in per_invoice
+        fully_paid_obligation = (len(invoice_adjustments) == 0) or all(
+            invoice_adjustment.net_outstanding_after == ZERO_DECIMAL for invoice_adjustment in invoice_adjustments
         )
 
         has_cash = DecreasedObligationHandler._determine_if_has_cash(
             fully_paid_obligation, refund_pool, over_corrected_tonnes, invoices, anchor_crv_id
         )
-        should_record_manual_handling = has_cash
 
         # --- Earned credits decision -------------------------------------------
         # If the decrease over-corrects past zero AND there were no cash payments,
@@ -295,9 +300,22 @@ def _build_adjustment_strategy(
             should_create_earned_credits = True
             earned_credits_tonnes = over_corrected_tonnes
 
+        # --- Manual handling decision -------------------------------------------
+        # Two situations require manual handling, differing only by the context:
+        #   - a refundable cash pool, or
+        #   - a decrease that pushed applied credits over the cap
+        # An over-correction into earned credits takes precedence over the over-cap case.
+        manual_handling_context: Optional[str] = None
+        if has_cash:
+            manual_handling_context = ComplianceReportVersionManualHandling.Context.OBLIGATION_REFUND_POOL_CASH
+        elif not should_create_earned_credits and DecreasedObligationHandler._has_credit_usage_over_cap(
+            invoice_adjustments
+        ):
+            manual_handling_context = ComplianceReportVersionManualHandling.Context.CREDITS_OVER_ALLOWED_PERCENTAGE
+
         return AdjustmentStrategy(
-            invoices=per_invoice,
-            should_record_manual_handling=should_record_manual_handling,
+            invoices=invoice_adjustments,
+            manual_handling_context=manual_handling_context,
             should_create_earned_credits=should_create_earned_credits,
             earned_credits_tonnes=earned_credits_tonnes,
         )
@@ -653,6 +671,7 @@ def _mark_previous_version_fully_met(previous_version_id: int) -> None:
     @staticmethod
     def _record_manual_handling(
         compliance_report_version_id: int,
+        context: str = ComplianceReportVersionManualHandling.Context.OBLIGATION_REFUND_POOL_CASH,
     ) -> None:
         """
         Create a related ComplianceReportVersionManualHandling record and set the
@@ -664,12 +683,31 @@ def _record_manual_handling(
         ComplianceReportVersionManualHandling.objects.create(
             compliance_report_version=crv,
             handling_type=ComplianceReportVersionManualHandling.HandlingType.OBLIGATION,
-            context=ComplianceReportVersionManualHandling.Context.OBLIGATION_REFUND_POOL_CASH,
+            context=context,
         )
 
         crv.status = ComplianceReportVersion.ComplianceStatus.REQUIRES_MANUAL_HANDLING
         crv.save(update_fields=['status'])
 
+    @staticmethod
+    def _has_credit_usage_over_cap(invoice_adjustments: List[InvoiceAdjustment]) -> bool:
+        """
+        Return True if the decrease pushes the compliance units already applied to any target obligation
+        over the allowed cap (the decrease shrinks the cap). The invoice_adjustments decrease amount is passed as
+        the pending supplementary adjustment, so the cap reflects the decrease before it is posted
+        """
+        from compliance.service.bc_carbon_registry.apply_compliance_units_service import ApplyComplianceUnitsService
+
+        return any(
+            ApplyComplianceUnitsService.is_credit_usage_over_cap(
+                invoice_adjustment.version_id,
+                pending_supplementary_adjustment=(
+                    ZERO_DECIMAL if invoice_adjustment.should_void_invoice else invoice_adjustment.applied
+                ),
+            )
+            for invoice_adjustment in invoice_adjustments
+        )
+
     @staticmethod
     def _create_earned_credits(compliance_report_version_id: int, tonnes: Decimal) -> None:
         """