audit_log_rails 0.1.0

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/audit_logger/actor_context_resolver.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module AuditLogger
+  class ActorContextResolver
+    def self.call(configuration)
+      new(configuration).call
+    end
+
+    def initialize(configuration)
+      @configuration = configuration
+    end
+
+    # Resolve todos os campos de contexto do ator em um unico ponto.
+    def call
+      {
+        changed_by_id: call_resolver(:changed_by_id, configuration.changed_by_id_resolver),
+        changed_by_type: call_resolver(:changed_by_type, configuration.changed_by_type_resolver),
+        changed_by_other: normalize_json_object(call_resolver(:changed_by_other, configuration.changed_by_other_resolver)),
+        uuid: resolve_uuid,
+        ip_remote: call_resolver(:ip_remote, configuration.ip_resolver)
+      }
+    end
+
+    private
+
+    attr_reader :configuration
+
+    # Executa o resolver apenas quando ele foi configurado e isola falhas.
+    def call_resolver(label, resolver)
+      return nil if resolver.nil?
+
+      resolver.call
+    rescue StandardError => e
+      log_warning(label, e)
+      nil
+    end
+
+    # Garante que o metadado adicional sempre seja persistido como objeto JSON.
+    def normalize_json_object(value)
+      return {} if value.nil?
+      return value if value.is_a?(Hash)
+
+      { value: value }
+    end
+
+    # Mantem um fallback seguro para correlacao quando o app nao informar uuid.
+    def resolve_uuid
+      value = call_resolver(:uuid, configuration.uuid_resolver)
+      return value if value && !value.to_s.empty?
+
+      SecureRandom.uuid
+    end
+
+    # Evita que falhas de contexto derrubem a auditoria inteira da requisicao.
+    def log_warning(label, error)
+      message = "[AuditLogger] Falha ao resolver #{label}: #{error.class} - #{error.message}"
+
+      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        Rails.logger.warn(message)
+      else
+        warn(message)
+      end
+    end
+  end
+end

data/lib/audit_logger/audit_log.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module AuditLogger
+  class AuditLog < ActiveRecord::Base
+    self.table_name = "audit_logs"
+
+    JSON_FIELDS = %w[changed_by_other audited_changes audited_changes_humanize].freeze
+
+    # Mantem compatibilidade entre bancos nativos JSON/JSONB e colunas texto sem
+    # depender de conexao ativa no carregamento da classe.
+    JSON_FIELDS.each do |field_name|
+      define_method("#{field_name}=") do |value|
+        super(normalize_json_assignment(field_name, value))
+      end
+
+      define_method(field_name) do
+        deserialize_json_value(super())
+      end
+    end
+
+    private
+
+    # Em bancos sem suporte nativo a JSON, persiste como string JSON.
+    def normalize_json_assignment(field_name, value)
+      return value if value.nil? || json_like_column?(field_name)
+      return value if value.is_a?(String)
+
+      JSON.generate(value)
+    end
+
+    # Ao ler colunas texto, reconstrói o Hash/Array original para o restante da gem.
+    def deserialize_json_value(value)
+      return value unless value.is_a?(String)
+
+      JSON.parse(value)
+    rescue JSON::ParserError
+      value
+    end
+
+    # A verificacao do tipo fica em runtime, quando a conexao ja deve estar disponivel.
+    def json_like_column?(field_name)
+      self.class.type_for_attribute(field_name.to_s).type.in?([ :json, :jsonb ])
+    rescue ActiveRecord::ConnectionNotDefined, ActiveRecord::NoDatabaseError
+      false
+    end
+  end
+end

