super_admin 0.2.0

data/app/controllers/super_admin/base_controller.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "ostruct"
+
+module SuperAdmin
+  # Base controller for all SuperAdmin controllers.
+  # Handles authentication, authorization, and custom layout.
+  class BaseController < SuperAdmin::ApplicationController
+    before_action :authorize_super_admin!
+
+    private
+
+    # Pagy helper method for pagination
+    # Returns a simple pagination object and the paginated collection
+    def pagy(collection, **vars)
+      # Set default items per page
+      items_per_page = vars.delete(:limit) || 25
+
+      # Get current page from params
+      page = (params[:page] || 1).to_i
+      page = 1 if page < 1
+
+      # Calculate total count
+      count = collection.count
+
+      # Calculate pagination values
+      pages = (count.to_f / items_per_page).ceil
+      pages = 1 if pages < 1
+      page = pages if page > pages
+
+      offset = (page - 1) * items_per_page
+
+      # Create a simple pagination object
+      pagy_obj = OpenStruct.new(
+        count: count,
+        page: page,
+        items: items_per_page,
+        pages: pages,
+        offset: offset,
+        limit: items_per_page,
+        next: (page < pages ? page + 1 : nil),
+        prev: (page > 1 ? page - 1 : nil),
+        in: [ [ (offset + 1), count ].min, [ offset + items_per_page, count ].min ]
+      )
+
+      # Return paginated collection
+      [ pagy_obj, collection.offset(offset).limit(items_per_page) ]
+    end
+
+    def authorize_super_admin!
+      return if SuperAdmin::Authorization.call(self)
+
+      # Si call retourne false, l'adapter a déjà géré la réponse (redirect/render).
+      # On stoppe la suite du traitement via la primitive Rack disponible.
+      if request.respond_to?(:halt)
+        request.halt
+      end
+
+      false
+    end
+
+    def available_models
+      @available_models ||= SuperAdmin::ModelInspector.all_models
+    end
+    helper_method :available_models
+
+    def model_display_name(model_class)
+      model_class.model_name.human(count: 2)
+    end
+    helper_method :model_display_name
+
+    def model_path(model_class)
+      SuperAdmin::Engine.routes.url_helpers.resources_path(resource: model_class.name.underscore.pluralize)
+    end
+    helper_method :model_path
+
+    # Helper methods for routes that work in both standalone and mounted engine contexts
+    def super_admin_root_path
+      SuperAdmin::Engine.routes.url_helpers.root_path
+    end
+    helper_method :super_admin_root_path
+
+    def super_admin_exports_path
+      SuperAdmin::Engine.routes.url_helpers.exports_path
+    end
+    helper_method :super_admin_exports_path
+
+    def super_admin_audit_logs_path
+      SuperAdmin::Engine.routes.url_helpers.audit_logs_path
+    end
+    helper_method :super_admin_audit_logs_path
+
+    def super_admin_export_path(token)
+      SuperAdmin::Engine.routes.url_helpers.export_path(token)
+    end
+    helper_method :super_admin_export_path
+
+    def download_super_admin_export_path(token)
+      SuperAdmin::Engine.routes.url_helpers.download_export_path(token)
+    end
+    helper_method :download_super_admin_export_path
+
+    def super_admin_resources_path(options = {})
+      SuperAdmin::Engine.routes.url_helpers.resources_path(options)
+    end
+    helper_method :super_admin_resources_path
+
+    def super_admin_resource_path(options = {})
+      SuperAdmin::Engine.routes.url_helpers.resource_path(options)
+    end
+    helper_method :super_admin_resource_path
+
+    def super_admin_new_resource_path(options = {})
+      SuperAdmin::Engine.routes.url_helpers.new_resource_path(options)
+    end
+    helper_method :super_admin_new_resource_path
+
+    def super_admin_edit_resource_path(options = {})
+      SuperAdmin::Engine.routes.url_helpers.edit_resource_path(options)
+    end
+    helper_method :super_admin_edit_resource_path
+
+    def super_admin_bulk_action_path(options = {})
+      SuperAdmin::Engine.routes.url_helpers.bulk_action_path(options)
+    end
+    helper_method :super_admin_bulk_action_path
+
+    def super_admin_association_search_path(options = {})
+      SuperAdmin::Engine.routes.url_helpers.association_search_path(options)
+    end
+    helper_method :super_admin_association_search_path
+  end
+end

