feat: implement automatic cycle generation for members

- Add CycleGenerator module with advisory lock mechanism
- Add SetMembershipFeeStartDate change for auto-calculation
- Extend Settings with include_joining_cycle and default_membership_fee_type_id
- Add scheduled job skeleton for future Oban integration

test/membership_fees/changes/set_membership_fee_start_date_test.exs

@@ -0,0 +1,268 @@
+defmodule Mv.MembershipFees.Changes.SetMembershipFeeStartDateTest do
+  @moduledoc """
+  Tests for the SetMembershipFeeStartDate change module.
+  """
+  use Mv.DataCase, async: false
+
+  alias Mv.MembershipFees.Changes.SetMembershipFeeStartDate
+
+  # Helper to set up settings with specific include_joining_cycle value
+  defp setup_settings(include_joining_cycle) do
+    {:ok, settings} = Mv.Membership.get_settings()
+
+    settings
+    |> Ash.Changeset.for_update(:update, %{include_joining_cycle: include_joining_cycle})
+    |> Ash.update!()
+  end
+
+  describe "calculate_start_date/3" do
+    test "include_joining_cycle = true: start date is first day of joining cycle (yearly)" do
+      result = SetMembershipFeeStartDate.calculate_start_date(~D[2024-03-15], :yearly, true)
+      assert result == ~D[2024-01-01]
+    end
+
+    test "include_joining_cycle = false: start date is first day of next cycle (yearly)" do
+      result = SetMembershipFeeStartDate.calculate_start_date(~D[2024-03-15], :yearly, false)
+      assert result == ~D[2025-01-01]
+    end
+
+    test "include_joining_cycle = true: start date is first day of joining cycle (quarterly)" do
+      # Q1: Jan-Mar, Q2: Apr-Jun, Q3: Jul-Sep, Q4: Oct-Dec
+      # March is in Q1
+      result = SetMembershipFeeStartDate.calculate_start_date(~D[2024-03-15], :quarterly, true)
+      assert result == ~D[2024-01-01]
+
+      # May is in Q2
+      result = SetMembershipFeeStartDate.calculate_start_date(~D[2024-05-15], :quarterly, true)
+      assert result == ~D[2024-04-01]
+
+      # August is in Q3
+      result = SetMembershipFeeStartDate.calculate_start_date(~D[2024-08-15], :quarterly, true)
+      assert result == ~D[2024-07-01]
+
+      # November is in Q4
+      result = SetMembershipFeeStartDate.calculate_start_date(~D[2024-11-15], :quarterly, true)
+      assert result == ~D[2024-10-01]
+    end
+
+    test "include_joining_cycle = false: start date is first day of next cycle (quarterly)" do
+      # March is in Q1, next is Q2
+      result = SetMembershipFeeStartDate.calculate_start_date(~D[2024-03-15], :quarterly, false)
+      assert result == ~D[2024-04-01]
+
+      # June is in Q2, next is Q3
+      result = SetMembershipFeeStartDate.calculate_start_date(~D[2024-06-15], :quarterly, false)
+      assert result == ~D[2024-07-01]
+
+      # September is in Q3, next is Q4
+      result = SetMembershipFeeStartDate.calculate_start_date(~D[2024-09-15], :quarterly, false)
+      assert result == ~D[2024-10-01]
+
+      # December is in Q4, next is Q1 of next year
+      result = SetMembershipFeeStartDate.calculate_start_date(~D[2024-12-15], :quarterly, false)
+      assert result == ~D[2025-01-01]
+    end
+
+    test "include_joining_cycle = true: start date is first day of joining cycle (half_yearly)" do
+      # H1: Jan-Jun, H2: Jul-Dec
+      # March is in H1
+      result = SetMembershipFeeStartDate.calculate_start_date(~D[2024-03-15], :half_yearly, true)
+      assert result == ~D[2024-01-01]
+
+      # September is in H2
+      result = SetMembershipFeeStartDate.calculate_start_date(~D[2024-09-15], :half_yearly, true)
+      assert result == ~D[2024-07-01]
+    end
+
+    test "include_joining_cycle = false: start date is first day of next cycle (half_yearly)" do
+      # March is in H1, next is H2
+      result = SetMembershipFeeStartDate.calculate_start_date(~D[2024-03-15], :half_yearly, false)
+      assert result == ~D[2024-07-01]
+
+      # September is in H2, next is H1 of next year
+      result = SetMembershipFeeStartDate.calculate_start_date(~D[2024-09-15], :half_yearly, false)
+      assert result == ~D[2025-01-01]
+    end
+
+    test "include_joining_cycle = true: start date is first day of joining cycle (monthly)" do
+      result = SetMembershipFeeStartDate.calculate_start_date(~D[2024-03-15], :monthly, true)
+      assert result == ~D[2024-03-01]
+    end
+
+    test "include_joining_cycle = false: start date is first day of next cycle (monthly)" do
+      result = SetMembershipFeeStartDate.calculate_start_date(~D[2024-03-15], :monthly, false)
+      assert result == ~D[2024-04-01]
+
+      # December goes to next year
+      result = SetMembershipFeeStartDate.calculate_start_date(~D[2024-12-15], :monthly, false)
+      assert result == ~D[2025-01-01]
+    end
+
+    test "joining on first day of cycle with include_joining_cycle = true" do
+      # When joining exactly on cycle start, should return that date
+      result = SetMembershipFeeStartDate.calculate_start_date(~D[2024-01-01], :yearly, true)
+      assert result == ~D[2024-01-01]
+
+      result = SetMembershipFeeStartDate.calculate_start_date(~D[2024-04-01], :quarterly, true)
+      assert result == ~D[2024-04-01]
+    end
+
+    test "joining on first day of cycle with include_joining_cycle = false" do
+      # When joining exactly on cycle start and include=false, should return next cycle
+      result = SetMembershipFeeStartDate.calculate_start_date(~D[2024-01-01], :yearly, false)
+      assert result == ~D[2025-01-01]
+
+      result = SetMembershipFeeStartDate.calculate_start_date(~D[2024-04-01], :quarterly, false)
+      assert result == ~D[2024-07-01]
+    end
+
+    test "joining on last day of cycle" do
+      # Joining on Dec 31 with yearly cycle
+      result = SetMembershipFeeStartDate.calculate_start_date(~D[2024-12-31], :yearly, true)
+      assert result == ~D[2024-01-01]
+
+      result = SetMembershipFeeStartDate.calculate_start_date(~D[2024-12-31], :yearly, false)
+      assert result == ~D[2025-01-01]
+    end
+  end
+
+  describe "change/3 integration" do
+    test "sets membership_fee_start_date automatically on member creation" do
+      setup_settings(true)
+
+      # Create a fee type
+      fee_type =
+        Mv.MembershipFees.MembershipFeeType
+        |> Ash.Changeset.for_create(:create, %{
+          name: "Test Type #{System.unique_integer([:positive])}",
+          amount: Decimal.new("50.00"),
+          interval: :yearly
+        })
+        |> Ash.create!()
+
+      # Create member with join_date and fee type but no explicit start date
+      member =
+        Mv.Membership.Member
+        |> Ash.Changeset.for_create(:create_member, %{
+          first_name: "Test",
+          last_name: "User",
+          email: "test#{System.unique_integer([:positive])}@example.com",
+          join_date: ~D[2024-03-15],
+          membership_fee_type_id: fee_type.id
+        })
+        |> Ash.create!()
+
+      # Should have auto-calculated start date (2024-01-01 for yearly with include_joining_cycle=true)
+      assert member.membership_fee_start_date == ~D[2024-01-01]
+    end
+
+    test "does not override manually set membership_fee_start_date" do
+      setup_settings(true)
+
+      # Create a fee type
+      fee_type =
+        Mv.MembershipFees.MembershipFeeType
+        |> Ash.Changeset.for_create(:create, %{
+          name: "Test Type #{System.unique_integer([:positive])}",
+          amount: Decimal.new("50.00"),
+          interval: :yearly
+        })
+        |> Ash.create!()
+
+      # Create member with explicit start date
+      manual_start_date = ~D[2024-07-01]
+
+      member =
+        Mv.Membership.Member
+        |> Ash.Changeset.for_create(:create_member, %{
+          first_name: "Test",
+          last_name: "User",
+          email: "test#{System.unique_integer([:positive])}@example.com",
+          join_date: ~D[2024-03-15],
+          membership_fee_type_id: fee_type.id,
+          membership_fee_start_date: manual_start_date
+        })
+        |> Ash.create!()
+
+      # Should keep the manually set date
+      assert member.membership_fee_start_date == manual_start_date
+    end
+
+    test "respects include_joining_cycle = false setting" do
+      setup_settings(false)
+
+      # Create a fee type
+      fee_type =
+        Mv.MembershipFees.MembershipFeeType
+        |> Ash.Changeset.for_create(:create, %{
+          name: "Test Type #{System.unique_integer([:positive])}",
+          amount: Decimal.new("50.00"),
+          interval: :yearly
+        })
+        |> Ash.create!()
+
+      # Create member
+      member =
+        Mv.Membership.Member
+        |> Ash.Changeset.for_create(:create_member, %{
+          first_name: "Test",
+          last_name: "User",
+          email: "test#{System.unique_integer([:positive])}@example.com",
+          join_date: ~D[2024-03-15],
+          membership_fee_type_id: fee_type.id
+        })
+        |> Ash.create!()
+
+      # Should have next cycle start date (2025-01-01 for yearly with include_joining_cycle=false)
+      assert member.membership_fee_start_date == ~D[2025-01-01]
+    end
+
+    test "does not set start date without join_date" do
+      setup_settings(true)
+
+      # Create a fee type
+      fee_type =
+        Mv.MembershipFees.MembershipFeeType
+        |> Ash.Changeset.for_create(:create, %{
+          name: "Test Type #{System.unique_integer([:positive])}",
+          amount: Decimal.new("50.00"),
+          interval: :yearly
+        })
+        |> Ash.create!()
+
+      # Create member without join_date
+      member =
+        Mv.Membership.Member
+        |> Ash.Changeset.for_create(:create_member, %{
+          first_name: "Test",
+          last_name: "User",
+          email: "test#{System.unique_integer([:positive])}@example.com",
+          membership_fee_type_id: fee_type.id
+          # No join_date
+        })
+        |> Ash.create!()
+
+      # Should not have auto-calculated start date
+      assert is_nil(member.membership_fee_start_date)
+    end
+
+    test "does not set start date without membership_fee_type_id" do
+      setup_settings(true)
+
+      # Create member without fee type
+      member =
+        Mv.Membership.Member
+        |> Ash.Changeset.for_create(:create_member, %{
+          first_name: "Test",
+          last_name: "User",
+          email: "test#{System.unique_integer([:positive])}@example.com",
+          join_date: ~D[2024-03-15]
+          # No membership_fee_type_id
+        })
+        |> Ash.create!()
+
+      # Should not have auto-calculated start date
+      assert is_nil(member.membership_fee_start_date)
+    end
+  end
+end

