dscf-core 0.2.5 → 0.2.7

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

@@ -78,25 +78,30 @@ module Dscf
                 status: :bad_request
               )
             end
-            perform_review_action(**action_config.slice(:status, :require_feedback, :after, :update_model))
+            perform_review_action(**action_config.slice(:status, :require_feedback, :after, :update_model, :from))
           end
         end
 
         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},
-            resubmit: {status: "pending", update_model: true}
+            resubmit: {status: "pending", update_model: true, from: "modify"}
           }
         end
 
         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
             }
           }
@@ -104,10 +109,22 @@ module Dscf
 
         def validate_action_config(actions, statuses, context_name)
           actions.each do |action_name, opts|
-            next if statuses.include?(opts[:status])
+            unless statuses.include?(opts[:status])
+              raise ArgumentError, <<~MSG
+                Action '#{action_name}' in context '#{context_name}' maps to invalid status '#{opts[:status]}'. Must be one of: #{statuses.join(', ')}
+              MSG
+            end
+
+            # Validate 'from' constraints if present
+            next unless opts[:from].present?
+
+            from_statuses = Array(opts[:from]).map(&:to_s)
+            invalid_statuses = from_statuses - statuses
+
+            next if invalid_statuses.empty?
 
             raise ArgumentError, <<~MSG
-              Action '#{action_name}' in context '#{context_name}' maps to invalid status '#{opts[:status]}'. Must be one of: #{statuses.join(', ')}
+              Action '#{action_name}' in context '#{context_name}' has invalid 'from' statuses: #{invalid_statuses.join(', ')}. Must be one of: #{statuses.join(', ')}
             MSG
           end
         end
@@ -141,7 +158,8 @@ 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,
+                                from: nil)
         begin
           context_config
         rescue ArgumentError => e
@@ -149,6 +167,28 @@ module Dscf
         end
 
         current_review = reviewable_resource.current_review_for(current_review_context)
+        current_status = current_review&.status || context_config[:initial_status]
+
+        # Check if action can be performed from the current status
+        if from.present?
+          allowed_from_statuses = Array(from).map(&:to_s)
+          unless allowed_from_statuses.include?(current_status)
+            error_message = "Action '#{action_name}' can only be performed from: " \
+                            "#{allowed_from_statuses.join(', ')}. Current status is '#{current_status}'"
+            return render_error(
+              errors: [error_message],
+              status: :unprocessable_entity
+            )
+          end
+        end
+
+        # 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]
@@ -159,10 +199,10 @@ module Dscf
                      feedback_data
                    end
 
-        unless valid_transition?(current_review&.status, status)
+        unless valid_transition?(current_status, status)
           return render_error(
             errors: [
-              "Cannot transition from '#{current_review&.status || context_config[:initial_status]}' to '#{status}'"
+              "Cannot transition from '#{current_status}' to '#{status}'"
             ]
           )
         end
@@ -261,6 +301,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,308 @@
+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?
+            # Apply main record filtering (supports only/except at root level)
+            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
+          # Support both old format (array) and new format (hash with per-association filters)
+          associations_config = normalize_associated_config(config[:associated])
+
+          associations_config.each do |assoc_name, assoc_options|
+            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 per-association filtering
+            assoc_only = assoc_options[:only]
+            assoc_except = assoc_options[:except]
+            filtered_assoc_changes = filter_associated_changes(assoc_changes, assoc_only, assoc_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
+
+      # Normalize associated config to support both array and hash formats
+      # Input: [:reviews, :comments] or { reviews: { only: [:status] }, comments: {} }
+      # Output: { reviews: { only: [...], except: [...] }, comments: { only: nil, except: nil } }
+      def normalize_associated_config(associated)
+        return {} if associated.blank?
+
+        if associated.is_a?(Array)
+          # Old format: [:reviews, :comments] -> convert to hash with no filters
+          associated.each_with_object({}) { |name, h| h[name] = {only: nil, except: nil} }
+        elsif associated.is_a?(Hash)
+          # New format: already a hash, ensure each value is a hash with only/except
+          associated.transform_values do |value|
+            if value.is_a?(Hash)
+              {only: value[:only], except: value[:except]}
+            else
+              {only: nil, except: nil}
+            end
+          end
+        else
+          {}
+        end
+      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)
+      # Automatically excludes timestamp fields (created_at, updated_at) for associated records
+      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]
+
+          # Convert attributes to change format (old: nil, new: value)
+          # Skip timestamp fields automatically
+          created_changes = {}
+          (after_rec[:attributes] || {}).each do |key, value|
+            next if %w[created_at updated_at].include?(key.to_s)
+
+            created_changes[key] = {old: nil, new: value}
+          end
+
+          changes["#{assoc_name}.#{id}"] = {
+            action: "created",
+            changes: created_changes
+          }
+        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)
+          # Skip timestamp fields from updates
+          record_changes.reject! { |key, _| %w[created_at updated_at].include?(key.to_s) }
+          next unless record_changes.present?
+
+          changes["#{assoc_name}.#{id}"] = {
+            action: "updated",
+            changes: record_changes
+          }
+        end
+
+        # Detect deleted records (in before but not in after)
+        before_map.each do |id, before_rec|
+          next if after_map[id]
+
+          # Convert attributes to change format (old: value, new: nil)
+          # Skip timestamp fields automatically
+          deleted_changes = {}
+          (before_rec[:attributes] || {}).each do |key, value|
+            next if %w[created_at updated_at].include?(key.to_s)
+
+            deleted_changes[key] = {old: value, new: nil}
+          end
+
+          changes["#{assoc_name}.#{id}"] = {
+            action: "deleted",
+            changes: deleted_changes
+          }
+        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