hr_lite 0.5.0 → 0.5.3

data/db/migrate/20260817182124_add_status_constraints_and_appraisal_fk_to_hr_lite.rb

@@ -0,0 +1,63 @@
+class AddStatusConstraintsAndAppraisalFkToHrLite < ActiveRecord::Migration[8.1]
+  # Every status column in the engine is a plain string validated only in
+  # Ruby, so anything that skips validations — update_column, update_all,
+  # insert_all, a console fix, a future migration — can write a value no
+  # screen renders and no transition accepts. These constraints put the
+  # allowed set somewhere it cannot be bypassed.
+  #
+  # Deliberately in step with each model's own STATUSES array: adding a
+  # status now means writing a migration, which is the point.
+  STATUSES = {
+    hr_lite_attendance_records: %w[present half_day],
+    hr_lite_leave_requests: %w[pending approved rejected cancelled],
+    hr_lite_comp_off_requests: %w[pending approved rejected cancelled],
+    hr_lite_regularization_requests: %w[pending approved rejected cancelled],
+    hr_lite_resignations: %w[pending accepted withdrawn],
+    hr_lite_appraisals: %w[draft shared],
+    hr_lite_payroll_runs: %w[draft processing review finalized published]
+  }.freeze
+
+  def up
+    # On an install that already holds an off-list value the constraint build
+    # fails with a bare integrity error naming neither the row nor the value.
+    # Say what is actually in the way instead — this runs on live data.
+    offenders = STATUSES.filter_map do |table, statuses|
+      found = select_values(
+        "SELECT DISTINCT status FROM #{table} WHERE status NOT IN (#{quoted(statuses)})"
+      )
+      "#{table}: #{found.join(', ')}" if found.any?
+    end
+
+    if offenders.any?
+      raise ActiveRecord::IrreversibleMigration,
+            "Cannot constrain status columns — these rows hold values no model " \
+            "declares. Correct them first:\n  #{offenders.join("\n  ")}"
+    end
+
+    STATUSES.each do |table, statuses|
+      add_check_constraint table, status_sql(statuses), name: constraint_name(table)
+    end
+
+    # has_one :designation_change, dependent: :nullify — with neither an index
+    # nor a foreign key. Destroying an appraisal scanned the whole table to
+    # find its promotion row, and nothing stopped that row from being left
+    # pointing at an appraisal that no longer exists.
+    add_index :hr_lite_designation_changes, :appraisal_id
+    add_foreign_key :hr_lite_designation_changes, :hr_lite_appraisals,
+                    column: :appraisal_id, on_delete: :nullify
+  end
+
+  def down
+    remove_foreign_key :hr_lite_designation_changes, column: :appraisal_id
+    remove_index :hr_lite_designation_changes, :appraisal_id
+    STATUSES.each_key { |table| remove_check_constraint table, name: constraint_name(table) }
+  end
+
+  private
+
+  def status_sql(statuses) = "status IN (#{quoted(statuses)})"
+
+  def quoted(statuses) = statuses.map { |s| connection.quote(s) }.join(", ")
+
+  def constraint_name(table) = "#{table}_status_check"
+end

data/lib/hr_lite/amount_in_words.rb

@@ -14,15 +14,28 @@ module HrLite
       rupees = Money.round_rupee(amount).to_i
       return "Zero rupees" if rupees.zero?
 
+      # A negative amount rendered as bare " rupees": no group was >= its
+      # divisor, so nothing was ever appended.
+      sentence = groups(rupees.abs).join(" ")
+      sentence = "minus #{sentence}" if rupees.negative?
+      "#{sentence.capitalize} rupees"
+    end
+
+    def groups(rupees)
       parts = []
       SCALES.each do |divisor, label|
         next unless rupees >= divisor
 
-        parts << "#{two_digit(rupees / divisor)} #{label}"
+        # The crore group is unbounded — every later group is reduced below
+        # 100 by the preceding modulo, but this one is not, and two_digit
+        # only knows 0..99. Recurse for anything above a hundred crore.
+        count = rupees / divisor
+        spelled = count > 99 ? groups(count).join(" ") : two_digit(count)
+        parts << "#{spelled} #{label}"
         rupees %= divisor
       end
       parts << two_digit(rupees) if rupees.positive?
-      "#{parts.join(' ').capitalize} rupees"
+      parts
     end
 
     def two_digit(number)

data/lib/hr_lite/configuration.rb

@@ -46,16 +46,13 @@ module HrLite
       @currency_symbol      = "₹"
       @on_designation_change = ->(user, designation) { }
       @leadership_emails     = []
