event_sourced_accounting 0.1.6 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d898cf40cfd5525402b244a8ebde093e0e9948fa
-  data.tar.gz: 4a925d9356d3aeee2a08790ad1b2ea28838dfc9c
+  metadata.gz: 725485c3fb1eb0802b7e7f3553a0fdb598f0c927
+  data.tar.gz: 9a5c5aef5200ebd25e0a1aadc0e791d213bac61a
 SHA512:
-  metadata.gz: 6e6c5f2d437c040f89af829811cc5b0f92b9da413c03a380479c03b6c9f2089d4ad7d7ea424833ea99a53be8f1eb112a8b6bbcd11bbd7ab3969a8f7951c4c740
-  data.tar.gz: 4d4c47371255499bcda065a9c78213a09a3ccb983388058057d4fa4db9fb60812a3e03a0686feac878b4024c527df1ea8308d95cb82a67b124b26e09a8be3d26
+  metadata.gz: b7229fe63379704b0388f1a97971a630c24f0bd2faa28fa9b89d1aca1a3887c92a9d76068cd1aa8ee0759c0e25d0c24f0a6351d82619d41593a40539bd63795b
+  data.tar.gz: 5c177694686252945b7823a5163e7f7e6023827118e2797f82918affcec077ae5aefad2710349239c0e00c94d172c4900a53fe3a35a12ad4d0fd7384ef1c751f

data/README.markdown

@@ -27,10 +27,187 @@ Installation
 
 - run migrations `rake db:migrate`
 
-- add `include ESA::Traits::Accountable` to relevant models
 
-- implement the corresponding Event, Flag, Ruleset and Transaction classes for relevant models
+Integration
+============
+
+First, configure the gem by creating `config/initializers/accounting.rb`.
+```
+require 'esa'
+
+ESA.configure do |config|
+  config.processor = ESA::BlockingProcessor # default
+  config.extension_namespace = 'Accounting' # default
+  config.register('BankTransaction')
+  ...
+end
+```
+
+Then add `include ESA::Traits::Accountable` to the registered models.
+```
+class BankTransaction < ActiveRecord::Base
+  include ESA::Traits::Accountable
+  ...
+end
+```
+
+Implement the corresponding Event, Flag, Ruleset and Transaction classes for the registered models.
+```
+# app/models/accounting/events/bank_transaction_event.rb
+module Accounting
+  module Events
+    class BankTransactionEvent < ESA::Event
+      enumerize :nature, in: [
+                        :adjustment, # mandatory
+                        :confirm,    # example
+                        :revoke,     # example
+                      ]
+    end
+  end
+end
+```
+
+```
+# app/models/accounting/flags/bank_transaction_flag.rb
+module Accounting
+  module Flags
+    class BankTransactionFlag < ESA::Flag
+      enumerize :nature, in: [
+                        :complete, # example
+                     ]
+    end
+  end
+end
+```
+
+```
+# app/models/accounting/transactions/bank_transaction_transaction.rb
+module Accounting
+  module Transactions
+    class BankTransactionTransaction < ESA::Transaction
+      # this relation definition is optional
+      has_one :bank_transaction, :through => :flag, :source => :accountable, :source_type => "BankTransaction"
+    end
+  end
+end
+```
+
+```
+# app/models/accounting/rulesets/bank_transaction_ruleset.rb
+module Accounting
+  module Rulesets
+    class BankTransactionRuleset < ESA::Ruleset
+      # events that have happened according to the current state
+      def event_times(bank_transaction)
+        {
+          confirm: bank_transaction.confirm_time,
+          revoke: bank_transaction.revoke_time,
+        }
+      end
+      
+      # flags to be changed when events occur
+      def event_nature_flags
+        {
+          confirm: {complete: true},
+          revoke: {complete: false},
+        }
+      end
+
+      # transaction for when the :complete flag is switched to true
+      def flag_complete_transactions(bank_transaction)
+        {
+          :description => 'BankTransaction completed',
+          :debits => [
+            {
+              :account => find_account('Asset', 'Bank'),
+              :amount => bank_transaction.transferred_amount
+            }
+          ],
+          :credits => [
+            {
+              :account => find_account('Asset', 'Bank Transit'),
+              :amount => bank_transaction.transferred_amount
+            }
+          ],
+        }
+      end
+    end
+  end
+end
+```
+
+Usage
+============
+
+In order to create events and transactions, the accountable objects
+have to pass through a processor, which will register the necessary
+Events, Flags & Transactions in the database.
+
+You can use the provided processor implementation, or inherit from
+the base implementation and provide your own class (e.g. to implement
+delayed or scheduled processing).
+
+```
+>> bank_transaction = BankTransaction.find(..)
+>> bank_transaction.confirm_time = Time.now
+>> bank_transaction.save
+true
+
+>> ESA.configuration.processor.enqueue(bank_transaction)
+
+>> bank_transaction.esa_events.count
+1
+
+>> bank_transaction.esa_flags.count
+1
+
+>> bank_transaction.esa_transactions.count
+1
+```
+
+Reporting
+============
 
