decidim-stratified_sortitions 0.0.1

data/app/presenters/decidim/stratified_sortitions/admin_log/stratified_sortition_presenter.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Decidim
+  module StratifiedSortitions
+    module AdminLog
+      # This class holds the logic to present a `Decidim::StratifiedSortitions::StratifiedSortition`
+      # for the `AdminLog` log.
+      #
+      # Usage should be automatic and you should not need to call this class
+      # directly, but here is an example:
+      #
+      #    action_log = Decidim::ActionLog.last
+      #    view_helpers # => this comes from the views
+      #    StratifiedSortitionPresenter.new(action_log, view_helpers).present
+      class StratifiedSortitionPresenter < Decidim::Log::BasePresenter
+        private
+
+        def action_string
+          case action
+          when "create", "update", "delete", "duplicate",
+               "execute", "export_results", "view_participants",
+               "import_sample", "remove_samples"
+            "decidim.stratified_sortitions.admin_log.stratified_sortition.#{action}"
+          else
+            super
+          end
+        end
+
+        def i18n_labels_scope
+          "activemodel.attributes.stratified_sortition"
+        end
+      end
+    end
+  end
+end

data/app/queries/decidim/stratified_sortitions/filtered_stratified_sortitions.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Decidim
+  module StratifiedSortitions
+    # A class used to find stratified sortitions filtered by components and a date range
+    class FilteredStratifiedSortitions < Decidim::Query
+      # Syntactic sugar to initialize the class and return the queried objects.
+      #
+      # components - An array of Decidim::Component
+      # start_at - A date to filter resources created after it
+      # end_at - A date to filter resources created before it.
+      def self.for(components, start_at = nil, end_at = nil)
+        new(components, start_at, end_at).query
+      end
+
+      # Initializes the class.
+      #
+      # components - An array of Decidim::Component
+      # start_at - A date to filter resources created after it
+      # end_at - A date to filter resources created before it.
+      # rubocop:disable Lint/MissingSuper
+      def initialize(components, start_at = nil, end_at = nil)
+        @components = components
+        @start_at = start_at
+        @end_at = end_at
+      end
+      # rubocop:enable Lint/MissingSuper
+
+      # Finds the StratifiedSortitions scoped to an array of components and filtered
+      # by a range of dates.
+      def query
+        stratified_sortitions = Decidim::StratifiedSortitions::StratifiedSortition.where(component: @components)
+        stratified_sortitions = stratified_sortitions.where(created_at: @start_at..) if @start_at.present?
+        stratified_sortitions = stratified_sortitions.where(created_at: ..@end_at) if @end_at.present?
+        stratified_sortitions
+      end
+    end
+  end
+end