data/lib/audit_logger/auditable.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module AuditLogger
+  module Auditable
+    extend ActiveSupport::Concern
+
+    included do
+      # Guarda a configuracao local da model sem poluir instancias.
+      class_attribute :audit_logger_model_config, instance_accessor: false, default: ModelConfig.new
+      # Evita registrar os mesmos callbacks mais de uma vez.
+      class_attribute :audit_logger_callbacks_registered, instance_accessor: false, default: false
+    end
+
+    class_methods do
+      # DSL principal da gem usada pelas models do projeto cliente.
+      def auditable(**options)
+        # Mantem a configuracao por model isolada do restante da gem.
+        self.audit_logger_model_config = ModelConfig.new(**options)
+
+        # Expoe uma associacao simples para consultar os logs desta model.
+        define_audit_logs_association!
+
+        return if audit_logger_callbacks_registered
+
+        # Usa callbacks de commit para evitar auditoria falsa em caso de rollback.
+        after_create_commit { AuditLogger::RecordAuditEntry.call(self, action: :create) }
+        after_update_commit { AuditLogger::RecordAuditEntry.call(self, action: :update) }
+        after_destroy_commit { AuditLogger::RecordAuditEntry.call(self, action: :destroy) }
+
+        self.audit_logger_callbacks_registered = true
+      end
+
+      private
+
+      # Define a associacao apenas uma vez para evitar conflitos com reload da classe.
+      def define_audit_logs_association!
+        return if reflect_on_association(:audit_logs)
+
+        has_many :audit_logs,
+                 ->(record) { where(model_class_name: record.class.name) },
+                 class_name: "AuditLogger::AuditLog",
+                 foreign_key: :id_object,
+                 primary_key: :id
+      end
+    end
+  end
+end

data/lib/audit_logger/change_extractor.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module AuditLogger
+  class ChangeExtractor
+    def initialize(record:, action:, model_config:, configuration:)
+      @record = record
+      @action = action.to_s
+      @model_config = model_config
+      @configuration = configuration
+    end
+
+    # Retorna o payload bruto no formato padronizado da gem.
+    def call
+      {
+        "type" => action,
+        "fields" => extract_fields
+      }
+    end
+
+    private
+
+    attr_reader :record, :action, :model_config, :configuration
+
+    # Direciona a extracao conforme o tipo da acao auditada.
+    def extract_fields
+      case action
+      when "create"
+        snapshot_fields
+      when "update"
+        update_fields
+      when "destroy"
+        snapshot_fields
+      else
+        {}
+      end
+    end
+
+    # Usa snapshot completo em create e destroy para preservar contexto.
+    def snapshot_fields
+      filtered_attributes.each_with_object({}) do |(attribute, value), result|
+        result[attribute] = { "value" => value }
+      end
+    end
+
+    # Em update salva apenas delta com old/new para reduzir ruido.
+    def update_fields
+      filtered_previous_changes.each_with_object({}) do |(attribute, values), result|
+        old_value, new_value = values
+        result[attribute] = {
+          "old_value" => old_value,
+          "new_value" => new_value
+        }
+      end
+    end
+
+    # Remove do snapshot os atributos que nao devem ser auditados.
+    def filtered_attributes
+      record.attributes.reject do |attribute, _value|
+        ignored_attributes.include?(attribute)
+      end
+    end
+
+    # Filtra as mudancas do ActiveRecord antes de montar o delta final.
+    def filtered_previous_changes
+      record.previous_changes.reject do |attribute, _value|
+        ignored_attributes.include?(attribute)
+      end
+    end
+
+    # Memoiza a lista final de ignored attributes para nao recalcular varias vezes.
+    def ignored_attributes
+      @ignored_attributes ||= model_config.effective_ignored_attributes(configuration)
+    end
+  end
+end