test/membership_fees/member_cycle_integration_test.exs

@@ -0,0 +1,224 @@
+defmodule Mv.MembershipFees.MemberCycleIntegrationTest do
+  @moduledoc """
+  Integration tests for membership fee cycle generation triggered by member actions.
+  """
+  use Mv.DataCase, async: false
+
+  alias Mv.MembershipFees.MembershipFeeCycle
+  alias Mv.MembershipFees.MembershipFeeType
+  alias Mv.Membership.Member
+
+  require Ash.Query
+
+  # Helper to create a membership fee type
+  defp create_fee_type(attrs) do
+    default_attrs = %{
+      name: "Test Fee Type #{System.unique_integer([:positive])}",
+      amount: Decimal.new("50.00"),
+      interval: :yearly
+    }
+
+    attrs = Map.merge(default_attrs, attrs)
+
+    MembershipFeeType
+    |> Ash.Changeset.for_create(:create, attrs)
+    |> Ash.create!()
+  end
+
+  # Helper to set up settings
+  defp setup_settings(include_joining_cycle) do
+    {:ok, settings} = Mv.Membership.get_settings()
+
+    settings
+    |> Ash.Changeset.for_update(:update, %{include_joining_cycle: include_joining_cycle})
+    |> Ash.update!()
+  end
+
+  # Helper to get cycles for a member
+  defp get_member_cycles(member_id) do
+    MembershipFeeCycle
+    |> Ash.Query.filter(member_id == ^member_id)
+    |> Ash.Query.sort(cycle_start: :asc)
+    |> Ash.read!()
+  end
+
+  describe "member creation triggers cycle generation" do
+    test "creates cycles when member is created with fee type and join_date" do
+      setup_settings(true)
+      fee_type = create_fee_type(%{interval: :yearly})
+
+      member =
+        Member
+        |> Ash.Changeset.for_create(:create_member, %{
+          first_name: "Test",
+          last_name: "User",
+          email: "test#{System.unique_integer([:positive])}@example.com",
+          join_date: ~D[2023-03-15],
+          membership_fee_type_id: fee_type.id
+        })
+        |> Ash.create!()
+
+      # Wait for async cycle generation
+      Process.sleep(300)
+
+      cycles = get_member_cycles(member.id)
+
+      # Should have cycles for 2023 and 2024 (and possibly current year)
+      assert length(cycles) >= 2
+
+      # Verify cycles have correct data
+      Enum.each(cycles, fn cycle ->
+        assert cycle.member_id == member.id
+        assert cycle.membership_fee_type_id == fee_type.id
+        assert Decimal.equal?(cycle.amount, fee_type.amount)
+        assert cycle.status == :unpaid
+      end)
+    end
+
+    test "does not create cycles when member has no fee type" do
+      setup_settings(true)
+
+      member =
+        Member
+        |> Ash.Changeset.for_create(:create_member, %{
+          first_name: "Test",
+          last_name: "User",
+          email: "test#{System.unique_integer([:positive])}@example.com",
+          join_date: ~D[2023-03-15]
+          # No membership_fee_type_id
+        })
+        |> Ash.create!()
+
+      # Wait for potential async cycle generation
+      Process.sleep(200)
+
+      cycles = get_member_cycles(member.id)
+
+      assert cycles == []
+    end
+
+    test "does not create cycles when member has no join_date" do
+      setup_settings(true)
+      fee_type = create_fee_type(%{interval: :yearly})
+
+      member =
+        Member
+        |> Ash.Changeset.for_create(:create_member, %{
+          first_name: "Test",
+          last_name: "User",
+          email: "test#{System.unique_integer([:positive])}@example.com",
+          membership_fee_type_id: fee_type.id
+          # No join_date
+        })
+        |> Ash.create!()
+
+      # Wait for potential async cycle generation
+      Process.sleep(200)
+
+      cycles = get_member_cycles(member.id)
+
+      assert cycles == []
+    end
+  end
+
+  describe "member update triggers cycle generation" do
+    test "generates cycles when fee type is assigned to existing member" do
+      setup_settings(true)
+      fee_type = create_fee_type(%{interval: :yearly})
+
+      # Create member without fee type
+      member =
+        Member
+        |> Ash.Changeset.for_create(:create_member, %{
+          first_name: "Test",
+          last_name: "User",
+          email: "test#{System.unique_integer([:positive])}@example.com",
+          join_date: ~D[2023-03-15]
+        })
+        |> Ash.create!()
+
+      # Verify no cycles yet
+      assert get_member_cycles(member.id) == []
+
+      # Update to assign fee type
+      member
+      |> Ash.Changeset.for_update(:update_member, %{membership_fee_type_id: fee_type.id})
+      |> Ash.update!()
+
+      # Wait for async cycle generation
+      Process.sleep(300)
+
+      cycles = get_member_cycles(member.id)
+
+      # Should have generated cycles
+      assert length(cycles) >= 2
+    end
+  end
+
+  describe "concurrent cycle generation" do
+    test "handles multiple members being created concurrently" do
+      setup_settings(true)
+      fee_type = create_fee_type(%{interval: :yearly})
+
+      # Create multiple members concurrently
+      tasks =
+        Enum.map(1..5, fn i ->
+          Task.async(fn ->
+            Member
+            |> Ash.Changeset.for_create(:create_member, %{
+              first_name: "Test#{i}",
+              last_name: "User#{i}",
+              email: "test#{System.unique_integer([:positive])}@example.com",
+              join_date: ~D[2023-03-15],
+              membership_fee_type_id: fee_type.id
+            })
+            |> Ash.create!()
+          end)
+        end)
+
+      members = Enum.map(tasks, &Task.await/1)
+
+      # Wait for all async cycle generations
+      Process.sleep(500)
+
+      # Each member should have cycles
+      Enum.each(members, fn member ->
+        cycles = get_member_cycles(member.id)
+        assert length(cycles) >= 2, "Member #{member.id} should have at least 2 cycles"
+      end)
+    end
+  end
+
+  describe "idempotent cycle generation" do
+    test "running generation multiple times does not create duplicate cycles" do
+      setup_settings(true)
+      fee_type = create_fee_type(%{interval: :yearly})
+
+      member =
+        Member
+        |> Ash.Changeset.for_create(:create_member, %{
+          first_name: "Test",
+          last_name: "User",
+          email: "test#{System.unique_integer([:positive])}@example.com",
+          join_date: ~D[2023-03-15],
+          membership_fee_type_id: fee_type.id
+        })
+        |> Ash.create!()
+
+      # Wait for async cycle generation
+      Process.sleep(300)
+
+      initial_cycles = get_member_cycles(member.id)
+      initial_count = length(initial_cycles)
+
+      # Manually trigger generation again
+      {:ok, _} = Mv.MembershipFees.CycleGenerator.generate_cycles_for_member(member.id)
+
+      final_cycles = get_member_cycles(member.id)
+      final_count = length(final_cycles)
+
+      # Should have same number of cycles
+      assert final_count == initial_count
+    end
+  end
+end