data/app/serializers/decidim/stratified_sortitions/sortition_result_serializer.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Decidim
+  module StratifiedSortitions
+    # Serializer for sortition results export.
+    # Includes sortition metadata only in the first row and participant data in each row.
+    class SortitionResultSerializer < Decidim::Exporters::Serializer
+      # Reset the metadata flag before each export run.
+      def self.reset!
+        @metadata_serialized = false
+      end
+
+      def self.metadata_serialized?
+        @metadata_serialized == true
+      end
+
+      def self.metadata_serialized!
+        @metadata_serialized = true
+      end
+
+      # @return [Hash] serialized data for one participant with sortition metadata (only first row)
+      def serialize
+        participant = resource
+        portfolio = participant.decidim_stratified_sortition.panel_portfolio
+        audit_log = portfolio.audit_log
+
+        data = if self.class.metadata_serialized?
+                 metadata_blank(audit_log)
+               else
+                 self.class.metadata_serialized!
+                 metadata_filled(audit_log)
+               end
+
+        data.merge!(participant_data(participant))
+        data
+      end
+
+      private
+
+      def metadata_filled(audit_log)
+        {
+          algorithm: audit_log[:algorithm],
+          version: audit_log[:version],
+          stratified_sortition_id: audit_log[:stratified_sortition_id],
+          generated_at: audit_log[:generated_at],
+          generation_time_seconds: audit_log[:generation_time_seconds],
+          num_panels: audit_log[:num_panels],
+          num_iterations: audit_log[:num_iterations],
+          convergence_achieved: audit_log[:convergence_achieved],
+          selected_at: audit_log[:selected_at],
+          selected_panel_index: audit_log[:selected_panel_index],
+          verification_seed: audit_log[:verification_seed],
+          random_value_used: audit_log[:random_value_used],
+          selected_panel_probability: audit_log[:selected_panel_probability],
+        }
+      end
+
+      def metadata_blank(_audit_log)
+        {
+          algorithm: nil,
+          version: nil,
+          stratified_sortition_id: nil,
+          generated_at: nil,
+          generation_time_seconds: nil,
+          num_panels: nil,
+          num_iterations: nil,
+          convergence_achieved: nil,
+          selected_at: nil,
+          selected_panel_index: nil,
+          verification_seed: nil,
+          random_value_used: nil,
+          selected_panel_probability: nil,
+        }
+      end
+
+      def participant_data(participant)
+        data = personal_data_fields(participant)
+        add_strata_columns(data, participant)
+        add_fairness_metrics(data, participant)
+        data
+      end
+
+      def personal_data_fields(participant)
+        {
+          personal_data_1: participant.personal_data_1,
+          personal_data_2: participant.personal_data_2,
+          personal_data_3: participant.personal_data_3,
+          personal_data_4: participant.personal_data_4,
+        }
+      end
+
+      def add_strata_columns(data, participant)
+        strata = participant.decidim_stratified_sortition.strata.order(:position)
+        strata.each do |stratum|
+          ps = participant.sample_participant_strata.find { |s| s.decidim_stratified_sortitions_stratum_id == stratum.id }
+          data[:"stratum_#{stratum_key(stratum)}"] = substratum_name_for(ps)
+        end
+      end
+
+      def stratum_key(stratum)
+        stratum.name.values.compact.first || stratum.id.to_s
+      end
+
+      def substratum_name_for(participant_stratum)
+        participant_stratum&.decidim_stratified_sortitions_substratum&.name&.values&.compact&.first || "-"
+      end
+
+      def add_fairness_metrics(data, participant)
+        metrics = participant.decidim_stratified_sortition.panel_portfolio.audit_log[:fairness_metrics]
+        return if metrics.blank?
+
+        metrics.each { |key, value| data[:"fairness_#{key}"] = value }
+      end
+    end
+  end
+end

data/app/services/decidim/stratified_sortitions/charts_pdf_generator.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "wicked_pdf"
+
+module Decidim
+  module StratifiedSortitions
+    # Generates a PDF with comparative pie charts for a stratified sortition.
+    # Uses WickedPdf (wkhtmltopdf) to convert an HTML template to PDF
+    class ChartsPdfGenerator
+      def initialize(stratified_sortition, strata_data, candidates_data, results_data, locale: I18n.locale)
+        @stratified_sortition = stratified_sortition
+        @strata_data = strata_data
+        @candidates_data = candidates_data
+        @results_data = results_data
+        @locale = locale
+      end
+
+      def generate
+        I18n.with_locale(@locale) do
+          html = controller.render_to_string(
+            template: "decidim/stratified_sortitions/admin/stratified_sortitions/export_charts_pdf",
+            layout: "decidim/stratified_sortitions/charts_pdf",
+            assigns: template_assigns
+          )
+
+          WickedPdf.new.pdf_from_string(html, orientation: "Portrait", page_size: "A4")
+        end
+      end
+
+      private
+
+      def template_assigns
+        {
+          title: t("pdf_title", name: translated_name(@stratified_sortition.title)),
+          subtitle: t("pdf_subtitle"),
+          belongs_to: t("pdf_belongs_to", space_name: participatory_space_name),
+          algorithm: t("pdf_algorithm", algorithm: algorithm_info),
+          executed_at: t("pdf_executed_at", date: execution_date),
+          no_data_text: t("pdf_no_data"),
+          col_target: t("target"),
+          col_candidates: t("candidates"),
+          col_results: t("results"),
+          strata_chart_data: build_strata_chart_data,
+        }
+      end
+
+      def build_strata_chart_data
+        @strata_data.each_with_index.map do |sd, idx|
+          {
+            name: translated_name(sd[:stratum].name),
+            target: sd[:chart_data],
+            candidates: @candidates_data[idx][:chart_data],
+            results: @results_data[idx][:chart_data],
+          }
+        end
+      end
+
+      def translated_name(hash)
+        return hash if hash.is_a?(String)
+
+        hash[@locale.to_s] || hash[hash.keys.first] || ""
+      end
+
+      def participatory_space_name
+        space = @stratified_sortition.participatory_space
+        translated_name(space.title)
+      rescue StandardError
+        "-"
+      end
+
+      def algorithm_info
+        portfolio = @stratified_sortition.panel_portfolio
+        return "-" unless portfolio&.sampled?
+
+        "#{portfolio.audit_log[:algorithm]} v#{portfolio.audit_log[:version]}"
+      end
+
+      def execution_date
+        portfolio = @stratified_sortition.panel_portfolio
+        return "-" unless portfolio&.sampled?
+
+        I18n.l(portfolio.selected_at, format: :decidim_short)
+      rescue StandardError
+        portfolio.selected_at.to_s
+      end
+
+      def t(key, **opts)
+        I18n.t(key, scope: "decidim.stratified_sortitions.admin.stratified_sortitions.execute", **opts)
+      end
+
+      def controller
+        @controller ||= ChartsPdfControllerHelper.new
+      end
+    end
+  end
+end