+There are many different reporting and filtering implementations available.
+For a simple example, let's look at a report that only involves the transaction.
+
+The following commands initialize the report and update the persisted values
+to the depth of 1, which includes the creation of sub-reports per each account
+involved in the transactions of that BankAccount.
+
+```
+>> report = ESA::Contexts::AccountableContext.create(chart: ESA::Chart.first, accountable: bank_transaction)
+>> report.check_freshness(1)
+```
+
+Complex reports can be constructed automatically using the context provider
+functionality. Reports, filters and context providers are available for:
+
+- account
+- accountable object (e.g. a single BankTransaction)
+- accountable type (e.g. all known BankTransactions)
+- date periods (year, month, date, custom)
+
+Please refer to the source code for examples.
+
+Subreport structure and context providers need to be configured:
+
+```
+ESA.configure do |config|
+  ...
+  config.context_providers['bank_account'] = Accounting::ContextProviders::BankAccountContextProvider
+  
+  config.context_tree = {
+    'month' => {
+      'account' => {
+        'bank_account' => {},
+        'date' => {},
+      },
+    },
+  }
+  ...
+end
+```
 
 Development
 ============

data/app/models/esa/account.rb

@@ -31,7 +31,7 @@ module ESA
 
     enumerize :normal_balance, in: [:none, :debit, :credit]
 
-    after_initialize :default_values
+    after_initialize :initialize_defaults
 
     before_validation :update_normal_balance
     validates_presence_of :type, :name, :chart, :normal_balance
@@ -69,7 +69,7 @@ module ESA
 
     private
 
-    def default_values
+    def initialize_defaults
       self.chart ||= Chart.where(:name => 'Chart of Accounts').first_or_create if self.chart_id.nil?
       self.normal_balance ||= :none
     end

data/app/models/esa/chart.rb

@@ -18,7 +18,7 @@ module ESA
     has_many :transactions, :through => :accounts, :uniq => true
     has_many :amounts, :through => :accounts, :uniq => true, :extend => ESA::Associations::AmountsExtension
 
-    after_initialize :default_values
+    after_initialize :initialize_defaults
 
     validates_presence_of :name
     validates_uniqueness_of :name
@@ -37,7 +37,7 @@ module ESA
 
     private
 
-    def default_values
+    def initialize_defaults
       self.name ||= "Chart of Accounts"
     end
   end

data/app/models/esa/context.rb

@@ -21,7 +21,7 @@ module ESA
     belongs_to :parent, :class_name => "Context"
     has_many :subcontexts, :class_name => "Context", :foreign_key => "parent_id", :dependent => :destroy
 
-    after_initialize :default_values, :initialize_filters
+    after_initialize :initialize_defaults, :initialize_filters
     before_validation :update_name, :update_position
     validates_presence_of :chart, :name
     validate :validate_parent
@@ -75,9 +75,13 @@ module ESA
       self.freshness.present? and (self.freshness + ESA.configuration.context_freshness_threshold) > time
     end
 
