decidim-stratified_sortitions 0.0.1

data/app/helpers/decidim/stratified_sortitions/application_helper.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Decidim
+  module StratifiedSortitions
+    # Custom helpers, scoped to the stratified_sortitions engine.
+    #
+    module ApplicationHelper
+      def component_name
+        i18n_key = "decidim.components.stratified_sortitions.name"
+        (defined?(current_component) && translated_attribute(current_component&.name).presence) || t(i18n_key)
+      end
+
+      def tabs_id_for_stratum(stratum)
+        "stratified-sortition-stratum-#{stratum.to_param}"
+      end
+
+      def tabs_id_for_substratum(substratum)
+        "stratified-sortition-stratum-substratum-#{substratum.to_param}"
+      end
+
+      # Renders the errors for a given object field in an HTML block.
+      # If there are no errors renders nothing.
+      def field_errors_block(form, field)
+        return if form.object.errors[field].blank?
+
+        html = <<~EOHTML
+          <div class="row column errors">#{form.error_for(field)}</div>
+        EOHTML
+        html.html_safe
+      end
+
+      def dynamic_title(title, **options)
+        data = {
+          "max-length" => options[:max_length],
+          "omission" => options[:omission],
+          "placeholder" => options[:placeholder],
+          "locale" => I18n.locale,
+        }
+        tag.span(class: options[:class], data:) do
+          truncate translated_attribute(title), length: options[:max_length], omission: options[:omission]
+        end
+      end
+
+      def navigation_menu_items(sortition)
+        has_sortition = sortition.present?
+
+        [
+          {
+            path: has_sortition ? edit_stratified_sortition_path(sortition) : new_stratified_sortition_path,
+            icon: "settings-4-line",
+            label: t("actions.configure", scope: "decidim.stratified_sortitions.admin"),
+            active: %w(new edit).include?(action_name),
+          },
+          {
+            path: has_sortition ? upload_sample_stratified_sortition_path(sortition) : "#",
+            icon: "group-line",
+            label: t("actions.census_management", scope: "decidim.stratified_sortitions.admin"),
+            active: action_name == "upload_sample",
+            disabled: has_sortition ? !sortition.strata_and_substrata_configured? : true,
+          },
+          {
+            path: has_sortition ? execute_stratified_sortition_path(sortition) : "#",
+            icon: "play-fill",
+            label: t("actions.execute", scope: "decidim.stratified_sortitions.admin"),
+            active: action_name == "execute",
+            disabled: has_sortition ? !sortition.can_execute? : true,
+          },
+        ]
+      end
+
+      def filter_sections_stratified_sortitions
+        sections = [{ method: :with_any_state, collection: filter_state_values, label_scope: "decidim.stratified_sortitions.stratified_sortitions.filters", id: "state" }]
+        sections.reject { |item| item[:collection].blank? }
+      end
+
+      def filter_state_values
+        [
+          ["all", t("all", scope: "decidim.stratified_sortitions.stratified_sortitions.filters")],
+          ["pending", t("pending", scope: "decidim.stratified_sortitions.stratified_sortitions.filters")],
+          ["executed", t("executed", scope: "decidim.stratified_sortitions.stratified_sortitions.filters")],
+        ]
+      end
+    end
+  end
+end