data/lib/audit_logger/config_validator.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module AuditLogger
+  class ConfigValidator
+    # Campos que aceitam estrategia configuravel via Proc/Lambda.
+    CALLABLE_FIELDS = %i[
+      changed_by_id_resolver
+      changed_by_type_resolver
+      changed_by_other_resolver
+      uuid_resolver
+      ip_resolver
+      humanizer
+    ].freeze
+
+    def self.validate!(configuration)
+      new(configuration).validate!
+    end
+
+    def initialize(configuration)
+      @configuration = configuration
+    end
+
+    # Centraliza a validacao para falhar cedo no boot da aplicacao.
+    def validate!
+      validate_callable_fields!
+      validate_humanize_by_default!
+      validate_i18n_scopes!
+      validate_ignored_attributes!
+
+      configuration
+    end
+
+    private
+
+    attr_reader :configuration
+
+    # Garante que os pontos extensivos da gem sejam sempre chamaveis.
+    def validate_callable_fields!
+      CALLABLE_FIELDS.each do |field_name|
+        value = configuration.public_send(field_name)
+        next if value.nil? || value.is_a?(Proc)
+
+        raise ConfigurationError,
+              "#{field_name} deve ser um Proc/Lambda ou nil"
+      end
+    end
+
+    # Evita estados ambiguos de configuracao para humanizacao.
+    def validate_humanize_by_default!
+      return if [true, false].include?(configuration.humanize_by_default)
+
+      raise ConfigurationError,
+            "humanize_by_default deve ser true ou false"
+    end
+
+    # Obriga escopos consistentes para o fallback de traducao.
+    def validate_i18n_scopes!
+      value = configuration.i18n_scopes
+
+      unless value.is_a?(Array) && value.all? { |item| item.is_a?(String) && !item.empty? }
+        raise ConfigurationError,
+              "i18n_scopes deve ser um Array de strings nao vazias"
+      end
+    end
+
+    # Mantem a comparacao de atributos ignorados previsivel.
+    def validate_ignored_attributes!
+      value = configuration.ignored_attributes
+
+      unless value.is_a?(Array) && value.all? { |item| item.is_a?(String) || item.is_a?(Symbol) }
+        raise ConfigurationError,
+              "ignored_attributes deve ser um Array de strings ou symbols"
+      end
+    end
+  end
+end

data/lib/audit_logger/configuration.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module AuditLogger
+  class Configuration
+    # Cada accessor representa um ponto configuravel da gem.
+    attr_accessor :changed_by_id_resolver,
+                  :changed_by_type_resolver,
+                  :changed_by_other_resolver,
+                  :uuid_resolver,
+                  :ip_resolver,
+                  :humanize_by_default,
+                  :i18n_scopes,
+                  :ignored_attributes,
+                  :humanizer
+
+    def initialize
+      reset!
+    end
+
+    # Restaura todos os defaults para um estado conhecido e previsivel.
+    def reset!
+      # Defaults simples para que a gem funcione sem obrigar configuracao imediata.
+      self.changed_by_id_resolver = nil
+      self.changed_by_type_resolver = nil
+      self.changed_by_other_resolver = -> { {} }
+      self.uuid_resolver = nil
+      self.ip_resolver = nil
+      self.humanize_by_default = true
+      self.i18n_scopes = default_i18n_scopes
+      self.ignored_attributes = default_ignored_attributes
+      self.humanizer = nil
+
+      self
+    end
+
+    private
+
+    # Escopos padrao usados para localizar labels de atributos.
+    def default_i18n_scopes
+      ["activerecord.attributes", "attributes"]
+    end
+
+    # Campos normalmente ruidosos que nao agregam valor na auditoria.
+    def default_ignored_attributes
+      %i[created_at updated_at lock_version]
+    end
+  end
+end

