dscf-core 0.2.8 → 0.2.9

data/app/models/concerns/dscf/core/attachable.rb

@@ -0,0 +1,403 @@
+# frozen_string_literal: true
+
+module Dscf
+  module Core
+    # Include this concern in any model to add file attachment capabilities
+    # Works exactly like ActiveStorage's has_one_attached and has_many_attached
+    # NO MIGRATION NEEDED per model - just include and declare!
+    #
+    # @example Single file attachment
+    #   class UserProfile < ApplicationRecord
+    #     include Dscf::Core::Attachable
+    #
+    #     has_one_file :avatar
+    #     has_one_file :cover_photo, max_size: 10.megabytes
+    #   end
+    #
+    #   profile.avatar.attach(params[:avatar])
+    #   profile.avatar.attached? # => true
+    #   profile.avatar.url       # => "/dscf/core/files/..."
+    #   profile.avatar.download  # => binary data
+    #   profile.avatar.purge     # deletes file
+    #
+    # @example Multiple files attachment
+    #   class Product < ApplicationRecord
+    #     include Dscf::Core::Attachable
+    #
+    #     has_many_files :images
+    #     has_many_files :documents, allowed_types: %w[application/pdf]
+    #   end
+    #
+    #   product.images.attach(params[:images])
+    #   product.images.attached? # => true
+    #   product.images.count     # => 3
+    #   product.images.first.url # => "/dscf/core/files/..."
+    #   product.images.purge_all # deletes all
+    #
+    module Attachable
+      extend ActiveSupport::Concern
+
+      included do
+        # Polymorphic association to the central file_attachments table
+        has_many :file_attachments,
+                 class_name: "Dscf::Core::FileAttachment",
+                 as: :attachable,
+                 dependent: :destroy
+
+        # Store attachment configurations
+        class_attribute :_file_attachment_configs, default: {}
+      end
+
+      class_methods do
+        # Define a single file attachment
+        # @param name [Symbol] attachment name
+        # @param options [Hash] configuration options
+        # @option options [Integer] :max_size maximum file size (default: 5MB)
+        # @option options [Array<String>] :allowed_types allowed MIME types
+        def has_one_file(name, **options)
+          _file_attachment_configs[name] = options.merge(multiple: false)
+          define_single_attachment_methods(name, options)
+        end
+
+        # Define a multiple file attachment
+        # @param name [Symbol] attachment name
+        # @param options [Hash] configuration options
+        def has_many_files(name, **options)
+          _file_attachment_configs[name] = options.merge(multiple: true)
+          define_multiple_attachment_methods(name, options)
+        end
+
+        private
+
+        def define_single_attachment_methods(name, options)
+          # Getter: returns a SingleAttachmentProxy (memoized to preserve state like errors)
+          ivar_name = "@_attachment_proxy_#{name}"
+          define_method(name) do
+            instance_variable_get(ivar_name) ||
+              instance_variable_set(ivar_name, SingleAttachmentProxy.new(self, name, options))
+          end
+
+          # Direct setter for convenience: model.avatar = file
+          define_method("#{name}=") do |file|
+            send(name).attach(file)
+          end
+        end
+
+        def define_multiple_attachment_methods(name, options)
+          # Getter: returns a MultipleAttachmentProxy (memoized to preserve state)
+          ivar_name = "@_attachment_proxy_#{name}"
+          define_method(name) do
+            instance_variable_get(ivar_name) ||
+              instance_variable_set(ivar_name, MultipleAttachmentProxy.new(self, name, options))
+          end
+          define_method("#{name}=") do |files|
+            send(name).attach(files)
+          end
+        end
+      end
+
+      # ==========================================================================
+      # SingleAttachmentProxy - handles has_one_file attachments
+      # ==========================================================================
+      class SingleAttachmentProxy
+        # Delegate common methods to the underlying FileAttachment record
+        delegate :file_key, :filename, :content_type, :size, :human_size,
+                 :extension, :image?, :pdf?, :video?, :url, :download,
+                 :metadata, :created_at, :id,
+                 to: :attachment, allow_nil: true
+
+        def initialize(record, name, options)
+          @record = record
+          @name = name.to_s
+          @options = options
+          @errors = []
+          @uploader_context = nil
+        end
+
+        # Set the user who is uploading the file
+        # @param user [ActiveRecord::Base] the user performing the upload
+        # @return [self]
+        def uploaded_by(user)
+          @uploader_context = user
+          self
+        end
+
+        # Attach a file to this record
+        # @param file [ActionDispatch::Http::UploadedFile, File, Hash, nil]
+        # @return [Boolean] success status
+        def attach(file)
+          @errors = []
+          return detach if file.nil?
+
+          # Validate and upload the file (pass record class for engine detection)
+          uploader = FileStorage::Uploader.new(uploader_options.merge(record_class: @record.class))
+          result = uploader.upload(file)
+
+          unless result
+            @errors = uploader.errors
+            return false
+          end
+
+          # Remove existing attachment (if any)
+          existing_attachment&.purge
+
+          # Create new attachment record
+          @record.file_attachments.create!(
+            name: @name,
+            file_key: result[:file_key],
+            filename: result[:filename],
+            content_type: result[:content_type],
+            size: result[:size],
+            metadata: result[:metadata] || {},
+            uploaded_by: @uploader_context
+          )
+
+          @attachment = nil # Reset cache
+          @uploader_context = nil # Reset uploader context
+          true
+        rescue StandardError => e
+          Rails.logger.error("Failed to attach file: #{e.message}")
+          @errors << "Failed to attach file: #{e.message}"
+          false
+        end
+
+        # Remove the attached file
+        # @return [Boolean]
+        def detach
+          existing_attachment&.purge
+          @attachment = nil
+          true
+        end
+
+        alias purge detach
+
+        # Check if a file is attached
+        # @return [Boolean]
+        def attached?
+          attachment.present? && attachment.attached?
+        end
+
+        # Get the underlying FileAttachment record
+        # @return [FileAttachment, nil]
+        def attachment
+          @attachment ||= @record.file_attachments.with_name(@name).first
+        end
+
+        # Check if file exists in storage
+        # @return [Boolean]
+        def exists?
+          attachment&.exists_in_storage? || false
+        end
+
+        # Get upload errors
+        # @return [Array<String>]
+        attr_reader :errors
+
+        # Serialize for JSON
+        # @return [Hash, nil]
+        def as_json(options = {})
+          return nil unless attached?
+
+          attachment.as_json(options)
+        end
+
+        private
+
+        def existing_attachment
+          @record.file_attachments.find_by(name: @name)
+        end
+
+        def uploader_options
+          opts = {}
+          opts[:max_size] = @options[:max_size] if @options[:max_size]
+          opts[:allowed_types] = @options[:allowed_types] if @options[:allowed_types]
+          opts
+        end
+      end
+
+      # ==========================================================================
+      # MultipleAttachmentProxy - handles has_many_files attachments
+      # ==========================================================================
+      class MultipleAttachmentProxy
+        include Enumerable
+
+        delegate :each, to: :attachments
+
+        def initialize(record, name, options)
+          @record = record
+          @name = name.to_s
+          @options = options
+          @errors = []
+          @uploader_context = nil
+        end
+
+        # Set the user who is uploading the files
+        # @param user [ActiveRecord::Base] the user performing the upload
+        # @return [self]
+        def uploaded_by(user)
+          @uploader_context = user
+          self
+        end
+
+        # Attach one or more files
+        # @param files [ActionDispatch::Http::UploadedFile, Array<ActionDispatch::Http::UploadedFile>]
+        # @param replace [Boolean] whether to replace existing files (default: false)
+        # @return [Boolean] success status
+        def attach(files, replace: false)
+          @errors = []
+          files = Array(files).compact
+          return true if files.empty?
+
+          # Purge existing if replacing
+          purge_all if replace
+
+          uploader = FileStorage::Uploader.new(uploader_options)
+          current_position = attachments.maximum(:position).to_i
+
+          files.each do |file|
+            result = uploader.upload(file)
+
+            if result
+              current_position += 1
+              @record.file_attachments.create!(
+                name: @name,
+                file_key: result[:file_key],
+                filename: result[:filename],
+                content_type: result[:content_type],
+                size: result[:size],
+                metadata: result[:metadata] || {},
+                position: current_position,
+                uploaded_by: @uploader_context
+              )
+            else
+              @errors.concat(uploader.errors)
+            end
+          end
+
+          @attachments = nil # Reset cache
+          @uploader_context = nil # Reset uploader context
+          @errors.empty?
+        rescue StandardError => e
+          Rails.logger.error("Failed to attach files: #{e.message}")
+          @errors << "Failed to attach files: #{e.message}"
+          false
+        end
+
+        # Remove a specific file by its file_key
+        # @param file_key [String]
+        # @return [Boolean]
+        def detach(file_key)
+          att = attachments.find_by(file_key: file_key)
+          return false unless att
+
+          att.purge
+          @attachments = nil
+          true
+        end
+
+        # Remove all attached files
+        # @return [Boolean]
+        def purge_all
+          attachments.each(&:purge)
+          @attachments = nil
+          true
+        end
+
+        # Check if any files are attached
+        # @return [Boolean]
+        def attached?
+          attachments.exists?
+        end
+
+        # Get all FileAttachment records for this attachment name
+        # @return [ActiveRecord::Relation]
+        def attachments
+          @attachments ||= @record.file_attachments.with_name(@name).ordered
+        end
+
+        # Get count of attached files
+        # @return [Integer]
+        def count
+          attachments.count
+        end
+
+        alias size count
+        alias length count
+
+        # Check if empty
+        # @return [Boolean]
+        def empty?
+          !attached?
+        end
+
+        # Get first attachment
+        # @return [FileAttachment, nil]
+        def first
+          attachments.first
+        end
+
+        # Get last attachment
+        # @return [FileAttachment, nil]
+        def last
+          attachments.last
+        end
+
+        # Find attachment by file_key
+        # @param file_key [String]
+        # @return [FileAttachment, nil]
+        def find_by_key(file_key)
+          attachments.find_by(file_key: file_key)
+        end
+
+        # Filter to only images
+        # @return [ActiveRecord::Relation]
+        def images
+          attachments.images
+        end
+
+        # Filter to only PDFs
+        # @return [ActiveRecord::Relation]
+        def pdfs
+          attachments.pdfs
+        end
+
+        # Filter to only videos
+        # @return [ActiveRecord::Relation]
+        def videos
+          attachments.videos
+        end
+
+        # Get total size of all attachments
+        # @return [Integer]
+        def total_size
+          attachments.sum(:size)
+        end
+
+        # Get human-readable total size
+        # @return [String]
+        def human_total_size
+          ActiveSupport::NumberHelper.number_to_human_size(total_size)
+        end
+
+        # Get upload errors
+        # @return [Array<String>]
+        attr_reader :errors
+
+        # Serialize for JSON
+        # @return [Array<Hash>]
+        def as_json(options = {})
+          attachments.map { |att| att.as_json(options) }
+        end
+
+        private
+
+        def uploader_options
+          opts = {}
+          opts[:max_size] = @options[:max_size] if @options[:max_size]
+          opts[:allowed_types] = @options[:allowed_types] if @options[:allowed_types]
+          opts
+        end
+      end
+    end
+  end
+end