data/app/controllers/super_admin/dashboard_controller.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module SuperAdmin
+  # SuperAdmin dashboard controller displaying all administrable models.
+  class DashboardController < SuperAdmin::BaseController
+    def index
+      @models_info = available_models.map do |model_class|
+        begin
+          count = model_class.count
+        rescue ActiveRecord::StatementInvalid, StandardError => e
+          Rails.logger.warn("Cannot count #{model_class.name}: #{e.message}")
+          count = 0
+        end
+
+        {
+          class: model_class,
+          name: model_class.name,
+          human_name: model_display_name(model_class),
+          count: count,
+          table_name: model_class.table_name,
+          path: model_path(model_class)
+        }
+      rescue StandardError => e
+        Rails.logger.error("Error inspecting model #{model_class.name}: #{e.message}")
+        nil
+      end.compact
+    end
+  end
+end

data/app/controllers/super_admin/exports_controller.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module SuperAdmin
+  # Handles creation and tracking of SuperAdmin CSV exports.
+  class ExportsController < SuperAdmin::BaseController
+    helper SuperAdmin::ExportsHelper
+
+    before_action :load_model_class, only: :create
+    before_action :find_export, only: %i[show download destroy]
+
+    def index
+      exports_scope = current_user.csv_exports.recent_first
+      exports_scope = exports_scope.includes(:file_attachment) if active_storage_available?
+      @pagy, @exports = pagy(exports_scope, limit: 20)
+    end
+
+    def show
+      nil if performed?
+    end
+
+    def create
+      return if performed?
+
+      filters = sanitized_filters(@model_class, params[:filters])
+
+      export = SuperAdmin::CsvExportCreator.call(
+        user: current_user,
+        model_class: @model_class,
+        resource: params[:resource],
+        search: params[:search],
+        sort: params[:sort],
+        direction: params[:direction],
+        filters: filters,
+        attributes: SuperAdmin::DashboardResolver.collection_attributes_for(@model_class)
+      )
+
+      redirect_to super_admin_exports_path,
+                  notice: t("super_admin.exports.flash.created", token: export.token)
+    end
+
+    def download
+      return unless @export
+      unless @export.ready_for_download?
+        redirect_to super_admin_exports_path,
+                    alert: t("super_admin.exports.flash.unavailable")
+        return
+      end
+
+      if @export.expires_at.present? && @export.expires_at.past?
+        redirect_to super_admin_exports_path,
+                    alert: t("super_admin.exports.flash.expired")
+        return
+      end
+
+      send_data @export.file.download,
+                filename: @export.file.filename.to_s,
+                type: @export.file.content_type || "text/csv",
+                disposition: "attachment"
+    end
+
+    def destroy
+      return unless @export
+
+      if active_storage_available?
+        @export.destroy!
+      else
+        @export.delete
+      end
+
+      redirect_to super_admin_exports_path,
+                  notice: t("super_admin.exports.flash.destroyed")
+    end
+
+    private
+
+    def load_model_class
+      @model_class = SuperAdmin::ModelInspector.find_model(params[:resource])
+
+      return if @model_class
+
+      redirect_to super_admin_root_path,
+                  alert: t("super_admin.resources.flash.load_model_failed", resource: params[:resource])
+    end
+
+    def sanitized_filters(model_class, raw_filters)
+      return {} if raw_filters.blank?
+
+      filters_params = raw_filters.is_a?(ActionController::Parameters) ? raw_filters : ActionController::Parameters.new(raw_filters)
+      permitted_keys = SuperAdmin::FilterBuilder.permitted_param_keys(model_class)
+      filters_params.permit(*permitted_keys).to_unsafe_h
+    end
+
+    def find_export
+      @export = current_user.csv_exports.find_by(token: params[:token])
+      return if @export
+
+      redirect_to super_admin_exports_path,
+                  alert: t("super_admin.exports.flash.not_found")
+    end
+
+    def active_storage_available?
+      return false unless defined?(ActiveStorage::Attachment)
+
+      ActiveStorage::Attachment.table_exists?
+    rescue ActiveRecord::StatementInvalid, ActiveRecord::NoDatabaseError
+      false
+    end
+  end
+end

