hr_lite 0.8.0 → 0.11.0

data/app/models/hr_lite/leave_request.rb

@@ -1,5 +1,7 @@
 module HrLite
   class LeaveRequest < ApplicationRecord
+    include Approvable
+
     STATUSES = %w[pending approved rejected cancelled].freeze
 
     belongs_to :user, class_name: HrLite.config.user_class
@@ -38,30 +40,23 @@ module HrLite
 
     # --- transitions -------------------------------------------------------
 
+    # With a flow configured this is ONE RUNG: the request becomes `approved`
+    # only once the last rung is satisfied. With no flow — or from somebody
+    # the flow is not waiting on, such as HR overriding — the first approval
+    # settles it, exactly as before.
+    #
     # Returns false (leaving the request pending) when the balance no longer
-    # covers it — the re-check runs inside the row lock so two concurrent
+    # covers it; the re-check runs inside the row lock so two concurrent
     # approvals cannot overdraw one balance.
     def approve!(actor:, note: nil)
-      insufficient = false
-      transition!("approved", actor, note) do
-        # Serialize on the BALANCE row. `transition!`'s own lock is on this
-        # request, and two pending requests are two different rows — so both
-        # approvals could read the same untouched balance and overdraw it.
-        LeaveBalance.lock_for(user, leave_type, LeaveYear.key_for(start_date)) unless leave_type.unlimited?
-
-        if insufficient_balance_now?
-          insufficient = true
-          raise ActiveRecord::Rollback
-        end
-      end
-      return false if insufficient
+      return record_routed_decision!(actor, note, :approved) if awaiting?(actor)
 
-      notify_decision("Leave approved")
-      notify_team
-      true
+      approve_outright!(actor: actor, note: note)
     end
 
     def reject!(actor:, note:)
+      return record_routed_decision!(actor, note, :rejected) if awaiting?(actor)
+
       transition!("rejected", actor, note)
       notify_decision("Leave rejected")
       true
@@ -86,6 +81,9 @@ module HrLite
         # Cancelling an APPROVED leave hands the days back to the balance, so
         # it is a quota change as much as a status change.
         audit!("cancelled", actor, was_approved ? "was approved" : nil)
