dscf-core 0.2.5 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76a29d2a9907fa50b70a858a3e0a01824f2f6168b54733d5bb22428552add9d2
-  data.tar.gz: e6cc6b64f3eaa57d5b29bed770f9ddeec43d462dd2cd23fa3f4bc8cde97bb1ef
+  metadata.gz: 230e498b674cb3acf80fd9c7637b89c3e8da0e697a108f5d1b8998b9218eda59
+  data.tar.gz: d62246472662f80db9df2478a08afa9eebd163af916aa9a70f408ccbe695bf25
 SHA512:
-  metadata.gz: 23411e23576b4f5fb2a0a32a505b5d21025535b511e63430c1fac639e4a2e5f1417f99caf09a45d9a2c49917d4462faebacbbf17963db7b91daab7ec37cc8ad9
-  data.tar.gz: e368003213a383cb9afcacf105c33c0d1fadd2acb1dd08a3ccc3039d28140cadb328c67cc5637758de604b9b9753bb3f5e96bb0926a75eb6a2ba890b05011e98
+  metadata.gz: aadfeecee56e8ffc6ade9f47f244a7e313b23e23913dd99636c0bcff48fa53deb029c0461c8f92d4094352932f99f9941c3de5c97987a5f71bad92aec01364e5
+  data.tar.gz: 5ec8e1e44f084814ba4139be60f4f9c306f42eb383aced86d12764c61a205369242a09e72450f98104e7cb15bece45680210473827dbb691d9c05388581b188b

data/app/controllers/concerns/dscf/core/auditable_controller.rb

