feat: add groups resource #371

lib/membership/changes/generate_slug.ex

@@ -1,4 +1,4 @@
-defmodule Mv.Membership.CustomField.Changes.GenerateSlug do
+defmodule Mv.Membership.Changes.GenerateSlug do
   @moduledoc """
   Ash Change that automatically generates a URL-friendly slug from the `name` attribute.
 
@@ -14,12 +14,26 @@ defmodule Mv.Membership.CustomField.Changes.GenerateSlug do
     - Trims leading/trailing hyphens
     - Truncates to max 100 characters
 
+  ## Usage
+
+  Works for any resource with `name` and `slug` attributes.
+  Used by CustomField and Group resources.
+
+      create :create do
+        accept [:name, :description]
+        change Mv.Membership.Changes.GenerateSlug
+        validate string_length(:slug, min: 1)
+      end
+
   ## Examples
 
       # Create with automatic slug generation
       CustomField.create!(%{name: "Mobile Phone"})
       # => %CustomField{name: "Mobile Phone", slug: "mobile-phone"}
 
+      Group.create!(%{name: "Test Group"})
+      # => %Group{name: "Test Group", slug: "test-group"}
+
       # German umlauts are converted
       CustomField.create!(%{name: "Café Müller"})
       # => %CustomField{name: "Café Müller", slug: "cafe-muller"}
@@ -32,7 +46,7 @@ defmodule Mv.Membership.CustomField.Changes.GenerateSlug do
   ## Implementation Note
 
   This change only runs on `:create` actions. The slug is immutable by design,
-  as changing slugs would break external references (e.g., CSV imports/exports).
+  as changing slugs would break external references (e.g., CSV imports/exports, URL routes).
   """
   use Ash.Resource.Change
 
@@ -47,11 +61,14 @@ defmodule Mv.Membership.CustomField.Changes.GenerateSlug do
   ## Parameters
 
   - `changeset` - The Ash changeset
+  - `_opts` - Options passed to the change (unused)
+  - `_context` - Ash context map (unused)
 
   ## Returns
 
   The changeset with the `:slug` attribute set to the generated slug.
   """
+  @impl true
   def change(changeset, _opts, _context) do
     # Only generate slug on create, not on update (immutability)
     if changeset.action_type == :create do
@@ -62,6 +79,9 @@ defmodule Mv.Membership.CustomField.Changes.GenerateSlug do
         name when is_binary(name) ->
           slug = generate_slug(name)
           Ash.Changeset.force_change_attribute(changeset, :slug, slug)
+
+        _ ->
+          changeset
       end
     else
       # On update, don't touch the slug (immutable)
@@ -80,6 +100,14 @@ defmodule Mv.Membership.CustomField.Changes.GenerateSlug do
   - Leading/trailing hyphens removed
   - Maximum length of 100 characters
 
+  ## Parameters
+
+  - `name` - The string to convert to a slug
+
+  ## Returns
+
+  A URL-friendly slug string, or empty string if input is invalid.
+
   ## Examples
 
       iex> generate_slug("Mobile Phone")
@@ -104,6 +132,7 @@ defmodule Mv.Membership.CustomField.Changes.GenerateSlug do
       "strasse"
 
   """
+  @spec generate_slug(String.t()) :: String.t()
   def generate_slug(name) when is_binary(name) do
     slug = Slug.slugify(name)
 

lib/membership/custom_field.ex

@@ -63,7 +63,7 @@ defmodule Mv.Membership.CustomField do
 
     create :create do
       accept [:name, :value_type, :description, :required, :show_in_overview]
-      change Mv.Membership.CustomField.Changes.GenerateSlug
+      change Mv.Membership.Changes.GenerateSlug
       validate string_length(:slug, min: 1)
     end
 

lib/membership/group.ex