data/app/controllers/super_admin/resources_controller.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+module SuperAdmin
+  # Generic CRUD controller for all resources.
+  # Uses ActiveRecord reflection to adapt dynamically to each model.
+  class ResourcesController < SuperAdmin::BaseController
+    before_action :load_resource_context
+    before_action :set_resource, only: %i[show edit update destroy]
+
+    # GET /super_admin/:resource
+    def index
+      collection = SuperAdmin::Resources::CollectionPresenter.new(context: @context, params: params)
+      @filter_definitions = collection.filter_definitions
+      @attributes = @context.displayable_attributes
+
+      respond_to do |format|
+        format.html do
+          @applied_filters = collection.filter_params
+          @pagy, @resources = pagy(collection.scope, limit: 25)
+        end
+
+        format.csv do
+          export = collection.queue_export!(current_user, @attributes)
+
+          flash[:notice] = t("super_admin.exports.flash.created", token: export.token)
+          redirect_to super_admin_exports_path
+        end
+      end
+    end
+
+    # GET /super_admin/:resource/:id
+    def show
+      @attributes = @context.show_attributes
+      @associations = @model_class.reflect_on_all_associations
+      @association_counts = SuperAdmin::Resources::AssociationInspector.new(@resource).has_many_counts(@associations)
+    end
+
+    # GET /super_admin/:resource/new
+    def new
+      @resource = @model_class.new
+      @editable_attributes = @context.editable_attributes
+    end
+
+    # POST /super_admin/:resource
+    def create
+      @resource = @model_class.new(resource_params)
+
+      if @resource.save
+        audit(:create, resource: @resource)
+        redirect_to super_admin_resource_path(resource: params[:resource], id: @resource.id),
+                    notice: t("super_admin.resources.flash.create.success", model: @model_class.model_name.human)
+      else
+        @editable_attributes = @context.editable_attributes
+        render :new, status: :unprocessable_entity
+      end
+    end
+
+    # GET /super_admin/:resource/:id/edit
+    def edit
+      @editable_attributes = @context.editable_attributes
+    end
+
+    # PATCH /super_admin/:resource/:id
+    def update
+      if @resource.update(resource_params)
+        audit(:update, resource: @resource, changes: @resource.previous_changes)
+        redirect_to super_admin_resource_path(resource: params[:resource], id: @resource.id),
+                    notice: t("super_admin.resources.flash.update.success", model: @model_class.model_name.human)
+      else
+        @editable_attributes = @context.editable_attributes
+        render :edit, status: :unprocessable_entity
+      end
+    end
+
+    # DELETE /super_admin/:resource/:id
+    def destroy
+      snapshot = @resource.attributes
+      @resource.destroy!
+      audit(
+        :destroy,
+        resource_type: @model_class.name,
+        resource_id: snapshot[@model_class.primary_key]&.to_s,
+        changes: { "before" => snapshot }
+      )
+
+      redirect_to super_admin_resources_path(resource: params[:resource]),
+                  notice: t("super_admin.resources.flash.destroy.success", model: @model_class.model_name.human)
+    rescue ActiveRecord::InvalidForeignKey, ActiveRecord::DeleteRestrictionError
+      redirect_to super_admin_resource_path(resource: params[:resource], id: @resource.id),
+                  alert: t("super_admin.resources.flash.destroy.dependencies")
+    end
+
+    # POST /super_admin/:resource/bulk
+    def bulk
+      collection = SuperAdmin::Resources::CollectionPresenter.new(context: @context, params: params)
+      selection = bulk_params[:resource_ids]&.reject(&:blank?) || []
+      action = bulk_params[:bulk_action]
+
+      if selection.empty?
+        redirect_to super_admin_resources_path(resource: params[:resource], **collection.preserved_params),
+                    alert: t("super_admin.resources.flash.bulk.selection_required")
+        return
+      end
+
+      case action
+      when "destroy"
+        records = @model_class.where(id: selection)
+        destroyed_count = records.size
+        @model_class.transaction do
+          records.find_each do |record|
+            snapshot = record.attributes
+            record.destroy!
+            audit(
+              :destroy,
+              resource_type: @model_class.name,
+              resource_id: snapshot[@model_class.primary_key]&.to_s,
+              changes: { "before" => snapshot, "bulk" => true, "selection" => selection }
+            )
+          end
+        end
+        redirect_to super_admin_resources_path(resource: params[:resource], **collection.preserved_params),
+                    notice: t("super_admin.resources.flash.bulk.success", count: destroyed_count, model: @model_class.model_name.human(count: destroyed_count))
+      else
+        redirect_to super_admin_resources_path(resource: params[:resource], **collection.preserved_params),
+                    alert: t("super_admin.resources.flash.bulk.unsupported_action")
+      end
+    rescue ActiveRecord::InvalidForeignKey, ActiveRecord::DeleteRestrictionError
+      redirect_to super_admin_resources_path(resource: params[:resource], **collection.preserved_params),
+                  alert: t("super_admin.resources.flash.bulk.dependencies")
+    end
+
+    private
+
+    def load_resource_context
+      @context = SuperAdmin::Resources::Context.new(params[:resource])
+      @model_class = @context.model_class
+
+      return if @context.valid?
+
+      flash[:alert] = t("super_admin.resources.flash.load_model_failed", resource: params[:resource])
+      redirect_to super_admin_root_path
+      request.halt if request.respond_to?(:halt)
+    end
+
+    def set_resource
+      relation = @model_class
+      if action_name == "show"
+        # Use dashboard-configured includes or fall back to AssociationInspector
+        includes = SuperAdmin::DashboardResolver.show_includes_for(@model_class)
+        if includes.empty?
+          includes = SuperAdmin::Resources::AssociationInspector.preloadable_names(@model_class)
+        end
+        relation = relation.includes(includes) if includes.any?
+      end
+
+      @resource = relation.find(params[:id])
+    rescue ActiveRecord::RecordNotFound
+      flash[:alert] = t("super_admin.resources.flash.not_found", model: @model_class.model_name.human)
+      redirect_to super_admin_resources_path(resource: params[:resource])
+    end
+
+    def bulk_params
+      params.permit(:bulk_action, resource_ids: [])
+    end
+
+    # Dynamic strong parameters based on model attributes and nested attributes
+    def resource_params
+      permitted = SuperAdmin::Resources::PermittedAttributes.new(@model_class).permit(params)
+      SuperAdmin::Resources::ValueNormalizer.new(@model_class, permitted).normalize
+    end
+
+    def audit(action, resource: nil, resource_type: nil, resource_id: nil, changes: nil)
+      return unless auditable?
+
+      SuperAdmin::Auditing.log!(
+        user: current_user,
+        resource: resource,
+        resource_type: resource_type,
+        resource_id: resource_id,
+        action: action,
+        changes: changes,
+        context: audit_context
+      )
+    end
+
+    def auditable?
+      @model_class.present? && @model_class.name != "SuperAdmin::AuditLog"
+    end
+
+    def audit_context
+      {
+        "resource" => params[:resource],
+        "resource_id" => params[:id],
+        "request_path" => request.fullpath,
+        "request_id" => request.request_id,
+        "controller" => controller_name,
+        "action" => action_name
+      }.compact
+    end
+  end
+end