data/app/helpers/decidim/stratified_sortitions/charts_pdf_helper.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Decidim
+  module StratifiedSortitions
+    # View helpers used in the charts PDF template.
+    # Generates inline SVG pie charts and HTML legends.
+    module ChartsPdfHelper
+      CHART_COLORS = %w(
+        #3366CC #DC3912 #FF9900 #109618 #990099
+        #0099C6 #DD4477 #66AA00 #B82E2E #316395
+        #994499 #22AA99 #AAAA11 #6633CC #E67300
+        #8B0707 #651067 #329262 #5574A6 #3B3EAC
+      ).freeze
+
+      # Generates an inline SVG pie chart from a data array of [label, value] pairs.
+      def svg_pie_chart(data, size: 155)
+        return "" if data.blank?
+
+        total = data.sum { |_label, value| value.to_f }
+        return "" if total.zero?
+
+        cx = size / 2
+        cy = size / 2
+        r = (size / 2) - 4
+        paths = []
+        cumulative = 0.0
+
+        data.each_with_index do |(_label, value), idx|
+          slice = (value.to_f / total) * 360.0
+          start_angle = cumulative
+          end_angle = cumulative + slice
+          cumulative = end_angle
+
+          start_rad = (start_angle - 90) * Math::PI / 180.0
+          end_rad = (end_angle - 90) * Math::PI / 180.0
+
+          x_1 = cx + (r * Math.cos(start_rad))
+          y_1 = cy + (r * Math.sin(start_rad))
+          x_2 = cx + (r * Math.cos(end_rad))
+          y_2 = cy + (r * Math.sin(end_rad))
+
+          color = CHART_COLORS[idx % CHART_COLORS.size]
+          large_arc = slice > 180 ? 1 : 0
+
+          paths << if slice >= 359.99
+                     %(<circle cx="#{cx}" cy="#{cy}" r="#{r}" fill="#{color}" stroke="white" stroke-width="1"/>)
+                   else
+                     path_d = "M#{cx},#{cy} L#{x_1.round(2)},#{y_1.round(2)} " \
+                              "A#{r},#{r} 0 #{large_arc},1 #{x_2.round(2)},#{y_2.round(2)} Z"
+                     %(<path d="#{path_d}" fill="#{color}" stroke="white" stroke-width="1"/>)
+                   end
+        end
+
+        %(<svg width="#{size}" height="#{size}" viewBox="0 0 #{size} #{size}" xmlns="http://www.w3.org/2000/svg">#{paths.join}</svg>).html_safe
+      end
+
+      # Generates an HTML legend block for the given chart data.
+      def legend_html(data)
+        return "" if data.blank?
+
+        total = data.sum { |_label, value| value.to_f }
+
+        items = data.each_with_index.map do |(label, value), idx|
+          pct = total.positive? ? ((value.to_f / total) * 100).round(1) : 0.0
+          color = CHART_COLORS[idx % CHART_COLORS.size]
+          %(<div class="legend-item"><span class="legend-color" style="background:#{color}"></span>#{h(label)} (#{pct}%)</div>)
+        end
+
+        %(<div class="legend">#{items.join}</div>).html_safe
+      end
+    end
+  end
+end

data/app/helpers/decidim/stratified_sortitions/stratified_sortition_cells_helper.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Decidim
+  module StratifiedSortitions
+    # Custom helpers, scoped to the stratified sortitions engine.
+    #
+    module StratifiedSortitionCellsHelper
+      include Decidim::StratifiedSortitions::ApplicationHelper
+      include Decidim::StratifiedSortitions::Engine.routes.url_helpers
+      include Decidim::LayoutHelper
+      include Decidim::ApplicationHelper
+      include Decidim::TranslationsHelper
+      include Decidim::ResourceReferenceHelper
+      include Decidim::TranslatableAttributes
+      include Decidim::CardHelper
+
+      delegate :title, to: :model
+
+      def has_actions?
+        return context[:has_actions] if context[:has_actions].present?
+
+        stratified_sortitions_controller? && index_action? && current_settings.votes_enabled? && !model.draft?
+      end
+
+      def has_footer?
+        return context[:has_footer] if context[:has_footer].present?
+
+        stratified_sortitions_controller? && index_action? && current_settings.votes_enabled? && !model.draft?
+      end
+
+      def stratified_sortitions_controller?
+        context[:controller].instance_of?(::Decidim::StratifiedSortitions::StratifiedSortitionsController)
+      end
+
+      def index_action?
+        context[:controller].action_name == "index"
+      end
+
+      def current_settings
+        model.component.current_settings
+      end
+
+      def component_settings
+        model.component.settings
+      end
+
+      def current_component
+        model.component
+      end
+
+      def from_context
+        options[:from]
+      end
+    end
+  end
+end

data/app/javascript/channels/sample_import_progress.js

@@ -0,0 +1,12 @@
+import consumer from "./consumer"
+
+export default function subscribeSampleImportProgress(sampleImportId, onProgress) {
+  return consumer.subscriptions.create(
+    { channel: "SampleImportProgressChannel", sample_import_id: sampleImportId },
+    {
+      received(data) {
+        if (onProgress) onProgress(data)
+      }
+    }
+  )
+}

data/app/jobs/decidim/stratified_sortitions/admin/execute_sortition_job.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Decidim
+  module StratifiedSortitions
+    module Admin
+      class ExecuteSortitionJob < ApplicationJob
+        queue_as :stratified_sortitions
+
+        def perform(stratified_sortition, user)
+          result = FairSortitionService.new(stratified_sortition).call
+          if result.success?
+            stratified_sortition.update!(status: "executed", execution_error: nil)
+            Decidim.traceability.perform_action!("execute", stratified_sortition, user, visibility: "all")
+          else
+            stratified_sortition.update!(status: "failed", execution_error: result.error)
+          end
+        end
+      end
+    end
+  end
+end

data/app/jobs/decidim/stratified_sortitions/admin/import_sample_job.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require "csv"
+require "rubyXL"
+
+module Decidim
+  module StratifiedSortitions
+    module Admin
+      class ImportSampleJob < ApplicationJob
+        queue_as :stratified_sortitions
+
+        def perform(file_content, filename, stratified_sortition, user)
+          sample_import = Decidim::StratifiedSortitions::SampleImport.create!(
+            stratified_sortition:,
+            filename:,
+            status: :processing
+          )
+          processing_errors = []
+          total_rows = 0
+
+          each_import_row(file_content, filename) do |headers, row|
+            total_rows += 1
+
+            errors = process_row(row, headers, stratified_sortition, sample_import)
+
+            processing_errors << errors if errors.present?
+          end
+
+          status = processing_errors.flatten.empty? ? :completed : :failed
+          sample_import.update(
+            status:,
+            total_rows:,
+            imported_rows: total_rows - processing_errors.flatten.size,
+            failed_rows: processing_errors.flatten.size,
+            import_errors: processing_errors.flatten
+          )
+
+          Decidim::StratifiedSortitions::Admin::ImportMailer.import(user, sample_import).deliver_now
+        end
+
+        private
+
+        def each_import_row(file_content, filename, &)
+          if File.extname(filename.to_s).casecmp(".xlsx").zero?
+            parse_xlsx_rows(file_content, &)
+          else
+            parse_csv_rows(file_content, &)
+          end
+        end
+
+        def parse_csv_rows(file_content)
+          CSV.parse(file_content, headers: true, col_sep: ",") do |row|
+            headers = row.headers
+            values = row.fields.map { |value| normalize_value(value) }
+            next if values.all?(&:blank?)
+
+            yield(headers, values)
+          end
+        end
+
+        def parse_xlsx_rows(file_content)
+          workbook = RubyXL::Parser.parse_buffer(file_content)
+          worksheet = workbook[0]
+          rows = worksheet&.sheet_data&.rows || []
+          return if rows.empty?
+
+          headers = extract_xlsx_row_values(rows.first)
+
+          rows.drop(1).each do |xlsx_row|
+            values = extract_xlsx_row_values(xlsx_row)
+            next if values.all?(&:blank?)
+
+            yield(headers, values)
+          end
+        end
+
+        def extract_xlsx_row_values(xlsx_row)
+          return [] unless xlsx_row&.cells
+
+          last_index = xlsx_row.cells.rindex { |cell| cell&.value.present? }
+          return [] unless last_index
+
+          (0..last_index).map do |index|
+            normalize_value(xlsx_row.cells[index]&.value)
+          end
+        end
+
+        def normalize_value(value)
+          return nil if value.nil?
+
+          normalized = value.is_a?(String) ? value.strip : value.to_s.strip
+          normalized.presence
+        end
+
+        def process_row(row, headers, stratified_sortition, sample_import)
+          ActiveRecord::Base.transaction do
+            participant = Decidim::StratifiedSortitions::SampleParticipant.find_or_create_by(
+              personal_data_1: row[0]
+            )
+
+            participant.update!(
+              decidim_stratified_sortition: stratified_sortition,
+              decidim_stratified_sortitions_sample_import: sample_import,
+              personal_data_2: row[1],
+              personal_data_3: row[2],
+              personal_data_4: row[3],
+            )
+
+            # Strata is saved in the order of the strata creation
+            strata = Decidim::StratifiedSortitions::Stratum.where(stratified_sortition:).order(position: :asc)
+
+            strata_index = 4
+            strata.each do |stratum|
+              row_value = row[strata_index]
+
+              substratum = find_substratum(stratum, row_value)
+
+              raise "No valid substratum found for value '#{row_value}' in stratum '#{stratum.name}'" if substratum.nil?
+
+              Decidim::StratifiedSortitions::SampleParticipantStratum.create!(
+                decidim_stratified_sortitions_sample_participant: participant,
+                decidim_stratified_sortitions_stratum: stratum,
+                decidim_stratified_sortitions_substratum: substratum
+              )
+
+              strata_index += 1
+            end
+          end
+
+          nil
+        rescue StandardError => e
+          {
+            row: build_error_row(headers, row),
+            error: e.message,
+            backtrace: e.backtrace.first(3),
+          }
+        end
+
+        def build_error_row(headers, row)
+          return row if headers.blank?
+
+          headers.each_with_index.to_h do |header, index|
+            [header, row[index]]
+          end
+        end
+
+        def find_substratum(stratum, value)
+          if stratum.kind == "value"
+            normalized_value = normalize_value(value)
+            Decidim::StratifiedSortitions::Substratum.find_by(
+              decidim_stratified_sortitions_stratum_id: stratum.id,
+              value: normalized_value
+            )
+          elsif stratum.kind == "numeric_range"
+            numeric_value = normalize_value(value).to_f
+            stratum.substrata.find do |substratum|
+              next if substratum.range.blank?
+
+              range_parts = substratum.range.split("-")
+              min_value = range_parts[0].to_f
+              max_value = range_parts[1].to_f
+
+              numeric_value >= min_value && numeric_value <= max_value
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/jobs/decidim/stratified_sortitions/admin/remove_samples_job.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Decidim
+  module StratifiedSortitions
+    module Admin
+      class RemoveSamplesJob < ApplicationJob
+        queue_as :stratified_sortitions
+
+        def perform(stratified_sortition, user)
+          RemoveUploadedSamples.call(stratified_sortition) do
+            on(:ok) do
+              Decidim.traceability.perform_action!("remove_samples", stratified_sortition, user, visibility: "all")
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/jobs/decidim/stratified_sortitions/admin/sortition_results_export_job.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Decidim
+  module StratifiedSortitions
+    module Admin
+      # Background job that generates a sortition results export and sends it
+      # to the requesting user as a zipped email attachment.
+      # Follows the same pattern as Decidim::ExportJob in decidim-core.
+      class SortitionResultsExportJob < ApplicationJob
+        queue_as :stratified_sortitions
+
+        def perform(user, stratified_sortition, format)
+          exporter = SortitionResultsExporter.new(stratified_sortition)
+
+          export_data = case format
+                        when "excel" then exporter.export_excel
+                        when "json" then exporter.export_json
+                        else exporter.export_csv
+                        end
+
+          export_name = "sortition_results_#{stratified_sortition.id}"
+
+          Decidim::ExportMailer.export(user, export_name, export_data).deliver_now
+        end
+      end
+    end
+  end
+end

data/app/mailers/decidim/stratified_sortitions/admin/import_mailer.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Decidim
+  module StratifiedSortitions
+    module Admin
+      # This mailer sends a notification email with the results of the import process.
+      class ImportMailer < ApplicationMailer
+        # Public: Sends a notification email with the result of an import process.
+        #
+        # user          - The user to be notified.
+        # sample_import - The sample import record containing the import results.
+        #
+        # Returns nothing.
+        def import(user, sample_import)
+          @user = user
+          @organization = user.organization
+          @sample_import = sample_import
+
+          with_user(user) do
+            mail(to: "#{user.name} <#{user.email}>", subject: I18n.t("decidim.stratified_sortitions.admin.import_mailer.subject"))
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/decidim/stratified_sortitions/application_record.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Decidim
+  module StratifiedSortitions
+    class ApplicationRecord < ActiveRecord::Base
+      self.abstract_class = true
+    end
+  end
+end

data/app/models/decidim/stratified_sortitions/panel_portfolio.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module Decidim
+  module StratifiedSortitions
+    # Stores the portfolio of panels generated by the LEXIMIN algorithm.
+    #
+    # This model enables a two-phase sortition process:
+    # 1. Generate portfolio (expensive computation, stores panels and probabilities)
+    # 2. Sample from portfolio (fast, selects one panel according to distribution)
+    #
+    # The separation allows for:
+    # - Background generation of portfolios
+    # - Public/auditable sampling ceremonies
+    # - Verification of results using the stored data
+    #
+    # @example Generate and sample
+    #   portfolio = PanelPortfolio.create!(
+    #     stratified_sortition: sortition,
+    #     panels: [[1, 2, 3], [4, 5, 6]],
+    #     probabilities: [0.6, 0.4],
+    #     generated_at: Time.current
+    #   )
+    #
+    #   # Later, sample from the portfolio
+    #   portfolio.sample!(verification_seed: "public_seed")
+    #   portfolio.selected_panel # => [1, 2, 3] or [4, 5, 6]
+    #
+    class PanelPortfolio < ApplicationRecord
+      self.table_name = "decidim_stratified_sortitions_panel_portfolios"
+
+      belongs_to :stratified_sortition,
+                 class_name: "Decidim::StratifiedSortitions::StratifiedSortition",
+                 foreign_key: "decidim_stratified_sortitions_stratified_sortition_id"
+
+      validates :panels, presence: true
+      validates :probabilities, presence: true
+      validates :generated_at, presence: true
+      validate :panels_and_probabilities_match
+      validate :probabilities_sum_to_one
+
+      # Check if the portfolio has been sampled
+      #
+      # @return [Boolean]
+      def sampled?
+        selected_panel_index.present?
+      end
+
+      # Get the selected panel (after sampling)
+      #
+      # @return [Array<Integer>, nil] Array of participant IDs or nil if not sampled
+      def selected_panel
+        return nil unless sampled?
+
+        panels[selected_panel_index]
+      end
+
+      # Get the probability of the selected panel
+      #
+      # @return [Float, nil]
+      def selected_panel_probability
+        return nil unless sampled?
+
+        probabilities[selected_panel_index]
+      end
+
+      # Sample a panel from this portfolio
+      #
+      # @param verification_seed [String, nil] Optional seed for reproducible sampling
+      # @return [Leximin::PanelSampler::Result]
+      # @raise [RuntimeError] if already sampled
+      def sample!(verification_seed: nil)
+        raise I18n.t("decidim.stratified_sortitions.errors.panel_portfolio.already_sampled") if sampled?
+
+        random_seed = Decidim::StratifiedSortitions.derive_random_seed(verification_seed)
+        sampler = Leximin::PanelSampler.new(panels, probabilities, random_seed:)
+        result = sampler.sample
+
+        if result.success?
+          update!(
+            selected_panel_index: result.selected_index,
+            selected_at: Time.current,
+            verification_seed:,
+            random_value_used: result.random_value
+          )
+        end
+
+        result
+      end
+
+      # Load selected participants from database
+      #
+      # @return [Array<SampleParticipant>]
+      def selected_participants
+        return [] unless sampled?
+
+        SampleParticipant.where(id: selected_panel).order(:id).to_a
+      end
+
+      # Number of panels in the portfolio
+      #
+      # @return [Integer]
+      def num_panels
+        panels&.size || 0
+      end
+
+      # Fairness metrics for this portfolio
+      #
+      # @return [Hash]
+      def fairness_metrics
+        probs = selection_probabilities.values
+        return {} if probs.empty?
+
+        {
+          min_probability: probs.min,
+          max_probability: probs.max,
+          mean_probability: probs.sum / probs.size,
+          probability_range: probs.max - probs.min,
+        }
+      end
+
+      # Build audit log for the portfolio
+      #
+      # @return [Hash]
+      def audit_log
+        {
+          algorithm: "LEXIMIN",
+          version: "1.0",
+          stratified_sortition_id: stratified_sortition.id,
+          generated_at: generated_at&.iso8601,
+          generation_time_seconds:,
+          num_panels:,
+          num_iterations:,
+          convergence_achieved:,
+          sampled: sampled?,
+          selected_at: selected_at&.iso8601,
+          selected_panel_index:,
+          verification_seed:,
+          random_value_used:,
+          selected_panel_probability:,
+          fairness_metrics:,
+        }
+      end
+
+      private
+
+      def panels_and_probabilities_match
+        return if panels.blank? || probabilities.blank?
+        return if panels.size == probabilities.size
+
+        errors.add(:probabilities, I18n.t("decidim.stratified_sortitions.errors.panel_portfolio.probabilities_size_mismatch",
+                                          panels_count: panels.size,
+                                          probabilities_count: probabilities.size))
+      end
+
+      def probabilities_sum_to_one
+        return if probabilities.blank?
+
+        total = probabilities.sum
+        return if (total - 1.0).abs < 0.001
+
+        errors.add(:probabilities, I18n.t("decidim.stratified_sortitions.errors.panel_portfolio.probabilities_sum_invalid", total:))
+      end
+    end
+  end
+end

data/app/models/decidim/stratified_sortitions/sample_import.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Decidim
+  module StratifiedSortitions
+    class SampleImport < ApplicationRecord
+      self.table_name = "decidim_stratified_sortitions_sample_imports"
+
+      belongs_to :stratified_sortition
+      has_many :sample_participants, dependent: :destroy, foreign_key: :decidim_stratified_sortitions_sample_import_id
+
+      enum :status, { pending: "pending", processing: "processing", completed: "completed", failed: "failed" }
+    end
+  end
+end