hr_lite 0.5.0 → 0.5.3

data/app/models/hr_lite/leave_balance.rb

@@ -19,6 +19,34 @@ module HrLite
       find_or_initialize_by(user_id: user.id, leave_type: leave_type, year: year)
     end
 
+    # Persisted and row-locked so concurrent writers serialize here. The
+    # create sits in its own savepoint: on PostgreSQL a failed INSERT aborts
+    # the enclosing transaction, so a plain rescue could never run.
+    def self.lock_for(user, leave_type, year)
+      attributes = { user_id: user.id, leave_type_id: leave_type.id, year: year }
+      balance = find_by(attributes)
+      balance ||= begin
+        transaction(requires_new: true) { create!(attributes) }
+      rescue ActiveRecord::RecordNotUnique, ActiveRecord::RecordInvalid
+        find_by!(attributes)
+      end
+      balance.lock!
+      balance
+    end
+
+    # The single write path for the stored adjustment. Both callers — the
+    # comp-off credit and the admin correction — increment the same column,
+    # and read-modify-write without the lock lost one of them.
+    def self.adjust!(user, leave_type, year, delta:, note:)
+      transaction do
+        balance = lock_for(user, leave_type, year)
+        balance.adjustment += delta
+        balance.adjustment_note = [ balance.adjustment_note.presence, note ].compact.join("; ")
+        balance.save!
+        balance
+      end
+    end
+
     def entitled(as_of: Date.current)
       return Float::INFINITY if leave_type.unlimited?
 
@@ -30,7 +58,12 @@ module HrLite
       requests = LeaveRequest.approved
                              .where(user_id: user_id, leave_type_id: leave_type_id)
                              .where(start_date: range)
-      requests.sum { |request| LeaveDayCounter.count(request) }
+      # ONE calendar for the whole leave year, reused across every request.
+      # Building one per request meant a Holiday query and a Setting query
+      # each — and the admin balances grid reads this cell for every employee
+      # times every leave type.
+      calendar = WorkingCalendar.new(range)
+      requests.sum { |request| LeaveDayCounter.count(request, calendar: calendar) }
     end
 
     def available(as_of: Date.current)
@@ -46,28 +79,41 @@ module HrLite
     def accrued_base(as_of)
       range = LeaveYear.range(year)
       start = accrual_start(range)
-      return 0 if start.nil?
+      finish = accrual_end(range)
+      return 0 if start.nil? || start > finish
 
       monthly_rate = leave_type.annual_quota / 12
       months =
         if leave_type.accrual == "monthly"
-          cap = [ as_of, range.last ].min
+          cap = [ as_of, finish ].min
           start > cap ? 0 : months_between(start, cap)
         else
-          months_between(start, range.last)
+          months_between(start, finish)
         end
       monthly_rate * months
     end
 
     # nil when the person joins only after this leave year ends.
     def accrual_start(range)
-      doj = EmployeeProfile.where(user_id: user_id).pick(:date_of_joining)
+      doj = employment_window.first
       return range.first if doj.nil? || doj <= range.first
 
       start = doj.day <= 15 ? doj.beginning_of_month : doj.next_month.beginning_of_month
       start > range.last ? nil : start
     end
 
+    # Quota stops accruing on the last working day — entitlement used to keep
+    # growing for months after someone had left.
+    def accrual_end(range)
+      exit_date = employment_window.last
+      exit_date ? [ exit_date, range.last ].min : range.last
+    end
+
+    def employment_window
+      @employment_window ||= EmployeeProfile.where(user_id: user_id)
+                                            .pick(:date_of_joining, :date_of_exit) || [ nil, nil ]
+    end
+
     def months_between(from, to)
       (to.year * 12 + to.month) - (from.year * 12 + from.month) + 1
     end

data/app/models/hr_lite/leave_request.rb

@@ -44,6 +44,11 @@ module HrLite
     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
@@ -73,10 +78,15 @@ module HrLite
 
     def cancel!(actor:)
       was_approved = approved?