-      @leadership_check      = ->(user) do
-        emails = HrLite.config.leadership_emails.map { |e| e.to_s.downcase.strip }
-        emails.include?(user.email.to_s.downcase)
-      end
+      @leadership_check      = ->(user) { HrLite.email_listed?(user, HrLite.config.leadership_emails) }
       # Money tier: salary structures, payroll, slips, appraisals. Empty
       # list means "same as leadership" (pre-0.5.0 behaviour).
       @superadmin_emails     = []
       @superadmin_check      = ->(user) do
-        emails = HrLite.config.superadmin_emails.map { |e| e.to_s.downcase.strip }.reject(&:empty?)
-        emails.empty? ? HrLite.leadership?(user) : emails.include?(user.email.to_s.downcase)
+        list = HrLite.normalize_email_list(HrLite.config.superadmin_emails)
+        list.empty? ? HrLite.leadership?(user) : HrLite.email_listed?(user, list)
       end
       @extra_stylesheets     = [] # host stylesheets linked AFTER hr_lite.css (CSS-var overrides)
       @mailer_from           = "hr@example.com"

data/lib/hr_lite/financial_year.rb

@@ -0,0 +1,26 @@
+module HrLite
+  # The Indian financial year runs 1 April – 31 March. Three places worked
+  # this out for themselves (the slip's year-to-date sums, the TDS projector
+  # and the rate card); it lives here once so they cannot drift apart.
+  module FinancialYear
+    START_MONTH = 4
+
+    # First day of the FY containing `date`. March 2027 belongs to the year
+    # that opened on 1 April 2026.
+    def self.start_for(date)
+      year = date.month >= START_MONTH ? date.year : date.year - 1
+      Date.new(year, START_MONTH, 1)
+    end
+
+    # "2026-27" — for warnings and screens, never for arithmetic.
+    def self.label(date)
+      start = start_for(date)
+      "#{start.year}-#{format('%02d', (start.year + 1) % 100)}"
+    end
+
+    # True when `date` falls in an earlier FY than `other`.
+    def self.before?(date, other)
+      start_for(date) < start_for(other)
+    end
+  end
+end

data/lib/hr_lite/money.rb

@@ -29,5 +29,23 @@ module HrLite
     def round_to_10(value)
       (d(value) / 10).round(0, BigDecimal::ROUND_HALF_UP) * 10
     end
+
+    # Indian digit grouping: 12,34,567 — not the western 1,234,567. It lives
+    # here rather than only in the view helper because the slip PDF is
+    # rendered by HOST code (config.render_pdf), where engine helpers are out
+    # of scope — which is why the PDF printed a bare "75000.0" next to the
+    # web slip's "₹75,000.00".
+    def format(amount)
+      return "—" if amount.nil?
+
+      whole, fraction = round2(amount).to_s("F").split(".")
+      sign = whole.start_with?("-") ? "-" : ""
+      whole = whole.delete_prefix("-")
+      if whole.length > 3
+        head = whole[0..-4].reverse.scan(/\d{1,2}/).join(",").reverse
+        whole = "#{head},#{whole[-3..]}"
+      end
+      "#{sign}#{HrLite.config.currency_symbol}#{whole}.#{fraction.ljust(2, '0')}"
+    end
   end
 end

data/lib/hr_lite/notifications.rb

@@ -49,17 +49,27 @@ module HrLite
         DEFAULT_MATRIX.merge(HrLite.config.notification_matrix || {})
       end
 
-      def publish(event, title:, body: nil, path: nil, bell_to: [], email_to: [], lines: [], diff: nil, link_url: nil)
+      # `leadership:` overrides title/body/path for the leadership copies of an
+      # event. Some events are written in the second person and point at an
+      # employee-scoped path ("Your appraisal has been shared", /appraisals/7):
+      # fanned out verbatim, leadership read them as being about themselves and
+      # followed a link their own scope 404s or resolves to their own record.
+      def publish(event, title:, body: nil, path: nil, bell_to: [], email_to: [], lines: [],
+                  diff: nil, link_url: nil, leadership: {})
         row = matrix[event.to_s]
         unless row
           Rails.logger.warn("[hr_lite] unknown notification event #{event}")
           return
         end
 
+        lead_title = leadership[:title] || title
+        lead_body = leadership.key?(:body) ? leadership[:body] : body
+        lead_path = leadership[:path] || path
+
         deliver_bells(event, row, bell_to, title, body, path)
         deliver_emails(row, email_to, title, body, path, lines, link_url)
