decidim-stratified_sortitions 0.0.1

data/README.md

@@ -0,0 +1,91 @@
+# Decidim::StratifiedSortitions
+
+## Usage
+
+Simply include it in your Decidim instance.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'decidim-stratified_sortitions'
+```
+
+And then execute:
+
+```bash
+bundle
+```
+
+### System Dependencies
+
+This module uses the COIN-OR CBC solver for the LEXIMIN fair selection algorithm. You need to install CBC on your system:
+
+**Ubuntu/Debian:**
+```bash
+sudo apt install coinor-cbc coinor-libcbc-dev
+```
+
+**macOS (Homebrew):**
+```bash
+brew install cbc
+```
+
+**Fedora/RHEL:**
+```bash
+sudo dnf install coin-or-Cbc coin-or-Cbc-devel
+```
+
+### Import migrations
+
+After installing the gem you must import and execute the migrations bundled with the gem:
+
+```bash
+bundle exec rails decidim_stratified_sortitions:install:migrations
+bundle exec rails db:migrate
+```
+
+## Usage
+
+Decidim::StratifiedSortitions allows fair sortitions in two ways.
+
+1. Generate all the panels and extract the samples at once.
+2. Execute the sortition in two phases
+
+See `Decidim::StratifiedSortitions::FairSortitionService` for more details on how to each workflow works.
+
+## Running tests
+
+Create a dummy app in your application (if not present):
+
+```bash
+bundle exec rake test_app
+cd spec/decidim_dummy_app/
+bundle exec rails decidim_stratified_sortitions:install:migrations
+RAILS_ENV=test bundle exec rails db:migrate
+```
+
+And run tests:
+
+```bash
+# Run all tests
+bundle exec rspec spec
+
+# Run only performance tests
+bundle exec rspec --tag performance
+
+# Run all tests except performance (default)
+bundle exec rspec --tag ~performance
+
+# Run also slow tests
+bundle exec rspec --tag performance --tag slow
+```
+
+## Contributing
+
+See [Decidim](https://github.com/decidim/decidim).
+
+## License
+
+See [Decidim](https://github.com/decidim/decidim).

data/Rakefile

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "decidim/dev/common_rake"
+
+def install_module(path)
+  Dir.chdir(path) do
+    system("bundle exec rake decidim_stratified_sortitions:install:migrations")
+    system("bundle exec rake db:migrate")
+  end
+end
+
+def seed_db(path)
+  Dir.chdir(path) do
+    system("bundle exec rake db:seed")
+  end
+end
+
+desc "Generates a dummy app for testing"
+task test_app: "decidim:generate_external_test_app" do
+  ENV["RAILS_ENV"] = "test"
+  install_module("spec/decidim_dummy_app")
+end
+
+# rubocop disable:Rails/RakeEnvironment
+desc "Generates a development app."
+task development_app: :environment do
+  Bundler.with_original_env do
+    generate_decidim_app(
+      "development_app",
+      "--app_name",
+      "#{base_app_name}_development_app",
+      "--path",
+      "..",
+      "--recreate_db",
+      "--demo"
+    )
+  end
+
+  install_module("development_app")
+  seed_db("development_app")
+end
+# rubocop enable:Rails/RakeEnvironment

data/app/cells/decidim/stratified_sortitions/stratified_sortition_cell.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "cell/partial"
+
+module Decidim
+  module StratifiedSortitions
+    # This cell renders the card for an instance of a StratifiedSortition
+    # the default size is the Large Card (:l)
+    class StratifiedSortitionCell < Decidim::ViewModel
+      def show
+        cell card_size, model, @options
+      end
+
+      private
+
+      def card_size
+        "decidim/stratified_sortitions/stratified_sortition_l"
+      end
+    end
+  end
+end

data/app/cells/decidim/stratified_sortitions/stratified_sortition_l_cell.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "cell/partial"
+
+module Decidim
+  module StratifiedSortitions
+    # This cell renders a stratified sortition with its L-size card.
+    class StratifiedSortitionLCell < Decidim::CardLCell
+      include Decidim::StratifiedSortitions::Engine.routes.url_helpers
+
+      private
+
+      def has_state?
+        true
+      end
+
+      def metadata_cell
+        "decidim/stratified_sortitions/stratified_sortition_metadata"
+      end
+    end
+  end
+end

data/app/cells/decidim/stratified_sortitions/stratified_sortition_metadata_cell.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Decidim
+  module StratifiedSortitions
+    # This cell renders the stratified sortition metadata for l card
+    class StratifiedSortitionMetadataCell < Decidim::CardMetadataCell
+      include Decidim::StratifiedSortitions::ApplicationHelper
+
+      def initialize(*)
+        super
+
+        @items.prepend(*stratified_sortition_items)
+      end
+
+      def stratified_sortition_items
+        [candidates_item, status_item]
+      end
+
+      def candidates_item
+        {
+          text: data_with_text(model.num_candidates.to_s, t("decidim.stratified_sortitions.stratified_sortitions.stratified_sortition.num_candidates")),
+          icon: "group-line",
+        }
+      end
+
+      def status_item
+        {
+          text: content_tag(:span, class: "label #{status_classes}") { status_name },
+        }
+      end
+
+      def strata_item
+        {
+          text: data_with_text(model.strata.count.to_s, t("decidim.stratified_sortitions.stratified_sortitions.stratified_sortition.strata_count")),
+          icon: "bar-chart-box-line",
+        }
+      end
+
+      def has_badge?
+        false
+      end
+
+      def status_name
+        t(model.status, scope: "decidim.stratified_sortitions.stratified_sortitions.show.statuses", default: model.status)
+      end
+
+      def data_with_text(data, text)
+        "#{content_tag(:strong) { data }}#{content_tag(:span) { text }}".html_safe
+      end
+
+      def status_classes
+        case model.status
+        when "executed"
+          "success"
+        when "pending"
+          "warning"
+        else
+          "muted"
+        end
+      end
+    end
+  end
+end

data/app/commands/decidim/stratified_sortitions/admin/create_stratified_sortition.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Decidim
+  module StratifiedSortitions
+    module Admin
+      # Command that creates a stratified sortition
+      class CreateStratifiedSortition < Decidim::Command
+        # Public: Initializes the command.
+        #
+        # form - A form object with the params.
+        def initialize(form)
+          super()
+          @form = form
+        end
+
+        # Executes the command. Broadcasts these events:
+        #
+        # - :ok when everything is valid.
+        # - :invalid if the form was not valid and we could not proceed.
+        #
+        # Returns nothing.
+        def call
+          return broadcast(:invalid) if form.invalid?
+
+          transaction do
+            create_stratified_sortition!
+            create_strata(stratified_sortition)
+          end
+
+          broadcast(:ok, stratified_sortition)
+        end
+
+        private
+
+        attr_reader :form, :stratified_sortition
+
+        def create_stratified_sortition!
+          parsed_title = Decidim::ContentProcessor.parse_with_processor(:hashtag, form.title, current_organization: form.current_organization).rewrite
+          parsed_description = Decidim::ContentProcessor.parse_with_processor(:hashtag, form.description, current_organization: form.current_organization).rewrite
+          parsed_selection_criteria = Decidim::ContentProcessor.parse_with_processor(:hashtag, form.selection_criteria, current_organization: form.current_organization).rewrite
+          parsed_selected_profiles_description = Decidim::ContentProcessor.parse_with_processor(:hashtag, form.selected_profiles_description,
+                                                                                                current_organization: form.current_organization).rewrite
+          params = {
+            title: parsed_title,
+            description: parsed_description,
+            selection_criteria: parsed_selection_criteria,
+            selected_profiles_description: parsed_selected_profiles_description,
+            component: form.current_component,
+            num_candidates: form.num_candidates,
+          }
+
+          @stratified_sortition = Decidim.traceability.create!(
+            Decidim::StratifiedSortitions::StratifiedSortition,
+            form.current_user,
+            params,
+            visibility: "all"
+          )
+        end
+
+        def create_strata(stratified_sortition)
+          form.strata_to_persist.each do |stratum_form|
+            stratum = Decidim::StratifiedSortitions::Stratum.create!(
+              stratified_sortition:,
+              name: stratum_form.name,
+              kind: stratum_form.kind,
+              position: stratum_form.position
+            )
+
+            stratum_form.substrata_to_persist.each do |substratum_form|
+              Decidim::StratifiedSortitions::Substratum.create!(
+                stratum:,
+                name: substratum_form.name,
+                value: substratum_form.value,
+                range: substratum_form.range,
+                max_quota_percentage: substratum_form.max_quota_percentage,
+                position: substratum_form.position
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/commands/decidim/stratified_sortitions/admin/destroy_stratified_sortition.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Decidim
+  module StratifiedSortitions
+    module Admin
+      # This command deals with destroying a StratifiedSortition from the admin panel.
+      class DestroyStratifiedSortition < Decidim::Command
+        # Public: Initializes the command.
+        #
+        # page - The StratifiedSortition to be destroyed.
+        def initialize(stratified_sortition, current_user)
+          super()
+          @stratified_sortition = stratified_sortition
+          @current_user = current_user
+        end
+
+        # Public: Executes the command.
+        #
+        # Broadcasts :ok if it got destroyed
+        # Broadcasts :has_problems if not destroyed 'cause dependent
+        # Broadcasts :invalid if it not destroyed
+        def call
+          destroy_stratified_sortition
+          broadcast(:ok)
+        rescue ActiveRecord::DeleteRestrictionError
+          broadcast(:has_problems)
+        rescue ActiveRecord::RecordNotDestroyed
+          broadcast(:invalid)
+        end
+
+        private
+
+        attr_reader :stratified_sortition, :current_user
+
+        def destroy_stratified_sortition
+          transaction do
+            Decidim.traceability.perform_action!(
+              "delete",
+              stratified_sortition,
+              current_user
+            ) do
+              stratified_sortition.destroy!
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/commands/decidim/stratified_sortitions/admin/duplicate_stratified_sortition.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Decidim
+  module StratifiedSortitions
+    module Admin
+      # A command with all the business logic when a user duplicates a stratified sortition.
+      class DuplicateStratifiedSortition < Decidim::Command
+        include ::Decidim::AttachmentAttributesMethods
+
+        # Public: Initializes the command.
+        #
+        # stratified_sortition - the stratified sortition to update.
+        # current_user - the user performing the duplication.
+        def initialize(stratified_sortition, current_user)
+          super()
+          @stratified_sortition = stratified_sortition
+          @current_user = current_user
+        end
+
+        # Executes the command. Broadcasts these events:
+        #
+        # - :ok when everything is valid, together with the duplicated_stratified_sortition.
+        #
+        # Returns nothing.
+        def call
+          transaction do
+            duplicate_stratified_sortition
+          end
+
+          broadcast(:ok)
+        end
+
+        private
+
+        attr_reader :stratified_sortition, :current_user
+
+        def duplicate_stratified_sortition
+          @stratified_sortition = Decidim.traceability.perform_action!(
+            :duplicate,
+            stratified_sortition,
+            current_user,
+          ) do
+            @duplicated_stratified_sortition = stratified_sortition.dup
+            @duplicated_stratified_sortition.status = :pending
+            if @duplicated_stratified_sortition.save!
+              duplicate_strata
+              @duplicated_stratified_sortition
+            else
+              broadcast(:invalid)
+            end
+          end
+        end
+
+        def duplicate_strata
+          stratified_sortition.strata.order(:position).each do |stratum|
+            new_stratum = stratum.dup
+            new_stratum.decidim_stratified_sortition_id = @duplicated_stratified_sortition.id
+            new_stratum.save!
+
+            duplicate_substrata(stratum, new_stratum)
+          end
+        end
+
+        def duplicate_substrata(stratum, new_stratum)
+          stratum.substrata.order(:position).each do |substratum|
+            new_substratum = substratum.dup
+            new_substratum.decidim_stratified_sortitions_stratum_id = new_stratum.id
+            new_substratum.save!
+          end
+        end
+      end
+    end
+  end
+end

data/app/commands/decidim/stratified_sortitions/admin/import_sample.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Decidim
+  module StratifiedSortitions
+    module Admin
+      # Command that import samples of a stratified sortition
+      class ImportSample < Decidim::Command
+        # Public: Initializes the command.
+        #
+        # form - A SampleUploadForm with the file blob
+        # stratified_sortition - The stratified sortition to import samples to
+        # user - The user performing the import
+        def initialize(form, stratified_sortition, user)
+          super()
+          @form = form
+          @stratified_sortition = stratified_sortition
+          @user = user
+        end
+
+        # Executes the command. Broadcasts these events:
+        #
+        # - :ok when everything is valid.
+        # - :invalid if the form was not valid and we could not proceed.
+        #
+        # Returns nothing.
+        def call
+          return broadcast(:invalid) unless @form.valid?
+
+          blob = @form.file
+          file_content = blob.download
+          filename = blob.filename.to_s
+
+          Decidim::StratifiedSortitions::Admin::ImportSampleJob
+            .perform_later(file_content, filename, @stratified_sortition, @user)
+          broadcast(:ok)
+        end
+      end
+    end
+  end
+end

data/app/commands/decidim/stratified_sortitions/admin/remove_uploaded_samples.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Decidim
+  module StratifiedSortitions
+    module Admin
+      # Command that removes uploaded samples of a stratified sortition
+      class RemoveUploadedSamples < Decidim::Command
+        # Public: Initializes the command.
+        #
+        # stratified_sortition - The stratified sortition to import samples to
+        # user - The user performing the import
+        def initialize(stratified_sortition)
+          super()
+          @stratified_sortition = stratified_sortition
+        end
+
+        # Executes the command. Broadcasts these events:
+        #
+        # - :ok when everything is valid.
+        # - :invalid if the form was not valid and we could not proceed.
+        #
+        # Returns nothing.
+        def call
+          remove_participants
+          remove_samples
+          broadcast(:ok)
+        rescue StandardError
+          broadcast(:invalid)
+        end
+
+        private
+
+        def remove_participants
+          participant_scope = Decidim::StratifiedSortitions::SampleParticipant.where(
+            decidim_stratified_sortition: @stratified_sortition
+          )
+
+          Decidim::StratifiedSortitions::SampleParticipantStratum.where(
+            decidim_stratified_sortitions_sample_participant_id: participant_scope.select(:id)
+          ).delete_all
+
+          participant_scope.delete_all
+        end
+
+        def remove_samples
+          Decidim::StratifiedSortitions::SampleImport.where(
+            stratified_sortition: @stratified_sortition
+          ).delete_all
+        end
+      end
+    end
+  end
+end