data/app/services/decidim/stratified_sortitions/fair_sortition_service.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+module Decidim
+  module StratifiedSortitions
+    # Complete Fair Sortition Service
+    #
+    # Orchestrates the full LEXIMIN-based fair sortition process:
+    # 1. Runs LEXIMIN algorithm to find optimal panel distribution
+    # 2. Samples a panel according to the fair probability distribution
+    # 3. Returns the selected participants
+    #
+    # Supports two modes:
+    # - Single-phase: Generate and sample in one call
+    # - Two-phase: Generate portfolio first, sample later (for public ceremonies)
+    #
+    # @example Basic usage (single-phase)
+    #   result = FairSortitionService.new(stratified_sortition).call
+    #   if result.success?
+    #     result.selected_participants  # Array of SampleParticipant records
+    #     result.selection_log          # Audit information
+    #   end
+    #
+    # @example Two-phase usage (for public/auditable draws)
+    #   service = FairSortitionService.new(stratified_sortition)
+    #
+    #   # Phase 1: Generate portfolio (can be done in background)
+    #   portfolio_result = service.generate_portfolio
+    #   # Publish portfolio_result.portfolio.panels for transparency
+    #
+    #   # Phase 2: Sample from portfolio (can be done publicly)
+    #   final_result = service.sample_from_portfolio(verification_seed: SecureRandom.hex(64))
+    #
+    # @example With verification seed (for auditable draws)
+    #   result = FairSortitionService.new(stratified_sortition, verification_seed: "public_seed_123").call
+    #
+    class FairSortitionService
+      # Result object containing all sortition outputs
+      Result = Struct.new(
+        :selected_participants,
+        :selected_participant_ids,
+        :selection_probabilities,
+        :portfolio,
+        :sampling_result,
+        :selection_log,
+        :success,
+        :error,
+        keyword_init: true
+      ) do
+        def success?
+          success
+        end
+      end
+
+      # Result for portfolio generation
+      PortfolioResult = Struct.new(:portfolio, :success, :error, keyword_init: true) do
+        def success?
+          success
+        end
+      end
+
+      def initialize(stratified_sortition, verification_seed: nil)
+        @stratified_sortition = stratified_sortition
+        @verification_seed = verification_seed
+      end
+
+      # Execute the complete fair sortition process (single-phase)
+      #
+      # This generates the portfolio and samples in one call.
+      # For two-phase process, use generate_portfolio and sample_from_portfolio.
+      #
+      # @return [Result] containing selected participants and audit log
+      def call
+        # Check if already sampled
+        return error_result(error: I18n.t("decidim.stratified_sortitions.errors.fair_sortition.already_performed")) if existing_portfolio&.sampled?
+
+        # Generate or retrieve portfolio
+        portfolio = find_or_generate_portfolio
+        return error_result(error: portfolio.error) unless portfolio.is_a?(PanelPortfolio)
+
+        # Sample from portfolio
+        sample_from_portfolio(verification_seed: @verification_seed)
+      end
+
+      # Generate portfolio without sampling (Phase 1 of two-phase process)
+      #
+      # Creates a PanelPortfolio with all candidate panels and their probabilities.
+      # The portfolio is persisted to the database for later sampling.
+      #
+      # @return [PortfolioResult] containing the generated portfolio
+      def generate_portfolio
+        if existing_portfolio.present?
+          return PortfolioResult.new(
+            portfolio: existing_portfolio,
+            success: true,
+            error: nil
+          )
+        end
+
+        start_time = Time.current
+        leximin_result = LeximinSelector.new(@stratified_sortition).call
+
+        unless leximin_result.success?
+          return PortfolioResult.new(
+            portfolio: nil,
+            success: false,
+            error: leximin_result.error
+          )
+        end
+
+        @existing_portfolio = portfolio = PanelPortfolio.create!(
+          stratified_sortition: @stratified_sortition,
+          panels: leximin_result.panels,
+          probabilities: leximin_result.probabilities,
+          selection_probabilities: leximin_result.selection_probabilities,
+          generated_at: Time.current,
+          generation_time_seconds: Time.current - start_time,
+          num_iterations: leximin_result.panels.size, # Approximation
+          convergence_achieved: true
+        )
+
+        PortfolioResult.new(
+          portfolio:,
+          success: true,
+          error: nil
+        )
+      rescue StandardError => e
+        PortfolioResult.new(
+          portfolio: nil,
+          success: false,
+          error: I18n.t("decidim.stratified_sortitions.errors.fair_sortition.portfolio_generation_failed", error: e.message)
+        )
+      end
+
+      # Sample from existing portfolio (Phase 2 of two-phase process)
+      #
+      # @param verification_seed [String, nil] Optional seed for reproducible sampling
+      # @return [Result] containing selected participants and audit log
+      def sample_from_portfolio(verification_seed: nil)
+        portfolio = existing_portfolio
+
+        return error_result(error: I18n.t("decidim.stratified_sortitions.errors.fair_sortition.no_portfolio")) unless portfolio
+
+        if portfolio.sampled?
+          # Return existing result
+          return build_success_result(portfolio)
+        end
+
+        sampling_result = portfolio.sample!(verification_seed:)
+
+        return error_result(error: sampling_result.error) unless sampling_result.success?
+
+        build_success_result(portfolio.reload)
+      rescue StandardError => e
+        Rails.logger.error("Error while sampling portfolio: #{e.message}\n#{e.backtrace.join("\n")}")
+        error_result(error: I18n.t("decidim.stratified_sortitions.errors.fair_sortition.sampling_failed", error: e.message))
+      end
+
+      # Verify a previous sortition result
+      #
+      # Given the same seed and data, should produce the same result
+      #
+      # @param expected_ids [Array<Integer>] expected selected participant IDs
+      # @param verification_seed [String] the seed used in the original draw
+      # @return [Boolean] true if verification passes
+      def verify(expected_ids, verification_seed:)
+        portfolio = existing_portfolio
+        return false unless portfolio&.sampled?
+
+        # Re-sample with the same seed (doesn't persist)
+        random_seed = Decidim::StratifiedSortitions.derive_random_seed(verification_seed)
+        sampler = Leximin::PanelSampler.new(
+          portfolio.panels,
+          portfolio.probabilities,
+          random_seed:
+        )
+        result = sampler.sample
+        return false unless result.success?
+
+        Set.new(result.selected_panel) == Set.new(expected_ids)
+      end
+
+      # Check if this sortition has already been performed
+      #
+      # @return [Boolean]
+      def already_performed?
+        existing_portfolio&.sampled? || false
+      end
+
+      # Get the existing portfolio if any
+      #
+      # @return [PanelPortfolio, nil]
+      def existing_portfolio
+        @existing_portfolio ||= @stratified_sortition.panel_portfolio
+      end
+
+      private
+
+      def find_or_generate_portfolio
+        return existing_portfolio if existing_portfolio.present?
+
+        result = generate_portfolio
+        result.success? ? result.portfolio : result
+      end
+
+      def load_participants(participant_ids)
+        return [] if participant_ids.empty?
+
+        SampleParticipant
+          .where(id: participant_ids)
+          .order(:id)
+          .to_a
+      end
+
+      def build_success_result(portfolio)
+        Result.new(
+          selected_participants: portfolio.selected_participants,
+          selected_participant_ids: portfolio.selected_panel,
+          selection_probabilities: portfolio.selection_probabilities,
+          portfolio:,
+          sampling_result: Leximin::PanelSampler::Result.new(
+            selected_panel: portfolio.selected_panel,
+            selected_index: portfolio.selected_panel_index,
+            random_value: portfolio.random_value_used,
+            success: true,
+            error: nil
+          ),
+          selection_log: portfolio.audit_log,
+          success: true,
+          error: nil
+        )
+      end
+
+      def error_result(error:)
+        Result.new(
+          selected_participants: [],
+          selected_participant_ids: [],
+          selection_probabilities: {},
+          portfolio: existing_portfolio,
+          sampling_result: nil,
+          selection_log: { error: },
+          success: false,
+          error:
+        )
+      end
+    end
+  end
+end