data/app/models/dscf/core/file_attachment.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+module Dscf
+  module Core
+    # FileAttachment model - stores file metadata with polymorphic association
+    # This is the central table for ALL file attachments across ALL engines
+    #
+    # @example Direct usage (rarely needed)
+    #   attachment = Dscf::Core::FileAttachment.find(1)
+    #   attachment.download     # => binary data
+    #   attachment.url          # => "/dscf/core/files/..."
+    #   attachment.purge        # => deletes from MinIO and database
+    #
+    # @example Querying across all attachments
+    #   Dscf::Core::FileAttachment.images          # => all image attachments
+    #   Dscf::Core::FileAttachment.pdfs            # => all PDF attachments
+    #   Dscf::Core::FileAttachment.sum(:size)      # => total storage used
+    #
+    class FileAttachment < ApplicationRecord
+      # Associations
+      belongs_to :attachable, polymorphic: true
+      belongs_to :uploaded_by, polymorphic: true, optional: true
+
+      # Validations
+      validates :name, presence: true
+      validates :file_key, presence: true, uniqueness: true
+      validates :filename, presence: true
+      validates :content_type, presence: true
+      validates :size, presence: true, numericality: {greater_than: 0}
+      validates :attachable_type, presence: true
+      validates :attachable_id, presence: true
+
+      # Callbacks
+      before_destroy :purge_from_storage
+
+      # Scopes
+      scope :with_name, ->(name) { where(name: name.to_s) }
+      scope :images, -> { where("content_type LIKE ?", "image/%") }
+      scope :pdfs, -> { where(content_type: "application/pdf") }
+      scope :videos, -> { where("content_type LIKE ?", "video/%") }
+      scope :ordered, -> { order(position: :asc, created_at: :asc) }
+      scope :recent, -> { order(created_at: :desc) }
+      scope :by_type, ->(type) { where(content_type: type) }
+      scope :larger_than, ->(bytes) { where("size > ?", bytes) }
+      scope :smaller_than, ->(bytes) { where("size < ?", bytes) }
+      scope :uploaded_by, ->(record) { where(uploaded_by: record) }
+
+      # Class methods for analytics
+      class << self
+        def total_storage
+          sum(:size) || 0
+        end
+
+        # Ransack configuration for filtering
+        def ransackable_attributes(_auth_object = nil)
+          %w[id name filename content_type size attachable_type attachable_id
+             uploaded_by_type uploaded_by_id position created_at updated_at]
+        end
+
+        def ransackable_associations(_auth_object = nil)
+          %w[attachable uploaded_by]
+        end
+
+        def storage_by_model
+          group(:attachable_type).sum(:size)
+        end
+
+        def storage_by_content_type
+          group(:content_type).sum(:size)
+        end
+
+        def count_by_model
+          group(:attachable_type).count
+        end
+      end
+
+      # Download the actual file content from MinIO
+      # @return [String] binary file data
+      def download
+        result = storage_client.download(file_key)
+        result[:data]
+      rescue FileStorage::Client::DownloadError => e
+        Rails.logger.error("Failed to download file #{file_key}: #{e.message}")
+        nil
+      end
+
+      # Get the download URL for this attachment
+      # Works across all engines that mount dscf-core
+      # @param _expires_in [ActiveSupport::Duration] URL expiration time (reserved for future signed URLs)
+      # @return [String] the download URL
+      def url(_expires_in: 1.hour)
+        # Try to get URL through main app's mounted engine routes (most reliable)
+        if defined?(Rails.application) && Rails.application.routes.named_routes.key?(:dscf_core)
+          Rails.application.routes.url_helpers.dscf_core.file_download_path(file_key: file_key)
+        else
+          # Fallback: Use engine routes directly (works when engine is the main app or in tests)
+          Dscf::Core::Engine.routes.url_helpers.file_download_path(file_key: file_key)
+        end
+      rescue StandardError
+        # Last resort fallback with configurable base path
+        base_path = Dscf::Core.file_download_base_path
+        "#{base_path}/#{file_key}"
+      end
+
+      # Check if the file exists in MinIO storage
+      # @return [Boolean]
+      def exists_in_storage?
+        storage_client.exists?(file_key)
+      rescue StandardError
+        false
+      end
+
+      # Get the file extension
+      # @return [String, nil]
+      def extension
+        return nil unless filename
+
+        ext = File.extname(filename).delete_prefix(".")
+        ext.presence
+      end
+
+      # Get human-readable file size
+      # @return [String, nil]
+      def human_size
+        return nil unless size
+
+        ActiveSupport::NumberHelper.number_to_human_size(size)
+      end
+
+      # Check if this is an image file
+      # @return [Boolean]
+      def image?
+        content_type&.start_with?("image/")
+      end
+
+      # Check if this is a PDF file
+      # @return [Boolean]
+      def pdf?
+        content_type == "application/pdf"
+      end
+
+      # Check if this is a video file
+      # @return [Boolean]
+      def video?
+        content_type&.start_with?("video/")
+      end
+
+      # Check if attachment is properly persisted
+      # @return [Boolean]
+      def attached?
+        persisted? && file_key.present?
+      end
+
+      # Delete file from MinIO and destroy the record
+      # @return [Boolean]
+      def purge
+        purge_from_storage
+        destroy
+      end
+
+      # Delete file from MinIO and destroy the record (bang version)
+      # @return [Boolean]
+      def purge!
+        purge_from_storage
+        destroy!
+      end
+
+      # Serialize for JSON API responses
+      # @return [Hash]
+      def as_json(_options = {})
+        {
+          id: id,
+          file_key: file_key,
+          filename: filename,
+          content_type: content_type,
+          size: size,
+          human_size: human_size,
+          extension: extension,
+          is_image: image?,
+          is_pdf: pdf?,
+          is_video: video?,
+          url: url,
+          position: position,
+          created_at: created_at&.iso8601,
+          metadata: metadata
+        }
+      end
+
+      private
+
+      def storage_client
+        @storage_client ||= FileStorage::Client.new
+      end
+
+      def purge_from_storage
+        return unless file_key.present?
+
+        storage_client.delete(file_key)
+      rescue StandardError => e
+        Rails.logger.error("Failed to purge file #{file_key} from storage: #{e.message}")
+        # Don't raise - allow the database record to be deleted even if MinIO fails
+      end
+    end
+  end
+end

