sie-analysis 0.1.1

data/lib/sie_analysis/amounts.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module SieAnalysis
+  # Shared ledger amount presentation helpers for Analysis.
+  module Amounts
+    private
+
+    # Period keys are either account or [account, dimension_no, object_code].
+    def dimension_parts(key)
+      case key
+      when Array
+        account, dim, code = key
+        [account, dim, code]
+      else
+        [key, nil, nil]
+      end
+    end
+
+    def income_group?(group)
+      group && Groups::INCOME.any? { |item| item.equal?(group) }
+    end
+
+    def present_amount(raw, kind)
+      kind == :revenue ? -raw : raw
+    end
+
+    def present_balance(raw, kind)
+      kind == :equity_liability ? -raw : raw
+    end
+
+    def round_money(value)
+      BigDecimal(value.to_s).round(2, BigDecimal::ROUND_HALF_UP)
+    end
+
+    def present_ledger_amount(raw, account_number)
+      group = Groups.for_account(account_number)
+      return round_money(raw) unless group
+
+      presented = if income_group?(group)
+                    present_amount(raw, group.fetch(:kind))
+                  else
+                    present_balance(raw, group.fetch(:kind))
+                  end
+      round_money(presented)
+    end
+
+    def raw_period_amount(account, month_hash)
+      month_hash.fetch(account, BigDecimal("0"))
+    end
+  end
+end

