event_sourced_accounting 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 50060f8c9f1f6d7255e40b89573a8f8b57557b0a
+  data.tar.gz: baf5ccaa16ad6488d6a94997692e780932bdd35e
+SHA512:
+  metadata.gz: 6c6c898e8105dfa1bf731b6985108e0110413d6cad12d4dd2cfdb8b0710e4ce585a2f7a88a15d2c290b6f69d0118d9e20782035fb37168596a221d8ef2120f2f
+  data.tar.gz: 6543bd307114e95356464413db9633a0de666576c19a14541a7eb3f84d4719052bc09b222a6431caca23406ac860e58a026e5a0b9dc921d7efda57c1d9808cd6

data/LICENSE

@@ -0,0 +1,23 @@
+Copyright (c) 2013-2014 Lenno Nagel, 2010 Michael Bulat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+Except as contained in this notice, the name(s) of the above copyright holders
+shall not be used in advertising or otherwise to promote the sale, use or 
+other dealings in this Software without prior written authorization.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,37 @@
+Event-Sourced Accounting
+=================
+
+The Event-Sourced Accounting plugin provides an event-sourced double entry accounting system.
+It uses the data models of a Rails application as a data source and automatically 
+generates accounting transactions based on defined accounting rules.
+
+This plugin began life as a fork of the [Plutus](https://github.com/mbulat/plutus) plugin with
+many added features and refactored compontents. As the aims of the ESA plug-in have completely
+changed compared to the original project, it warrants a release under its own name.
+
+The API is not yet declared frozen and may change, as some refactoring is still due.
+The documentation and test coverage is expected to be completed within April-May 2014. 
+
+
+Installation
+============
+
+- Add `gem "event-sourced-accounting"` to your Gemfile
+
+- generate migration files with `rails g esa`
+
+- 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
+
+
+Development
+============
+
+Any comments and contributions are welcome. Will gladly accept patches sent via pull requests.
+
+- run rspec tests simply with `rake`
+
+- update documentation with `yard`

data/Rakefile

@@ -0,0 +1,11 @@
+require 'bundler/setup'
+
+require 'rspec/core/rake_task'
+
+desc "run specs"
+RSpec::Core::RakeTask.new do |t|
+  t.rspec_opts = ["-c", "-f d", "-r ./spec/spec_helper.rb"]
+  t.pattern = 'spec/**/*_spec.rb'
+end
+
+task :default  => :spec

data/app/assets/javascripts/esa/application.js

@@ -0,0 +1,15 @@
+// This is a manifest file that'll be compiled into application.js, which will include all the files
+// listed below.
+//
+// Any JavaScript/Coffee file within this directory, lib/assets/javascripts, vendor/assets/javascripts,
+// or vendor/assets/javascripts of plugins, if any, can be referenced here using a relative path.
+//
+// It's not advisable to add code directly here, but if you do, it'll appear at the bottom of the
+// the compiled file.
+//
+// WARNING: THE FIRST BLANK LINE MARKS THE END OF WHAT'S TO BE PROCESSED, ANY BLANK LINE SHOULD
+// GO AFTER THE REQUIRES BELOW.
+//
+//= require jquery
+//= require jquery_ujs
+//= require_tree .

data/app/assets/stylesheets/esa/application.css

@@ -0,0 +1,13 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or vendor/assets/stylesheets of plugins, if any, can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the top of the
+ * compiled file, but it's generally better to create a new file per style scope.
+ *
+ *= require_self
+ *= require_tree .
+*/

data/app/assets/stylesheets/esa/main.css.scss

@@ -0,0 +1,86 @@
+.esa_container {
+
+  /* CSS from http://wptheming.com/2011/01/simple-table-css3/ */
+  
+  margin:0;
+  padding:0;
+  border:0;
+  font-family: "Helvetica Neue",Arial, Helvetica, sans-serif;
+  
+  /*
+  Pretty Table Styling
+  CSS Tricks also has a nice writeup: http://css-tricks.com/feature-table-design/
+  */
+  
+  table {
+    overflow:hidden;
+    border:1px solid #d3d3d3;
+    background:#fefefe;
+    width:70%;
+    margin:5% auto 0;
+    -moz-border-radius:5px; /* FF1+ */
+    -webkit-border-radius:5px; /* Saf3-4 */
+    border-radius:5px;
+    -moz-box-shadow: 0 0 4px rgba(0, 0, 0, 0.2);
+    -webkit-box-shadow: 0 0 4px rgba(0, 0, 0, 0.2);
+  }
+  
+  th, td {padding:10px 18px 10px; }
+  
+  th {padding-top:22px; text-shadow: 1px 1px 1px #fff; background:#e8eaeb;}
+  
+  td {border-top:1px solid #e0e0e0; border-right:1px solid #e0e0e0;}
+  
+  tr.even td {background:#f6f6f6;}
+  
+  td.first, th.first {text-align:left}
+  
+  td.last {border-right:none;}
+  
+  /*
+  Background gradients are completely unnessary but a neat effect.
+  */
+  
+  td {
+    background: -moz-linear-gradient(100% 25% 90deg, #fefefe, #f9f9f9);
+    background: -webkit-gradient(linear, 0% 0%, 0% 25%, from(#f9f9f9), to(#fefefe));
+  }
+  
+  tr.even td {
+    background: -moz-linear-gradient(100% 25% 90deg, #f6f6f6, #f1f1f1);
+    background: -webkit-gradient(linear, 0% 0%, 0% 25%, from(#f1f1f1), to(#f6f6f6));
+  }
+  
+  th {
+    background: -moz-linear-gradient(100% 20% 90deg, #e8eaeb, #ededed);
+    background: -webkit-gradient(linear, 0% 0%, 0% 20%, from(#ededed), to(#e8eaeb));
+  }
+  
+  /*
+  I know this is annoying, but we need dditional styling so webkit will recognize rounded corners on background elements.
+  Nice write up of this issue: http://www.onenaught.com/posts/266/css-inner-elements-breaking-border-radius
+  
+  And, since we've applied the background colors to td/th element because of IE, Gecko browsers also need it.
+  */
+  
+  tr:first-child th.first {
+    -moz-border-radius-topleft:5px;
+    -webkit-border-top-left-radius:5px; /* Saf3-4 */
+  }
+  
+  tr:first-child th.last {
+    -moz-border-radius-topright:5px;
+    -webkit-border-top-right-radius:5px; /* Saf3-4 */
+  }
+  
+  tr:last-child td.first {
+    -moz-border-radius-bottomleft:5px;
+    -webkit-border-bottom-left-radius:5px; /* Saf3-4 */
+  }
+  
+  tr:last-child td.last {
+    -moz-border-radius-bottomright:5px;
+    -webkit-border-bottom-right-radius:5px; /* Saf3-4 */
+  }
+
+}

data/app/models/esa/account.rb

@@ -0,0 +1,80 @@
+module ESA
+  # The Account class represents accounts in the system. Each account must be subclassed as one of the following types:
+  #
+  #   TYPE        | NORMAL BALANCE    | DESCRIPTION
+  #   --------------------------------------------------------------------------
+  #   Asset       | Debit             | Resources owned by the Business Entity
+  #   Liability   | Credit            | Debts owed to outsiders
+  #   Equity      | Credit            | Owners rights to the Assets
+  #   Revenue     | Credit            | Increases in owners equity
+  #   Expense     | Debit             | Assets or services consumed in the generation of revenue
+  #
+  # Each account can also be marked as a "Contra Account". A contra account will have it's
+  # normal balance swapped. For example, to remove equity, a "Drawing" account may be created
+  # as a contra equity account as follows:
+  #
+  #   ESA::Equity.create(:name => "Drawing", contra => true)
+  #
+  # @author Lenno Nagel, Michael Bulat
+  class Account < ActiveRecord::Base
+    extend ::Enumerize
+
+    attr_accessible :chart, :type, :code, :name, :contra
+    attr_accessible :chart, :type, :code, :name, :contra, :as => :admin
+    attr_readonly   :chart
+
+    belongs_to :chart
+    has_many :amounts, :extend => Associations::AmountsExtension
+    has_many :transactions, :through => :amounts, :source => :transaction
+
+    enumerize :normal_balance, in: [:none, :debit, :credit]
+
+    after_initialize :default_values
+
+    before_validation :update_normal_balance
+    validates_presence_of :type, :name, :chart, :normal_balance
+    validates_uniqueness_of :code, :scope => :chart_id
+    validates_uniqueness_of :name, :scope => :chart_id
+
+    # The balance of the account.
+    #
+    # @example
+    #   >> account.balance
+    #   => #<BigDecimal:103259bb8,'0.2E4',4(12)>
+    #
+    # @return [BigDecimal] The decimal value balance
+    def balance
+      if self.normal_balance.debit?
+        self.amounts.balance
+      elsif self.normal_balance.credit?
+        - self.amounts.balance
+      else
+        nil
+      end
+    end
+
+    def self.valid_type?(type)
+      type.in? ["Asset", "Liability", "Equity", "Revenue", "Expense"]
+    end
+
+    def self.namespaced_type(type)
+      if valid_type?(type)
+        "ESA::Accounts::#{type}"
+      else
+        type
+      end
+    end
+
+    private
+
+    def default_values
+      self.chart ||= Chart.where(:name => 'Chart of Accounts').first_or_create if self.chart_id.nil?
+      self.normal_balance ||= :none
+    end
+
+    # The normal balance for the account. Must be overridden in implementations.
+    def update_normal_balance
+      self.normal_balance = :none
+    end
+  end
+end

data/app/models/esa/accounts/asset.rb

@@ -0,0 +1,22 @@
+module ESA
+  module Accounts
+    # The Asset class is an account type used to represents resources owned by the business entity.
+    #
+    # === Normal Balance
+    # The normal balance on Asset accounts is a *Debit*.
+    #
+    # @see http://en.wikipedia.org/wiki/Asset Assets
+    #
+    # @author Lenno Nagel
+    class Asset < ESA::Account
+      # The normal balance for the account. Must be overridden in implementations.
+      def update_normal_balance
+        unless self.contra
+          self.normal_balance = :debit
+        else
+          self.normal_balance = :credit
+        end
+      end
+    end
+  end
+end

data/app/models/esa/accounts/equity.rb

@@ -0,0 +1,22 @@
+module ESA
+  module Accounts
+    # The Equity class is an account type used to represents owners rights to the assets.
+    #
+    # === Normal Balance
+    # The normal balance on Equity accounts is a *Credit*.
+    #
+    # @see http://en.wikipedia.org/wiki/Equity_(finance) Equity
+    #
+    # @author Lenno Nagel
+    class Equity < ESA::Account
+      # The normal balance for the account. Must be overridden in implementations.
+      def update_normal_balance
+        unless self.contra
+          self.normal_balance = :credit
+        else
+          self.normal_balance = :debit
+        end
+      end
+    end
+  end
+end

data/app/models/esa/accounts/expense.rb

@@ -0,0 +1,22 @@
+module ESA
+  module Accounts
+    # The Expense class is an account type used to represents assets or services consumed in the generation of revenue.
+    #
+    # === Normal Balance
+    # The normal balance on Expense accounts is a *Debit*.
+    #
+    # @see http://en.wikipedia.org/wiki/Expense Expenses
+    #
+    # @author Lenno Nagel
+    class Expense < ESA::Account
+      # The normal balance for the account. Must be overridden in implementations.
+      def update_normal_balance
+        unless self.contra
+          self.normal_balance = :debit
+        else
+          self.normal_balance = :credit
+        end
+      end
+    end
+  end
+end

data/app/models/esa/accounts/liability.rb

@@ -0,0 +1,22 @@
+module ESA
+  module Accounts
+    # The Liability class is an account type used to represents debts owed to outsiders.
+    #
+    # === Normal Balance
+    # The normal balance on Liability accounts is a *Credit*.
+    #
+    # @see http://en.wikipedia.org/wiki/Liability_(financial_accounting) Liability
+    #
+    # @author Lenno Nagel
+    class Liability < ESA::Account
+      # The normal balance for the account. Must be overridden in implementations.
+      def update_normal_balance
+        unless self.contra
+          self.normal_balance = :credit
+        else
+          self.normal_balance = :debit
+        end
+      end
+    end
+  end
+end

data/app/models/esa/accounts/revenue.rb

@@ -0,0 +1,22 @@
+module ESA
+  module Accounts
+    # The Revenue class is an account type used to represents increases in owners equity.
+    #
+    # === Normal Balance
+    # The normal balance on Revenue accounts is a *Credit*.
+    #
+    # @see http://en.wikipedia.org/wiki/Revenue Revenue
+    #
+    # @author Lenno Nagel
+    class Revenue < ESA::Account
+      # The normal balance for the account. Must be overridden in implementations.
+      def update_normal_balance
+        unless self.contra
+          self.normal_balance = :credit
+        else
+          self.normal_balance = :debit
+        end
+      end
+    end
+  end
+end

data/app/models/esa/amount.rb

@@ -0,0 +1,27 @@
+module ESA
+  # The Amount class represents debit and credit amounts in the system.
+  #
+  # @abstract
+  #   An amount must be a subclass as either a debit or a credit to be saved to the database. 
+  #
+  # @author Lenno Nagel, Michael Bulat
+  class Amount < ActiveRecord::Base
+    attr_accessible :type, :account, :amount, :transaction
+
+    belongs_to :transaction
+    belongs_to :account
+
+    validates_presence_of :type, :amount, :transaction, :account
+
+    scope :credits, lambda { where(type: Amounts::Credit) }
+    scope :debits, lambda { where(type: Amounts::Debit) }
+
+    def is_credit?
+      self.is_a? Amounts::Credit
+    end
+
+    def is_debit?
+      self.is_a? Amounts::Debit
+    end
+  end
+end

data/app/models/esa/amounts/credit.rb

@@ -0,0 +1,12 @@
+module ESA
+  module Amounts
+    # The Credit class represents credit entries in the transaction journal.
+    #
+    # @example
+    #     credit_amount = ESA::Amounts::Credit.new(:account => revenue, :amount => 1000)
+    #
+    # @author Lenno Nagel
+    class Credit < ESA::Amount
+    end
+  end
+end

data/app/models/esa/amounts/debit.rb

@@ -0,0 +1,12 @@
+module ESA
+  module Amounts
+    # The Debit class represents debit entries in the transaction journal.
+    #
+    # @example
+    #     debit_amount = ESA::Amounts::Debit.new(:account => cash, :amount => 1000)
+    #
+    # @author Lenno Nagel
+    class Debit < ESA::Amount
+    end
+  end
+end

data/app/models/esa/associations/amounts_extension.rb

@@ -0,0 +1,79 @@
+module ESA
+  module Associations
+    # Association extension for has_many :amounts relations. Internal.
+    module AmountsExtension
+      # Returns a total sum of the referenced Amount objects
+      def total
+        sums = group('esa_amounts.amount is null').
+               sum(:amount)
+
+        checked = sums.map do |s|
+          amount_is_nil, amount = s.flatten
+          amount
+        end
+
+        if checked.all?
+          return checked.inject(BigDecimal(0)){|x,y| x + y}
+        else
+          return nil
+        end
+      end
+
+      # Returns a sum of the referenced Amount objects.
+      def balance
+        sums = group('esa_amounts.amount is null').
+               group('esa_amounts.type').
+               sum(:amount)
+
+        signed = sums.map do |s|
+          amount_is_nil, amount_type, amount = s.flatten
+          amount_type = amount_type.demodulize.downcase
+
+          if amount_type == "debit"
+            amount
+          elsif amount_type == "credit"
+            - amount
+          else
+            nil
+          end
+        end
+
+        if signed.all?
+          return signed.inject(BigDecimal(0)){|x,y| x + y}
+        else
+          return nil
+        end
+      end
+
+      # Returns a sum of the referenced Amount objects.
+      def iterated_total
+        amounts = map(&:amount)
+
+        if amounts.all?
+          amounts.inject(BigDecimal(0)){|x,y| x + y}
+        else
+          return nil
+        end
+      end
+
+      # Returns a sum of the referenced Amount objects.
+      def iterated_balance
+        amounts = map do |a|
+          if a.is_debit?
+            a.amount
+          elsif a.is_credit? and not a.amount.nil?
+            - a.amount
+          else
+            nil
+          end
+        end
+        
+        if amounts.all?
+          amounts.inject(BigDecimal(0)){|x,y| x + y}
+        else
+          return nil
+        end
+      end
+    end
+  end
+end

data/app/models/esa/associations/events_extension.rb

@@ -0,0 +1,33 @@
+module ESA
+  module Associations
+    module EventsExtension
+      # This function adds an event only if there were no previous events,
+      # or the previous event was a different one, avoiding duplicates.
+      def maybe(attrs)
+        events = proxy_association.owner.esa_events
+        last_event = events.order('time DESC, created_at DESC').first
+
+        # make sure that the previous event was not of the same event type
+        if last_event.nil? or last_event.nature != attrs[:nature]
+          if attrs[:time].present? and last_event.present? and last_event.time.present? and last_event.time > attrs[:time]
+            # we cannot input past events, so let's make it most recent
+            attrs[:time] = last_event.time
+            e = events.new(attrs)
+          else
+            e = events.new(attrs)
+          end
+          e.save
+        else
+          # we didn't need to add anything
+          true
+        end
+      end
+
+      def hashes
+        proxy_association.owner.esa_events.
+            map{|e| {:nature => e.nature, :time => e.time}}.
+            sort_by{|e| e[:time]}
+      end
+    end
+  end
+end

data/app/models/esa/associations/flags_extension.rb

@@ -0,0 +1,35 @@
+module ESA
+  module Associations
+    module FlagsExtension
+      def most_recent(nature, time=Time.zone.now, exclude=nil)
+        query = where(nature: nature).
+              where('time <= ?', time)
+
+        if exclude.present?
+          query = query.where('esa_flags.id not in (?)', exclude)
+        end
+
+        query.order('time DESC, created_at DESC').first
+      end
+
+      def is_set?(nature, time=Time.zone.now, exclude=nil)
+        most_recent = most_recent(nature, time, exclude)
+        if most_recent.present?
+          most_recent.is_set? # return the set bit of this flag
+        else
+          false
+        end
+      end
+
+      def transition_for(flag)
+        if flag.state and not is_set?(flag.nature, flag.time, flag.id)
+          1
+        elsif not flag.state and is_set?(flag.nature, flag.time, flag.id)
+          -1
+        else
+          0
+        end
+      end
+    end
+  end
+end

data/app/models/esa/associations/transactions_extension.rb

@@ -0,0 +1,7 @@
+module ESA
+  module Associations
+    module TransactionsExtension
+      # for future usage
+    end
+  end
+end

data/app/models/esa/chart.rb

@@ -0,0 +1,41 @@
+module ESA
+  # The Chart class represents an organized set of accounts in the system.
+  #
+  # @author Lenno Nagel
+  class Chart < ActiveRecord::Base
+    include Traits::Extendable
+
+    attr_accessible :name
+
+    has_many :accounts
+    has_many :rulesets
+
+    has_many :events, :through => :rulesets, :uniq => true
+    has_many :flags, :through => :rulesets, :uniq => true
+    has_many :transactions, :through => :accounts, :uniq => true
+    has_many :amounts, :through => :accounts, :uniq => true, :extend => Associations::AmountsExtension
+
+    after_initialize :default_values
+
+    validates_presence_of :name
+    validates_uniqueness_of :name
+
+    # The trial balance of all accounts in the system. This should always equal zero,
+    # otherwise there is an error in the system.
+    #
+    # @example
+    #   >> chart.trial_balance.to_i
+    #   => 0
+    #
+    # @return [BigDecimal] The decimal value balance of all accounts
+    def trial_balance
+      self.amounts.balance
+    end
+
+    private
+
+    def default_values
+      self.name ||= "Chart of Accounts"
+    end
+  end
+end