-    def check_freshness(depth=0)
-      if self.is_update_needed?
-        self.update!
+    def has_subcontext_namespaces?(*namespaces)
+      (namespaces.flatten.compact - subcontext_namespaces).none?
+    end
+
+    def check_freshness(depth=0, options = {})
+      if self.is_update_needed? or not has_subcontext_namespaces?(options[:namespace])
+        self.update!(options)
       else
         self.update_freshness_timestamp!
       end
@@ -103,12 +107,12 @@ module ESA
       end
     end
 
-    def update!
+    def update!(options = {})
       self.freshness = Time.zone.now
 
       ESA.configuration.context_checkers.each do |checker|
         if checker.respond_to? :check
-          checker.check(self)
+          checker.check(self, options)
         end
       end
 
@@ -178,16 +182,21 @@ module ESA
       end
     end
 
-    def default_values
+    def initialize_defaults
       self.chart ||= self.parent.chart if self.chart_id.nil? and not self.parent_id.nil?
-      self.namespace ||= (self.type || self.class.name).demodulize.underscore.gsub(/_context$/, '')
+      self.namespace ||= self.default_namespace
+      self.position ||= self.default_position
+    end
+
+    def default_namespace
+      (self.type || self.class.name).demodulize.underscore.gsub(/_context$/, '')
     end
 
     def update_name
-      self.name = self.create_name
+      self.name = self.default_name
     end
 
-    def create_name
+    def default_name
       if self.type.nil?
         self.chart.name unless self.chart.nil?
       else
@@ -196,10 +205,10 @@ module ESA
     end
 
     def update_position
-      self.position = self.create_position
+      self.position = self.default_position
     end
 
-    def create_position
+    def default_position
       nil
     end
 

data/app/models/esa/contexts/account_context.rb

@@ -10,11 +10,11 @@ module ESA
 
       protected
 
-      def create_name
+      def default_name
         self.account.name unless self.account.nil?
       end
 
-      def create_position
+      def default_position
         self.account.code.gsub(/[^0-9]/, '').to_i unless self.account.nil? or self.account.code.nil?
       end
 

data/app/models/esa/contexts/accountable_context.rb

@@ -10,7 +10,7 @@ module ESA
 
       protected
 
-      def create_name
+      def default_name
         "#{self.accountable_type} #{self.accountable_id}" unless self.accountable_type.nil?
       end
 

data/app/models/esa/contexts/accountable_type_context.rb

@@ -8,7 +8,7 @@ module ESA
 
       protected
 
-      def create_name
+      def default_name
         "#{self.accountable_type} accountables" unless self.accountable_type.nil?
       end
 

data/app/models/esa/contexts/date_context.rb

@@ -33,7 +33,27 @@ module ESA
         end
       end
 
-      def create_name
+      def default_namespace
+        if self.start_date.present? and self.end_date.present?
+          if self.start_date == self.end_date
+            "date"
+          elsif self.start_date == self.start_date.beginning_of_month and
+                self.end_date == self.end_date.end_of_month and
+                self.end_date == self.start_date.end_of_month then
+            "month"
+          elsif self.start_date == self.start_date.beginning_of_year and
+                self.end_date == self.end_date.end_of_year and
+                self.end_date == self.start_date.end_of_year then
+            "year"
+          else
+            "period"
+          end
+        else
+          "period"
+        end
+      end
+
+      def default_name
         if self.start_date.present? and self.end_date.present?
           if self.start_date == self.end_date
             "#{self.start_date.to_s}"
@@ -47,7 +67,7 @@ module ESA
         end
       end
 
-      def create_position
+      def default_position
         if self.start_date.present?
           self.start_date.to_time.to_i
         elsif self.end_date.present?

data/app/models/esa/contexts/empty_context.rb

@@ -7,7 +7,7 @@ module ESA
 
       protected
 
-      def create_name
+      def default_name
         "Empty"
       end
 

data/app/models/esa/event.rb