data/lib/sie_analysis/analysis.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+require "date"
+
+module SieAnalysis
+  # Reports for one parsed financial year. Monetary values are BigDecimal in SEK.
+  # Income and monthly summaries use period balances; daily summaries use vouchers.
+  class Analysis
+    include Amounts
+    include IncomeStatements
+    include DimensionStatements
+    include BalanceSheets
+    include Budgets
+
+    CURRENCY = "SEK"
+    DIMENSIONS = {
+      cost_center: 1,
+      project: 6
+    }.freeze
+
+    # @param document [Parser::Parsed] a decoded and parsed SIE export
+    def initialize(document)
+      @parsed = document
+    end
+
+    # Summarizes all calendar months touched by the inclusive date range.
+    # @param from [Date] first date
+    # @param to [Date] last date
+    # @param dimension [Symbol, nil] :project or :cost_center
+    # @return [Hash] income statement, balance sheet, budget, monthly totals and notes
+    def overview(from:, to:, dimension: nil)
+      start_date, end_date = from, to
+      validate_period!(start_date, end_date)
+      months = month_keys(start_date, end_date)
+      notes = overview_notes(start_date, end_date)
+      dim = require_dimension!(dimension, available_dimensions)
+      income = income_statement(months, dim)
+      balance = balance_sheet(end_date, months, dim)
+      soft_balance_note!(balance, income, notes)
+      notes << "Balance sheet totals are omitted when grouping by #{dim}." if dim
+
+      {
+        period: { from: start_date, to: end_date },
+        currency: CURRENCY,
+        granularity: "monthly",
+        available_dimensions: available_dimensions,
+        income_statement: income,
+        budget: budget_overview(months, dim),
+        balance_sheet: balance,
+        highlights: highlights(income, balance),
+        notes:,
+        monthly_totals: monthly_totals(months, dim)
+      }
+    end
+
+    # Lists non-zero monthly movements, optionally filtered by BAS group or object.
+    # @param month [String] YYYY-MM
+    # @param group_code [String, nil] report group, e.g. "revenue"
+    # @param account_number [Integer, nil] BAS account number
+    # @param dimension [Symbol, nil] :project or :cost_center
+    # @param dimension_code [String, nil] object code; requires dimension
+    # @return [Array<Hash>] account_number, account_name, movement and group/object fields
+    def account_movements(month:, group_code: nil, account_number: nil, dimension: nil, dimension_code: nil)
+      month_label = normalize_year_month(month)
+      dim = require_dimension!(dimension, available_dimensions)
+      raise ArgumentError, "dimension_code requires dimension" if dimension_code && !dim
+      accounts = account_rows_for_month(month_label.delete("-"), dim)
+      accounts.select! { |row| row.fetch(:group_code) == group_code } if group_code
+      accounts.select! { |row| row.fetch(:account_number) == Integer(account_number) } if account_number
+      accounts.select! { |row| row.fetch(:dimension_code) == dimension_code } if dimension_code
+      accounts
+    end
+
+    # Returns opening balance, movement and closing balance for exactly one period.
+    # @param account_number [Integer] BAS account number
+    # @param month [String, nil] YYYY-MM; mutually exclusive with on
+    # @param on [Date, nil] a single day; requires SIE 4
+    # @return [Hash] account fields, Date period boundaries and BigDecimal balances
+    def account_summary(account_number, month: nil, on: nil)
+      number = Integer(account_number)
+      raise ArgumentError, "Provide month or on, not both" if on && month
+      return day_account_summary(number, date_argument!(on)) if on
+      raise ArgumentError, "month or on is required" unless month
+
+      month_account_summary(number, month)
+    end
+
+    # Lists vouchers with a non-zero net movement on the account; requires SIE 4.
+    # @param account_number [Integer] BAS account number
+    # @param from [Date] inclusive first voucher date
+    # @param to [Date] inclusive last voucher date
+    # @return [Array<Hash>] series, number, Date, description and BigDecimal movement
+    def vouchers_on_account(account_number, from:, to:)
+      start_day, end_day = from, to
+      require_transactions!
+      validate_period!(start_day, end_day)
+      number = Integer(account_number)
+      @parsed.vouchers.filter_map do |voucher|
+        next unless voucher.date.between?(start_day, end_day)
+
+        raw = voucher.lines.sum { |line| line.account == number ? line.amount : BigDecimal("0") }
+        next if raw.zero?
+
+        {
+          voucher_series: voucher.series,
+          voucher_number: voucher.number,
+          date: voucher.date,
+          description: voucher.description,
+          movement: present_ledger_amount(raw, number)
+        }
+      end
+    end
+
+    # @return [Array<Symbol>] supported dimensions with objects declared in the export
+    def available_dimensions
+      dims = []
+      dims << :cost_center if @parsed.objects.keys.any? { |dim, _code| dim == 1 }
+      dims << :project if @parsed.objects.keys.any? { |dim, _code| dim == 6 }
+      dims
+    end
+
+    private
+
+    def date_argument!(date)
+      raise ArgumentError, "Expected a Date" unless date.instance_of?(Date)
+      date
+    end
+
+    def validate_period!(first, last)
+      date_argument!(first)
+      date_argument!(last)
+      raise ArgumentError, "Start date must not be after end date" if first > last
+    end
+
+    def require_transactions!
+      raise ArgumentError, "This analysis requires a SIE 4 export" unless @parsed.sie_type == 4
+    end
+
+    def overview_notes(start_date, end_date)
+      notes = ["Amounts use monthly period balances, not day-level bookkeeping."]
+      return notes if whole_months?(start_date, end_date)
+
+      notes << "The requested dates are not full calendar months; monthly balances still cover complete months."
+      notes
+    end
+
+    def month_account_summary(number, year_month)
+      month_label = normalize_year_month(year_month)
+      start_date = Date.strptime("#{month_label}-01", "%Y-%m-%d")
+      end_date = Date.new(start_date.year, start_date.month, -1)
+      month_key = month_label.delete("-")
+      raw_opening = raw_balance_before_month(number, month_key)
+      raw_period = raw_period_amount(number, @parsed.period_changes[month_key] || {})
+      build_account_summary(number, start_date, end_date, raw_opening, raw_period)
+    end
+
+    def day_account_summary(number, day)
+      require_transactions!
+      month_start = Date.new(day.year, day.month, 1)
+      raw_opening = raw_balance_before_month(number, day.strftime("%Y%m"))
+      raw_opening += raw_voucher_amount(number, month_start, day.prev_day) if day.day > 1
+      raw_period = raw_voucher_amount(number, day, day)
+      build_account_summary(number, day, day, raw_opening, raw_period)
+    end
+
+    def build_account_summary(number, start_date, end_date, raw_opening, raw_period)
+      {
+        account_number: number,
+        account_name: @parsed.accounts[number],
+        period: { from: start_date, to: end_date },
+        movement: present_ledger_amount(raw_period, number),
+        opening_balance: present_ledger_amount(raw_opening, number),
+        closing_balance: present_ledger_amount(raw_opening + raw_period, number)
+      }
+    end
+
+    def raw_balance_before_month(account, month_key)
+      opening = @parsed.opening_balances[account] || BigDecimal("0")
+      prior_months = @parsed.period_changes.keys.select { |key| key < month_key }
+      opening + prior_months.sum { |key| raw_period_amount(account, @parsed.period_changes[key] || {}) }
+    end
+
+    def raw_voucher_amount(account, start_day, end_day)
+      return BigDecimal("0") if end_day < start_day
+
+      @parsed.vouchers.sum do |voucher|
+        next BigDecimal("0") unless voucher.date.between?(start_day, end_day)
+
+        voucher.lines.sum { |line| line.account == account ? line.amount : BigDecimal("0") }
+      end
+    end
+
+    def require_dimension!(dimension, available)
+      dim = normalize_dimension(dimension)
+      return dim unless dim
+      return dim if available.include?(dim)
+
+      raise ArgumentError, "The financial export has no #{dim.to_s.tr('_', ' ')} objects"
+    end
+
+    def normalize_dimension(dimension)
+      return if dimension.nil?
+      raise ArgumentError, "Unsupported dimension" unless DIMENSIONS.key?(dimension)
+
+      dimension
+    end
+
+    def normalize_year_month(value)
+      text = value.to_s
+      raise ArgumentError, "month must be YYYY-MM" unless text.match?(/\A\d{4}-\d{2}\z/)
+
+      Date.strptime("#{text}-01", "%Y-%m-%d")
+      text
+    rescue Date::Error
+      raise ArgumentError, "month must be YYYY-MM"
+    end
+
+    def month_keys(start_date, end_date)
+      cursor = Date.new(start_date.year, start_date.month, 1)
+      last = Date.new(end_date.year, end_date.month, 1)
+      keys = []
+      while cursor <= last
+        keys << cursor.strftime("%Y%m")
+        cursor = cursor.next_month
+      end
+      keys
+    end
+
+    def whole_months?(start_date, end_date)
+      start_date.day == 1 && end_date == Date.new(end_date.year, end_date.month, -1)
+    end
+  end
+end