@@ -0,0 +1,171 @@
+defmodule Mv.Membership.Group do
+  @moduledoc """
+  Ash resource representing a group that members can belong to.
+
+  ## Overview
+  Groups allow organizing members into categories (e.g., "Board Members", "Active Members").
+  Each member can belong to multiple groups, and each group can contain multiple members.
+
+  ## Attributes
+  - `name` - Unique group name (required, max 100 chars, case-insensitive uniqueness)
+  - `slug` - URL-friendly identifier (required, max 100 chars, auto-generated from name, immutable)
+  - `description` - Optional description (max 500 chars)
+
+  ## Relationships
+  - `has_many :member_groups` - Relationship to MemberGroup join table
+  - `many_to_many :members` - Relationship to Members through MemberGroup
+
+  ## Constraints
+  - Name must be unique (case-insensitive, using LOWER(name) in database)
+  - Slug must be unique (case-sensitive, exact match)
+  - Name cannot be null
+  - Slug cannot be null
+
+  ## Calculations
+  - `member_count` - Returns the number of members in this group
+
+  ## Examples
+      # Create a new group
+      Group.create!(%{name: "Board Members", description: "Members of the board"})
+      # => %Group{name: "Board Members", slug: "board-members", ...}
+
+      # Update group (slug remains unchanged)
+      group = Group.get_by_slug!("board-members")
+      Group.update!(group, %{description: "Updated description"})
+      # => %Group{slug: "board-members", ...}  # slug unchanged!
+  """
+  use Ash.Resource,
+    domain: Mv.Membership,
+    data_layer: AshPostgres.DataLayer
+
+  require Ash.Query
+  import Ash.Expr
+  alias Mv.Helpers
+  alias Mv.Helpers.SystemActor
+  require Logger
+
+  postgres do
+    table "groups"
+    repo Mv.Repo
+  end
+
+  actions do
+    defaults [:read, :destroy]
+
+    create :create do
+      accept [:name, :description]
+      change Mv.Membership.Changes.GenerateSlug
+      validate string_length(:slug, min: 1)
+    end
+
+    update :update do
+      accept [:name, :description]
+      require_atomic? false
+    end
+  end
+
+  validations do
+    validate present(:name)
+
+    # Case-insensitive name uniqueness validation
+    validate fn changeset, _context ->
+      name = Ash.Changeset.get_attribute(changeset, :name)
+      current_id = Ash.Changeset.get_attribute(changeset, :id)
+
+      if name do
+        check_name_uniqueness(name, current_id)
+      else
+        :ok
+      end
+    end
+  end
+
+  attributes do
+    uuid_v7_primary_key :id
+
+    attribute :name, :string do
+      allow_nil? false
+      public? true
+
+      constraints max_length: 100,
+                  trim?: true
+    end
+
+    attribute :slug, :string do
+      allow_nil? false
+      public? true
+      writable? false
+
+      constraints max_length: 100,
+                  trim?: true
+    end
+
+    attribute :description, :string do
+      allow_nil? true
+      public? true
+
+      constraints max_length: 500,
+                  trim?: true
+    end
+
+    timestamps()
+  end
+
+  relationships do
+    has_many :member_groups, Mv.Membership.MemberGroup
+    many_to_many :members, Mv.Membership.Member, through: Mv.Membership.MemberGroup
+  end
+
+  calculations do
+    calculate :member_count, :integer do
+      description "Number of members in this group"
+
+      calculation fn [group], _context ->
+        system_actor = SystemActor.get_system_actor()
+        opts = Helpers.ash_actor_opts(system_actor)
+
+        query =
+          Mv.Membership.MemberGroup
+          |> Ash.Query.filter(group_id == ^group.id)
+
+        case Ash.read(query, opts) do
+          {:ok, member_groups} -> [length(member_groups)]
+          {:error, _} -> [0]
+        end
+      end
+    end
+  end
+
+  identities do
+    identity :unique_slug, [:slug]
+  end
+
+  # Private helper function for case-insensitive name uniqueness check
+  defp check_name_uniqueness(name, exclude_id) do
+    query =
+      Mv.Membership.Group
+      |> Ash.Query.filter(fragment("LOWER(?) = LOWER(?)", name, ^name))
+      |> maybe_exclude_id(exclude_id)
+
+    system_actor = SystemActor.get_system_actor()
+    opts = Helpers.ash_actor_opts(system_actor)
+
+    case Ash.read(query, opts) do
+      {:ok, []} ->
+        :ok
+
+      {:ok, _} ->
+        {:error, field: :name, message: "has already been taken", value: name}
+
+      {:error, reason} ->
+        Logger.warning(
+          "Name uniqueness validation query failed for group name '#{name}': #{inspect(reason)}. Allowing operation to proceed (fail-open)."
+        )
+
+        :ok
+    end
+  end
+
+  defp maybe_exclude_id(query, nil), do: query
+  defp maybe_exclude_id(query, id), do: Ash.Query.filter(query, id != ^id)
+end

lib/membership/member.ex

@@ -582,6 +582,12 @@ defmodule Mv.Membership.Member do
 
     # has_many: All fee cycles for this member
     has_many :membership_fee_cycles, Mv.MembershipFees.MembershipFeeCycle
+
+    # Groups relationships
+    # has_many: All member-group associations for this member
+    has_many :member_groups, Mv.Membership.MemberGroup
+    # many_to_many: All groups this member belongs to (through MemberGroup)
+    many_to_many :groups, Mv.Membership.Group, through: Mv.Membership.MemberGroup
   end
 
   calculations do

lib/membership/member_group.ex