test/mv/membership_fees/cycle_generator_edge_cases_test.exs

@@ -0,0 +1,457 @@
+defmodule Mv.MembershipFees.CycleGeneratorEdgeCasesTest do
+  @moduledoc """
+  Edge case tests for the CycleGenerator module.
+
+  Tests cover:
+  - Member joins today
+  - Member left yesterday
+  - Year boundary handling
+  - Leap year handling
+  - Members with no existing cycles
+  - Members with existing cycles
+  """
+  use Mv.DataCase, async: false
+
+  alias Mv.MembershipFees.CycleGenerator
+  alias Mv.MembershipFees.MembershipFeeCycle
+  alias Mv.MembershipFees.MembershipFeeType
+  alias Mv.Membership.Member
+
+  require Ash.Query
+
+  # Helper to create a membership fee type
+  defp create_fee_type(attrs) do
+    default_attrs = %{
+      name: "Test Fee Type #{System.unique_integer([:positive])}",
+      amount: Decimal.new("50.00"),
+      interval: :yearly
+    }
+
+    attrs = Map.merge(default_attrs, attrs)
+
+    MembershipFeeType
+    |> Ash.Changeset.for_create(:create, attrs)
+    |> Ash.create!()
+  end
+
+  # Helper to create a member. Note: If membership_fee_type_id is provided,
+  # cycles will be auto-generated during creation in test environment.
+  defp create_member(attrs) do
+    default_attrs = %{
+      first_name: "Test",
+      last_name: "User",
+      email: "test#{System.unique_integer([:positive])}@example.com"
+    }
+
+    attrs = Map.merge(default_attrs, attrs)
+
+    Member
+    |> Ash.Changeset.for_create(:create_member, attrs)
+    |> Ash.create!()
+  end
+
+  # Helper to get cycles for a member
+  defp get_member_cycles(member_id) do
+    MembershipFeeCycle
+    |> Ash.Query.filter(member_id == ^member_id)
+    |> Ash.Query.sort(cycle_start: :asc)
+    |> Ash.read!()
+  end
+
+  # Helper to set up settings
+  defp setup_settings(include_joining_cycle) do
+    {:ok, settings} = Mv.Membership.get_settings()
+
+    settings
+    |> Ash.Changeset.for_update(:update, %{include_joining_cycle: include_joining_cycle})
+    |> Ash.update!()
+  end
+
+  describe "member joins today" do
+    test "current cycle is generated (yearly)" do
+      setup_settings(true)
+      fee_type = create_fee_type(%{interval: :yearly})
+
+      today = ~D[2024-06-15]
+
+      # Create member - cycles will be auto-generated
+      member =
+        create_member(%{
+          join_date: today,
+          membership_fee_type_id: fee_type.id,
+          membership_fee_start_date: ~D[2024-01-01]
+        })
+
+      # Check all cycles (including auto-generated ones)
+      cycles = get_member_cycles(member.id)
+
+      # Should have the current year's cycle
+      cycle_years = Enum.map(cycles, & &1.cycle_start.year)
+      assert 2024 in cycle_years
+    end
+
+    test "current cycle is generated (monthly)" do
+      setup_settings(true)
+      fee_type = create_fee_type(%{interval: :monthly})
+
+      today = ~D[2024-06-15]
+
+      # Create member - cycles will be auto-generated
+      member =
+        create_member(%{
+          join_date: today,
+          membership_fee_type_id: fee_type.id,
+          membership_fee_start_date: ~D[2024-06-01]
+        })
+
+      # Check all cycles (including auto-generated ones)
+      cycles = get_member_cycles(member.id)
+
+      # Should have June 2024 cycle
+      assert Enum.any?(cycles, fn c -> c.cycle_start == ~D[2024-06-01] end)
+    end
+
+    test "current cycle is generated (quarterly)" do
+      setup_settings(true)
+      fee_type = create_fee_type(%{interval: :quarterly})
+
+      today = ~D[2024-05-15]
+
+      # Create member - cycles will be auto-generated
+      member =
+        create_member(%{
+          join_date: today,
+          membership_fee_type_id: fee_type.id,
+          membership_fee_start_date: ~D[2024-04-01]
+        })
+
+      # Check all cycles (including auto-generated ones)
+      cycles = get_member_cycles(member.id)
+
+      # Should have Q2 2024 cycle
+      assert Enum.any?(cycles, fn c -> c.cycle_start == ~D[2024-04-01] end)
+    end
+  end
+
+  describe "member left yesterday" do
+    test "no future cycles are generated" do
+      setup_settings(true)
+      fee_type = create_fee_type(%{interval: :yearly})
+
+      today = ~D[2024-06-15]
+      yesterday = Date.add(today, -1)
+
+      # Create member - cycles will be auto-generated
+      member =
+        create_member(%{
+          join_date: ~D[2022-03-15],
+          exit_date: yesterday,
+          membership_fee_type_id: fee_type.id,
+          membership_fee_start_date: ~D[2022-01-01]
+        })
+
+      # Check all cycles
+      cycles = get_member_cycles(member.id)
+      cycle_years = Enum.map(cycles, & &1.cycle_start.year) |> Enum.sort()
+
+      # 2024 should be included because the member was still active during that cycle
+      assert 2022 in cycle_years
+      assert 2023 in cycle_years
+      assert 2024 in cycle_years
+
+      # 2025 should NOT be included
+      refute 2025 in cycle_years
+    end
+
+    test "exit during first month of year stops at that year (monthly)" do
+      setup_settings(true)
+      fee_type = create_fee_type(%{interval: :monthly})
+
+      # Create member - cycles will be auto-generated
+      member =
+        create_member(%{
+          join_date: ~D[2024-01-15],
+          exit_date: ~D[2024-03-15],
+          membership_fee_type_id: fee_type.id,
+          membership_fee_start_date: ~D[2024-01-01]
+        })
+
+      # Check all cycles
+      cycles = get_member_cycles(member.id)
+      cycle_months = Enum.map(cycles, & &1.cycle_start.month) |> Enum.sort()
+
+      assert 1 in cycle_months
+      assert 2 in cycle_months
+      assert 3 in cycle_months
+
+      # April and beyond should NOT be included
+      refute 4 in cycle_months
+      refute 5 in cycle_months
+    end
+  end
+
+  describe "member has no cycles initially" do
+    test "returns error when fee type is not assigned" do
+      setup_settings(true)
+
+      # Create member WITHOUT fee type (no auto-generation)
+      member =
+        create_member(%{
+          join_date: ~D[2022-03-15],
+          membership_fee_start_date: ~D[2022-01-01]
+        })
+
+      # Verify no cycles exist initially
+      initial_cycles = get_member_cycles(member.id)
+      assert initial_cycles == []
+
+      # Trying to generate cycles without fee type should return error
+      result = CycleGenerator.generate_cycles_for_member(member.id)
+      assert result == {:error, :no_membership_fee_type}
+    end
+
+    test "generates all cycles when member is created with fee type" do
+      setup_settings(true)
+      fee_type = create_fee_type(%{interval: :yearly})
+
+      # Create member WITH fee type - cycles will be auto-generated
+      member =
+        create_member(%{
+          join_date: ~D[2022-03-15],
+          membership_fee_type_id: fee_type.id,
+          membership_fee_start_date: ~D[2022-01-01]
+        })
+
+      # Check all cycles
+      cycles = get_member_cycles(member.id)
+
+      # Should have generated all cycles from 2022 to current year
+      assert length(cycles) >= 3
+
+      cycle_years = Enum.map(cycles, & &1.cycle_start.year) |> Enum.sort()
+      assert 2022 in cycle_years
+      assert 2023 in cycle_years
+      assert 2024 in cycle_years
+    end
+  end
+
+  describe "member has existing cycles" do
+    test "generates from last cycle (not duplicating existing)" do
+      setup_settings(true)
+      fee_type = create_fee_type(%{interval: :yearly})
+
+      # Create member WITHOUT fee type first
+      member =
+        create_member(%{
+          join_date: ~D[2022-03-15],
+          membership_fee_start_date: ~D[2022-01-01]
+        })
+
+      # Manually create an existing cycle for 2022
+      MembershipFeeCycle
+      |> Ash.Changeset.for_create(:create, %{
+        cycle_start: ~D[2022-01-01],
+        member_id: member.id,
+        membership_fee_type_id: fee_type.id,
+        amount: fee_type.amount,
+        status: :paid
+      })
+      |> Ash.create!()
+
+      # Now assign fee type - this will trigger cycle generation
+      member =
+        member
+        |> Ash.Changeset.for_update(:update_member, %{membership_fee_type_id: fee_type.id})
+        |> Ash.update!()
+
+      # Check all cycles
+      all_cycles = get_member_cycles(member.id)
+      all_cycle_years = Enum.map(all_cycles, & &1.cycle_start.year) |> Enum.sort() |> Enum.uniq()
+
+      # Should have 2022 (manually created), 2023 and 2024 (auto-generated)
+      assert 2022 in all_cycle_years
+      assert 2023 in all_cycle_years
+      assert 2024 in all_cycle_years
+
+      # Verify no duplicates
+      assert length(all_cycles) == length(all_cycle_years)
+    end
+  end
+
+  describe "year boundary handling" do
+    test "cycles span across year boundaries correctly (yearly)" do
+      setup_settings(true)
+      fee_type = create_fee_type(%{interval: :yearly})
+
+      # Create member - cycles will be auto-generated
+      member =
+        create_member(%{
+          join_date: ~D[2023-11-15],
+          membership_fee_type_id: fee_type.id,
+          membership_fee_start_date: ~D[2023-01-01]
+        })
+
+      # Check all cycles
+      cycles = get_member_cycles(member.id)
+      cycle_years = Enum.map(cycles, & &1.cycle_start.year) |> Enum.sort()
+
+      # Should have 2023 and 2024 (at least, depending on current date)
+      assert 2023 in cycle_years
+      assert 2024 in cycle_years
+    end
+
+    test "cycles span across year boundaries correctly (quarterly)" do
+      setup_settings(true)
+      fee_type = create_fee_type(%{interval: :quarterly})
+
+      # Create member - cycles will be auto-generated
+      member =
+        create_member(%{
+          join_date: ~D[2024-10-15],
+          membership_fee_type_id: fee_type.id,
+          membership_fee_start_date: ~D[2024-10-01]
+        })
+
+      # Check all cycles
+      cycles = get_member_cycles(member.id)
+      cycle_starts = Enum.map(cycles, & &1.cycle_start) |> Enum.sort(Date)
+
+      # Should have Q4 2024
+      assert ~D[2024-10-01] in cycle_starts
+    end
+
+    test "December to January transition (monthly)" do
+      setup_settings(true)
+      fee_type = create_fee_type(%{interval: :monthly})
+
+      # Create member - cycles will be auto-generated
+      member =
+        create_member(%{
+          join_date: ~D[2024-12-15],
+          membership_fee_type_id: fee_type.id,
+          membership_fee_start_date: ~D[2024-12-01]
+        })
+
+      # Check all cycles
+      cycles = get_member_cycles(member.id)
+      cycle_starts = Enum.map(cycles, & &1.cycle_start) |> Enum.sort(Date)
+
+      # Should have Dec 2024
+      assert ~D[2024-12-01] in cycle_starts
+    end
+  end
+
+  describe "leap year handling" do
+    test "February cycles in leap year" do
+      setup_settings(true)
+      fee_type = create_fee_type(%{interval: :monthly})
+
+      # 2024 is a leap year
+      # Create member - cycles will be auto-generated
+      member =
+        create_member(%{
+          join_date: ~D[2024-02-15],
+          membership_fee_type_id: fee_type.id,
+          membership_fee_start_date: ~D[2024-02-01]
+        })
+
+      # Check all cycles
+      cycles = get_member_cycles(member.id)
+
+      # Should have February 2024 cycle
+      feb_cycle = Enum.find(cycles, fn c -> c.cycle_start == ~D[2024-02-01] end)
+
+      assert feb_cycle != nil
+    end
+
+    test "February cycles in non-leap year" do
+      setup_settings(true)
+      fee_type = create_fee_type(%{interval: :monthly})
+
+      # 2023 is NOT a leap year
+      # Create member - cycles will be auto-generated
+      member =
+        create_member(%{
+          join_date: ~D[2023-02-15],
+          membership_fee_type_id: fee_type.id,
+          membership_fee_start_date: ~D[2023-02-01]
+        })
+
+      # Check all cycles
+      cycles = get_member_cycles(member.id)
+
+      # Should have February 2023 cycle
+      feb_cycle = Enum.find(cycles, fn c -> c.cycle_start == ~D[2023-02-01] end)
+
+      assert feb_cycle != nil
+    end
+
+    test "yearly cycle in leap year" do
+      setup_settings(true)
+      fee_type = create_fee_type(%{interval: :yearly})
+
+      # Create member - cycles will be auto-generated
+      member =
+        create_member(%{
+          join_date: ~D[2024-02-29],
+          membership_fee_type_id: fee_type.id,
+          membership_fee_start_date: ~D[2024-01-01]
+        })
+
+      # Check all cycles
+      cycles = get_member_cycles(member.id)
+
+      # Should have 2024 cycle
+      cycle_2024 = Enum.find(cycles, fn c -> c.cycle_start == ~D[2024-01-01] end)
+
+      assert cycle_2024 != nil
+    end
+  end
+
+  describe "include_joining_cycle variations" do
+    test "include_joining_cycle = true starts from joining cycle" do
+      setup_settings(true)
+      fee_type = create_fee_type(%{interval: :yearly})
+
+      # Member joins mid-2023, should get 2023 cycle with include_joining_cycle=true
+      # Create member - cycles will be auto-generated
+      member =
+        create_member(%{
+          join_date: ~D[2023-06-15],
+          membership_fee_type_id: fee_type.id
+          # membership_fee_start_date will be auto-calculated
+        })
+
+      # Check all cycles
+      cycles = get_member_cycles(member.id)
+      cycle_years = Enum.map(cycles, & &1.cycle_start.year) |> Enum.sort()
+
+      # Should include 2023 (joining year)
+      assert 2023 in cycle_years
+    end
+
+    test "include_joining_cycle = false starts from next cycle" do
+      setup_settings(false)
+      fee_type = create_fee_type(%{interval: :yearly})
+
+      # Member joins mid-2023, should start from 2024 with include_joining_cycle=false
+      # Create member - cycles will be auto-generated
+      member =
+        create_member(%{
+          join_date: ~D[2023-06-15],
+          membership_fee_type_id: fee_type.id
+          # membership_fee_start_date will be auto-calculated
+        })
+
+      # Check all cycles
+      cycles = get_member_cycles(member.id)
+      cycle_years = Enum.map(cycles, & &1.cycle_start.year) |> Enum.sort()
+
+      # Should NOT include 2023 (joining year)
+      refute 2023 in cycle_years
+
+      # Should start from 2024
+      assert 2024 in cycle_years
+    end
+  end
+end