data/lib/sie_analysis/balance_sheets.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module SieAnalysis
+  # Balance-sheet builders and closing-balance helpers for Analysis.
+  module BalanceSheets
+    private
+
+    def balance_sheet(end_date, months, dimension)
+      return dimension_balance_placeholder if dimension
+
+      groups = Groups::BALANCE.map { |group| balance_group_row(group, months) }
+      assets = group_amount(groups, "assets")
+      equity = group_amount(groups, "equity_and_liabilities")
+      {
+        as_of: end_date,
+        assets:,
+        equity_and_liabilities: equity,
+        cash_and_bank: round_money(cash_total(months)),
+        groups: groups.reject { |group| group.fetch(:amount).zero? && group.fetch(:accounts).empty? }
+      }
+    end
+
+    def group_amount(groups, code)
+      groups.find { |row| row[:code] == code }&.fetch(:amount) || BigDecimal("0")
+    end
+
+    def cash_total(months)
+      balance_accounts_in(Groups::CASH_RANGE).sum do |number|
+        present_balance(closing_balance_for(number, months), :asset)
+      end
+    end
+
+    def balance_group_row(group, months)
+      rows = balance_accounts_in(group.fetch(:range)).filter_map do |number|
+        presented = present_balance(closing_balance_for(number, months), group.fetch(:kind))
+        next if presented.zero?
+
+        { account_number: number, account_name: @parsed.accounts[number], amount: round_money(presented) }
+      end
+      {
+        code: group.fetch(:code),
+        label: group.fetch(:label),
+        amount: round_money(rows.sum { |row| row.fetch(:amount) }),
+        accounts: rows.sort_by { |row| row.fetch(:account_number) }
+      }
+    end
+
+    def dimension_balance_placeholder
+      { as_of: nil, assets: nil, equity_and_liabilities: nil, cash_and_bank: nil, groups: [] }
+    end
+
+    def soft_balance_note!(balance, income, notes)
+      return if balance[:assets].nil? || balance[:equity_and_liabilities].nil?
+
+      gap = (balance.fetch(:assets) - balance.fetch(:equity_and_liabilities) - income.fetch(:result)).abs
+      return if gap < BigDecimal("0.05")
+
+      notes << "Balance sheet assets and equity/liabilities differ after including period result; common mid-year."
+    end
+
+    def closing_balance_for(account, months)
+      if @parsed.closing_balances.key?(account) && months_cover_year_end?(months)
+        return @parsed.closing_balances[account]
+      end
+
+      opening = @parsed.opening_balances[account] || BigDecimal("0")
+      through_end = @parsed.period_changes.keys.select { |month| month <= months.last }
+      opening + through_end.sum { |month| raw_period_amount(account, @parsed.period_changes[month]) }
+    end
+
+    def months_cover_year_end?(months)
+      rar = @parsed.financial_years[0]
+      return false unless rar && rar[:to]
+
+      year_end = Date.strptime(rar[:to].to_s, "%Y%m%d")
+      months.include?(year_end.strftime("%Y%m"))
+    rescue Date::Error, TypeError
+      false
+    end
+
+    def balance_accounts_in(range)
+      (
+        @parsed.accounts.keys + @parsed.opening_balances.keys + @parsed.closing_balances.keys +
+          @parsed.period_changes.values.flat_map { |hash| hash.keys.map { |key| dimension_parts(key).first } }
+      ).uniq.select { |number| range.cover?(number) }.sort
+    end
+  end
+end