-        deliver_leadership_email(event, row, title, body, path, lines, diff)
-        deliver_leadership_bells(event, row, bell_to, title, body, path)
+        deliver_leadership_email(event, row, lead_title, lead_body, lead_path, lines, diff)
+        deliver_leadership_bells(event, row, bell_to, lead_title, lead_body, lead_path)
         nil
       end
 
@@ -76,15 +86,20 @@ module HrLite
       def deliver_emails(row, email_to, title, body, path, lines, link_url = nil)
         return unless row[:email]
 
+        # Rescued PER RECIPIENT. Wrapping the whole loop meant one bad address
+        # or a single enqueue failure silently dropped everyone after it — on
+        # a team-wide leave notice, most of the team.
         Array(email_to).compact.uniq.each do |user|
           next if user.email.blank?
 
-          EventMailer.event(to: user.email, subject: title, heading: title,
-                            body: body, lines: lines, path: path,
-                            link_url: link_url).deliver_later
+          begin
+            EventMailer.event(to: user.email, subject: title, heading: title,
+                              body: body, lines: lines, path: path,
+                              link_url: link_url).deliver_later
+          rescue => e
+            Rails.logger.error("[hr_lite] event email failed: #{e.class}: #{e.message}")
+          end
         end
-      rescue => e
-        Rails.logger.error("[hr_lite] event email failed: #{e.class}: #{e.message}")
       end
 
       def deliver_leadership_email(event, row, title, body, path, lines, diff)

data/lib/hr_lite/statutory_rate_card.rb

@@ -3,9 +3,13 @@ module HrLite
   # is a one-hash edit that gets code review and a spec diff, never an
   # inline-constant hunt.
   #
-  # VERIFY WITH A CA before the first run of any new financial year; the
-  # FY 2026-27 card ships with FY 2025-26 figures pending confirmation of
-  # the Feb 2026 Finance Act.
+  # VERIFY WITH A CA before the first run of any new financial year. Adding
+  # a year is one new dated entry in CARDS; nothing else changes.
+  #
+  # When no card exists for a run's financial year the lookup falls back to
+  # the newest one it has — payroll cannot simply stop every April — but
+  # `warning_for` says so on the run, and `PayrollRunProcessor` puts that
+  # sentence in front of every other warning until a card is added.
   module StatutoryRateCard
     def self.r(value) = BigDecimal(value.to_s)
     private_class_method :r
@@ -24,11 +28,16 @@ module HrLite
           "none" => [],
           "uttar_pradesh" => [],
           "uttarakhand" => [],
