rails_onboarding 0.6.1

data/app/controllers/rails_onboarding/ab_tests_controller.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+module RailsOnboarding
+  # Controller for managing A/B tests and viewing results
+  # Provides endpoints for test management and analytics
+  class AbTestsController < ApplicationController
+    include RailsOnboarding::AdminAuthorization
+    include RailsOnboarding::RateLimitable
+
+    # These actions view A/B test results and flip tests on/off, and
+    # assign_variant writes onto arbitrary user records - admin-only, same gate
+    # as the Admin dashboard. No StandardError handler here, so the two
+    # specific rescues need no ordering guard.
+    before_action :authenticate_admin!
+    before_action :verify_admin_authorization!
+
+    rescue_from UnauthorizedError, with: :handle_admin_unauthorized
+    rescue_from NotImplementedError, with: :handle_admin_not_implemented
+
+    before_action :set_ab_test, only: [ :show, :results, :toggle ]
+
+    # GET /ab_tests
+    # List all configured A/B tests
+    def index
+      @ab_tests = RailsOnboarding.configuration.ab_tests || {}
+
+      respond_to do |format|
+        format.html
+        format.json { render json: @ab_tests }
+      end
+    end
+
+    # GET /ab_tests/:test_name
+    # Show details for a specific A/B test
+    def show
+      respond_to do |format|
+        format.html
+        format.json { render json: test_details }
+      end
+    end
+
+    # GET /ab_tests/:test_name/results
+    # View results and analytics for an A/B test
+    def results
+      @results = calculate_results
+      @funnel = calculate_funnel_by_variant
+
+      respond_to do |format|
+        format.html
+        format.json { render json: { results: @results, funnel: @funnel } }
+      end
+    end
+
+    # POST /ab_tests/:test_name/toggle
+    # Enable or disable an A/B test
+    def toggle
+      # Note: This modifies runtime configuration, not persistent storage
+      # For production use, configuration should be managed via config files or database
+      current_state = @test_config[:enabled]
+      @test_config[:enabled] = !current_state
+
+      flash[:notice] = "A/B test #{@test_name} #{@test_config[:enabled] ? 'enabled' : 'disabled'}"
+
+      respond_to do |format|
+        format.html { redirect_to ab_tests_path }
+        format.json { render json: { enabled: @test_config[:enabled] } }
+      end
+    end
+
+    # POST /ab_tests/:test_name/assign_variant
+    # Manually assign a user to a specific variant
+    def assign_variant
+      user_id = params[:user_id]
+      variant = params[:variant]
+      test_name = params[:test_name]
+
+      user = user_class.find_by(id: user_id)
+
+      if user && user.respond_to?(:assign_variant)
+        user.assign_variant(test_name, variant)
+        render json: { success: true, variant: variant }
+      else
+        render json: { success: false, error: "User not found or AbTestable not included" }, status: :unprocessable_entity
+      end
+    end
+
+    private
+
+    def set_ab_test
+      # Sanitize test_name to prevent SQL injection
+      raw_test_name = params[:test_name] || params[:id]
+
+      # Only allow alphanumeric characters, underscores, and hyphens
+      unless raw_test_name =~ /\A[a-zA-Z0-9_-]+\z/
+        respond_to do |format|
+          format.html { redirect_to ab_tests_path, alert: "Invalid test name format" }
+          format.json { render json: { error: "Invalid test name format" }, status: :bad_request }
+        end
+        return
+      end
+
+      @test_name = raw_test_name
+      @test_config = RailsOnboarding.configuration.ab_tests[@test_name.to_sym]
+
+      unless @test_config
+        respond_to do |format|
+          format.html { redirect_to ab_tests_path, alert: "A/B test not found: #{@test_name}" }
+          format.json { render json: { error: "Test not found" }, status: :not_found }
+        end
+      end
+    end
+
+    def test_details
+      {
+        name: @test_name,
+        enabled: @test_config[:enabled],
+        variants: @test_config[:variants],
+        weights: @test_config[:weights],
+        participant_count: participant_count,
+        variant_distribution: variant_distribution
+      }
+    end
+
+    # ab_test_assignments is a serialized JSON column that isn't a queryable
+    # jsonb type on every database the gem supports, so all variant filtering is
+    # done in Ruby to stay portable (mirrors Admin::AbTestsController#calculate_results).
+    def all_test_users
+      @all_test_users ||= user_class.all.select { |user| user.respond_to?(:ab_test_variant) }
+    end
+
+    def users_in_variant(variant)
+      all_test_users.select { |user| user.ab_test_variant(@test_name) == variant }
+    end
+
+    def participant_count
+      all_test_users.count { |user| user.ab_test_variant(@test_name).present? }
+    rescue StandardError
+      0
+    end
+
+    def variant_distribution
+      return {} unless user_class.method_defined?(:ab_test_variant)
+
+      @test_config[:variants].each_with_object({}) do |variant, distribution|
+        distribution[variant] = users_in_variant(variant).count
+      end
+    end
+
+    def calculate_results
+      variants = @test_config[:variants]
+      results = {}
+
+      variants.each do |variant|
+        results[variant] = {
+          participants: participant_count_for_variant(variant),
+          completions: completion_count_for_variant(variant),
+          conversion_rate: conversion_rate_for_variant(variant),
+          average_time: average_completion_time_for_variant(variant),
+          skip_rate: skip_rate_for_variant(variant)
+        }
+      end
+
+      results
+    end
+
+    def participant_count_for_variant(variant)
+      users_in_variant(variant).count
+    rescue StandardError
+      0
+    end
+
+    def completion_count_for_variant(variant)
+      users_in_variant(variant).count(&:onboarding_completed)
+    rescue StandardError
+      0
+    end
+
+    def conversion_rate_for_variant(variant)
+      participants = participant_count_for_variant(variant)
+      return 0 if participants.zero?
+
+      completions = completion_count_for_variant(variant)
+      (completions.to_f / participants * 100).round(2)
+    end
+
+    def average_completion_time_for_variant(variant)
+      users = users_in_variant(variant).select do |user|
+        user.onboarding_completed && user.onboarding_completed_at
+      end
+
+      return 0 if users.empty?
+
+      times = users.map do |user|
+        next unless user.created_at && user.onboarding_completed_at
+
+        (user.onboarding_completed_at - user.created_at).to_i
+      end.compact
+
+      return 0 if times.empty?
+
+      (times.sum / times.size.to_f).round(2)
+    end
+
+    def skip_rate_for_variant(variant)
+      participants = participant_count_for_variant(variant)
+      return 0 if participants.zero?
+
+      skipped = users_in_variant(variant).count(&:onboarding_skipped)
+
+      (skipped.to_f / participants * 100).round(2)
+    end
+
+    def calculate_funnel_by_variant
+      variants = @test_config[:variants]
+      steps = RailsOnboarding.configuration.steps.map { |s| s[:name].to_s }
+
+      funnel = {}
+
+      variants.each do |variant|
+        funnel[variant] = {}
+
+        steps.each_with_index do |step, index|
+          if index.zero?
+            # First step - all participants start here
+            funnel[variant][step] = participant_count_for_variant(variant)
+          else
+            # Subsequent steps - count users who reached this step
+            funnel[variant][step] = users_reached_step_count(variant, step)
+          end
+        end
+      end
+
+      funnel
+    end
+
+    def users_reached_step_count(variant, step)
+      # This requires analytics events to track step progression
+      # For now, return a simplified version
+      step_index = RailsOnboarding.configuration.steps.index { |s| s[:name].to_s == step }
+      return 0 unless step_index
+
+      # Users who completed onboarding definitely reached all steps
+      completed = completion_count_for_variant(variant)
+
+      # Users currently on this step or beyond
+      current_on_step = users_in_variant(variant).count do |user|
+        user.onboarding_current_step == step
+      end
+
+      completed + current_on_step
+    end
+
+    def user_class
+      @user_class ||= RailsOnboarding.configuration.user_class_name.constantize
+    end
+  end
+end

