Add periodic engagements and statutory due dates

app/modules/services/client_services.py

@@ -24,6 +24,48 @@ SUBSCRIPTION_STATUSES = [
 ASSIGNMENT_ROLE_NAMES = ("Partner", "Branch Manager", "Staff")
 
 
+MONTHLY_PERIODS = (
+    (4, "Apr"), (5, "May"), (6, "Jun"), (7, "Jul"), (8, "Aug"), (9, "Sep"),
+    (10, "Oct"), (11, "Nov"), (12, "Dec"), (1, "Jan"), (2, "Feb"), (3, "Mar"),
+)
+QUARTERLY_PERIODS = ("Q1", "Q2", "Q3", "Q4")
+
+
+def normalized_recurrence_type(value: str | None) -> str:
+    return (value or "").strip().lower().replace("-", "_").replace(" ", "_")
+
+
+def recurrence_requires_period(value: str | None) -> bool:
+    return normalized_recurrence_type(value) in {"monthly", "quarterly"}
+
+
+def period_choices_for_service(financial_year: str | None, recurrence_type: str | None) -> list[tuple[str, str]]:
+    recurrence = normalized_recurrence_type(recurrence_type)
+    fy = normalize_financial_year(financial_year)
+    start_year = int(fy.split("-", 1)[0])
+    end_year = start_year + 1
+    if recurrence == "monthly":
+        result = []
+        for month, label in MONTHLY_PERIODS:
+            year = start_year if month >= 4 else end_year
+            result.append((f"{year:04d}-{month:02d}", f"{label} {year}"))
+        return result
+    if recurrence == "quarterly":
+        return [(value, f"{value} {fy}") for value in QUARTERLY_PERIODS]
+    return [("", "Not applicable")]
+
+
+def normalize_period_label(value: str | None, *, financial_year: str | None, recurrence_type: str | None) -> str:
+    recurrence = normalized_recurrence_type(recurrence_type)
+    raw = (value or "").strip()
+    if not recurrence_requires_period(recurrence):
+        return ""
+    valid = {code for code, _ in period_choices_for_service(financial_year, recurrence)}
+    if raw not in valid:
+        raise ValueError("A valid month or quarter is required for this recurring service.")
+    return raw
+
+
 def current_financial_year(today: date | None = None) -> str:
     today = today or date.today()
     if today.month >= 4:
@@ -139,6 +181,7 @@ def get_existing_subscription(
     client_id: int,
     service_catalogue_id: int,
     financial_year: str | None = None,
+    period_label: str | None = None,
 ) -> ClientServiceSubscription | None:
     return db.execute(
         select(ClientServiceSubscription).where(
@@ -146,6 +189,7 @@ def get_existing_subscription(
             ClientServiceSubscription.client_id == client_id,
             ClientServiceSubscription.service_catalogue_id == service_catalogue_id,
             ClientServiceSubscription.financial_year == normalize_financial_year(financial_year),
+            ClientServiceSubscription.period_label == (period_label or "").strip(),
         )
     ).scalar_one_or_none()