feat: implement calendar-based cycle calculation functions

Add CalendarCycles module with functions for all interval types.
Includes comprehensive tests for edge cases.

lib/mv/membership_fees/calendar_cycles.ex

@@ -0,0 +1,267 @@
+defmodule Mv.MembershipFees.CalendarCycles do
+  @moduledoc """
+  Calendar-based cycle calculation functions for membership fees.
+
+  This module provides pure functions for calculating cycle boundaries
+  based on interval types (monthly, quarterly, half-yearly, yearly).
+
+  All functions are pure (no side effects) and work with Elixir's `Date` type.
+
+  ## Interval Types
+
+  - `:monthly` - Cycles from 1st to last day of each month
+  - `:quarterly` - Cycles from 1st of Jan/Apr/Jul/Oct to last day of quarter
+  - `:half_yearly` - Cycles from 1st of Jan/Jul to last day of half-year
+  - `:yearly` - Cycles from Jan 1st to Dec 31st
+
+  ## Examples
+
+      iex> date = ~D[2024-03-15]
+      iex> Mv.MembershipFees.CalendarCycles.calculate_cycle_start(date, :monthly)
+      ~D[2024-03-01]
+
+      iex> cycle_start = ~D[2024-01-01]
+      iex> Mv.MembershipFees.CalendarCycles.calculate_cycle_end(cycle_start, :yearly)
+      ~D[2024-12-31]
+
+      iex> cycle_start = ~D[2024-01-01]
+      iex> Mv.MembershipFees.CalendarCycles.next_cycle_start(cycle_start, :yearly)
+      ~D[2025-01-01]
+  """
+
+  @type interval :: :monthly | :quarterly | :half_yearly | :yearly
+
+  @doc """
+  Calculates the start date of the cycle that contains the given date.
+
+  ## Parameters
+
+    - `date` - The date for which to find the cycle start
+    - `interval` - The interval type (`:monthly`, `:quarterly`, `:half_yearly`, `:yearly`)
+    - `reference_date` - Optional reference date (defaults to `date`)
+
+  ## Returns
+
+    The start date of the cycle containing the given date.
+
+  ## Examples
+
+      iex> calculate_cycle_start(~D[2024-03-15], :monthly)
+      ~D[2024-03-01]
+
+      iex> calculate_cycle_start(~D[2024-05-15], :quarterly)
+      ~D[2024-04-01]
+
+      iex> calculate_cycle_start(~D[2024-09-15], :half_yearly)
+      ~D[2024-07-01]
+
+      iex> calculate_cycle_start(~D[2024-12-15], :yearly)
+      ~D[2024-01-01]
+  """
+  @spec calculate_cycle_start(Date.t(), interval(), Date.t() | nil) :: Date.t()
+  def calculate_cycle_start(date, interval, reference_date \\ nil) do
+    reference = reference_date || date
+
+    case interval do
+      :monthly -> monthly_cycle_start(reference)
+      :quarterly -> quarterly_cycle_start(reference)
+      :half_yearly -> half_yearly_cycle_start(reference)
+      :yearly -> yearly_cycle_start(reference)
+    end
+  end
+
+  @doc """
+  Calculates the end date of a cycle based on its start date and interval.
+
+  ## Parameters
+
+    - `cycle_start` - The start date of the cycle
+    - `interval` - The interval type
+
+  ## Returns
+
+    The end date of the cycle.
+
+  ## Examples
+
+      iex> calculate_cycle_end(~D[2024-03-01], :monthly)
+      ~D[2024-03-31]
+
+      iex> calculate_cycle_end(~D[2024-02-01], :monthly)
+      ~D[2024-02-29]
+
+      iex> calculate_cycle_end(~D[2024-01-01], :quarterly)
+      ~D[2024-03-31]
+
+      iex> calculate_cycle_end(~D[2024-01-01], :half_yearly)
+      ~D[2024-06-30]
+
+      iex> calculate_cycle_end(~D[2024-01-01], :yearly)
+      ~D[2024-12-31]
+  """
+  @spec calculate_cycle_end(Date.t(), interval()) :: Date.t()
+  def calculate_cycle_end(cycle_start, interval) do
+    case interval do
+      :monthly -> monthly_cycle_end(cycle_start)
+      :quarterly -> quarterly_cycle_end(cycle_start)
+      :half_yearly -> half_yearly_cycle_end(cycle_start)
+      :yearly -> yearly_cycle_end(cycle_start)
+    end
+  end
+
+  @doc """
+  Calculates the start date of the next cycle.
+
+  ## Parameters
+
+    - `cycle_start` - The start date of the current cycle
+    - `interval` - The interval type
+
+  ## Returns
+
+    The start date of the next cycle.
+
+  ## Examples
+
+      iex> next_cycle_start(~D[2024-01-01], :monthly)
+      ~D[2024-02-01]
+
+      iex> next_cycle_start(~D[2024-01-01], :quarterly)
+      ~D[2024-04-01]
+
+      iex> next_cycle_start(~D[2024-01-01], :half_yearly)
+      ~D[2024-07-01]
+
+      iex> next_cycle_start(~D[2024-01-01], :yearly)
+      ~D[2025-01-01]
+  """
+  @spec next_cycle_start(Date.t(), interval()) :: Date.t()
+  def next_cycle_start(cycle_start, interval) do
+    cycle_end = calculate_cycle_end(cycle_start, interval)
+    next_date = Date.add(cycle_end, 1)
+    calculate_cycle_start(next_date, interval)
+  end
+
+  @doc """
+  Checks if the cycle contains today's date.
+
+  ## Parameters
+
+    - `cycle_start` - The start date of the cycle
+    - `interval` - The interval type
+
+  ## Returns
+
+    `true` if today is within the cycle, `false` otherwise.
+
+  ## Examples
+
+      # Assuming today is 2024-03-15
+      iex> current_cycle?(~D[2024-03-01], :monthly)
+      true
+
+      iex> current_cycle?(~D[2024-02-01], :monthly)
+      false
+  """
+  @spec current_cycle?(Date.t(), interval()) :: boolean()
+  def current_cycle?(cycle_start, interval) do
+    today = Date.utc_today()
+    cycle_end = calculate_cycle_end(cycle_start, interval)
+
+    Date.compare(cycle_start, today) in [:lt, :eq] and
+      Date.compare(today, cycle_end) in [:lt, :eq]
+  end
+
+  @doc """
+  Checks if the cycle was just completed (ended yesterday or earlier, but is the most recent completed cycle).
+
+  ## Parameters
+
+    - `cycle_start` - The start date of the cycle
+    - `interval` - The interval type
+
+  ## Returns
+
+    `true` if the cycle ended yesterday or earlier and is the last completed cycle, `false` otherwise.
+
+  ## Examples
+
+      # Assuming today is 2024-04-01 (cycle ended yesterday)
+      iex> last_completed_cycle?(~D[2024-03-01], :monthly)
+      true
+
+      # Assuming today is 2024-03-15 (cycle is still current)
+      iex> last_completed_cycle?(~D[2024-03-01], :monthly)
+      false
+  """
+  @spec last_completed_cycle?(Date.t(), interval()) :: boolean()
+  def last_completed_cycle?(cycle_start, interval) do
+    today = Date.utc_today()
+    cycle_end = calculate_cycle_end(cycle_start, interval)
+
+    # Cycle must have ended (yesterday or earlier)
+    case Date.compare(today, cycle_end) do
+      :gt ->
+        # Check if this is the most recent completed cycle
+        # by verifying that the next cycle hasn't ended yet
+        next_start = next_cycle_start(cycle_start, interval)
+        next_end = calculate_cycle_end(next_start, interval)
+
+        Date.compare(today, next_end) in [:lt, :eq]
+
+      _ ->
+        false
+    end
+  end
+
+  # Private helper functions
+
+  defp monthly_cycle_start(date) do
+    Date.new!(date.year, date.month, 1)
+  end
+
+  defp monthly_cycle_end(cycle_start) do
+    Date.end_of_month(cycle_start)
+  end
+
+  defp quarterly_cycle_start(date) do
+    quarter_start_month =
+      case date.month do
+        m when m in [1, 2, 3] -> 1
+        m when m in [4, 5, 6] -> 4
+        m when m in [7, 8, 9] -> 7
+        m when m in [10, 11, 12] -> 10
+      end
+
+    Date.new!(date.year, quarter_start_month, 1)
+  end
+
+  defp quarterly_cycle_end(cycle_start) do
+    case cycle_start.month do
+      1 -> Date.new!(cycle_start.year, 3, 31)
+      4 -> Date.new!(cycle_start.year, 6, 30)
+      7 -> Date.new!(cycle_start.year, 9, 30)
+      10 -> Date.new!(cycle_start.year, 12, 31)
+    end
+  end
+
+  defp half_yearly_cycle_start(date) do
+    half_start_month = if date.month in 1..6, do: 1, else: 7
+    Date.new!(date.year, half_start_month, 1)
+  end
+
+  defp half_yearly_cycle_end(cycle_start) do
+    case cycle_start.month do
+      1 -> Date.new!(cycle_start.year, 6, 30)
+      7 -> Date.new!(cycle_start.year, 12, 31)
+    end
+  end
+
+  defp yearly_cycle_start(date) do
+    Date.new!(date.year, 1, 1)
+  end
+
+  defp yearly_cycle_end(cycle_start) do
+    Date.new!(cycle_start.year, 12, 31)
+  end
+end