data/app/controllers/rails_onboarding/admin/ab_tests_controller.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module RailsOnboarding
+  module Admin
+    # Admin A/B tests controller
+    # View and toggle the A/B tests defined in RailsOnboarding.configuration.ab_tests,
+    # and inspect their results. Tests are config-defined (see RailsOnboarding::AbTestable),
+    # so there is no create/edit/destroy here - only viewing and enabling/disabling.
+    class AbTestsController < BaseController
+      before_action :set_ab_test, only: [ :show, :start, :stop, :export ]
+
+      def index
+        @ab_tests = ab_tests_collection
+        @active_tests = @ab_tests.select { |t| t[:enabled] }
+        @inactive_tests = @ab_tests.reject { |t| t[:enabled] }
+
+        # The screen renders two lists off one collection, so paginate the
+        # concatenation - active first, matching the order the sections appear in -
+        # and split the current page back out. Paginating the two lists separately
+        # would need two page parameters and two navs.
+        #
+        # @active_tests/@inactive_tests stay whole so the stat cards keep reporting
+        # collection totals rather than per-page counts.
+        @pagy, page_of_tests = paginate(@active_tests + @inactive_tests)
+        @page_active_tests = page_of_tests.select { |t| t[:enabled] }
+        @page_inactive_tests = page_of_tests.reject { |t| t[:enabled] }
+      end
+
+      def show
+        @results = calculate_results(@test_name, @test_config)
+      end
+
+      def start
+        set_enabled(true)
+        flash[:notice] = "A/B test '#{@test_name}' started"
+        redirect_to admin_ab_test_path(@test_name)
+      end
+
+      def stop
+        set_enabled(false)
+        flash[:notice] = "A/B test '#{@test_name}' stopped"
+        redirect_to admin_ab_test_path(@test_name)
+      end
+
+      def export
+        results = calculate_results(@test_name, @test_config)
+
+        respond_to do |format|
+          format.csv do
+            send_data generate_csv_export(results),
+              filename: "ab_test_#{@test_name}_results_#{Date.current}.csv",
+              type: "text/csv"
+          end
+        end
+      end
+
+      private
+
+      def ab_tests_collection
+        (RailsOnboarding.configuration.ab_tests || {}).map do |name, config|
+          {
+            name: name.to_s,
+            enabled: !!config[:enabled],
+            variants: config[:variants] || [],
+            weights: config[:weights]
+          }
+        end
+      end
+
+      def set_ab_test
+        @test_name = params[:id]
+        @test_config = RailsOnboarding.configuration.ab_tests&.[](@test_name.to_sym)
+
+        unless @test_config
+          flash[:alert] = "A/B test not found: #{@test_name}"
+          redirect_to admin_ab_tests_path
+        end
+      end
+
+      def set_enabled(value)
+        RailsOnboarding.configuration.ab_tests[@test_name.to_sym][:enabled] = value
+      end
+
+      # Computed in Ruby rather than SQL: ab_test_assignments is a serialized
+      # JSON column, not always a queryable jsonb type, so this stays portable
+      # across the databases the gem supports.
+      def calculate_results(test_name, test_config)
+        variants = test_config[:variants] || []
+        users = user_class.all.select { |u| u.respond_to?(:ab_test_variant) }
+
+        variants.each_with_object({}) do |variant, results|
+          in_variant = users.select { |u| u.ab_test_variant(test_name) == variant }
+          total = in_variant.size
+          completed = in_variant.count(&:onboarding_completed)
+
+          results[variant] = {
+            participants: total,
+            completions: completed,
+            conversion_rate: total.zero? ? 0 : (completed.to_f / total * 100).round(2)
+          }
+        end
+      end
+
+      def generate_csv_export(results)
+        require "csv"
+
+        CSV.generate do |csv|
+          csv << [ "Variant", "Participants", "Completions", "Conversion Rate (%)" ]
+
+          results.each do |variant, data|
+            csv << [ variant, data[:participants], data[:completions], data[:conversion_rate] ]
+          end
+        end
+      end
+
+      def user_class
+        @user_class ||= RailsOnboarding.configuration.user_class_name.constantize
+      end
+    end
+  end
+end