+        # And nobody should still be asked to decide a request that has been
+        # called off — it would sit in their inbox for ever.
+        approval_route.cancel_all!
       end
 
       Notifications.publish(
@@ -112,6 +110,63 @@ module HrLite
 
     private
 
+    # One rung answered. The route says whether that settles the request; if
+    # it does, the ordinary transition runs and does the real work — crediting
+    # or releasing balance, notifying, auditing — so routing never becomes a
+    # second path that can drift from the first.
+    def record_routed_decision!(actor, note, intent)
+      approval = approval_for(actor)
+      result = approval_route.decide!(approval, status: intent.to_s, actor: actor, note: note)
+
+      case result.outcome
+      when :approved then approve_outright!(actor: actor, note: note)
+      when :rejected then reject_outright!(actor: actor, note: note.presence || "Rejected")
+      else
+        notify_pending_approvers
+        true
+      end
+    end
+
+    def approve_outright!(actor:, note:)
+      insufficient = false
+      transition!("approved", actor, note) do
+        # Serialize on the BALANCE row. `transition!`'s own lock is on this
+        # request, and two pending requests are two different rows — so both
+        # approvals could read the same untouched balance and overdraw it.
+        LeaveBalance.lock_for(user, leave_type, LeaveYear.key_for(start_date)) unless leave_type.unlimited?
+
+        if insufficient_balance_now?
+          insufficient = true
+          raise ActiveRecord::Rollback
+        end
+      end
+      return false if insufficient
+
+      notify_decision("Leave approved")
+      notify_team
+      true
+    end
+
+    def reject_outright!(actor:, note:)
+      transition!("rejected", actor, note)
+      notify_decision("Leave rejected")
+      true
+    end
+
+    # The next rung has just opened; tell the people it opened on.
+    def notify_pending_approvers
+      approvers = pending_approvals.map(&:approver).compact.uniq
+      return if approvers.empty?
+
+      Notifications.publish(
+        "leave.requested",
+        title: "#{HrLite.display_name(user)} — #{leave_type.name} (#{date_range_label}) needs your approval",
+        body: reason.presence,
+        path: "/admin/leave_requests/#{id}",
+        bell_to: approvers
+      )
+    end
+
     def transition!(new_status, actor, note)
       with_lock do
         raise ActiveRecord::RecordInvalid.new(self), "not pending" unless pending?

data/app/models/hr_lite/loan.rb

@@ -0,0 +1,65 @@
+module HrLite
+  # A salary advance or loan, repaid by a fixed monthly deduction.
+  #
+  # The outstanding balance is DERIVED from the repayments actually taken,
+  # never stored. A stored balance and a recomputed payroll run disagree the
+  # first time somebody deletes a draft.
+  class Loan < ApplicationRecord
+    include EncryptedMoney
+    include Audited
+
+    STATUSES = %w[active closed cancelled].freeze
+
+    encrypted_money :principal, :monthly_instalment
+
+    belongs_to :user, class_name: HrLite.config.user_class
+    belongs_to :approved_by, class_name: HrLite.config.user_class, optional: true
+    has_many :loan_repayments, class_name: "HrLite::LoanRepayment", dependent: :destroy
+
+    validates :status, inclusion: { in: STATUSES }
+    validates :starts_on, presence: true
+    validate :amounts_are_positive
+    validate :instalment_is_not_larger_than_the_loan
+
+    scope :active, -> { where(status: "active") }
+
+    STATUSES.each { |s| define_method("#{s}?") { status == s } }
+
+    def repaid = loan_repayments.sum(BigDecimal(0)) { |r| r.amount || BigDecimal(0) }
+
+    def outstanding = [ principal - repaid, BigDecimal(0) ].max
+
+    # What to deduct this month: the instalment, or whatever is left if that
+    # is less — the last instalment is almost never a round one.
+    def instalment_for(period_month)
+      return BigDecimal(0) unless active?
+      return BigDecimal(0) if period_month < starts_on.beginning_of_month
+      return BigDecimal(0) if loan_repayments.exists?(period_month: period_month)
+
+      [ monthly_instalment, outstanding ].min
+    end
+
+    # Called after a run is FINALIZED, not at compute: a draft is recomputed
+    # freely and each pass would otherwise book another repayment.
+    def record_repayment!(period_month, amount)
+      return if amount.nil? || amount <= 0
+
+      loan_repayments.create!(period_month: period_month, amount: amount)
+      update!(status: "closed") if outstanding.zero?
+    end
+
+    private
+
+    def amounts_are_positive
+      errors.add(:principal, "must be more than zero") unless principal&.positive?
+      errors.add(:monthly_instalment, "must be more than zero") unless monthly_instalment&.positive?
+    end
+
+    def instalment_is_not_larger_than_the_loan
+      return if principal.nil? || monthly_instalment.nil?
+      return if monthly_instalment <= principal
+
+      errors.add(:monthly_instalment, "cannot be more than the loan itself")
+    end
+  end
+end

data/app/models/hr_lite/loan_repayment.rb

@@ -0,0 +1,14 @@
+module HrLite
+  # One month's deduction actually taken. Written when the run is finalized,
+  # so recomputing a draft never books a repayment twice — and the unique
+  # index on [loan, month] means a retry cannot either.
+  class LoanRepayment < ApplicationRecord
+    include EncryptedMoney
+
+    encrypted_money :amount
+
+    belongs_to :loan, class_name: "HrLite::Loan"
+
+    validates :period_month, presence: true, uniqueness: { scope: :loan_id }
+  end
+end

data/app/models/hr_lite/payroll_line_item.rb

@@ -0,0 +1,57 @@
+module HrLite
+  # A one-off on one month's payslip: a bonus, an incentive, arrears after a
+  # backdated revision, a reimbursement, a one-time deduction.
+  #
+  # Dated to the MONTH, not to the run, so deleting a draft run and computing
+  # it again does not lose them.
+  class PayrollLineItem < ApplicationRecord
+    include EncryptedMoney
+    include Audited
+
+    encrypted_money :amount
+
+    belongs_to :component, class_name: "HrLite::SalaryComponent"
+    belongs_to :user, class_name: HrLite.config.user_class
+    belongs_to :created_by, class_name: HrLite.config.user_class, optional: true
+
+    validates :period_month, presence: true
+    validate :period_is_first_of_month
+    validate :amount_is_positive
+    validate :period_is_not_already_paid, on: :create
+
+    scope :for_month, ->(month) { where(period_month: month) }
+
+    def self.for_slip(user, period_month)
+      where(user_id: user.id, period_month: period_month).includes(:component)
+    end
+
+    private
+
+    def period_is_first_of_month
+      return if period_month.nil? || period_month.day == 1
+
+      errors.add(:period_month, "must be the 1st of a month")
+    end
+
+    # Amounts are signed by the component's KIND, not by the number: a
+    # deduction of -500 and a deduction of 500 would otherwise both be
+    # storable and mean opposite things.
+    def amount_is_positive
+      return if amount.nil? || amount.positive?
+
+      errors.add(:amount, "must be more than zero — a deduction is a deduction by its component, not by a minus sign")
+    end
+
+    # A published slip is immutable. Adding a line to that month afterwards
+    # would show on no payslip and quietly change the year-to-date totals the
+    # TDS projector reads.
+    def period_is_not_already_paid
+      return if user_id.nil? || period_month.nil?
+
+      settled = SalarySlip.settled.exists?(user_id: user_id, period_month: period_month)
+      return unless settled
+
+      errors.add(:period_month, "has already been paid — put this on the next open month")
+    end
+  end
+end

data/app/models/hr_lite/payroll_run.rb

@@ -64,6 +64,7 @@ module HrLite
         # Finalizing freezes every slip in the run. Who did it, to how many
         # people, is the row an investigation starts from.
         audit!("payroll.finalized", actor, "slips" => salary_slips.count)
+        book_loan_repayments!
       end
       Notifications.publish(
         "payroll.finalized",
@@ -77,6 +78,10 @@ module HrLite
       raise_unless %w[finalized]
       transaction do
         update!(status: "review")
+        # The slips are editable again, so the repayments booked at finalize
+        # have to come back off the loans — otherwise unlocking and
+        # refinalizing takes the instalment twice.
+        unbook_loan_repayments!
         # Reopening frozen slips for editing is the single most sensitive
         # transition in the module — it is the one that has to leave a trace.
         audit!("payroll.unlocked", actor, "slips" => salary_slips.count)
@@ -124,6 +129,35 @@ module HrLite
 
     private
 
+    # A repayment is booked when the run is FINALIZED, never at compute: a
+    # draft is recomputed as often as the operator likes, and each pass would
+    # otherwise take another instalment off the loan.
+    def book_loan_repayments!
+      salary_slips.includes(:user).find_each do |slip|
+        taken = slip.deduction_amount("loan_repayment")
+        next unless taken.positive?
+
+        remaining = taken
+        Loan.active.where(user_id: slip.user_id).order(:starts_on).each do |loan|
+          break unless remaining.positive?
+
+          share = [ loan.instalment_for(period_month), remaining ].min
+          next unless share.positive?
+
+          loan.record_repayment!(period_month, share)
+          remaining -= share
+        end
+      end
+    end
+
+    def unbook_loan_repayments!
+      LoanRepayment.where(period_month: period_month)
+                   .where(loan_id: Loan.where(user_id: salary_slips.select(:user_id)))
+                   .destroy_all
+      Loan.where(user_id: salary_slips.select(:user_id), status: "closed")
+          .each { |loan| loan.update!(status: "active") if loan.outstanding.positive? }
+    end
+
     # Amounts stay out of it on purpose: audit_logs is a plaintext table and
     # every slip amount in this module is encrypted. The row records WHO
     # moved the run and HOW FAR, never what anyone is paid.

data/app/models/hr_lite/salary_component.rb

@@ -0,0 +1,59 @@
+module HrLite
+  # An earning or deduction head. Data, so an install can add "Night shift
+  # allowance" without a gem release — and so a payslip line says what it
+  # was for instead of disappearing into "other".
+  class SalaryComponent < ApplicationRecord
+    include Audited
+
+    KINDS = %w[earning deduction].freeze
+
+    # Heads the structure itself owns. A line item may not use these — they
+    # already have a column, and two sources for one number is how a payslip
+    # stops adding up.
+    STRUCTURAL_CODES = %w[basic hra special_allowance other_earnings].freeze
+
+    has_many :payroll_line_items, class_name: "HrLite::PayrollLineItem",
+                                  foreign_key: :component_id, dependent: :restrict_with_error
+
+    validates :code, presence: true, uniqueness: { case_sensitive: false },
+                     format: { with: /\A[a-z0-9_]+\z/, message: "is lowercase letters, numbers and underscores" }
+    validates :label, presence: true
+    validates :kind, inclusion: { in: KINDS }
+    validate :code_is_not_a_structural_one, on: :create
+
+    scope :active, -> { where(active: true) }
+    scope :earnings, -> { where(kind: "earning") }
+    scope :deductions, -> { where(kind: "deduction") }
+    scope :ordered, -> { order(:position, :label) }
+
+    KINDS.each { |k| define_method("#{k}?") { kind == k } }
+
+    def self.seed_defaults!
+      [
+        { code: "bonus", label: "Bonus", prorated: false, position: 10 },
+        { code: "incentive", label: "Incentive", prorated: false, position: 20 },
+        { code: "arrears", label: "Arrears", prorated: false, position: 30 },
+        { code: "lta", label: "Leave travel allowance", prorated: false, position: 40 },
+        { code: "reimbursement", label: "Reimbursement", prorated: false, taxable: false,
+          counts_for_esi: false, position: 50 },
+        { code: "loan_repayment", label: "Loan repayment", kind: "deduction",
+          prorated: false, taxable: false, counts_for_esi: false, position: 60 },
+        { code: "other_deduction", label: "Other deduction", kind: "deduction",
+          prorated: false, taxable: false, counts_for_esi: false, position: 70 }
+      ].filter_map do |attributes|
+        next if exists?(code: attributes[:code])
+
+        create!(attributes)
+        attributes[:code]
+      end
+    end
+
+    private
+
+    def code_is_not_a_structural_one
+      return unless STRUCTURAL_CODES.include?(code.to_s)
+
+      errors.add(:code, "is already a salary-structure field — pick another name")
+    end
+  end
+end

data/app/models/hr_lite/tax_declaration.rb

@@ -0,0 +1,93 @@
+module HrLite
+  # What an employee claims for the year, section by section, replacing the
+  # single `declared_annual_deductions` figure an admin used to type in.
+  #
+  # The whole year's TDS is projected from this number, so it matters that it
+  # is broken down, that the employee submitted it themselves, and that HR
+  # can record what the proof actually supported.
+  class TaxDeclaration < ApplicationRecord
+    include Audited
+
+    STATUSES = %w[draft submitted verified rejected].freeze
+    REGIMES = %w[new old].freeze
+
+    has_many :tax_declaration_items, -> { order(:section) },
+             class_name: "HrLite::TaxDeclarationItem",
+             foreign_key: :declaration_id, dependent: :destroy
+    accepts_nested_attributes_for :tax_declaration_items, allow_destroy: true
+
+    belongs_to :user, class_name: HrLite.config.user_class
+    belongs_to :verified_by, class_name: HrLite.config.user_class, optional: true
+
+    validates :status, inclusion: { in: STATUSES }
+    validates :regime, inclusion: { in: REGIMES }
+    validates :financial_year, presence: true, uniqueness: { scope: :user_id }
+    validate :financial_year_opens_in_april
+
+    STATUSES.each { |s| define_method("#{s}?") { status == s } }
+
+    def self.for(user, period_month)
+      find_by(user_id: user.id, financial_year: FinancialYear.start_for(period_month))
+    end
+
+    def label = "FY #{FinancialYear.label(financial_year)}"
+
+    def declared_total = tax_declaration_items.sum(BigDecimal(0)) { |i| i.declared_amount || 0 }
+
+    # What payroll should actually deduct against. Until HR has verified it,
+    # the declared figure stands — asking somebody to overpay tax all year
+    # because paperwork is slow is its own kind of wrong — but once verified,
+    # only what the proof supported counts.
+    def allowable_total
+      return declared_total unless verified?
+
+      tax_declaration_items.sum(BigDecimal(0)) { |i| i.verified_amount || BigDecimal(0) }
+    end
+
+    def submit!(actor:)
+      raise ActiveRecord::RecordInvalid.new(self), "not a draft" unless draft? || rejected?
+
+      update!(status: "submitted", submitted_at: Time.current)
+      Notifications.publish(
+        "tax.declaration_submitted",
+        title: "#{HrLite.display_name(user)} submitted a #{label} tax declaration",
+        path: "/admin/tax_declarations/#{id}",
+        bell_to: HrLite.users_holding("tax.manage").to_a
+      )
+      true
+    end
+
+    def verify!(actor:, note: nil)
+      raise ActiveRecord::RecordInvalid.new(self), "not submitted" unless submitted?
+
+      update!(status: "verified", verified_by_id: actor.id, verified_at: Time.current,
+              note: note.presence)
+      notify_employee("Your #{label} tax declaration was verified")
+      true
+    end
+
+    def reject!(actor:, note:)
+      raise ArgumentError, "a rejection needs a reason" if note.blank?
+
+      update!(status: "rejected", verified_by_id: actor.id, verified_at: Time.current, note: note)
+      notify_employee("Your #{label} tax declaration needs attention")
+      true
+    end
+
+    private
+
+    def notify_employee(title)
+      Notifications.publish(
+        "tax.declaration_decided", title: title, body: note.presence,
+        path: "/tax_declaration", bell_to: [ user ], email_to: [ user ]
+      )
+    end
+
+    def financial_year_opens_in_april
+      return if financial_year.blank?
+      return if financial_year == FinancialYear.start_for(financial_year)
+
+      errors.add(:financial_year, "must be 1 April — a declaration covers a whole year")
+    end
+  end
+end

data/app/models/hr_lite/tax_declaration_item.rb

@@ -0,0 +1,32 @@
+module HrLite
+  # One line of a declaration: "80C — ELSS — ₹1,50,000".
+  #
+  # `verified_amount` is what the proof actually supported, which is often
+  # less than what was claimed and is the number payroll uses once HR has
+  # looked. Both are encrypted: what somebody invests is their business.
+  class TaxDeclarationItem < ApplicationRecord
+    include EncryptedMoney
+
+    SECTIONS = %w[80c 80d 80ccd_1b 24b hra other].freeze
+
+    encrypted_money :declared_amount, :verified_amount
+
+    belongs_to :declaration, class_name: "HrLite::TaxDeclaration"
+
+    validates :section, inclusion: { in: SECTIONS }
+    validate :amounts_are_not_negative
+
+    def section_label
+      { "80c" => "80C — investments", "80d" => "80D — health insurance",
+        "80ccd_1b" => "80CCD(1B) — NPS", "24b" => "24(b) — home loan interest",
+        "hra" => "HRA exemption", "other" => "Other" }.fetch(section, section)
+    end
+
+    private
+
+    def amounts_are_not_negative
+      errors.add(:declared_amount, "cannot be negative") if declared_amount&.negative?
+      errors.add(:verified_amount, "cannot be negative") if verified_amount&.negative?
+    end
+  end
+end

data/app/services/hr_lite/approval_route.rb

@@ -0,0 +1,109 @@
+module HrLite
+  # Drives one record through its flow: opens the first rung, advances when a
+  # rung is satisfied, and reports when the whole thing is settled.
+  #
+  # It decides NOTHING about the subject itself. `Approvable` owns what
+  # "approved" means for a leave request; this class only knows whose turn it
+  # is. That split is why adding expenses later needs no change here.
+  class ApprovalRoute
+    Result = Struct.new(:outcome, :approval, keyword_init: true)
+
+    def initialize(subject)
+      @subject = subject
+    end
+
+    attr_reader :subject
+
+    def flow = @flow ||= ApprovalFlow.for(subject.class.name)
+
+    def routed? = flow.present?
+
+    # Opens the first rung that has anybody on it. A rung whose rule resolves
+    # to nobody — no manager recorded, say — is SKIPPED rather than left
+    # waiting for a person who does not exist.
+    def open!
+      return Result.new(outcome: :unrouted) unless routed?
+
+      flow.approval_steps.ordered.each do |step|
+        approvers = step.approvers_for(subject)
+        next skip!(step) if approvers.empty?
+
+        create_rows(step, approvers)
+        return Result.new(outcome: :pending)
+      end
+
+      # Every rung skipped: nobody in the flow can decide, so the request
+      # carries itself. Better than a request that can never be answered.
+      Result.new(outcome: :approved)
+    end
+
+    def pending_rows = Approval.pending.where(subject: subject)
+
+    def current_position = pending_rows.minimum(:position)
+
+    # Records one decision and works out what it means for the record.
+    #
+    #   :pending  — the rung still needs somebody
+    #   :approved — every rung is satisfied
+    #   :rejected — one refusal ends it
+    #   :returned — sent back to the requester for correction
+    def decide!(approval, status:, actor:, note: nil)
+      approval.decide!(status: status, actor: actor, note: note)
+
+      case status.to_s
+      when "rejected", "returned"
+        cancel_remaining!(approval.position)
+        Result.new(outcome: status.to_sym, approval: approval)
+      else
+        advance_from(approval)
+      end
+    end
+
+    def cancel_all!
+      pending_rows.update_all(status: "cancelled", decided_at: Time.current) # rubocop:disable Rails/SkipsModelValidations
+    end
+
+    private
+
+    def advance_from(approval)
+      rung = Approval.where(subject: subject).at_position(approval.position)
+      # A unanimous rung waits for everybody; otherwise the first answer
+      # settles it and the rest are stood down.
+      if approval.step.unanimous && rung.pending.exists?
+        return Result.new(outcome: :pending, approval: approval)
+      end
+
+      rung.pending.each { |other| other.decide!(status: "skipped", actor: nil) }
+      open_next_after(approval.position) || Result.new(outcome: :approved, approval: approval)
+    end
+
+    def open_next_after(position)
+      flow.approval_steps.ordered.each do |step|
+        next if step.position <= position
+
+        approvers = step.approvers_for(subject)
+        next skip!(step) if approvers.empty?
+
+        create_rows(step, approvers)
+        return Result.new(outcome: :pending)
+      end
+      nil
+    end
+
+    def create_rows(step, approvers)
+      approvers.uniq.each do |approver|
+        Approval.create!(subject: subject, step: step, position: step.position,
+                         approver_id: approver.id)
+      end
+    end
+
+    # Nothing to record: a rung nobody occupies never happened. Returning nil
+    # keeps `each`'s `next` readable at the call sites.
+    def skip!(_step) = nil
+
+    def cancel_remaining!(position)
+      Approval.pending.where(subject: subject).where("position >= ?", position)
+              .each { |row| row.decide!(status: "cancelled", actor: nil) }
+    end
+  end
+end