data/lib/audit_logger/humanizer.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module AuditLogger
+  class Humanizer
+    def initialize(record:, payload:, model_config:, configuration:)
+      @record = record
+      @payload = payload
+      @model_config = model_config
+      @configuration = configuration
+    end
+
+    # Gera o payload humanizado mantendo a mesma estrutura do payload bruto.
+    def call
+      return empty_payload unless model_config.humanize_enabled?(configuration)
+
+      {
+        "type" => payload["type"],
+        "fields" => humanized_fields
+      }
+    end
+
+    private
+
+    attr_reader :record, :payload, :model_config, :configuration
+
+    # Quando a humanizacao estiver desabilitada, preserva apenas o tipo da acao.
+    def empty_payload
+      {
+        "type" => payload["type"],
+        "fields" => {}
+      }
+    end
+
+    # Humaniza campo por campo para permitir fallback individual.
+    def humanized_fields
+      payload.fetch("fields", {}).each_with_object({}) do |(attribute, values), result|
+        result[attribute] = build_field_payload(attribute, values)
+      end
+    end
+
+    # Tenta humanizer customizado primeiro e cai no comportamento padrao.
+    def build_field_payload(attribute, values)
+      custom_result = call_custom_humanizer(attribute, values)
+      return normalize_custom_result(attribute, values, custom_result) unless custom_result.nil?
+
+      default_field_payload(attribute, values)
+    end
+
+    # O humanizer recebe model, atributo e valores bruto para maximo contexto.
+    def call_custom_humanizer(attribute, values)
+      humanizer = model_config.effective_humanizer(configuration)
+      return nil if humanizer.nil?
+
+      humanizer.call(record.class, attribute, values["old_value"], values["new_value"] || values["value"])
+    rescue StandardError => e
+      log_warning(attribute, e)
+      nil
+    end
+
+    # Aceita retorno em Hash para sobrescrita rica ou valor simples para casos basicos.
+    def normalize_custom_result(attribute, values, custom_result)
+      return default_field_payload(attribute, values).merge(stringify_keys(custom_result)) if custom_result.is_a?(Hash)
+
+      default_field_payload(attribute, values).merge("value" => custom_result)
+    end
+
+    # Mantem o label traduzido e preserva os dados do payload bruto.
+    def default_field_payload(attribute, values)
+      result = { "label" => translate_attribute(attribute) }
+
+      values.each do |key, value|
+        result[key] = value
+      end
+
+      result
+    end
+
+    # Faz o fallback de traducao por escopo ate encontrar um label valido.
+    def translate_attribute(attribute)
+      scopes = model_config.effective_i18n_scopes(configuration)
+      model_key = record.class.model_name.i18n_key
+
+      scopes.each do |scope|
+        translation = I18n.t("#{scope}.#{model_key}.#{attribute}", default: nil)
+        return translation if translation
+
+        fallback = I18n.t("#{scope}.#{attribute}", default: nil)
+        return fallback if fallback
+      end
+
+      attribute.to_s.humanize
+    end
+
+    # Normaliza chaves vindas do humanizer customizado para JSON consistente.
+    def stringify_keys(hash)
+      hash.each_with_object({}) do |(key, value), result|
+        result[key.to_s] = value
+      end
+    end
+
+    # Evita que falhas no humanizer customizado interrompam a gravacao da auditoria.
+    def log_warning(attribute, error)
+      message = "[AuditLogger] Falha ao humanizar #{record.class.name}##{attribute}: #{error.class} - #{error.message}"
+
+      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        Rails.logger.warn(message)
+      else
+        warn(message)
+      end
+    end
+  end
+end

data/lib/audit_logger/model_config.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module AuditLogger
+  class ModelConfig
+    # Guarda apenas a configuracao local da model, sem misturar com a global.
+    attr_reader :humanize, :i18n_scopes, :humanizer, :ignored_attributes
+
+    def initialize(humanize: nil, i18n_scopes: nil, humanizer: nil, ignored_attributes: [])
+      @humanize = humanize
+      @i18n_scopes = i18n_scopes
+      @humanizer = humanizer
+      @ignored_attributes = Array(ignored_attributes)
+
+      validate!
+    end
+
+    # Resolve se a humanizacao ficara ativa considerando override local.
+    def humanize_enabled?(global_configuration)
+      return global_configuration.humanize_by_default if humanize.nil?
+
+      humanize
+    end
+
+    # Retorna os escopos efetivos usados para traducao desta model.
+    def effective_i18n_scopes(global_configuration)
+      return global_configuration.i18n_scopes if i18n_scopes.nil? || i18n_scopes.empty?
+
+      i18n_scopes
+    end
+
+    # Prioriza o humanizer da model e cai no global quando necessario.
+    def effective_humanizer(global_configuration)
+      humanizer || global_configuration.humanizer
+    end
+
+    # Combina ignored attributes globais e locais em uma lista unica.
+    def effective_ignored_attributes(global_configuration)
+      (global_configuration.ignored_attributes + ignored_attributes).map(&:to_s).uniq
+    end
+
+    private
+
+    # Concentra as validacoes do contrato aceito pela DSL `auditable`.
+    def validate!
+      validate_humanize!
+      validate_i18n_scopes!
+      validate_humanizer!
+      validate_ignored_attributes!
+    end
+
+    # Limita o override de humanizacao a valores simples e previsiveis.
+    def validate_humanize!
+      return if humanize.nil? || [true, false].include?(humanize)
+
+      raise ConfigurationError, "humanize da model deve ser true, false ou nil"
+    end
+
+    # Garante que o fallback de I18n nao receba dados inconsistentes.
+    def validate_i18n_scopes!
+      return if i18n_scopes.nil?
+      return if i18n_scopes.is_a?(Array) && i18n_scopes.all? { |item| item.is_a?(String) && !item.empty? }
+
+      raise ConfigurationError, "i18n_scopes da model deve ser um Array de strings nao vazias"
+    end
+
+    # Mantem o ponto de extensao da model com a mesma regra do config global.
+    def validate_humanizer!
+      return if humanizer.nil? || humanizer.is_a?(Proc)
+
+      raise ConfigurationError, "humanizer da model deve ser um Proc/Lambda ou nil"
+    end
+
+    # Normaliza a entrada para facilitar o filtro de atributos depois.
+    def validate_ignored_attributes!
+      return if ignored_attributes.all? { |item| item.is_a?(String) || item.is_a?(Symbol) }
+
+      raise ConfigurationError, "ignored_attributes da model deve ser um Array de strings ou symbols"
+    end
+  end
+end