data/app/controllers/rails_onboarding/admin/base_controller.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module RailsOnboarding
+  module Admin
+    # Base controller for admin interface
+    # Provides authentication and authorization for admin actions
+    class BaseController < ApplicationController
+      include RailsOnboarding::AdminAuthorization
+      include Pagy::Method
+
+      DEFAULT_PER_PAGE = 25
+      # Upper bound on the client-supplied ?per_page=, so a crafted URL can't ask
+      # for a whole table in one query.
+      MAX_PER_PAGE = 100
+
+      before_action :authenticate_admin!
+      before_action :verify_admin_authorization!
+      layout "rails_onboarding/admin"
+
+      # rescue_from handlers are checked most-recently-registered-first, so the
+      # generic StandardError handler must be registered BEFORE the specific
+      # ones or it swallows them all (UnauthorizedError is a StandardError
+      # subclass). Keep StandardError first; the concern supplies the handler
+      # methods for the two specific cases.
+      rescue_from StandardError, with: :handle_admin_error
+      rescue_from NotImplementedError, with: :handle_admin_not_implemented
+      rescue_from UnauthorizedError, with: :handle_admin_unauthorized
+
+      private
+
+      # Shared pagination entry point for the admin index screens.
+      #
+      # limit_key keeps the ?per_page= parameter these screens have always
+      # documented working - pagy's own default is ?limit=. max_limit is doing
+      # double duty: it is both what makes pagy honour a client-supplied value at
+      # all (without it the parameter is ignored outright) and the cap enforced on
+      # that value.
+      #
+      # Accepts an Array as well as a relation - pagy slices arrays directly - but
+      # returns [] rather than nil for a page past the end of an array, which is
+      # what pagy's own Array slicing gives you.
+      def paginate(collection, limit: DEFAULT_PER_PAGE)
+        pagy, records = pagy(collection,
+                             limit: limit,
+                             limit_key: "per_page",
+                             max_limit: MAX_PER_PAGE)
+        [ pagy, records || [] ]
+      end
+
+      # Admin-area catch-all: unlike the concern's admin-only handlers, an
+      # unexpected error here sends the operator back to the admin dashboard.
+      def handle_admin_error(exception)
+        logger.error "Admin error: #{exception.message}"
+        logger.error exception.backtrace.join("\n")
+
+        respond_to do |format|
+          format.html do
+            flash[:alert] = "An error occurred: #{exception.message}"
+            redirect_to admin_dashboard_path
+          end
+          format.json do
+            render json: { error: exception.message }, status: :internal_server_error
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/rails_onboarding/admin/dashboard_controller.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module RailsOnboarding
+  module Admin
+    # Admin dashboard controller
+    # Provides analytics overview and metrics visualization
+    class DashboardController < BaseController
+      def index
+        @date_range = params[:date_range] || "30"
+        @start_date = date_range_start(@date_range)
+        @end_date = Time.current
+
+        load_analytics_data
+        load_milestone_data
+        load_ab_test_data
+      end
+
+      private
+
+      def load_analytics_data
+        return unless defined?(RailsOnboarding::AnalyticsEvent)
+
+        # Overall metrics
+        @total_users = user_class.count
+        @onboarding_started = user_class.where.not(onboarding_current_step: nil).count
+        @onboarding_completed = user_class.where(onboarding_completed: true).count
+        @completion_rate = calculate_completion_rate
+
+        # Time-based metrics
+        @avg_completion_time = calculate_avg_completion_time
+        @recent_completions = recent_completions_count
+
+        # Step funnel
+        @step_funnel = calculate_step_funnel
+
+        # Recent events
+        @recent_events = RailsOnboarding::AnalyticsEvent
+          .where("created_at >= ?", @start_date)
+          .order(created_at: :desc)
+          .limit(10)
+
+        # Daily completion trend
+        @daily_completions = daily_completion_trend
+      rescue StandardError => e
+        logger.error "Error loading analytics: #{e.message}"
+        @analytics_error = e.message
+      end
+
+      def load_milestone_data
+        return unless defined?(RailsOnboarding::Milestone)
+
+        @total_milestones = RailsOnboarding::Milestone.count
+
+        # Use Arel to build safe SQL
+        users_table = user_class.arel_table
+        @milestone_achievements = user_class
+          .joins("LEFT JOIN rails_onboarding_milestone_achievements ON rails_onboarding_milestone_achievements.user_id = #{users_table.name}.id")
+          .group(users_table[:id])
+          .count
+        @top_milestones = top_achieved_milestones
+      rescue StandardError => e
+        logger.error "Error loading milestone data: #{e.message}"
+        @milestone_error = e.message
+      end
+
+      def load_ab_test_data
+        ab_tests = RailsOnboarding.configuration.ab_tests || {}
+
+        @total_tests = ab_tests.size
+        @active_tests = ab_tests.count { |_name, config| config[:enabled] }
+      rescue StandardError => e
+        logger.error "Error loading A/B test data: #{e.message}"
+        @ab_test_error = e.message
+      end
+
+      def calculate_completion_rate
+        return 0 if @onboarding_started.zero?
+        (@onboarding_completed.to_f / @onboarding_started * 100).round(2)
+      end
+
+      def calculate_avg_completion_time
+        completed_users = user_class
+          .where(onboarding_completed: true)
+          .where.not(onboarding_completed_at: nil)
+          .where("onboarding_completed_at >= ?", @start_date)
+
+        return 0 if completed_users.empty?
+
+        total_time = completed_users.sum do |user|
+          next 0 unless user.created_at && user.onboarding_completed_at
+          (user.onboarding_completed_at - user.created_at).to_i
+        end
+
+        (total_time / completed_users.count / 3600.0).round(2) # Convert to hours
+      end
+
+      def recent_completions_count
+        user_class
+          .where(onboarding_completed: true)
+          .where("onboarding_completed_at >= ?", @start_date)
+          .count
+      end
+
+      def calculate_step_funnel
+        steps = RailsOnboarding.configuration.steps
+        funnel = []
+
+        # A true entry funnel: count distinct users who *reached* each step
+        # (step_started), not just those who completed it. `properties` is a
+        # JSON-serialized text column, so filter by step in Ruby rather than
+        # with a DB JSON operator (not portable to text/MySQL).
+        step_events = if defined?(RailsOnboarding::AnalyticsEvent)
+          RailsOnboarding::AnalyticsEvent
+            .where(event_type: RailsOnboarding::AnalyticsEvent::ONBOARDING_STEP_STARTED)
+            .where("created_at >= ?", @start_date)
+            .to_a
+        else
+          []
+        end
+
+        steps.each do |step|
+          step_name = step[:name].to_s
+          users_reached = step_events
+            .select { |e| e.properties.to_h["step_name"].to_s == step_name }
+            .map(&:user_id).uniq.count
+
+          funnel << {
+            step: step_name,
+            title: step[:title],
+            users: users_reached,
+            percentage: @onboarding_started.zero? ? 0 : (users_reached.to_f / @onboarding_started * 100).round(2)
+          }
+        end
+
+        funnel
+      end
+
+      def daily_completion_trend
+        return [] unless defined?(RailsOnboarding::AnalyticsEvent)
+
+        days = 7
+        trend = []
+
+        days.times do |i|
+          date = i.days.ago.to_date
+          completions = user_class
+            .where(onboarding_completed: true)
+            .where("DATE(onboarding_completed_at) = ?", date)
+            .count
+
+          trend.unshift({ date: date.strftime("%m/%d"), count: completions })
+        end
+
+        trend
+      end
+
+      def top_achieved_milestones
+        return [] unless defined?(RailsOnboarding::Milestone)
+
+        RailsOnboarding::Milestone
+          .joins("LEFT JOIN rails_onboarding_milestone_achievements ON rails_onboarding_milestone_achievements.milestone_id = rails_onboarding_milestones.id")
+          .group("rails_onboarding_milestones.id", "rails_onboarding_milestones.name", "rails_onboarding_milestones.title")
+          .order("COUNT(rails_onboarding_milestone_achievements.id) DESC")
+          .limit(5)
+          .pluck("rails_onboarding_milestones.name", "rails_onboarding_milestones.title", "COUNT(rails_onboarding_milestone_achievements.id)")
+          .map { |name, title, count| { name: name, title: title, count: count } }
+      end
+
+      def date_range_start(range)
+        case range
+        when "7"
+          7.days.ago
+        when "30"
+          30.days.ago
+        when "90"
+          90.days.ago
+        when "all"
+          100.years.ago
+        else
+          30.days.ago
+        end
+      end
+
+      def user_class
+        @user_class ||= RailsOnboarding.configuration.user_class_name.constantize
+      end
+    end
+  end
+end