data/app/dashboards/super_admin/base_dashboard.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+module SuperAdmin
+  # Base DSL to configure how resources are displayed inside SuperAdmin.
+  # Inspired by Administrate dashboards but focused on selecting visible attributes.
+  class BaseDashboard
+    class_attribute :_resource_class, instance_writer: false
+    class_attribute :_collection_attributes, default: nil, instance_writer: false
+    class_attribute :_show_attributes, default: nil, instance_writer: false
+    class_attribute :_form_attributes, default: nil, instance_writer: false
+    class_attribute :_collection_includes, default: nil, instance_writer: false
+    class_attribute :_show_includes, default: nil, instance_writer: false
+
+    class << self
+      # Explicitly sets the resource class managed by this dashboard.
+      # When omitted, the class is inferred from the dashboard name (e.g. UserDashboard => User).
+      def resource(model_class)
+        self._resource_class = model_class
+      end
+
+      # Defines attributes shown on the collection (index) page.
+      # Usage: collection_attributes :id, :name, :status
+      def collection_attributes(*attrs)
+        self._collection_attributes = normalize_flat_attribute_list(attrs)
+      end
+
+      # Defines attributes shown on the resource detail (show) page.
+      def show_attributes(*attrs)
+        self._show_attributes = normalize_flat_attribute_list(attrs)
+      end
+
+      # Defines attributes shown in resource forms (new/edit).
+      def form_attributes(*attrs)
+        self._form_attributes = normalize_flat_attribute_list(attrs)
+      end
+
+      # Defines associations to preload for the collection (index) page to avoid N+1 queries.
+      # Usage: collection_includes :author, :tags, comments: :user
+      def collection_includes(*associations)
+        self._collection_includes = associations.freeze
+      end
+
+      # Defines associations to preload for the show page to avoid N+1 queries.
+      # Usage: show_includes :author, :tags, comments: :user
+      def show_includes(*associations)
+        self._show_includes = associations.freeze
+      end
+
+      # Returns the ActiveRecord class associated with the dashboard.
+      def resource_class
+        resolved_resource_class || infer_resource_class
+      end
+
+      # Returns attributes configured for a given view.
+      def attributes_for(view)
+        case view.to_sym
+        when :index, :collection, :list
+          collection_attributes_list
+        when :show, :detail
+          show_attributes_list
+        when :form, :new, :edit
+          form_attributes_list
+        else
+          []
+        end
+      end
+
+      # Returns configured collection attributes or sensible defaults.
+      def collection_attributes_list
+        _collection_attributes || default_collection_attributes
+      end
+
+      # Returns configured show attributes or sensible defaults.
+      def show_attributes_list
+        _show_attributes || default_show_attributes
+      end
+
+      # Returns configured form attributes or sensible defaults.
+      def form_attributes_list
+        _form_attributes || default_form_attributes
+      end
+
+      # Returns associations to preload for collection view
+      def collection_includes_list
+        _collection_includes || default_collection_includes
+      end
+
+      # Returns associations to preload for show view
+      def show_includes_list
+        _show_includes || default_show_includes
+      end
+
+      private
+
+      def resolved_resource_class
+        case _resource_class
+        when Class
+          _resource_class
+        when String, Symbol
+          _resource_class.to_s.constantize
+        else
+          nil
+        end
+      rescue NameError
+        nil
+      end
+
+      def normalize_attribute_list(attrs)
+        Array(attrs).flatten.compact.map do |attribute|
+          normalize_attribute_entry(attribute)
+        end.freeze
+      end
+
+      def normalize_flat_attribute_list(attrs)
+        normalize_attribute_list(attrs).flat_map do |entry|
+          entry.is_a?(Hash) ? entry.keys.map(&:to_sym) : entry
+        end.map(&:to_sym).freeze
+      end
+
+      def normalize_attribute_entry(attribute)
+        case attribute
+        when Hash
+          attribute.each_with_object({}) do |(key, value), hash|
+            hash[key.to_sym] = Array(value).flatten.compact.map { |entry| normalize_attribute_entry(entry) }
+          end
+        else
+          attribute.to_sym
+        end
+      end
+
+      def infer_resource_class
+        name.delete_suffix("Dashboard").constantize
+      rescue NameError
+        nil
+      end
+
+      def default_collection_attributes
+        default_displayable_attributes
+      end
+
+      def default_show_attributes
+        default_displayable_attributes
+      end
+
+      def default_form_attributes
+        resource = resource_class
+        return [] unless resource
+
+        editable = SuperAdmin::ResourceConfiguration.editable_attributes(resource)
+        editable.map { |attr| attr.to_sym }
+      end
+
+      def default_displayable_attributes
+        resource = resource_class
+        return [] unless resource
+
+        attrs = SuperAdmin::ResourceConfiguration.displayable_attributes(resource)
+        attrs.map { |attr| attr.to_sym }
+      end
+
+      def default_collection_includes
+        resource = resource_class
+        return [] unless resource
+
+        # Auto-detect preloadable associations explicitly listed in the collection attributes
+        associations_from_attributes(collection_attributes_list, resource)
+      end
+
+      def default_show_includes
+        resource = resource_class
+        return [] unless resource
+
+        # Auto-detect belongs_to and has_one associations which benefit from eager loading
+        preloadable_association_names(resource)
+      rescue StandardError
+        []
+      end
+
+      def associations_from_attributes(attributes, resource)
+        return [] unless resource.respond_to?(:reflect_on_all_associations)
+
+        preloadable_associations = preloadable_association_names(resource)
+
+        # Only preload associations explicitly referenced in the attribute list.
+        attributes.select do |attr|
+          preloadable_associations.include?(attr)
+        end.uniq
+      rescue StandardError
+        []
+      end
+
+      def preloadable_association_names(resource)
+        resource.reflect_on_all_associations
+          .select { |reflection| %i[belongs_to has_one].include?(reflection.macro) }
+          .reject(&:polymorphic?)
+          .map(&:name)
+      end
+    end
+  end
+end

data/app/errors/super_admin/configuration_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module SuperAdmin
+  # Raised when the SuperAdmin engine is misconfigured.
+  class ConfigurationError < StandardError; end
+end