data/lib/sie_analysis/budgets.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module SieAnalysis
+  # Compare only explicitly exported monthly income budgets with matching ledger rows.
+  module Budgets
+    private
+
+    def budget_overview(months, dimension)
+      rows = months.flat_map do |month|
+        (@parsed.budgets[month] || {}).filter_map do |key, raw|
+          budget_row(month, key, raw, dimension)
+        end
+      end
+      rows.sort_by! { |row| [row[:month], row[:dimension_code].to_s, row[:account_number]] }
+      {
+        status: rows.empty? ? "unavailable" : "available",
+        rows:
+      }
+    end
+
+    def budget_row(month, key, raw, dimension)
+      account, dim, code = dimension_parts(key)
+      return unless dim == (dimension && Analysis::DIMENSIONS.fetch(dimension))
+
+      group = Groups.for_account(account)
+      return unless income_group?(group)
+
+      budget = round_money(present_amount(raw, group.fetch(:kind)))
+      actual_raw = (@parsed.period_changes[month] || {}).fetch(key, BigDecimal("0"))
+      actual = round_money(present_amount(actual_raw, group.fetch(:kind)))
+      {
+        month: "#{month[0, 4]}-#{month[4, 2]}",
+        account_number: account, account_name: @parsed.accounts[account],
+        dimension_code: code, dimension_label: code && (@parsed.objects[[dim, code]] || code),
+        budget:, actual:, variance: round_money(actual - budget)
+      }
+    end
+  end
+end