@@ -0,0 +1,539 @@
+module Dscf
+  module Core
+    # Custom exception for missing auditable record
+    class AuditableRecordNotFoundError < StandardError; end
+
+    module AuditableController
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :_audit_configs, default: []
+        class_attribute :_explicit_auditable_model, default: nil
+
+        before_action :capture_audit_snapshot, if: :audit_needed?
+        after_action :enqueue_audit, if: :audit_needed?
+      end
+
+      class_methods do
+        # DSL: Define what to audit
+        # auditable associated: [:reviews], only: [:status], on: [:approve, :reject]
+        # auditable only: [:name, :email], on: [:create, :update]
+        def auditable(associated: [], only: [], except: [], on: [], action: nil, transactional: true)
+          # Validate configuration
+          validate_audit_config!(associated: associated, only: only, except: except, on: on, action: action)
+
+          config = {
+            associated: Array(associated),
+            only: Array(only),
+            except: Array(except),
+            on: Array(on).map(&:to_sym),
+            action: action,
+            transactional: transactional
+          }
+          self._audit_configs += [config]
+        end
+
+        # Validate audit configuration at definition time
+        def validate_audit_config!(associated:, only:, except:, on:, action:)
+          # Validate associated is array of symbols
+          Array(associated).each do |assoc|
+            unless assoc.is_a?(Symbol)
+              raise ArgumentError, "auditable associated: must be an array of symbols, got #{assoc.class} for #{assoc.inspect}"
+            end
+          end
+
+          # Validate only/except don't overlap
+          only_arr = Array(only).map(&:to_sym)
+          except_arr = Array(except).map(&:to_sym)
+          overlap = only_arr & except_arr
+          if overlap.any?
+            Rails.logger.warn "⚠️  Auditable config warning: 'only' and 'except' overlap for fields: " \
+                              "#{overlap.join(', ')}. 'except' will take precedence."
+          end
+
+          # Validate action format
+          if action.present?
+            unless action.is_a?(String) || action.is_a?(Hash)
+              raise ArgumentError, "auditable action: must be a String or Hash, got #{action.class}"
+            end
+
+            if action.is_a?(Hash)
+              action.each do |key, value|
+                unless key.is_a?(Symbol) && value.is_a?(String)
+                  raise ArgumentError, "auditable action: Hash keys must be Symbols and values must be Strings"
+                end
+              end
+            end
+          end
+
+          # Validate on actions
+          on_arr = Array(on).map(&:to_sym)
+          valid_actions = %i[index show create update destroy approve reject request_modification resubmit submit]
+          invalid_actions = on_arr - valid_actions
+          return unless invalid_actions.any? && !Rails.env.production?
+
+          Rails.logger.warn "⚠️  Auditable config warning: Unknown actions detected: #{invalid_actions.join(', ')}. " \
+                            "Make sure these are valid controller actions."
+        end
+
+        # DSL: Explicitly set the model class (optional)
+        def auditable_model(klass)
+          self._explicit_auditable_model = klass
+        end
+
+        # DSL: Define action-specific record resolution (optional)
+        # Override auto-discovery for specific actions where needed
+        #
+        # Example:
+        #   auditable_record_for :approve, -> { @reviewable_resource }
+        #   auditable_record_for :reject, -> { @reviewable_resource }
+        #
+        # Or using a map:
+        #   def auditable_record_map
+        #     {
+        #       approve: -> { @reviewable_resource },
+        #       reject:  -> { @reviewable_resource },
+        #       custom_action: -> { @my_custom_var }
+        #     }
+        #   end
+        def auditable_record_for(action_name, resolver = nil, &block)
+          self._audit_configs ||= []
+          resolver_proc = block || resolver
+
+          raise ArgumentError, "auditable_record_for requires a block or lambda" unless resolver_proc
+
+          # Store in class attribute for later access
+          @_auditable_record_resolvers ||= {}
+          @_auditable_record_resolvers[action_name.to_sym] = resolver_proc
+        end
+
+        def auditable_record_resolvers
+          @_auditable_record_resolvers || {}
+        end
+      end
+
+      private
+
+      # Check if current action needs auditing
+      def audit_needed?
+        return false if _audit_configs.empty?
+
+        _audit_configs.any? { |c| c[:on].empty? || c[:on].include?(action_name.to_sym) }
+      end
+
+      # Step 1: Capture state BEFORE action executes
+      def capture_audit_snapshot
+        @audit_snapshot = {}
+
+        # For create actions, we'll capture after the record is created
+        if action_name.to_sym == :create
+          @audit_snapshot[:is_create] = true
+          @audit_snapshot[:before_main] = nil
+          @audit_snapshot[:before_associated] = {}
+          Rails.logger.debug "Audit: Create action detected, will capture state after creation"
+          return
+        end
+
+        record = resolve_auditable_record
+        return unless record
+
+        # Store record identification
+        @audit_snapshot[:record_id] = record.id
+        @audit_snapshot[:record_type] = record.class.name
+
+        # Capture current state of main record
+        @audit_snapshot[:before_main] = capture_record_state(record)
+
+        # Capture current state of associations
+        @audit_snapshot[:before_associated] = {}
+        active_configs.each do |config|
+          config[:associated].each do |assoc_name|
+            next unless record.respond_to?(assoc_name)
+
+            begin
+              assoc_records = Array(record.public_send(assoc_name)).compact
+              @audit_snapshot[:before_associated][assoc_name] = assoc_records.map { |r| capture_record_state(r) }
+            rescue StandardError => e
+              Rails.logger.debug "Audit: Could not capture #{assoc_name}: #{e.message}"
+            end
+          end
+        end
+
+        # Clear memoization to allow fresh resolution in after_action
+        # This handles cases where controllers reload/modify the record (e.g., Common module)
+        remove_instance_variable(:@resolve_auditable_record) if defined?(@resolve_auditable_record)
+      rescue StandardError => e
+        Rails.logger.warn "Audit snapshot failed: #{e.message}"
+        @audit_snapshot = nil
+      end
+
+      # Step 2: Enqueue audit job AFTER action completes
+      def enqueue_audit
+        Rails.logger.debug "Audit: enqueue_audit called for #{action_name}"
+
+        unless @audit_snapshot.present?
+          Rails.logger.debug "Audit: No snapshot present, skipping"
+          return
+        end
+
+        # For create actions, check early if we should skip auditing
+        # This prevents misleading error logs for validation failures
+        if @audit_snapshot[:is_create]
+          # Try to find the record WITHOUT triggering error logging
+          model_klass = _explicit_auditable_model || detect_model_class
+          record = find_created_record_quietly(model_klass)
+
+          if record.nil? || !record.persisted?
+            Rails.logger.debug "Audit: Skipping failed create (record not persisted)"
+            return
+          end
+
+          # Set record info for successful create
+          @audit_snapshot[:record_id] = record.id
+          @audit_snapshot[:record_type] = record.class.name
+          Rails.logger.debug "Audit: Set record info for create action"
+        end
+
+        # Now resolve the record (for both create and other actions)
+        record = resolve_auditable_record
+
+        # For non-create actions, fail fast if we can't find the record
+        unless record
+          # CRITICAL: Fail fast if we can't find the record
+          log_resolution_failure(detect_model_class, action_name.to_sym)
+          return
+        end
+
+        Rails.logger.debug "Audit: Found record #{record.class.name}##{record.id}"
+
+        # Capture state AFTER action
+        after_main = capture_record_state(record)
+        after_associated = {}
+
+        active_configs.each do |config|
+          config[:associated].each do |assoc_name|
+            next unless record.respond_to?(assoc_name)
+
+            begin
+              # Reload association to get fresh state
+              record.association(assoc_name).reload if record.association(assoc_name).loaded?
+              assoc_records = Array(record.public_send(assoc_name)).compact
+              after_associated[assoc_name] = assoc_records.map { |r| capture_record_state(r) }
+              Rails.logger.debug "Audit: Captured #{assoc_records.count} #{assoc_name} records"
+            rescue StandardError => e
+              Rails.logger.debug "Audit: Could not capture after state for #{assoc_name}: #{e.message}"
+            end
+          end
+        end
+
+        Rails.logger.debug "Audit: Enqueuing job with #{active_configs.count} configs"
+
+        # Check if any config requires transactional safety
+        requires_transaction = active_configs.any? { |c| c[:transactional] != false }
+
+        # Enqueue job with complete snapshot
+        job_args = {
+          record_id: @audit_snapshot[:record_id],
+          record_type: @audit_snapshot[:record_type],
+          before_main: @audit_snapshot[:before_main],
+          after_main: after_main,
+          before_associated: @audit_snapshot[:before_associated] || {},
+          after_associated: after_associated,
+          actor_id: current_actor&.id,
+          actor_type: current_actor&.class&.name,
+          action_name: action_name,
+          controller_name: controller_name,
+          request_uuid: request.uuid,
+          ip_address: request.remote_ip,
+          user_agent: request.user_agent,
+          configs: active_configs.map { |c| c.except(:block) }
+        }
+
+        if requires_transaction
+          # For critical actions, ensure audit is enqueued synchronously within transaction
+          # This prevents data commits without corresponding audit trail
+          begin
+            AuditLoggerJob.perform_later(**job_args)
+            Rails.logger.debug "Audit: Job enqueued successfully (transactional)"
+          rescue StandardError => e
+            # Re-raise to trigger transaction rollback
+            Rails.logger.error "CRITICAL: Audit enqueue failed - transaction will rollback: #{e.message}"
+            raise Dscf::Core::AuditableRecordNotFoundError,
+                  "Critical Audit Failure: Could not enqueue audit job. Transaction rolled back to prevent untracked changes."
+          end
+        else
+          # For non-critical actions, log errors but don't block the transaction
+          AuditLoggerJob.perform_later(**job_args)
+          Rails.logger.debug "Audit: Job enqueued successfully (non-transactional)"
+        end
+      rescue Dscf::Core::AuditableRecordNotFoundError
+        # Re-raise audit errors to trigger rollback
+        raise
+      rescue StandardError => e
+        # Handle other unexpected errors based on transactional requirement
+        Rails.logger.error "Audit enqueue failed: #{e.message}\n#{e.backtrace.first(5).join("\n")}"
+        requires_transaction = active_configs.any? { |c| c[:transactional] != false }
+        if requires_transaction
+          raise Dscf::Core::AuditableRecordNotFoundError,
+                "Critical Audit Failure: Unexpected error during audit enqueue. Transaction rolled back."
+        end
+      end
+
+      # Capture complete state of a record
+      def capture_record_state(record)
+        return nil unless record&.persisted?
+
+        {
+          id: record.id,
+          type: record.class.name,
+          attributes: record.attributes.dup,
+          timestamp: Time.current.to_f
+        }
+      rescue StandardError => e
+        Rails.logger.debug "Could not capture record state: #{e.message}"
+        nil
+      end
+
+      # Get active audit configs for current action
+      def active_configs
+        _audit_configs.select { |c| c[:on].empty? || c[:on].include?(action_name.to_sym) }
+      end
+
+      # Resolve the main record being audited
+      def resolve_auditable_record
+        return @resolve_auditable_record if defined?(@resolve_auditable_record)
+
+        @resolve_auditable_record = perform_record_resolution
+      end
+
+      # Perform the actual record resolution logic
+      def perform_record_resolution
+        model_klass = _explicit_auditable_model || detect_model_class
+        return nil unless model_klass.respond_to?(:ancestors) && model_klass.ancestors.include?(ActiveRecord::Base)
+
+        current_action = action_name.to_sym
+
+        # Priority 0: Action-specific resolver (explicit configuration via DSL)
+        resolver = self.class.auditable_record_resolvers[current_action]
+        if resolver
+          begin
+            record = instance_exec(&resolver)
+            if record.is_a?(model_klass)
+              Rails.logger.debug "Audit: Found record via action-specific resolver for :#{current_action}"
+              return record
+            elsif record.present?
+              Rails.logger.warn "Audit: Action-specific resolver for :#{current_action} returned " \
+                                "#{record.class.name}, expected #{model_klass.name}"
+            end
+          rescue StandardError => e
+            Rails.logger.error "Audit: Action-specific resolver for :#{current_action} failed: #{e.message}"
+          end
+        end
+
+        # Priority 1: Instance method map (auditable_record_map)
+        if respond_to?(:auditable_record_map, true)
+          begin
+            record_map = auditable_record_map
+            if record_map.is_a?(Hash) && record_map[current_action]
+              resolver_proc = record_map[current_action]
+              record = instance_exec(&resolver_proc)
+              if record.is_a?(model_klass)
+                Rails.logger.debug "Audit: Found record via auditable_record_map for :#{current_action}"
+                return record
+              end
+            end
+          rescue StandardError => e
+            Rails.logger.warn "Audit: auditable_record_map failed for :#{current_action}: #{e.message}"
+          end
+        end
+
+        # Priority 2: Generic hook method (auditable_record)
+        if respond_to?(:auditable_record, true)
+          record = auditable_record
+          if record.is_a?(model_klass)
+            Rails.logger.debug "Audit: Found record via auditable_record hook"
+            return record
+          end
+        end
+
+        # Priority 3: Check ALL instance variables for objects of the model class
+        instance_variables.each do |ivar|
+          # Skip internal audit instance variables
+          next if ivar.to_s.start_with?("@__")
+
+          obj = instance_variable_get(ivar)
+          if obj.is_a?(model_klass)
+            Rails.logger.debug "Audit: Found record via instance variable #{ivar}"
+            return obj
+          end
+        end
+
+        # Priority 4: Try standard Rails @model_name pattern (e.g., @business)
+        ivar_name = "@#{model_klass.name.demodulize.underscore}"
+        if instance_variable_defined?(ivar_name)
+          obj = instance_variable_get(ivar_name)
+          if obj.is_a?(model_klass)
+            Rails.logger.debug "Audit: Found record via naming convention #{ivar_name}"
+            return obj
+          end
+        end
+
+        # Priority 5: Try finding by params[:id] (for show/update/delete actions)
+        if params[:id].present? && current_action != :create
+          begin
+            record = model_klass.find(params[:id])
+            Rails.logger.debug "Audit: Found record via params[:id]"
+            return record
+          rescue ActiveRecord::RecordNotFound, ArgumentError
+            # Record not found or invalid ID
+          end
+        end
+
+        # Priority 6: For create actions, check if a record was just created
+        if current_action == :create
+          # Try to find the most recently created record
+          # This is a fallback for controllers that don't set instance variables
+          recent_record = model_klass.order(created_at: :desc).first
+          if recent_record && recent_record.created_at > 5.seconds.ago
+            Rails.logger.debug "Audit: Found record via recent creation"
+            return recent_record
+          end
+        end
+
+        # FAIL-FAST: Log helpful error message with configuration instructions
+        log_resolution_failure(model_klass, current_action)
+        nil
+      rescue StandardError => e
+        Rails.logger.error "Audit: Failed to resolve record for #{model_klass}: #{e.message}\n#{e.backtrace.first(3).join("\n")}"
+        nil
+      end
+
+      # Handle missing auditable record with environment-aware fail-fast behavior
+      #
+      # This method implements a critical safety feature:
+      # - In development/test: Raises detailed error with full diagnostic info
+      # - In production: Raises concise error and logs full details
+      #
+      # @param model_class [Class] The model class that couldn't be resolved
+      # @param action [Symbol] The controller action being audited
+      # @raise [Dscf::Core::AuditableRecordNotFoundError] Always raises to halt transaction
+      def log_resolution_failure(model_class, action)
+        # Safely collect instance variable information
+        instance_vars_info = instance_variables.filter_map do |v|
+          obj = instance_variable_get(v)
+          "  - #{v} (#{obj.class.name})"
+        rescue StandardError
+          nil
+        end.join("\n")
+
+        # Build comprehensive diagnostic message
+        detailed_message = <<~ERROR
+          ═══════════════════════════════════════════════════════════════════════════
+          🚨 AUDITABLE SYSTEM ERROR: Could not resolve record for audit logging
+          ═══════════════════════════════════════════════════════════════════════════
+
+          Controller: #{self.class.name}
+          Action: #{action}
+          Model: #{model_class.name}
+
+          The Auditable system tried to find the #{model_class.name} record but failed.
+
+          💡 SOLUTION: Define an action-specific resolver in your controller:
+
+          Option 1 - Using auditable_record_map (recommended for multiple actions):
+          ─────────────────────────────────────────────────────────────────────────
+          private
+
+          def auditable_record_map
+            {
+              #{action}: -> { @your_instance_variable }
+            }
+          end
+
+          Option 2 - Using class-level DSL:
+          ─────────────────────────────────────────────────────────────────────────
+          auditable_record_for :#{action}, -> { @your_instance_variable }
+
+          Option 3 - Using a generic hook (for all actions):
+          ─────────────────────────────────────────────────────────────────────────
+          private
+
+          def auditable_record
+            @your_instance_variable
+          end
+
+          📋 Available instance variables in controller:
+          #{instance_vars_info.presence || '  (none found)'}
+
+          ═══════════════════════════════════════════════════════════════════════════
+        ERROR
+
+        # Always log the full detailed message
+        Rails.logger.error(detailed_message)
+
+        # Environment-specific behavior
+        raise Dscf::Core::AuditableRecordNotFoundError, detailed_message unless Rails.env.production?
+
+        Rails.logger.error("[CRITICAL] Audit system failed to resolve #{model_class.name} for action :#{action} in #{self.class.name}")
+
+        # Raise concise error that will halt the transaction
+        raise Dscf::Core::AuditableRecordNotFoundError,
+              "Critical Audit Failure: Could not resolve auditable record for #{model_class.name}##{action}. " \
+              "This transaction has been rolled back to prevent untracked data changes. " \
+              "Check application logs for detailed diagnostic information."
+      end
+
+      # Find created record without triggering error logging
+      # This is used for create actions to check if record was saved before attempting full resolution
+      # @param model_klass [Class] The model class to search for
+      # @return [ActiveRecord::Base, nil] The found record or nil
+      def find_created_record_quietly(model_klass)
+        return nil unless model_klass.respond_to?(:ancestors) && model_klass.ancestors.include?(ActiveRecord::Base)
+
+        # Priority 1: Check ALL instance variables for objects of the model class
+        instance_variables.each do |ivar|
+          # Skip internal instance variables
+          next if ivar.to_s.start_with?("@__", "@audit")
+
+          obj = instance_variable_get(ivar)
+          return obj if obj.is_a?(model_klass)
+        end
+
+        # Priority 2: Try standard Rails @model_name pattern (e.g., @business_type)
+        ivar_name = "@#{model_klass.name.demodulize.underscore}"
+        if instance_variable_defined?(ivar_name)
+          obj = instance_variable_get(ivar_name)
+          return obj if obj.is_a?(model_klass)
+        end
+
+        # Priority 3: Try finding the most recently created record (fallback)
+        recent_record = model_klass.order(created_at: :desc).first
+        return recent_record if recent_record && recent_record.created_at > 5.seconds.ago
+
+        nil
+      rescue StandardError => e
+        Rails.logger.debug "Audit: Could not quietly find created record: #{e.message}"
+        nil
+      end
+
+      # Auto-detect model class from controller name
+      def detect_model_class
+        model_name = controller_name.classify
+        namespace = self.class.name.deconstantize
+
+        if namespace.present? && namespace != "Object"
+          "#{namespace}::#{model_name}".safe_constantize
+        else
+          model_name.safe_constantize
+        end
+      end
+
+      # Get current actor (user performing the action)
+      def current_actor
+        return @current_actor if defined?(@current_actor)
+
+        @current_actor = current_user if respond_to?(:current_user, true)
+      end
+    end
+  end
+end