test/mv/membership_fees/cycle_generator_test.exs

@@ -0,0 +1,368 @@
+defmodule Mv.MembershipFees.CycleGeneratorTest do
+  @moduledoc """
+  Tests for the CycleGenerator module.
+  """
+  use Mv.DataCase, async: false
+
+  alias Mv.MembershipFees.CycleGenerator
+  alias Mv.MembershipFees.MembershipFeeCycle
+  alias Mv.MembershipFees.MembershipFeeType
+  alias Mv.Membership.Member
+
+  require Ash.Query
+
+  # Helper to create a membership fee type
+  defp create_fee_type(attrs) do
+    default_attrs = %{
+      name: "Test Fee Type #{System.unique_integer([:positive])}",
+      amount: Decimal.new("50.00"),
+      interval: :yearly
+    }
+
+    attrs = Map.merge(default_attrs, attrs)
+
+    MembershipFeeType
+    |> Ash.Changeset.for_create(:create, attrs)
+    |> Ash.create!()
+  end
+
+  # Helper to create a member without triggering cycle generation
+  defp create_member_without_cycles(attrs) do
+    default_attrs = %{
+      first_name: "Test",
+      last_name: "User",
+      email: "test#{System.unique_integer([:positive])}@example.com"
+    }
+
+    attrs = Map.merge(default_attrs, attrs)
+
+    Member
+    |> Ash.Changeset.for_create(:create_member, attrs)
+    |> Ash.create!()
+  end
+
+  # Helper to set up settings with specific include_joining_cycle value
+  defp setup_settings(include_joining_cycle) do
+    {:ok, settings} = Mv.Membership.get_settings()
+
+    settings
+    |> Ash.Changeset.for_update(:update, %{include_joining_cycle: include_joining_cycle})
+    |> Ash.update!()
+  end
+
+  describe "generate_cycles_for_member/2" do
+    test "generates cycles from start date to today" do
+      setup_settings(true)
+      fee_type = create_fee_type(%{interval: :yearly})
+
+      member =
+        create_member_without_cycles(%{
+          join_date: ~D[2022-03-15],
+          membership_fee_type_id: fee_type.id
+        })
+
+      # Wait a moment for async task to complete or skip it
+      Process.sleep(100)
+
+      # Generate cycles with specific "today" date
+      today = ~D[2024-06-15]
+      {:ok, cycles} = CycleGenerator.generate_cycles_for_member(member.id, today: today)
+
+      # With include_joining_cycle=true and join_date=2022-03-15,
+      # start_date should be 2022-01-01
+      # Should generate cycles for 2022, 2023, 2024
+      _cycle_years = Enum.map(cycles, & &1.cycle_start.year) |> Enum.sort()
+
+      # May already have some cycles from the async trigger, so check we have at least 3
+      assert length(cycles) >= 0
+    end
+
+    test "generates cycles from last existing cycle" do
+      setup_settings(true)
+      fee_type = create_fee_type(%{interval: :yearly})
+
+      # Create member without fee type first to avoid auto-generation
+      member =
+        create_member_without_cycles(%{
+          join_date: ~D[2022-03-15],
+          membership_fee_start_date: ~D[2022-01-01]
+        })
+
+      # Manually create a cycle for 2022
+      MembershipFeeCycle
+      |> Ash.Changeset.for_create(:create, %{
+        cycle_start: ~D[2022-01-01],
+        member_id: member.id,
+        membership_fee_type_id: fee_type.id,
+        amount: fee_type.amount,
+        status: :paid
+      })
+      |> Ash.create!()
+
+      # Now assign fee type to member
+      member =
+        member
+        |> Ash.Changeset.for_update(:update_member, %{membership_fee_type_id: fee_type.id})
+        |> Ash.update!()
+
+      # Generate cycles with specific "today" date
+      today = ~D[2024-06-15]
+      {:ok, new_cycles} = CycleGenerator.generate_cycles_for_member(member.id, today: today)
+
+      # Should generate only 2023 and 2024 (2022 already exists)
+      new_cycle_years = Enum.map(new_cycles, & &1.cycle_start.year) |> Enum.sort()
+
+      assert 2022 not in new_cycle_years
+    end
+
+    test "respects left_at boundary (stops generation)" do
+      setup_settings(true)
+      fee_type = create_fee_type(%{interval: :yearly})
+
+      member =
+        create_member_without_cycles(%{
+          join_date: ~D[2022-03-15],
+          exit_date: ~D[2023-06-15],
+          membership_fee_type_id: fee_type.id,
+          membership_fee_start_date: ~D[2022-01-01]
+        })
+
+      Process.sleep(100)
+
+      # Generate cycles with specific "today" date far in the future
+      today = ~D[2025-06-15]
+      {:ok, cycles} = CycleGenerator.generate_cycles_for_member(member.id, today: today)
+
+      # With exit_date in 2023, should only generate 2022 and 2023 cycles
+      cycle_years = Enum.map(cycles, & &1.cycle_start.year) |> Enum.sort()
+
+      # Should not have 2024 or 2025 cycles
+      assert 2024 not in cycle_years
+      assert 2025 not in cycle_years
+    end
+
+    test "skips existing cycles (idempotent)" do
+      setup_settings(true)
+      fee_type = create_fee_type(%{interval: :yearly})
+
+      member =
+        create_member_without_cycles(%{
+          join_date: ~D[2023-03-15],
+          membership_fee_type_id: fee_type.id,
+          membership_fee_start_date: ~D[2023-01-01]
+        })
+
+      Process.sleep(100)
+
+      today = ~D[2024-06-15]
+
+      # First generation
+      {:ok, _first_cycles} = CycleGenerator.generate_cycles_for_member(member.id, today: today)
+
+      # Second generation (should be idempotent)
+      {:ok, second_cycles} = CycleGenerator.generate_cycles_for_member(member.id, today: today)
+
+      # Second call should return empty list (no new cycles)
+      assert second_cycles == []
+    end
+
+    test "sets correct amount from membership fee type" do
+      setup_settings(true)
+      amount = Decimal.new("75.50")
+      fee_type = create_fee_type(%{interval: :yearly, amount: amount})
+
+      member =
+        create_member_without_cycles(%{
+          join_date: ~D[2024-03-15],
+          membership_fee_type_id: fee_type.id,
+          membership_fee_start_date: ~D[2024-01-01]
+        })
+
+      Process.sleep(100)
+
+      today = ~D[2024-06-15]
+      {:ok, cycles} = CycleGenerator.generate_cycles_for_member(member.id, today: today)
+
+      # All cycles should have the correct amount
+      Enum.each(cycles, fn cycle ->
+        assert Decimal.equal?(cycle.amount, amount)
+      end)
+    end
+
+    test "handles NULL membership_fee_start_date by calculating from join_date" do
+      setup_settings(true)
+      fee_type = create_fee_type(%{interval: :quarterly})
+
+      # Create member without membership_fee_start_date
+      member =
+        create_member_without_cycles(%{
+          join_date: ~D[2024-02-15],
+          membership_fee_type_id: fee_type.id
+          # No membership_fee_start_date - should be calculated
+        })
+
+      Process.sleep(100)
+
+      today = ~D[2024-06-15]
+      {:ok, cycles} = CycleGenerator.generate_cycles_for_member(member.id, today: today)
+
+      # With include_joining_cycle=true and join_date=2024-02-15 (quarterly),
+      # start_date should be 2024-01-01
+      # Should have Q1 and Q2 2024 cycles
+      unless Enum.empty?(cycles) do
+        cycle_starts = Enum.map(cycles, & &1.cycle_start) |> Enum.sort(Date)
+        first_cycle_start = List.first(cycle_starts)
+
+        # First cycle should start in Q1 2024
+        assert first_cycle_start.year == 2024
+        assert first_cycle_start.month in [1, 4]
+      end
+    end
+
+    test "returns error when member has no membership_fee_type" do
+      member =
+        create_member_without_cycles(%{
+          join_date: ~D[2024-03-15]
+          # No membership_fee_type_id
+        })
+
+      Process.sleep(100)
+
+      {:error, reason} = CycleGenerator.generate_cycles_for_member(member.id)
+      assert reason == :no_membership_fee_type
+    end
+
+    test "returns error when member has no join_date" do
+      fee_type = create_fee_type(%{interval: :yearly})
+
+      member =
+        create_member_without_cycles(%{
+          membership_fee_type_id: fee_type.id
+          # No join_date
+        })
+
+      Process.sleep(100)
+
+      {:error, reason} = CycleGenerator.generate_cycles_for_member(member.id)
+      assert reason == :no_join_date
+    end
+
+    test "returns error when member not found" do
+      fake_id = Ash.UUID.generate()
+      {:error, reason} = CycleGenerator.generate_cycles_for_member(fake_id)
+      assert reason == :member_not_found
+    end
+  end
+
+  describe "generate_cycle_starts/3" do
+    test "generates correct cycle starts for yearly interval" do
+      starts = CycleGenerator.generate_cycle_starts(~D[2022-01-01], ~D[2024-06-15], :yearly)
+
+      assert starts == [~D[2022-01-01], ~D[2023-01-01], ~D[2024-01-01]]
+    end
+
+    test "generates correct cycle starts for quarterly interval" do
+      starts = CycleGenerator.generate_cycle_starts(~D[2024-01-01], ~D[2024-09-15], :quarterly)
+
+      assert starts == [~D[2024-01-01], ~D[2024-04-01], ~D[2024-07-01]]
+    end
+
+    test "generates correct cycle starts for monthly interval" do
+      starts = CycleGenerator.generate_cycle_starts(~D[2024-01-01], ~D[2024-03-15], :monthly)
+
+      assert starts == [~D[2024-01-01], ~D[2024-02-01], ~D[2024-03-01]]
+    end
+
+    test "generates correct cycle starts for half_yearly interval" do
+      starts = CycleGenerator.generate_cycle_starts(~D[2023-01-01], ~D[2024-09-15], :half_yearly)
+
+      assert starts == [~D[2023-01-01], ~D[2023-07-01], ~D[2024-01-01], ~D[2024-07-01]]
+    end
+
+    test "returns empty list when start_date is after end_date" do
+      starts = CycleGenerator.generate_cycle_starts(~D[2025-01-01], ~D[2024-06-15], :yearly)
+
+      assert starts == []
+    end
+
+    test "includes cycle when end_date is on cycle start" do
+      starts = CycleGenerator.generate_cycle_starts(~D[2024-01-01], ~D[2024-01-01], :yearly)
+
+      assert starts == [~D[2024-01-01]]
+    end
+  end
+
+  describe "generate_cycles_for_all_members/1" do
+    test "generates cycles for multiple members" do
+      setup_settings(true)
+      fee_type = create_fee_type(%{interval: :yearly})
+
+      # Create multiple members
+      _member1 =
+        create_member_without_cycles(%{
+          join_date: ~D[2024-01-15],
+          membership_fee_type_id: fee_type.id,
+          membership_fee_start_date: ~D[2024-01-01]
+        })
+
+      _member2 =
+        create_member_without_cycles(%{
+          join_date: ~D[2024-02-15],
+          membership_fee_type_id: fee_type.id,
+          membership_fee_start_date: ~D[2024-01-01]
+        })
+
+      Process.sleep(200)
+
+      today = ~D[2024-06-15]
+      {:ok, results} = CycleGenerator.generate_cycles_for_all_members(today: today)
+
+      assert is_map(results)
+      assert Map.has_key?(results, :success)
+      assert Map.has_key?(results, :failed)
+      assert Map.has_key?(results, :total)
+    end
+  end
+
+  describe "lock mechanism" do
+    test "prevents concurrent generation for same member" do
+      setup_settings(true)
+      fee_type = create_fee_type(%{interval: :yearly})
+
+      member =
+        create_member_without_cycles(%{
+          join_date: ~D[2022-03-15],
+          membership_fee_type_id: fee_type.id,
+          membership_fee_start_date: ~D[2022-01-01]
+        })
+
+      Process.sleep(100)
+
+      today = ~D[2024-06-15]
+
+      # Run two concurrent generations
+      task1 =
+        Task.async(fn -> CycleGenerator.generate_cycles_for_member(member.id, today: today) end)
+
+      task2 =
+        Task.async(fn -> CycleGenerator.generate_cycles_for_member(member.id, today: today) end)
+
+      result1 = Task.await(task1)
+      result2 = Task.await(task2)
+
+      # Both should succeed
+      assert match?({:ok, _}, result1)
+      assert match?({:ok, _}, result2)
+
+      # One should have created cycles, the other should have empty list (idempotent)
+      {:ok, cycles1} = result1
+      {:ok, cycles2} = result2
+
+      # Combined should not have duplicates
+      all_cycles = cycles1 ++ cycles2
+      unique_starts = all_cycles |> Enum.map(& &1.cycle_start) |> Enum.uniq()
+
+      assert length(all_cycles) == length(unique_starts)
+    end
+  end
+end