data/lib/sie_analysis/dimension_statements.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module SieAnalysis
+  # Cost-center / project income and account-row builders for Analysis.
+  module DimensionStatements
+    private
+
+    def dimension_income_groups(months, dimension)
+      dim_no = Analysis::DIMENSIONS.fetch(dimension)
+      totals = accumulate_dimension_totals(months, dim_no)
+      groups = dimension_group_rows(totals, dim_no)
+      revenue = totals.values.sum { |values| values[:revenue] }
+      expenses = totals.values.sum { |values| values[:expenses] }
+      {
+        revenue: round_money(revenue),
+        expenses: round_money(expenses),
+        result: round_money(revenue - expenses),
+        groups:
+      }
+    end
+
+    def accumulate_dimension_totals(months, dim_no)
+      totals = Hash.new { |hash, key| hash[key] = { revenue: BigDecimal("0"), expenses: BigDecimal("0"), accounts: Hash.new(BigDecimal("0")) } }
+      months.each do |month|
+        (@parsed.period_changes[month] || {}).each do |key, raw|
+          account, dim, code = dimension_parts(key)
+          next unless dim == dim_no && code
+
+          group = Groups.for_account(account)
+          next unless income_group?(group)
+
+          presented = present_amount(raw, group.fetch(:kind))
+          bucket = totals[code]
+          bucket[group.fetch(:kind) == :revenue ? :revenue : :expenses] += presented
+          bucket[:accounts][account] += presented
+        end
+      end
+      totals
+    end
+
+    def dimension_group_rows(totals, dim_no)
+      rows = totals.map do |code, values|
+        accounts = values[:accounts].filter_map do |number, amount|
+          next if amount.zero?
+
+          { account_number: number, account_name: @parsed.accounts[number], amount: round_money(amount) }
+        end
+        {
+          code:,
+          label: @parsed.objects[[dim_no, code]] || code,
+          amount: round_money(values[:revenue] - values[:expenses]),
+          accounts: accounts.sort_by { |row| row.fetch(:account_number) }
+        }
+      end
+      rows.sort_by { |group| group.fetch(:code) }
+    end
+
+    def dimension_account_rows(month, dimension)
+      dim_no = Analysis::DIMENSIONS.fetch(dimension)
+      rows = []
+      (@parsed.period_changes[month] || {}).each do |key, raw|
+        account, dim, code = dimension_parts(key)
+        next unless dim == dim_no && code
+
+        group = Groups.for_account(account)
+        next unless group
+
+        presented = presented_period(raw, group)
+        next if presented.zero?
+
+        rows << {
+          account_number: account,
+          account_name: @parsed.accounts[account],
+          group_code: group.fetch(:code),
+          dimension_code: code,
+          movement: round_money(presented),
+          dimension_label: @parsed.objects[[dim_no, code]] || code
+        }
+      end
+      rows.sort_by { |row| [row.fetch(:dimension_code), row.fetch(:account_number)] }
+    end
+  end
+end

data/lib/sie_analysis/groups.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module SieAnalysis
+  module Groups
+    INCOME = [
+      { code: "revenue", label: "Revenue", range: 3000..3999, kind: :revenue },
+      { code: "cost_of_goods", label: "Cost of goods sold", range: 4000..4999, kind: :expense },
+      { code: "external_costs", label: "External costs", range: 5000..6999, kind: :expense },
+      { code: "personnel_costs", label: "Personnel costs", range: 7000..7699, kind: :expense },
+      { code: "depreciation", label: "Depreciation", range: 7700..7899, kind: :expense },
+      { code: "other_operating", label: "Other operating items", range: 7900..7999, kind: :expense },
+      { code: "financial_income", label: "Financial income", range: 8000..8399, kind: :revenue },
+      { code: "financial_expenses", label: "Financial expenses", range: 8400..8799, kind: :expense },
+      { code: "appropriations_tax", label: "Appropriations and tax", range: 8800..8999, kind: :expense }
+    ].freeze
+
+    BALANCE = [
+      { code: "assets", label: "Assets", range: 1000..1999, kind: :asset },
+      { code: "equity_and_liabilities", label: "Equity and liabilities", range: 2000..2999, kind: :equity_liability }
+    ].freeze
+
+    CASH_RANGE = 1910..1999
+
+    def self.for_account(number)
+      (INCOME + BALANCE).find { |group| group.fetch(:range).cover?(number) }
+    end
+  end
+end