data/app/controllers/concerns/dscf/core/common.rb

@@ -103,7 +103,11 @@ module Dscf
         end
 
         if obj.save
+          # Store in instance variable for auditing and other concerns
+          @obj = obj
+
           obj = @clazz.includes(eager_loaded_associations).find(obj.id) if eager_loaded_associations.present?
+          @obj = obj  # Update with reloaded version
 
           includes = serializer_includes_for_action(:create)
           options[:include] = includes if includes.present?
@@ -135,6 +139,7 @@ module Dscf
 
         if obj.update(model_params)
           obj = @clazz.includes(eager_loaded_associations).find(obj.id) if eager_loaded_associations.present?
+          @obj = obj  # Update with reloaded version for auditing
 
           includes = serializer_includes_for_action(:update)
           options[:include] = includes if includes.present?

data/app/controllers/concerns/dscf/core/reviewable_controller.rb

@@ -84,6 +84,7 @@ module Dscf
 
         def default_actions
           {
+            submit: {status: "pending", require_submission_ready: true},
             approve: {status: "approved"},
             reject: {status: "rejected", require_feedback: true},
             request_modification: {status: "modify", require_feedback: true},
@@ -94,9 +95,13 @@ module Dscf
         def default_context_config
           {
             default: {
-              statuses: %w[pending approved rejected modify],
-              initial_status: "pending",
-              transitions: {"pending" => %w[approved rejected modify], "modify" => ["pending"]},
+              statuses: %w[draft pending approved rejected modify],
+              initial_status: "draft",
+              transitions: {
+                "draft" => ["pending"],
+                "pending" => %w[approved rejected modify],
+                "modify" => ["pending"]
+              },
               actions: default_actions
             }
           }
@@ -141,7 +146,7 @@ module Dscf
         self.class.review_action_names.include?(action_name.to_sym)
       end
 
-      def perform_review_action(status:, require_feedback: false, after: nil, update_model: false)
+      def perform_review_action(status:, require_feedback: false, require_submission_ready: false, after: nil, update_model: false)
         begin
           context_config
         rescue ArgumentError => e
@@ -150,6 +155,14 @@ module Dscf
 
         current_review = reviewable_resource.current_review_for(current_review_context)
 
+        # Check if submission is ready (for submit action)
+        if require_submission_ready && !submission_ready?(reviewable_resource)
+          return render_error(
+            errors: ["Resource must be complete and valid before submission"],
+            status: :unprocessable_entity
+          )
+        end
+
         feedback = if require_feedback
                      feedback_data = params[:review_feedback]
                      feedback_data = feedback_data.to_unsafe_h if feedback_data.respond_to?(:to_unsafe_h)
@@ -261,6 +274,15 @@ module Dscf
         # Override for custom auth
       end
 
+      def submission_ready?(resource)
+        # Default implementation - validates the resource is ready for submission
+        # Override this method in your controller for custom validation logic
+        # Return true if ready, false otherwise
+        return true unless resource.respond_to?(:valid?)
+
+        resource.valid?
+      end
+
       def before_review_action(review)
         # Default implementation - can be overridden
         # Check if there's a custom hook method defined

data/app/controllers/dscf/core/businesses_controller.rb

@@ -9,7 +9,7 @@ module Dscf
           business = @clazz.new(model_params)
           business.user = current_user
           business.reviews.build(
-            status: "pending",
+            status: "draft",
             context: "default"
           )
 
@@ -25,6 +25,17 @@ module Dscf
         end
       end
 
+      def update
+        unless @obj.editable?
+          return render_error(
+            errors: ["Cannot update Business after submission. Use modification request workflow instead."],
+            status: :unprocessable_entity
+          )
+        end
+
+        super
+      end
+
       def my_business
         index do
           current_user.businesses

data/app/jobs/dscf/core/audit_logger_job.rb

@@ -0,0 +1,256 @@
+module Dscf
+  module Core
+    class AuditLoggerJob < ApplicationJob
+      queue_as :audit
+      retry_on StandardError, wait: 5.seconds, attempts: 3
+      discard_on ActiveRecord::RecordNotFound
+
+      def perform(record_id:, record_type:, before_main:, after_main:, before_associated:, after_associated:,
+                  action_name:, controller_name:, actor_id: nil, actor_type: nil,
+                  request_uuid: nil, ip_address: nil, user_agent: nil, configs: [])
+        # Find the auditable record
+        record = record_type.constantize.find_by(id: record_id)
+        return unless record
+
+        # Find the actor if present
+        actor = actor_id && actor_type ? actor_type.constantize.find_by(id: actor_id) : nil
+
+        # Calculate changes
+        all_changes = calculate_changes(
+          before_main: before_main,
+          after_main: after_main,
+          before_associated: before_associated,
+          after_associated: after_associated,
+          configs: configs
+        )
+
+        # Skip if no changes detected
+        # Check for empty structured format
+        return if all_changes.blank? ||
+                  (all_changes.is_a?(Hash) &&
+                   all_changes[:main].blank? &&
+                   all_changes[:associated].blank?)
+
+        # Resolve action label
+        action_label = resolve_action_label(action_name, configs)
+
+        # Create audit log
+        record.record_audit!(
+          action_label,
+          audited_changes: all_changes,
+          metadata: {
+            controller: controller_name,
+            action: action_name,
+            request_uuid: request_uuid
+          },
+          actor: actor,
+          request_uuid: request_uuid,
+          ip_address: ip_address,
+          user_agent: user_agent
+        )
+      rescue StandardError => e
+        Rails.logger.error "AuditLoggerJob failed: #{e.message}\n#{e.backtrace.first(5).join("\n")}"
+        raise
+      end
+
+      private
+
+      # Calculate all changes by comparing before/after snapshots
+      # Returns structured format: { main: { changes: {...} }, associated: { assoc_name: [...] } }
+      def calculate_changes(before_main:, after_main:, before_associated:, after_associated:, configs:)
+        structured_changes = {
+          main: {},
+          associated: {}
+        }
+
+        # Process each config
+        configs.each do |config|
+          # 1. Main record changes
+          main_changes = diff_records(before_main, after_main)
+          if main_changes.present?
+            filtered = filter_changes(main_changes, config[:only], config[:except])
+            if filtered.present?
+              structured_changes[:main][:changes] ||= {}
+              structured_changes[:main][:changes].merge!(filtered)
+            end
+          end
+
+          # 2. Associated record changes
+          config[:associated].each do |assoc_name|
+            assoc_key = assoc_name.to_sym
+            before_assoc = before_associated[assoc_key] || []
+            after_assoc = after_associated[assoc_key] || []
+
+            assoc_changes = diff_associated_records(before_assoc, after_assoc, assoc_name)
+            next unless assoc_changes.present?
+
+            # Apply filtering to associated changes
+            filtered_assoc_changes = filter_associated_changes(assoc_changes, config[:only], config[:except])
+            next unless filtered_assoc_changes.present?
+
+            # Structure: { "reviews.123" => { action: "created", changes: {...} } }
+            # Convert to: { reviews: [{ id: 123, action: "created", model: "Review", changes: {...} }] }
+            structured_changes[:associated][assoc_name.to_s] ||= []
+
+            filtered_assoc_changes.each do |key, value|
+              # Extract record ID from key like "reviews.123"
+              record_id = key.to_s.split(".").last
+              model_name = after_assoc.find { |r| r[:id].to_s == record_id }&.dig(:type) ||
+                           before_assoc.find { |r| r[:id].to_s == record_id }&.dig(:type) ||
+                           assoc_name.to_s.singularize.camelize
+
+              structured_changes[:associated][assoc_name.to_s] << {
+                id: record_id.to_i,
+                action: value[:action] || value["action"],
+                model: model_name,
+                changes: value[:changes] || value["changes"] || {}
+              }
+            end
+          end
+        end
+
+        # Return flat hash if no changes (for compatibility)
+        return {} if structured_changes[:main].empty? && structured_changes[:associated].empty?
+
+        structured_changes
+      end
+
+      # Diff two record states (before/after)
+      def diff_records(before, after)
+        return {} if after.blank?
+
+        # For create actions, before is nil - treat all attributes as new
+        if before.blank?
+          changes = {}
+          after_attrs = after[:attributes] || {}
+          after_attrs.each do |key, new_val|
+            # Skip timestamps and IDs for create
+            next if %w[id created_at updated_at].include?(key.to_s)
+            # Skip nil valbues
+            next if new_val.nil?
+
+            changes[key] = {old: nil, new: new_val}
+          end
+          return changes
+        end
+
+        return {} if before[:id] != after[:id]
+
+        changes = {}
+        before_attrs = before[:attributes] || {}
+        after_attrs = after[:attributes] || {}
+
+        # Find changed attributes
+        all_keys = (before_attrs.keys + after_attrs.keys).uniq
+        all_keys.each do |key|
+          old_val = before_attrs[key]
+          new_val = after_attrs[key]
+
+          # Skip if unchanged
+          next if old_val == new_val
+
+          changes[key] = {old: old_val, new: new_val}
+        end
+
+        changes
+      end
+
+      # Diff associated records (handle create/update/delete)
+      def diff_associated_records(before_list, after_list, assoc_name)
+        changes = {}
+
+        # Build ID maps
+        before_map = before_list.each_with_object({}) { |rec, h| h[rec[:id]] = rec if rec[:id] }
+        after_map = after_list.each_with_object({}) { |rec, h| h[rec[:id]] = rec if rec[:id] }
+
+        # Detect created records (in after but not in before)
+        after_map.each do |id, after_rec|
+          next if before_map[id]
+
+          changes["#{assoc_name}.#{id}"] = {
+            action: "created",
+            attributes: after_rec[:attributes]
+          }
+        end
+
+        # Detect updated records (in both, but with differences)
+        before_map.each do |id, before_rec|
+          after_rec = after_map[id]
+          next unless after_rec
+
+          record_changes = diff_records(before_rec, after_rec)
+          next unless record_changes.present?
+
+          changes["#{assoc_name}.#{id}"] = {
+            action: "updated",
+            changes: record_changes
+          }
+
+          # Detect deleted records (in before but not in after)
+          next if after_map[id]
+
+          changes["#{assoc_name}.#{id}"] = {
+            action: "deleted",
+            attributes: before_rec[:attributes]
+          }
+        end
+
+        changes
+      end
+
+      # Filter changes based on only/except rules
+      def filter_changes(changes, only, except)
+        return changes if only.blank? && except.blank?
+
+        filtered = changes.dup
+        filtered = filtered.slice(*only.map(&:to_s)) if only.present?
+        filtered = filtered.except(*except.map(&:to_s)) if except.present?
+        filtered
+      end
+
+      # Filter associated changes
+      # Input: { "reviews.46" => { action: "updated", changes: {...} } }
+      # Output: Same structure but with filtered changes
+      def filter_associated_changes(assoc_changes, only, except)
+        return assoc_changes if only.blank? && except.blank?
+
+        filtered = {}
+
+        assoc_changes.each do |key, record_data|
+          # Filter attributes (for created/deleted records)
+          if record_data[:attributes].present?
+            filtered_attrs = filter_changes(record_data[:attributes], only, except)
+            next if filtered_attrs.blank?
+
+            filtered[key] = record_data.merge(attributes: filtered_attrs)
+          # Filter changes (for updated records)
+          elsif record_data[:changes].present?
+            filtered_changes = filter_changes(record_data[:changes], only, except)
+            next if filtered_changes.blank?
+
+            filtered[key] = record_data.merge(changes: filtered_changes)
+          else
+            filtered[key] = record_data
+          end
+        end
+
+        filtered
+      end
+
+      # Resolve human-readable action label
+      def resolve_action_label(action, configs)
+        config = configs.find { |c| c[:action].present? }
+        return action.to_s.humanize unless config
+
+        case config[:action]
+        when String
+          config[:action]
+        when Hash
+          config[:action][action.to_sym] || config[:action][action.to_s] || action.to_s.humanize
+        else
+          action.to_s.humanize
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+module Dscf
+  module Core
+    module AuditableModel
+      extend ActiveSupport::Concern
+
+      included do
+        has_many :audit_logs,
+                 as: :auditable,
+                 class_name: "Dscf::Core::AuditLog",
+                 dependent: :destroy
+      end
+
+      def record_audit!(action_name, audited_changes: {}, metadata: {}, actor: nil, request_uuid: nil, ip_address: nil, user_agent: nil)
+        audit_logs.create!(
+          action: action_name,
+          audited_changes: audited_changes.presence || {},
+          metadata: metadata.presence || {},
+          actor: actor,
+          request_uuid: request_uuid,
+          ip_address: ip_address,
+          user_agent: user_agent
+        )
+      end
+
+      def audit_history(limit: 50)
+        audit_logs.order(created_at: :desc).limit(limit)
+      end
+
+      def last_audit
+        audit_logs.order(created_at: :desc).first
+      end
+    end
+  end
+end

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

@@ -20,12 +20,45 @@ module Dscf
         return current_review.status if current_review
 
         # Return default initial status for zero-config
-        "pending"
+        "draft"
       end
 
       def build_review_for(context = :default)
         reviews.build(context: context.to_s)
       end
+
+      # Helper methods for common status checks
+      def draft?(context = :default)
+        current_status_for(context) == "draft"
+      end
+
+      def pending?(context = :default)
+        current_status_for(context) == "pending"
+      end
+
+      def approved?(context = :default)
+        current_status_for(context) == "approved"
+      end
+
+      def rejected?(context = :default)
+        current_status_for(context) == "rejected"
+      end
+
+      def modification_requested?(context = :default)
+        current_status_for(context) == "modify"
+      end
+
+      # Check if resource can be edited via regular update endpoint
+      # Only draft records can be edited freely
+      # For modify status, use resubmit action with update_model: true
+      def editable?(context = :default)
+        draft?(context)
+      end
+
+      # Check if resource has been submitted
+      def submitted?(context = :default)
+        !draft?(context)
+      end
     end
   end
 end

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

@@ -0,0 +1,26 @@
+# app/models/dscf/core/audit_log.rb
+module Dscf
+  module Core
+    class AuditLog < ApplicationRecord
+      self.table_name = "dscf_core_audit_logs"
+
+      belongs_to :auditable, polymorphic: true
+      belongs_to :actor, polymorphic: true, optional: true
+
+      validates :action, presence: true
+
+      scope :for_auditable, ->(obj) { where(auditable_type: obj.class.name, auditable_id: obj.id) }
+      scope :by_actor, ->(actor) { where(actor_type: actor.class.name, actor_id: actor.id) }
+      scope :for_action, ->(name) { where(action: name.to_s) }
+      scope :recent, -> { order(created_at: :desc) }
+
+      def self.ransackable_attributes(_auth_object = nil)
+        %w[id auditable_type auditable_id action created_at updated_at]
+      end
+
+      def self.ransackable_associations(_auth_object = nil)
+        %w[auditable actor]
+      end
+    end
+  end
+end

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

@@ -22,6 +22,10 @@ module Dscf
         %w[business_type_id contact_email contact_phone created_at description id id_value name tin_number
            updated_at user_id]
       end
+
+      def self.ransackable_associations(_auth_object = nil)
+        %w[user business_type documents reviews]
+      end
     end
   end
 end

data/app/serializers/dscf/core/audit_log_serializer.rb

@@ -0,0 +1,40 @@
+module Dscf
+  module Core
+    class AuditLogSerializer < ActiveModel::Serializer
+      attributes :id, :action, :audited_changes, :metadata,
+                 :request_uuid, :ip_address, :user_agent,
+                 :created_at, :updated_at
+
+      attribute :actor do
+        if object.actor
+          {
+            id: object.actor.id,
+            type: object.actor_type,
+            name: self.class.actor_display_name(object.actor)
+          }
+        end
+      end
+
+      attribute :auditable do
+        {
+          id: object.auditable_id,
+          type: object.auditable_type
+        }
+      end
+
+      def self.actor_display_name(actor)
+        return nil unless actor
+
+        if actor.respond_to?(:full_name) && actor.full_name.present?
+          actor.full_name
+        elsif actor.respond_to?(:name) && actor.name.present?
+          actor.name
+        elsif actor.respond_to?(:email)
+          actor.email
+        else
+          "#{actor.class.name.demodulize} ##{actor.id}"
+        end
+      end
+    end
+  end
+end

data/config/locales/en.yml

@@ -40,6 +40,7 @@ en:
       show: "Business details retrieved successfully"
       create: "Business created successfully"
       update: "Business updated successfully"
+      submit: "Business submitted successfully"
       approve: "Business approved successfully"
       reject: "Business rejected successfully"
       request_modification: "Business modification requested successfully"
@@ -50,6 +51,7 @@ en:
       show: "Business not found"
       create: "Failed to create business"
       update: "Failed to update business"
+      submit: "Failed to submit business"
       approve: "Failed to approve business"
       reject: "Failed to reject business"
       request_modification: "Failed to request modification for business"

data/config/routes.rb

@@ -4,6 +4,7 @@ Dscf::Core::Engine.routes.draw do
       get "my_business"
     end
     member do
+      patch "submit"
       patch "approve"
       patch "reject"
       patch "request_modification"

data/db/migrate/20250926102025_create_dscf_core_reviews.rb

@@ -3,7 +3,7 @@ class CreateDscfCoreReviews < ActiveRecord::Migration[8.0]
     create_table :dscf_core_reviews do |t|
       t.references :reviewable, polymorphic: true, null: false
       t.string :context
-      t.string :status, default: "pending"
+      t.string :status, default: "draft"
       t.jsonb :feedback
       t.references :reviewed_by, polymorphic: true
       t.datetime :reviewed_at

data/db/migrate/20251023000000_create_dscf_core_audit_logs.rb

@@ -0,0 +1,25 @@
+class CreateDscfCoreAuditLogs < ActiveRecord::Migration[6.1]
+  def change
+    create_table :dscf_core_audit_logs do |t|
+      t.references :auditable, polymorphic: true, null: false
+
+      t.string :action, null: false
+      t.jsonb :audited_changes, null: false, default: {}
+      t.jsonb :metadata, default: {}
+
+      t.references :actor, polymorphic: true
+
+      t.string :request_uuid
+      t.string :ip_address
+      t.string :user_agent
+
+      t.timestamps
+    end
+
+    add_index :dscf_core_audit_logs, %i[auditable_type auditable_id], name: "index_audit_logs_on_auditable"
+    add_index :dscf_core_audit_logs, %i[actor_type actor_id], name: "index_audit_logs_on_actor"
+    add_index :dscf_core_audit_logs, :request_uuid
+    add_index :dscf_core_audit_logs, :created_at
+    add_index :dscf_core_audit_logs, :action
+  end
+end

data/lib/dscf/core/version.rb

@@ -1,5 +1,5 @@
 module Dscf
   module Core
-    VERSION = "0.2.5".freeze
+    VERSION = "0.2.6".freeze
   end
 end

data/spec/factories/auditable_test_model.rb

@@ -0,0 +1,11 @@
+FactoryBot.define do
+  factory :auditable_test_model, class: "AuditableTestModel" do
+    name { Faker::Company.name }
+    description { Faker::Company.catch_phrase }
+    contact_email { Faker::Internet.email }
+    contact_phone { Faker::PhoneNumber.phone_number }
+    tin_number { Faker::Number.number(digits: 10).to_s }
+    user
+    business_type
+  end
+end

data/spec/factories/dscf/core/audit_logs.rb

@@ -0,0 +1,12 @@
+FactoryBot.define do
+  factory :audit_log, class: "Dscf::Core::AuditLog" do
+    auditable { association :business }
+    action { "update" }
+    audited_changes { {"name" => ["Old name", "New name"]} }
+    metadata { {} }
+    actor { association :user }
+    request_uuid { SecureRandom.uuid }
+    ip_address { "127.0.0.1" }
+    user_agent { "RSpec" }
+  end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: dscf-core
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.2.6
 platform: ruby
 authors:
 - Asrat
 bindir: bin
 cert_chain: []
-date: 2025-10-13 00:00:00.000000000 Z
+date: 2025-11-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -425,6 +425,7 @@ files:
 - MIT-LICENSE
 - README.md
 - Rakefile
+- app/controllers/concerns/dscf/core/auditable_controller.rb
 - app/controllers/concerns/dscf/core/authenticatable.rb
 - app/controllers/concerns/dscf/core/common.rb
 - app/controllers/concerns/dscf/core/filterable.rb
@@ -439,11 +440,14 @@ files:
 - app/controllers/dscf/core/businesses_controller.rb
 - app/errors/dscf/core/authentication_error.rb
 - app/jobs/dscf/core/application_job.rb
+- app/jobs/dscf/core/audit_logger_job.rb
 - app/mailers/dscf/core/application_mailer.rb
+- app/models/concerns/dscf/core/auditable_model.rb
 - app/models/concerns/dscf/core/reviewable_model.rb
 - app/models/concerns/dscf/core/user_authenticatable.rb
 - app/models/dscf/core/address.rb
 - app/models/dscf/core/application_record.rb
+- app/models/dscf/core/audit_log.rb
 - app/models/dscf/core/business.rb
 - app/models/dscf/core/business_type.rb
 - app/models/dscf/core/document.rb
@@ -454,6 +458,7 @@ files:
 - app/models/dscf/core/user_profile.rb
 - app/models/dscf/core/user_role.rb
 - app/serializers/dscf/core/address_serializer.rb
+- app/serializers/dscf/core/audit_log_serializer.rb
 - app/serializers/dscf/core/business_serializer.rb
 - app/serializers/dscf/core/business_type_serializer.rb
 - app/serializers/dscf/core/document_serializer.rb
@@ -482,6 +487,7 @@ files:
 - db/migrate/20250824200927_make_email_and_phone_optional_for_users.rb
 - db/migrate/20250825192113_add_defaults_to_user_profiles.rb
 - db/migrate/20250926102025_create_dscf_core_reviews.rb
+- db/migrate/20251023000000_create_dscf_core_audit_logs.rb
 - lib/dscf/core.rb
 - lib/dscf/core/engine.rb
 - lib/dscf/core/version.rb
@@ -491,7 +497,9 @@ files:
 - lib/generators/common/templates/request_spec.rb.erb
 - lib/generators/common/templates/serializer.rb.erb
 - lib/tasks/dscf/core_tasks.rake
+- spec/factories/auditable_test_model.rb
 - spec/factories/dscf/core/addresses.rb
+- spec/factories/dscf/core/audit_logs.rb
 - spec/factories/dscf/core/business_types.rb
 - spec/factories/dscf/core/businesses.rb
 - spec/factories/dscf/core/documents.rb