data/app/models/dscf/core/permission.rb

@@ -0,0 +1,27 @@
+module Dscf
+  module Core
+    class Permission < ApplicationRecord
+      validates :code, presence: true, uniqueness: {case_sensitive: false}
+      validates :resource, presence: true
+      validates :action, presence: true
+      validates :engine, presence: true
+      validates :resource, uniqueness: {scope: %i[action engine], message: "action and engine combination already exists"}
+
+      has_many :role_permissions, class_name: "Dscf::Core::RolePermission", dependent: :destroy
+      has_many :roles, through: :role_permissions, class_name: "Dscf::Core::Role"
+
+      scope :active, -> { where(active: true) }
+      scope :inactive, -> { where(active: false) }
+      scope :by_resource, ->(resource) { where(resource: resource.to_s) }
+      scope :by_engine, ->(engine) { where(engine: engine.to_s) }
+
+      def self.ransackable_attributes(_auth_object = nil)
+        %w[id code resource action engine description active created_at updated_at]
+      end
+
+      def self.ransackable_associations(_auth_object = nil)
+        %w[role_permissions roles]
+      end
+    end
+  end
+end

data/app/models/dscf/core/role.rb

@@ -4,15 +4,20 @@ module Dscf
       validates :code, presence: true, uniqueness: true
       validates :name, presence: true
 