@@ -0,0 +1,128 @@
+defmodule Mv.Membership.MemberGroup do
+  @moduledoc """
+  Ash resource representing the join table for the many-to-many relationship
+  between Members and Groups.
+
+  ## Overview
+  MemberGroup is a join table that links members to groups. It enables the
+  many-to-many relationship where:
+  - A member can belong to multiple groups
+  - A group can contain multiple members
+
+  ## Attributes
+  - `member_id` - Foreign key to Member (required)
+  - `group_id` - Foreign key to Group (required)
+
+  ## Relationships
+  - `belongs_to :member` - Relationship to Member
+  - `belongs_to :group` - Relationship to Group
+
+  ## Constraints
+  - Unique constraint on `(member_id, group_id)` - prevents duplicate memberships
+  - CASCADE delete: Removing member removes all group associations
+  - CASCADE delete: Removing group removes all member associations
+
+  ## Examples
+      # Add member to group
+      MemberGroup.create!(%{member_id: member.id, group_id: group.id})
+
+      # Remove member from group
+      member_group = MemberGroup.get_by_member_and_group!(member.id, group.id)
+      MemberGroup.destroy!(member_group)
+  """
+  use Ash.Resource,
+    domain: Mv.Membership,
+    data_layer: AshPostgres.DataLayer
+
+  require Ash.Query
+  import Ash.Expr
+
+  postgres do
+    table "member_groups"
+    repo Mv.Repo
+  end
+
+  actions do
+    defaults [:read, :destroy]
+
+    create :create do
+      accept [:member_id, :group_id]
+    end
+  end
+
+  validations do
+    validate present(:member_id)
+    validate present(:group_id)
+
+    # Prevent duplicate associations
+    validate fn changeset, _context ->
+      member_id = Ash.Changeset.get_attribute(changeset, :member_id)
+      group_id = Ash.Changeset.get_attribute(changeset, :group_id)
+      current_id = Ash.Changeset.get_attribute(changeset, :id)
+
+      if member_id && group_id do
+        check_duplicate_association(member_id, group_id, current_id)
+      else
+        :ok
+      end
+    end
+  end
+
+  attributes do
+    uuid_v7_primary_key :id
+
+    attribute :member_id, :uuid do
+      allow_nil? false
+    end
+
+    attribute :group_id, :uuid do
+      allow_nil? false
+    end
+
+    timestamps()
+  end
+
+  relationships do
+    belongs_to :member, Mv.Membership.Member do
+      allow_nil? false
+    end
+
+    belongs_to :group, Mv.Membership.Group do
+      allow_nil? false
+    end
+  end
+
+  identities do
+    identity :unique_member_group, [:member_id, :group_id]
+  end
+
+  # Private helper function to check for duplicate associations
+  defp check_duplicate_association(member_id, group_id, exclude_id) do
+    alias Mv.Helpers
+    alias Mv.Helpers.SystemActor
+
+    query =
+      Mv.Membership.MemberGroup
+      |> Ash.Query.filter(member_id == ^member_id and group_id == ^group_id)
+      |> maybe_exclude_id(exclude_id)
+
+    system_actor = SystemActor.get_system_actor()
+    opts = Helpers.ash_actor_opts(system_actor)
+
+    case Ash.read(query, opts) do
+      {:ok, []} ->
+        :ok
+
+      {:ok, _} ->
+        {:error, field: :member_id, message: "Member is already in this group", value: member_id}
+
+      {:error, _reason} ->
+        # Fail-open: if query fails, allow operation to proceed
+        # Database constraint will catch duplicates anyway
+        :ok
+    end
+  end
+
+  defp maybe_exclude_id(query, nil), do: query
+  defp maybe_exclude_id(query, id), do: Ash.Query.filter(query, id != ^id)
+end

lib/membership/membership.ex

@@ -7,6 +7,8 @@ defmodule Mv.Membership do
   - `CustomFieldValue` - Dynamic custom field values attached to members
   - `CustomField` - Schema definitions for custom fields
   - `Setting` - Global application settings (singleton)
+  - `Group` - Groups that members can belong to
+  - `MemberGroup` - Join table for many-to-many relationship between Members and Groups
 
   ## Public API
   The domain exposes these main actions:
@@ -14,6 +16,8 @@ defmodule Mv.Membership do
   - Custom field value management: `create_custom_field_value/1`, `list_custom_field_values/0`, etc.
   - Custom field management: `create_custom_field/1`, `list_custom_fields/0`, `list_required_custom_fields/0`, etc.
   - Settings management: `get_settings/0`, `update_settings/2`, `update_member_field_visibility/2`, `update_single_member_field_visibility/3`
+  - Group management: `create_group/1`, `list_groups/0`, `update_group/2`, `destroy_group/1`
+  - Member-group associations: `create_member_group/1`, `list_member_groups/0`, `destroy_member_group/1`
 
   ## Admin Interface
   The domain is configured with AshAdmin for management UI.
@@ -61,6 +65,19 @@ defmodule Mv.Membership do
       define :update_single_member_field_visibility,
         action: :update_single_member_field_visibility
     end
+
+    resource Mv.Membership.Group do
+      define :create_group, action: :create
+      define :list_groups, action: :read
+      define :update_group, action: :update
+      define :destroy_group, action: :destroy
+    end
+
+    resource Mv.Membership.MemberGroup do
+      define :create_member_group, action: :create
+      define :list_member_groups, action: :read
+      define :destroy_member_group, action: :destroy
+    end
   end
 
   # Singleton pattern: Get the single settings record