@@ -21,13 +21,13 @@ module ESA
 
     enumerize :nature, in: [:unknown, :adjustment]
 
-    after_initialize :default_values
+    after_initialize :initialize_defaults
     validates_presence_of :time, :nature, :accountable, :ruleset
     validates_inclusion_of :processed, :in => [true, false]
 
     private
 
-    def default_values
+    def initialize_defaults
       self.time ||= Time.zone.now if self.time.nil?
       self.ruleset ||= Ruleset.extension_instance(self.accountable) if self.ruleset_id.nil? and not self.accountable_id.nil?
       self.processed ||= false

data/app/models/esa/flag.rb

@@ -27,7 +27,7 @@ module ESA
 
     enumerize :nature, in: [:unknown]
 
-    after_initialize :default_values
+    after_initialize :initialize_defaults
     validates_presence_of :nature, :event, :time, :accountable, :ruleset
     validates_inclusion_of :state, :in => [true, false]
     validates_inclusion_of :processed, :in => [true, false]
@@ -77,7 +77,7 @@ module ESA
       end
     end
 
-    def default_values
+    def initialize_defaults
       if not self.event_id.nil?
         self.time ||= self.event.time if self.time.nil?
         self.accountable ||= self.event.accountable if self.accountable_id.nil?

data/app/models/esa/ruleset.rb

@@ -14,7 +14,7 @@ module ESA
     has_many   :events
     has_many   :flags
 
-    after_initialize :default_values
+    after_initialize :initialize_defaults
     validates_presence_of :type, :chart
 
     # accountable
@@ -25,18 +25,36 @@ module ESA
 
     # events
 
+    def event_times(accountable)
+      {}
+    end
+
     def stateful_events(accountable)
-      []
+      self.event_times(accountable).map do |nature,times|
+        if times.present? and times.is_a? Time
+          {nature: nature, time: times}
+        elsif times.present? and times.respond_to? :each
+          times.map do |t|
+            if t.is_a? Time
+              {nature: nature, time: t}
+            else
+              nil
+            end
+          end.compact
+        else
+          nil
+        end
+      end.flatten.compact
     end
 
     def stateful_events_as_attributes(accountable)
-      stateful_events(accountable).
-        sort_by{|event| event[:time]}.
-        map do |event|
-          event[:accountable] ||= accountable
-          event[:ruleset] ||= self
-          event
-        end
+      defaults = {
+        accountable: accountable,
+        ruleset: self,
+      }
+      stateful_events(accountable).map do |event|
+        defaults.merge(event)
+      end
     end
 
     def unrecorded_events_as_attributes(accountable)
@@ -48,18 +66,32 @@ module ESA
       stateful.reject{|s| [s[:nature].to_s, s[:time].to_i].in? recorded}
     end
 
+    def addable_unrecorded_events_as_attributes(accountable)
+      flag_times_max = accountable.esa_flags.group(:nature).maximum(:time)
+
+      unrecorded_events_as_attributes(accountable).select do |event|
+        event_flags = event_nature_flags[event[:nature]] || {}
+        flag_times = flag_times_max.slice(*event_flags.keys.map(&:to_s))
+
+        # allow when the event flags have not been used before or
+        # when all the currently used flag times are before the new event
+        flag_times.values.none? || flag_times.values.max <= event[:time]
+      end
+    end
+
     def is_adjustment_event_needed?(accountable)
       flags_needing_adjustment(accountable).count > 0
     end
 
     # flags
 
-    def event_flags(event)
+    def event_nature_flags
       {}
     end
 
     def event_flags_as_attributes(event)