-      has_many :user_roles, class_name: "Dscf::Core::UserRole"
+      has_many :user_roles, class_name: "Dscf::Core::UserRole", dependent: :destroy
       has_many :users, through: :user_roles, class_name: "Dscf::Core::User"
+      has_many :role_permissions, class_name: "Dscf::Core::RolePermission", dependent: :destroy
+      has_many :permissions, through: :role_permissions, class_name: "Dscf::Core::Permission"
+
+      scope :active, -> { where(active: true) }
+      scope :inactive, -> { where(active: false) }
 
       def self.ransackable_attributes(_auth_object = nil)
-        %w[id code name created_at updated_at]
+        %w[id code name description active created_at updated_at]
       end
 
       def self.ransackable_associations(_auth_object = nil)
-        %w[user_roles users reviews]
+        %w[user_roles users role_permissions permissions]
       end
     end
   end

data/app/models/dscf/core/role_permission.rb

@@ -0,0 +1,18 @@
+module Dscf
+  module Core
+    class RolePermission < ApplicationRecord
+      belongs_to :role, class_name: "Dscf::Core::Role"
+      belongs_to :permission, class_name: "Dscf::Core::Permission"
+
+      validates :permission_id, uniqueness: {scope: :role_id, message: "already assigned to this role"}
+
+      def self.ransackable_attributes(_auth_object = nil)
+        %w[id role_id permission_id created_at updated_at]
+      end
+
+      def self.ransackable_associations(_auth_object = nil)
+        %w[role permission]
+      end
+    end
+  end
+end