data/lib/sie_analysis/income_statements.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module SieAnalysis
+  # BAS income-statement and undimensioned account-row builders for Analysis.
+  module IncomeStatements
+    private
+
+    def income_statement(months, dimension)
+      dimension ? dimension_income_groups(months, dimension) : bas_income_groups(months)
+    end
+
+    def bas_income_groups(months)
+      groups = Groups::INCOME.map { |group| bas_group_row(months, group) }
+      revenue = sum_kind(groups, :revenue)
+      expenses = sum_kind(groups, :expense)
+      {
+        revenue: round_money(revenue),
+        expenses: round_money(expenses),
+        result: round_money(revenue - expenses),
+        groups: groups.reject { |group| group.fetch(:amount).zero? && group.fetch(:accounts).empty? }
+      }
+    end
+
+    def bas_group_row(months, group)
+      rows = account_amounts_for_range(months, group.fetch(:range), group.fetch(:kind))
+      {
+        code: group.fetch(:code),
+        label: group.fetch(:label),
+        amount: round_money(rows.sum { |row| row.fetch(:amount) }),
+        accounts: rows.reject { |row| row.fetch(:amount).zero? }
+      }
+    end
+
+    def sum_kind(groups, kind)
+      selected = groups.select do |row|
+        Groups::INCOME.find { |definition| definition[:code] == row[:code] }[:kind] == kind
+      end
+      selected.sum { |row| row.fetch(:amount) }
+    end
+
+    def account_rows_for_month(month, dimension)
+      return dimension_account_rows(month, dimension) if dimension
+
+      amounts = Hash.new(BigDecimal("0"))
+      (@parsed.period_changes[month] || {}).each do |key, raw|
+        account, dim, code = dimension_parts(key)
+        next if dim || code
+
+        group = Groups.for_account(account)
+        next unless group
+
+        amounts[account] += presented_period(raw, group)
+      end
+      amounts.filter_map { |number, amount| account_row(number, amount) unless amount.zero? }
+             .sort_by { |row| row.fetch(:account_number) }
+    end
+
+    def presented_period(raw, group)
+      income_group?(group) ? present_amount(raw, group.fetch(:kind)) : present_balance(raw, group.fetch(:kind))
+    end
+
+    def account_row(number, amount)
+      group = Groups.for_account(number)
+      {
+        account_number: number,
+        account_name: @parsed.accounts[number],
+        group_code: group&.fetch(:code),
+        movement: round_money(amount),
+        dimension_code: nil, dimension_label: nil
+      }
+    end
+
+    def account_amounts_for_range(months, range, kind)
+      totals = Hash.new(BigDecimal("0"))
+      months.each do |month|
+        (@parsed.period_changes[month] || {}).each do |key, raw|
+          account, dim, code = dimension_parts(key)
+          next if dim || code
+          next unless range.cover?(account)
+
+          totals[account] += present_amount(raw, kind)
+        end
+      end
+      totals.map { |number, amount| { account_number: number, account_name: @parsed.accounts[number], amount: round_money(amount) } }
+            .sort_by { |row| row.fetch(:account_number) }
+    end
+
+    def monthly_totals(months, dimension)
+      return if months.length <= 1
+
+      months.map do |month|
+        income = income_statement([month], dimension)
+        {
+          month: "#{month[0, 4]}-#{month[4, 2]}",
+          revenue: income.fetch(:revenue),
+          expenses: income.fetch(:expenses),
+          result: income.fetch(:result)
+        }
+      end
+    end
+
+    def highlights(income, balance)
+      revenue = income.fetch(:revenue)
+      result = income.fetch(:result)
+      margin = revenue.zero? ? nil : round_money((result / revenue) * 100)
+      { result:, profit_margin_percent: margin, cash_and_bank: balance[:cash_and_bank] }.compact
+    end
+  end
+end