-      event_flags(event).map do |nature,state|
+      flags = self.event_nature_flags[event.nature.to_sym] || {}
+      flags.map do |nature,state|
         {
           :accountable => event.accountable,
           :nature => nature,
@@ -76,24 +108,42 @@ module ESA
         accountable.esa_flags.transitioning.most_recent(nature)
       end.compact
 
-      set_flags = most_recent_flags.select(&:is_set?)
-
-      set_flags.reject do |flag|
-        specs = flag_transactions_as_attributes(flag)
-        flag.transactions_match_specs?(specs)
+      most_recent_flags.select do |flag|
+        flag.is_set? and not flag_transactions_match_specs?(flag)
       end
     end
 
     # transactions
 
+    def flag_transactions_spec(accountable, flag_nature)
+      function_name = "flag_#{flag_nature}_transactions"
+
+      if self.respond_to? function_name
+        transactions = self.send(function_name, accountable)
+
+        if transactions.is_a? Hash
+          [transactions]
+        elsif transactions.is_a? Array
+          transactions
+        else
+          []
+        end
+      else
+        []
+      end
+    end
+
     def flag_transactions_when_set(flag)
-      []
+      flag_transactions_spec(flag.accountable, flag.nature)
     end
 
     def flag_transactions_when_unset(flag)
-      self.flag_transactions_when_set(flag).each do |tx|
-        tx[:description] = "#{tx[:description]} / reversed"
-        tx[:debits], tx[:credits] = tx[:credits], tx[:debits] # swap
+      self.flag_transactions_when_set(flag).map do |tx|
+        tx.merge({
+          description: "#{tx[:description]} / reversed",
+          debits: tx[:credits],
+          credits: tx[:debits]
+        })
       end
     end
 
@@ -129,17 +179,33 @@ module ESA
     end
 
     def flag_transactions_as_attributes(flag)
+      defaults = {
+        time: flag.time,
+        accountable: flag.accountable,
+        flag: flag,
+      }
       flag_transactions(flag).map do |tx|
-        tx[:time] ||= flag.time
-        tx[:accountable] ||= flag.accountable
-        tx[:flag] ||= flag
+        attrs = defaults.merge(tx)
+        ensure_positive_amounts(attrs)
+      end
+    end
 
-        amounts = (tx[:debits] + tx[:credits]).map{|a| a[:amount]}
-        if amounts.map{|a| a <= BigDecimal(0)}.all?
-          tx[:debits], tx[:credits] = inverted(tx[:credits]), inverted(tx[:debits]) # invert & swap
-        end
+    def flag_transactions_match_specs?(flag)
+      specs = flag_transactions_as_attributes(flag)
+      flag.transactions_match_specs?(specs)
+    end
+
+    def ensure_positive_amounts(attrs)
+      amounts = attrs[:debits] + attrs[:credits]
+      nonpositives = amounts.map{|a| a[:amount] <= BigDecimal(0)}
 
-        tx
+      if nonpositives.all?
+        attrs.merge({
+          debits: inverted(attrs[:credits]),
+          credits: inverted(attrs[:debits]),
+        })
+      else
+        attrs
       end
     end
 
@@ -157,7 +223,7 @@ module ESA
 
     private
 
-    def default_values
+    def initialize_defaults
       self.chart ||= Chart.extension_instance(self) if self.chart_id.nil?
       self.name ||= "#{self.chart.name} #{self.class.name.demodulize}" if self.name.nil? and self.chart_id.present?
     end

data/app/models/esa/transaction.rb

@@ -19,7 +19,7 @@ module ESA
     has_many :amounts, :extend => ESA::Associations::AmountsExtension
     has_many :accounts, :through => :amounts, :source => :account, :uniq => true
 
-    after_initialize :default_values
+    after_initialize :initialize_defaults
 
     validates_presence_of :time, :description
     validate :has_credit_amounts?
@@ -71,7 +71,7 @@ module ESA
 
     private
 
-    def default_values
+    def initialize_defaults
       self.time ||= Time.zone.now
     end
 

data/lib/esa/balance_checker.rb

@@ -1,6 +1,6 @@
 module ESA
   class BalanceChecker
-    def self.check(context)
+    def self.check(context, options = {})
       if context.can_be_persisted? and not context.freshness.nil?
         #context.event_count = context.events.created_before(context.freshness).count
         #context.flag_count = context.flags.created_before(context.freshness).count