-      self.status = "cancelled"
-      self.decided_by_id = actor.id
-      self.decided_at = Time.current
-      save!
+      transaction do
+        self.status = "cancelled"
+        self.decided_by_id = actor.id
+        self.decided_at = Time.current
+        save!
+        # 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)
+      end
 
       Notifications.publish(
         "leave.cancelled",
@@ -112,15 +122,36 @@ module HrLite
         self.decided_at = Time.current
         self.decision_note = note
         save!
+        audit!(new_status, actor, note)
       end
     end
 
+    # Approve and reject both come through `transition!`, and `with_lock` is
+    # already a transaction — so a failed audit row rolls the decision back
+    # rather than leaving one that nobody can account for. The employee's own
+    # `reason` is deliberately not copied here; the approver's note is.
+    def audit!(action, actor, note)
+      AuditLog.record!(
+        action: "leave.#{action}", subject: self, actor: actor,
+        changes: {
+          "employee" => HrLite.display_name(user),
+          "type" => leave_type.code,
+          "dates" => date_range_label,
+          "days" => days_count&.to_s("F"),
+          "note" => note.presence
+        }.compact
+      )
+    end
+
     # This request is still pending here, so balance.used excludes it:
     # approving is valid iff the request fits the remaining balance.
     def insufficient_balance_now?
       return false if leave_type.unlimited?
 
-      LeaveDayCounter.count(self) > balance.available
+      # Same as-of date the create-time check used. Reading it as of TODAY
+      # meant a request validated against the balance it would have on the
+      # leave dates could never be approved on a monthly-accrual type.
+      LeaveDayCounter.count(self) > balance.available(as_of: start_date)
     end
 
     def notify_requested

data/app/models/hr_lite/leave_type.rb

@@ -13,6 +13,9 @@ module HrLite
     validates :annual_quota, numericality: { greater_than_or_equal_to: 0 }, allow_nil: true
     validates :carry_forward_cap, numericality: { greater_than_or_equal_to: 0 }
     validate :single_comp_off_type
+    # Retiring the flagged type hands the flag back, so a replacement can take
+    # it and `comp_off_type` (which resolves through `active`) keeps working.
+    before_save :release_comp_off_when_retired
 
     scope :active, -> { where(active: true).order(:position, :id) }
 
@@ -28,12 +31,19 @@ module HrLite
     private
 
     # Approvals credit into THE comp-off type — two flagged types would
-    # make the credit target position-order roulette.
+    # make the credit target position-order roulette. Scoped to ACTIVE rows
+    # so it agrees with `comp_off_type`, which resolves through `active`:
+    # counting a retired type here made the flag impossible to move to its
+    # replacement, and comp-off approval then failed for everyone.
     def single_comp_off_type
-      return unless comp_off
+      return unless comp_off && active
 
-      clash = self.class.where(comp_off: true).where.not(id: id)
+      clash = self.class.active.where(comp_off: true).where.not(id: id)
       errors.add(:comp_off, "is already set on #{clash.first.name}") if clash.exists?
     end
+
+    def release_comp_off_when_retired
+      self.comp_off = false if comp_off && !active
+    end
   end
 end

data/app/models/hr_lite/payroll_run.rb

@@ -13,6 +13,8 @@ module HrLite
     validates :period_month, presence: true, uniqueness: true
     validates :status, inclusion: { in: STATUSES }
     validate :period_is_first_of_month
+    # Create-only: an existing run must stay transitionable forever.
+    validate :period_is_a_closed_month, on: :create
     before_destroy :draft_only_destroy
 
     scope :recent_first, -> { order(period_month: :desc) }
@@ -27,23 +29,42 @@ module HrLite
       period_month.strftime("%B %Y")
     end
 
+    # `processing` is allowed back in so a run stranded there by a killed
+    # process (deploy roll, timeout) can be recomputed instead of blocking
+    # that month forever.
     def compute!(actor:)
-      raise_unless %w[draft review]
-
-      update!(status: "processing")
-      PayrollRunProcessor.call(self)
-      update!(status: "review", processed_at: Time.current)
-      true
-    rescue => e
-      update_columns(status: "draft") # rubocop:disable Rails/SkipsModelValidations
-      raise e
+      raise_unless %w[draft review processing]
+      previous = status
+
+      begin
+        update!(status: "processing")
+        PayrollRunProcessor.call(self)
+        transaction do
+          update!(status: "review", processed_at: Time.current)
+          audit!("payroll.computed", actor,
+                 "slips" => salary_slips.count, "warnings" => warnings.length,
+                 "from_status" => previous)
+        end
+        true
+      rescue => e
+        # Restore what the run WAS. Hardcoding "draft" here used to demote a
+        # finalized or published run — which then exposed the delete-draft
+        # control, and that cascades over every salary slip.
+        update_columns(status: previous) # rubocop:disable Rails/SkipsModelValidations
+        raise e
+      end
     end
 
     def finalize!(actor:)
       raise_unless %w[review]
       raise ActiveRecord::RecordInvalid.new(self), "no slips" if salary_slips.none?
 
-      update!(status: "finalized", finalized_at: Time.current, finalized_by_id: actor.id)
+      transaction do
+        update!(status: "finalized", finalized_at: Time.current, finalized_by_id: actor.id)
+        # 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)
+      end
       Notifications.publish(
         "payroll.finalized",
         title: "Payroll #{label} finalized — #{salary_slips.count} slips, net #{Money.round2(total_net).to_s('F')}",
@@ -54,21 +75,37 @@ module HrLite
 
     def unlock!(actor:)
       raise_unless %w[finalized]
-      update!(status: "review")
+      transaction do
+        update!(status: "review")
+        # 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)
+      end
       true
     end
 
     def publish!(actor:)
       raise_unless %w[finalized]
-      update!(status: "published", published_at: Time.current, published_by_id: actor.id)
+      transaction do
+        update!(status: "published", published_at: Time.current, published_by_id: actor.id)
+        audit!("payroll.published", actor, "slips" => salary_slips.count)
+      end
 
       slips = salary_slips.includes(:user).to_a
+      # Everyone is emailed — a final settlement matters most to the person who
+      # has left — but a bell is only useful to someone who can still sign in,
+      # and offboarding revokes that. Sending one pointed at a page they cannot
+      # open is just noise in a place they will never look.
+      exited = EmployeeProfile.where(user_id: slips.map(&:user_id))
+                              .where(date_of_exit: ..Date.current)
+                              .pluck(:user_id).to_set
+
       Notifications.publish(
         "payroll.published",
         title: "Your salary slip for #{label} is ready",
         body: "Open Earthly HR to view or download it.",
         path: "/salary_slips",
-        bell_to: slips.map(&:user),
+        bell_to: slips.reject { |slip| exited.include?(slip.user_id) }.map(&:user),
         email_to: slips.map(&:user)
       )
       true
@@ -87,6 +124,14 @@ module HrLite
 
     private
 
+    # 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.
+    def audit!(action, actor, changes)
+      AuditLog.record!(action: action, subject: self, actor: actor,
+                       changes: changes.merge("period" => label))
+    end
+
     def sum_slips(attribute)
       salary_slips.sum(BigDecimal(0)) { |slip| slip.public_send(attribute) || BigDecimal(0) }
     end
@@ -102,6 +147,16 @@ module HrLite
       errors.add(:period_month, "must be the 1st of a month")
     end
 
+    # Days that have not happened yet score as `upcoming`, which payroll folds
+    # into payable — so computing a month before it ends pays for days nobody
+    # worked, and once finalized the slips are immutable.
+    def period_is_a_closed_month
+      return unless period_month
+      return if period_month.end_of_month < Date.current
+
+      errors.add(:period_month, "must be a month that has already ended")
+    end
+
     def draft_only_destroy
       return if draft?
 

data/app/models/hr_lite/regularization_request.rb

@@ -49,6 +49,14 @@ module HrLite
     # InvalidMerge with the real story so the admin knows what to fix.
     def approve!(actor:, note: nil)
       transition!("approved", actor, note) do
+        # Re-checked at approval, not only at create: leave can be approved for
+        # that day while the ticket waits in the queue, and DayStatus ranks
+        # full-day leave above any punch — so the "fix" would write a record
+        # nothing reads while telling everyone attendance had been corrected.
+        if LeaveRequest.active_on(date).where(user_id: user_id, half_day: false).exists?
+          raise InvalidMerge, "the day is now covered by approved leave — cancel the leave first"
+        end
+
         record = AttendanceRecord.find_or_initialize_by(user_id: user_id, date: date)
         record.check_in_at = check_in_at if check_in_at
         record.check_out_at = check_out_at if check_out_at
@@ -63,10 +71,9 @@ module HrLite
         raise InvalidMerge, record.errors.full_messages.to_sentence unless record.valid?
 
         record.save!
-        AuditLog.create!(
-          actor: actor, action: "regularize",
-          subject_type: record.class.name, subject_id: record.id,
-          audited_changes: { "date" => record.date.to_s, "ticket" => id, "note" => reason }
+        AuditLog.record!(
+          action: "regularize", subject: record, actor: actor,
+          changes: { "date" => record.date.to_s, "ticket" => id, "note" => reason }
         )
       end
 

data/app/models/hr_lite/resignation.rb

@@ -29,9 +29,18 @@ module HrLite
         update!(status: "accepted", decided_by_id: actor.id, decided_at: Time.current,
                 decision_note: note.presence, proposed_last_day: final_day)
         profile = EmployeeProfile.find_by(user_id: user_id)
+        # Someone can resign before HR ever created their profile. That is not
+        # a reason to refuse the resignation — but the caller has to know
+        # nothing was stamped, because the screen used to claim it was.
+        @exit_date_recorded = profile.present?
         profile&.update!(date_of_exit: final_day)
       end
 
+      # Notice periods are the normal case, so access is revoked here only
+      # when the last day has already passed. Otherwise the person keeps
+      # working it out and leadership revokes from the employee page.
+      revoke_access! if final_day <= Date.current
+
       Notifications.publish(
         "resignation.accepted",
         title: "Resignation accepted — last working day #{final_day.strftime('%d %b %Y')}",
@@ -56,8 +65,21 @@ module HrLite
       true
     end
 
+    # False when the person had no employee profile to stamp — see accept!.
+    def exit_date_recorded?
+      @exit_date_recorded
+    end
+
     private
 
+    # Best-effort, like every other call of this hook: a host that cannot
+    # revoke must not roll back an accepted resignation.
+    def revoke_access!
+      HrLite.config.offboard_user.call(user)
+    rescue => e
+      Rails.logger.error("[hr_lite] offboard_user failed: #{e.class}: #{e.message}")
+    end
+
     def notify_submitted
       Notifications.publish(
         "resignation.submitted",
@@ -78,6 +100,11 @@ module HrLite
     def single_open_resignation
       if self.class.pending.where(user_id: user_id).exists?
         errors.add(:base, "You already have a pending resignation")
+      elsif self.class.where(user_id: user_id, status: "accepted").exists?
+        # Only `pending` used to block a second one, so someone whose exit was
+        # already agreed could resign again — and accepting the new one would
+        # overwrite the exit date payroll and attendance already clip to.
+        errors.add(:base, "Your resignation has already been accepted — talk to your manager to change the date")
       end
     end
   end

data/app/models/hr_lite/salary_slip.rb

@@ -18,6 +18,10 @@ module HrLite
     before_save :ensure_run_editable
 
     scope :published, -> { joins(:payroll_run).where(hr_lite_payroll_runs: { status: "published" }) }
+    # What counts as already paid for tax-to-date. A finalized run is money
+    # already decided; waiting for publication made the next month's TDS
+    # projection read those earnings as zero.
+    scope :settled, -> { joins(:payroll_run).where(hr_lite_payroll_runs: { status: %w[finalized published] }) }
     scope :recent_first, -> { order(period_month: :desc) }
 
     def published?
@@ -33,13 +37,12 @@ module HrLite
       lop_override || lop_days
     end
 
-    # Indian FY (Apr 1) to-date sums of PUBLISHED slips before this period —
+    # Indian FY (Apr 1) to-date sums of SETTLED slips before this period —
     # feeds the TDS projector and the slip's YTD table.
     def self.fy_to_date(user, period_month)
-      fy_start = period_month.month >= 4 ? Date.new(period_month.year, 4, 1)
-                                         : Date.new(period_month.year - 1, 4, 1)
-      slips = published.where(user_id: user.id)
-                       .where(period_month: fy_start...period_month)
+      fy_start = FinancialYear.start_for(period_month)
+      slips = settled.where(user_id: user.id)
+                     .where(period_month: fy_start...period_month)
       {
         gross: slips.sum(BigDecimal(0)) { |s| s.gross_earnings || BigDecimal(0) },
         tds: slips.sum(BigDecimal(0)) { |s| Money.d(s.deduction_amount("tds")) },

data/app/services/hr_lite/attendance_puncher.rb

@@ -4,6 +4,9 @@ module HrLite
   # without GPS or outside every office radius is recorded AND flagged —
   # denying GPS must not stop anyone from working.
   class AttendancePuncher
+    # What the browser can legitimately report (geo_punch.js).
+    GEO_STATUSES = %w[ok denied unavailable timeout insecure].freeze
+
     Result = Struct.new(:record, :error, keyword_init: true) do
       def ok? = error.nil?
     end
@@ -18,7 +21,11 @@ module HrLite
       @lat = lat.presence
       @lng = lng.presence
       @accuracy_m = accuracy_m.presence
-      @geo_status = geo_status
+      # Client-supplied and rendered straight into the admin-facing flag note.
+      # Anything outside the browser's real permission states is not evidence:
+      # a blank one (JS never ran) produced "without GPS ()", and a crafted one
+      # let an employee write reassuring text onto their own flag.
+      @geo_status = GEO_STATUSES.include?(geo_status.to_s) ? geo_status.to_s : "unavailable"
     end
 
     def call

data/app/services/hr_lite/calculators/esi.rb

@@ -1,9 +1,12 @@
 module HrLite
   module Calculators
-    # ESI: eligibility is decided on the FULL structure monthly gross
-    # (a low-attendance month must not pull someone into ESI); when
-    # eligible, contributions apply to the earned gross and round UP
-    # to the next rupee (ESIC rule).
+    # ESI: eligibility is decided on the FULL structure monthly gross (a
+    # low-attendance month must not pull someone into ESI), and specifically
+    # on the gross in force at the START of the ESIC contribution period —
+    # April–September or October–March. A rise past the ceiling mid-period
+    # does not end coverage; the caller resolves that period-start gross and
+    # passes it here. Contributions apply to the EARNED gross and round up to
+    # the next rupee (ESIC rule).
     module Esi
       Result = Struct.new(:applicable, :employee, :employer, keyword_init: true) do
         def applicable? = applicable

data/app/services/hr_lite/calculators/professional_tax.rb

@@ -8,7 +8,11 @@ module HrLite
         slabs = rates[state.to_s] || []
         earned = Money.d(gross_earned)
 
-        slab = slabs.reverse.find { |row| earned > row[:above] }
+        # `from:` is an INCLUSIVE lower bound — ₹25,000 is taxed, ₹24,999.50 is
+        # not. The older exclusive `above:` form still works so a host's own
+        # slab table keeps functioning, but it cannot express that boundary on
+        # a decimal amount: `above: 24999` taxed a prorated ₹24,999.50.
+        slab = slabs.reverse.find { |row| row[:from] ? earned >= row[:from] : earned > row[:above] }
         return BigDecimal(0) unless slab
 
         amount = slab[:monthly]

data/app/services/hr_lite/calculators/tds.rb

@@ -35,7 +35,14 @@ module HrLite
         taxable = [ projected - deductions, BigDecimal(0) ].max
 
         slab_tax = slab_tax_for(taxable, table[:slabs])
-        slab_tax = BigDecimal(0) if taxable <= table[:rebate_cap] # §87A full rebate
+        if taxable <= table[:rebate_cap]
+          slab_tax = BigDecimal(0) # §87A full rebate
+        elsif table[:marginal_relief]
+          # Just past the cliff the tax may not exceed the income earned above
+          # it — without this, one rupee over ₹12,00,000 costs ~₹60,000 of tax.
+          # Old regime carries no such relief, hence the per-regime flag.
+          slab_tax = [ slab_tax, taxable - table[:rebate_cap] ].min
+        end
         annual = Money.round_to_10(slab_tax * (1 + table[:cess_rate]))
 
         monthly = Money.round_rupee((annual - Money.d(fy_tds_paid)) / months_remaining)

data/app/services/hr_lite/leave_day_counter.rb

@@ -3,19 +3,24 @@ module HrLite
   # company-wide holidays inside the range are free; a half-day (single-day
   # requests only) consumes 0.5.
   module LeaveDayCounter
-    def self.count(leave_request)
+    # `calendar:` lets a caller counting many requests over the same span
+    # build ONE calendar and reuse it. Each one costs a Holiday query and a
+    # Setting query, and the balances grid counts every approved request of
+    # every employee for every leave type.
+    def self.count(leave_request, calendar: nil)
       count_range(
         start_date: leave_request.start_date,
         end_date: leave_request.end_date,
-        half_day: leave_request.half_day
+        half_day: leave_request.half_day,
+        calendar: calendar
       )
     end
 
-    def self.count_range(start_date:, end_date:, half_day: false)
+    def self.count_range(start_date:, end_date:, half_day: false, calendar: nil)
       return 0 if start_date.nil? || end_date.nil? || end_date < start_date
 
       range = start_date..end_date
-      working = WorkingCalendar.new(range).working_days_in(range)
+      working = (calendar || WorkingCalendar.new(range)).working_days_in(range)
       return BigDecimal("0.5") if half_day && working.positive?
 
       BigDecimal(working)

data/app/services/hr_lite/overview_query.rb

@@ -15,6 +15,17 @@ module HrLite
       LeaveRequest.active_on(@date).includes(:leave_type, :user).order(:start_date)
     end
 
+    # Comp-off and regularization are approvals too. Counting leave alone made
+    # the board announce "All present and accounted for" while both queues
+    # still had work in them.
+    def pending_comp_offs
+      CompOffRequest.pending.includes(:user).recent_first
+    end
+
+    def pending_regularizations
+      RegularizationRequest.pending.includes(:user).recent_first
+    end
+
     def flagged_today
       AttendanceRecord.for_date(@date).flagged.includes(:user)
     end
@@ -25,7 +36,7 @@ module HrLite
 
     def kpis
       {
-        pending: pending_requests.count,
+        pending: pending_requests.count + pending_comp_offs.count + pending_regularizations.count,
         on_leave: on_leave_today.count,
         flagged: flagged_today.count,
         missing_checkout: missing_checkout_yesterday.count

data/app/services/hr_lite/payroll_run_processor.rb

@@ -12,7 +12,10 @@ module HrLite
     end
 
     def call
-      warnings = []
+      # First in the list on purpose: if the statutory card is from an older
+      # financial year, every number below it is computed on last year's
+      # rates and that is the thing to read first.
+      warnings = Array(StatutoryRateCard.warning_for(@run.period_month))
 
       ActiveRecord::Base.transaction do
         eligible = EmployeeProfile.active_for(@run.period_month).includes(:user).to_a
@@ -31,6 +34,11 @@ module HrLite
             run: @run, user: user, structure: structure, profile: profile,
             lop_override: slip.lop_override, tds_override: slip.tds_override
           )
+          if attributes[:total_deductions] > attributes[:gross_earnings]
+            warnings << "Deductions exceed earnings for #{HrLite.display_name(user)} — " \
+                        "net pay floored at zero, review the overrides"
+          end
+
           slip.assign_attributes(attributes)
           slip.save!
           keep_ids << slip.id