-          "karnataka" => [ { above: r("24999"), monthly: r("200") } ]
+          # Inclusive lower bounds. `above: 24999` with a strict `>` taxed a
+          # prorated gross of ₹24,999.50, which is below the real threshold.
+          "karnataka" => [ { from: r("25000"), monthly: r("200") } ]
         },
         income_tax: {
           "new" => {
             standard_deduction: r("75000"), rebate_cap: r("1200000"), cess_rate: r("0.04"),
+            # §115BAC carries marginal relief just above the rebate cap; the
+            # old regime does not, so this is a per-regime flag.
+            marginal_relief: true,
             slabs: [
               [ r("0"), r("400000"), r("0") ],
               [ r("400000"), r("800000"), r("0.05") ],
@@ -53,8 +62,44 @@ module HrLite
     }.freeze
 
     def self.for(period_month)
-      effective = CARDS.keys.sort.reverse.find { |date| date <= period_month }
-      effective ? CARDS[effective] : CARDS[CARDS.keys.min]
+      CARDS[effective_date_for(period_month)]
+    end
+
+    # Which card a run will actually use. A month older than every card
+    # borrows the earliest one — see `predates_cards?`, which says so.
+    def self.effective_date_for(period_month)
+      CARDS.keys.sort.reverse.find { |date| date <= period_month } || CARDS.keys.min
+    end
+
+    # The card in force is from an EARLIER financial year than the run. The
+    # lookup still returns figures — it has to, or payroll would stop dead
+    # every April — so the run carries the warning instead.
+    def self.stale_for?(period_month)
+      FinancialYear.before?(effective_date_for(period_month), period_month)
+    end
+
+    # The run is older than every card we ship, so it is being computed on
+    # rates that had not been announced yet.
+    def self.predates_cards?(period_month)
+      period_month < CARDS.keys.min
+    end
+
+    # One sentence naming both the run's FY and the card's, or nil when they
+    # match. Rendered verbatim in the run's warnings list.
+    def self.warning_for(period_month)
+      card_fy = FinancialYear.label(effective_date_for(period_month))
+      run_fy  = FinancialYear.label(period_month)
+
+      if predates_cards?(period_month)
+        "Payroll for FY #{run_fy} is being computed on the FY #{card_fy} " \
+        "statutory card — no card ships for a year that early. PF, ESI, PT " \
+        "and TDS on this run are not the rates that applied. Verify with your CA."
+      elsif stale_for?(period_month)
+        "Payroll for FY #{run_fy} is being computed on the FY #{card_fy} " \
+        "statutory card — no card ships for FY #{run_fy} yet. PF, ESI, PT and " \
+        "TDS on this run use last year's rates. Add a CA-verified card for " \
+        "FY #{run_fy} before publishing."
+      end
     end
   end
 end

data/lib/hr_lite/version.rb

@@ -1,3 +1,3 @@
 module HrLite
-  VERSION = "0.5.0"
+  VERSION = "0.5.3"
 end

data/lib/hr_lite.rb

@@ -3,6 +3,7 @@ require "hr_lite/engine"
 require "hr_lite/configuration"
 require "hr_lite/current"
 require "hr_lite/leave_year"
+require "hr_lite/financial_year"
 require "hr_lite/mention_parser"
 require "hr_lite/notifications"
 require "hr_lite/seeds"
@@ -42,18 +43,38 @@ module HrLite
       user.present? && !!config.superadmin_check.call(user)
     end
 
+    # An access list, cleaned. "a@x.com,,b@x.com".split(",") — one stray
+    # comma in an ENV var — used to put "" in the list, and a user whose
+    # email was blank then MATCHED it and was handed the tier.
+    def normalize_email_list(emails)
+      Array(emails).map { |e| e.to_s.downcase.strip }.reject(&:empty?)
+    end
+
+    # Whether a user's own email is on a configured access list. A blank
+    # email is never on any list, however the list is spelled.
+    def email_listed?(user, emails)
+      address = user.respond_to?(:email) ? user.email.to_s.downcase.strip : ""
+      return false if address.empty?
+
+      normalize_email_list(emails).include?(address)
+    end
+
     # Leadership members resolvable to actual user records (for bell
     # notifications). Emails configured but absent from the user table are
     # still reachable by email — see Notifications.
     def leadership_users
-      emails = config.leadership_emails.map { |e| e.to_s.downcase.strip }.reject(&:empty?)
+      emails = normalize_email_list(config.leadership_emails)
       return user_klass.none if emails.empty?
 
       user_klass.where("LOWER(#{user_klass.table_name}.email) IN (?)", emails)
     end
 
+    # Every domain event that bells the admins calls this. Loading and
+    # instantiating the entire users table to run admin_check per row is fine
+    # at ten staff and silly at a thousand — so it starts from employees_scope
+    # (which a host narrows to real staff) rather than every row that exists.
     def admin_users
-      user_klass.all.select { |u| admin?(u) }
+      employees.select { |u| admin?(u) }
     end
 
     # Everyone HR tracks (host-overridable to exclude bots/test accounts),

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hr_lite
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.3
 platform: ruby
 authors:
 - kshitiz sinha
@@ -50,6 +50,7 @@ files:
 - MIT-LICENSE
 - README.md
 - Rakefile
+- app/assets/javascripts/hr_lite/confirm.js
 - app/assets/javascripts/hr_lite/geo_punch.js
 - app/assets/javascripts/hr_lite/mention.js
 - app/assets/stylesheets/hr_lite/application.css
@@ -238,6 +239,10 @@ files:
 - db/migrate/20260719104317_create_hr_lite_regularization_requests.rb
 - db/migrate/20260719162154_add_manager_to_hr_lite_employee_profiles.rb
 - db/migrate/20260720094454_add_employee_code_prefix_to_hr_lite_settings.rb
+- db/migrate/20260807184103_add_live_uniqueness_indexes_to_hr_lite.rb
+- db/migrate/20260807184426_add_fy_opening_to_hr_lite_employee_profiles.rb
+- db/migrate/20260807184939_add_out_of_window_days_to_hr_lite_salary_slips.rb
+- db/migrate/20260817182124_add_status_constraints_and_appraisal_fk_to_hr_lite.rb
 - lib/generators/hr_lite/install/install_generator.rb
 - lib/generators/hr_lite/install/templates/AFTER_INSTALL
 - lib/generators/hr_lite/install/templates/initializer.rb
@@ -246,6 +251,7 @@ files:
 - lib/hr_lite/configuration.rb
 - lib/hr_lite/current.rb
 - lib/hr_lite/engine.rb
+- lib/hr_lite/financial_year.rb
 - lib/hr_lite/geo.rb
 - lib/hr_lite/leave_year.rb
 - lib/hr_lite/mention_parser.rb