data/lib/audit_logger/railtie.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module AuditLogger
+  class Railtie < Rails::Railtie
+    initializer "audit_logger.active_record" do
+      ActiveSupport.on_load(:active_record) do
+        include AuditLogger::Auditable
+      end
+    end
+
+    generators do
+      require_relative "../generators/audit_logger/install_generator"
+    end
+  end
+end

data/lib/audit_logger/record_audit_entry.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module AuditLogger
+  class RecordAuditEntry
+    def self.call(record, action:)
+      new(record, action: action).call
+    end
+
+    def initialize(record, action:)
+      @record = record
+      @action = action.to_s
+      @configuration = AuditLogger.configuration
+      @model_config = record.class.audit_logger_model_config
+    end
+
+    # Orquestra toda a montagem do log e persiste o resultado final.
+    def call
+      payload = ChangeExtractor.new(
+        record: record,
+        action: action,
+        model_config: model_config,
+        configuration: configuration
+      ).call
+
+      return if payload.fetch("fields", {}).empty?
+
+      # Resolve o contexto do ator e gera a versao amigavel do payload antes de persistir.
+      actor_context = ActorContextResolver.call(configuration)
+      humanized_payload = Humanizer.new(
+        record: record,
+        payload: payload,
+        model_config: model_config,
+        configuration: configuration
+      ).call
+
+      AuditLog.create!(
+        model_class_name: record.class.name,
+        id_object: resolve_record_id,
+        action: action,
+        uuid: actor_context[:uuid].to_s,
+        changed_by_id: actor_context[:changed_by_id],
+        changed_by_type: actor_context[:changed_by_type],
+        changed_by_other: actor_context[:changed_by_other],
+        audited_changes: payload,
+        audited_changes_humanize: humanized_payload,
+        ip_remote: actor_context[:ip_remote],
+        created_at: Time.current,
+        updated_at: Time.current
+      )
+    end
+
+    private
+
+    attr_reader :record, :action, :configuration, :model_config
+
+    # Normaliza o id como string para manter consistencia entre tipos de PK.
+    def resolve_record_id
+      record.id.to_s
+    end
+  end
+end

data/lib/audit_logger/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module AuditLogger
+  VERSION = "0.1.0"
+end

data/lib/audit_logger.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "audit_logger/version"
+require "active_support"
+require "active_support/concern"
+require "active_record"
+require "i18n"
+require "json"
+require "securerandom"
+require_relative "audit_logger/configuration"
+require_relative "audit_logger/config_validator"
+require_relative "audit_logger/model_config"
+require_relative "audit_logger/audit_log"
+require_relative "audit_logger/actor_context_resolver"
+require_relative "audit_logger/change_extractor"
+require_relative "audit_logger/humanizer"
+require_relative "audit_logger/record_audit_entry"
+require_relative "audit_logger/auditable"
+
+module AuditLogger
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+
+  class << self
+    # Retorna a configuracao global da gem, instanciando-a sob demanda.
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Permite configurar a gem via bloco e valida o resultado no final.
+    def configure
+      yield(configuration)
+      ConfigValidator.validate!(configuration)
+      configuration
+    end
+
+    # Facilita testes e reconfiguracao do estado global da gem.
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end
+
+require_relative "audit_logger/railtie" if defined?(Rails::Railtie)