hr_lite 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7dd5723f67a89de78893c7ef752581da400b8703fb60876ad7d283e280308d31
-  data.tar.gz: d8e517a4a80bb2026de50a9f30b7837b37b785d02a5aea79802ad72b78fcc630
+  metadata.gz: 1716d66b8a6859e70f044dc0025b2052a8085ad83c82567540cbad04a216be9d
+  data.tar.gz: bc4d26d3c69be4f280e55820672892fac8ae6a93c190be3b6b4272adda7754b2
 SHA512:
-  metadata.gz: ea7291efd85233dfabf368fdc2355f8050920a22e324ea9f0ac083ba10040aaacaf125f93ed2d89b94e3ab05ed496375d69a6499af66372a974498677a30a18b
-  data.tar.gz: 1c1ad921b96ae6d778711b61b62501b5a8fa2e6cfd08cb8fd2c162bc01d37c7f048bc9637a617f1eebcac2f51a01e669cff89d94adf3bd48724b7cb9c7959a05
+  metadata.gz: a0ce5511c8c763eac022ee7f900d3c92a0267057c0f6805e49d753076c9c07f6a842285c6d2f034cd3ee6fe40a2343865a4295fd696ef2f0ab4e2a44291c2ffe
+  data.tar.gz: bdfac21210c1a26383b2d9bed8782f093f651c479e5fe150fad94ad46a012a3612057098d4ea78a8f79f1a80652099c214e47954901cd546a8dd4b340e726b84

data/CHANGELOG.md

@@ -7,6 +7,61 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-08-18
+
+Statutory figures stop being code. **Adds one migration** (rate cards and
+professional-tax slabs) and seeds it from the figures the gem already
+shipped — no number changes on upgrade.
+
+### Fixed
+
+- **Every state except Karnataka deducted ₹0 professional tax, silently.** PT
+  is a state levy and only Karnataka had bands in code; every other state
+  resolved to an empty slab list and deducted nothing, which is a wrong answer
+  delivered confidently. Slabs are now per state and effective-dated, and a
+  run whose employees sit in a state nobody has configured says so — once per
+  state, not once per employee.
+- **Adding a financial year needed a gem release.** Every April was a deadline
+  the gem controlled and the company did not; 0.5.3 shipped a warning about
+  exactly that. Cards are rows now, entered on a screen.
+- A tax regime saved with an empty slab list validated on key presence and
+  then taxed every salary at zero. Refused.
+
+### Added
+
+- `hr_lite_statutory_rate_cards` — PF, ESI and both regimes' slabs per
+  financial year, effective-dated. A card must start on 1 April (a mid-year
+  card would mean two slab sets inside one year, and the TDS projector works
+  on an annual figure), and must carry every figure payroll reads — a card
+  missing one fails at save time rather than half way through computing
+  somebody's salary.
+- `hr_lite_professional_tax_slabs` — per state, per date, with the February
+  top-up the states that levy one need.
+- A rate-card screen (money tier). Adding a year copies the newest card, since
+  most years carry PF and ESI over untouched and move only the slabs — a blank
+  form would invite retyping eight numbers that were already right.
+- **Sign-off.** A card records who checked it and when, and payroll warns on
+  every run computed against one nobody has confirmed. Ranked below the
+  wrong-financial-year warning: bad figures matter more than missing paperwork.
+- `rake hr_lite:statutory`, and `hr_lite:seed` copies the shipped figures in.
+
+### Changed
+
+- `StatutoryRateCard.for` reads the table, falling back to the shipped hash
+  for a host that has upgraded the gem but not yet run `db:migrate` — payroll
+  must not 500 on a missing table.
+- Branch-coverage floor 90.5% -> 90.8%.
+
+### Deferred
+
+- **`config.legacy_tier_checks` and the pre-0.6.0 tier lambdas are still
+  here.** 0.6.0 said they would go in this release. They have not: removing an
+  access mechanism in the same release that rewrites where statutory figures
+  live puts two unrelated upgrade risks in one step, and this release is
+  otherwise purely additive. They go in **0.8.0**, on their own. If you are
+  still relying on the flag, the 0.6.0 migration has already created the
+  equivalent role assignments — turn it off and check the Roles screen.
+
 ## [0.6.0] - 2026-08-18
 
 Access stops being three lambdas and becomes a role table. **Breaking**, with
@@ -458,7 +513,8 @@ Initial release.
   bus with per-event channel matrix (bell, email, leadership email/bell),
   daily leadership digest and an append-only audit trail.
 
-[Unreleased]: https://github.com/kshtzkr/hr_lite/compare/v0.6.0...HEAD
+[Unreleased]: https://github.com/kshtzkr/hr_lite/compare/v0.7.0...HEAD
+[0.7.0]: https://github.com/kshtzkr/hr_lite/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/kshtzkr/hr_lite/compare/v0.5.3...v0.6.0
 [0.5.3]: https://github.com/kshtzkr/hr_lite/compare/v0.5.2...v0.5.3
 [0.5.2]: https://github.com/kshtzkr/hr_lite/compare/v0.5.1...v0.5.2

data/README.md

@@ -211,7 +211,7 @@ It prints who it put where, and it leaves a host that has already assigned
 roles by hand alone.
 
 Set `config.legacy_tier_checks = true` to keep the old lambdas in charge while
-you migrate. It is honoured for one minor version and removed in 0.7.0.
+you migrate. It is honoured for one minor version and removed in 0.8.0.
 
 ## Features
 

data/app/controllers/hr_lite/admin/statutory_rate_cards_controller.rb

@@ -0,0 +1,97 @@
+module HrLite
+  module Admin
+    # Adding a financial year, and recording who checked it. Money tier: these
+    # figures decide what lands in a bank account.
+    #
+    # New years are created by COPYING the newest card — a year's PF and ESI
+    # figures usually carry over untouched and only the slabs move, so a blank
+    # form would be an invitation to mistype eight numbers that were already
+    # right.
+    class StatutoryRateCardsController < SuperadminController
+      def index
+        @cards = StatutoryRateCardRecord.chronological.reverse
+        @states = ProfessionalTaxSlab.distinct.order(:state).pluck(:state)
+      end
+
+      def new
+        newest = StatutoryRateCardRecord.chronological.last
+        @card = StatutoryRateCardRecord.new(
+          effective_from: next_financial_year(newest),
+          pf: newest&.pf || {}, esi: newest&.esi || {}, income_tax: newest&.income_tax || {}
+        )
+        @copied_from = newest
+      end
+
+      def create
+        @card = StatutoryRateCardRecord.new(card_params)
+        if @card.save
+          redirect_to admin_statutory_rate_cards_path,
+                      notice: "FY #{@card.financial_year} card saved. Payroll will use it " \
+                              "from #{@card.effective_from.strftime('%d %b %Y')}."
+        else
+          @copied_from = nil
+          render :new, status: :unprocessable_entity
+        end
+      end
+
+      def edit
+        @card = StatutoryRateCardRecord.find(params[:id])
+      end
+
+      def update
+        @card = StatutoryRateCardRecord.find(params[:id])
+        if @card.update(card_params)
+          redirect_to admin_statutory_rate_cards_path, notice: "FY #{@card.financial_year} card updated."
+        else
+          render :edit, status: :unprocessable_entity
+        end
+      end
+
+      private
+
+      def next_financial_year(newest)
+        return FinancialYear.start_for(Date.current) if newest.nil?
+
+        [ newest.effective_from.next_year, FinancialYear.start_for(Date.current) ].max
+      end
+
+      # The figures arrive as flat strings from number fields and are stored
+      # as strings in JSON — a float would not survive the round trip intact,
+      # and these decide deductions.
+      def card_params
+        permitted = params.require(:statutory_rate_card)
+                          .permit(:effective_from, :verified_by, :verified_on, :notes,
+                                  pf: {}, esi: {}, income_tax: {})
+        permitted.to_h.tap do |attrs|
+          attrs["income_tax"] = rebuild_regimes(attrs["income_tax"]) if attrs["income_tax"]
+        end
+      end
+
+      # A blank `to` is the open-ended top slab and has to stay nil rather
+      # than becoming "" — the calculators read nil as "no upper bound".
+      def rebuild_regimes(income_tax)
+        income_tax.to_h do |regime, table|
+          rows = slab_rows(table["slabs"]).reject { |from, _to, _rate| from.blank? }
+          [ regime, table.except("slabs").merge(
+            "slabs" => rows.map { |from, to, rate| [ from, to.presence, rate ] },
+            "marginal_relief" => truthy?(table["marginal_relief"])
+          ) ]
+        end
+      end
+
+      # Two shapes reach here. The form posts index-keyed rows
+      # (`slabs[0][from]`), which Rails hands over as a hash. A card being
+      # copied — or a client posting one back unchanged — carries the stored
+      # array of [from, to, rate] triples.
+      def slab_rows(slabs)
+        case slabs
+        when Hash then slabs.values.map { |row| [ row["from"], row["to"], row["rate"] ] }
+        when Array then slabs.map { |row| Array(row).first(3) }
+        else []
+        end
+      end
+
+      def truthy?(value) = [ true, "1", "true" ].include?(value)
+    end
+  end
+end

data/app/helpers/hr_lite/application_helper.rb

@@ -29,7 +29,8 @@ module HrLite
     # other governing screens.
     SUPERADMIN_NAV_ITEMS = [
       { label: "Payroll", path: :admin_payroll_runs_path, match: [ "/admin/payroll_runs", "/admin/salary_slips" ] },
-      { label: "Roles",   path: :admin_roles_path,        match: [ "/admin/roles" ] }
+      { label: "Roles",   path: :admin_roles_path,        match: [ "/admin/roles" ] },
+      { label: "Rates",   path: :admin_statutory_rate_cards_path, match: [ "/admin/statutory_rate_cards" ] }
     ].freeze
 
     # Only items whose routes exist yet (the nav grows with each phase).

data/app/models/hr_lite/professional_tax_slab.rb

@@ -0,0 +1,41 @@
+module HrLite
+  # One state's professional-tax band. PT is a state levy with its own slabs
+  # and its own revision schedule, so it is dated separately from the central
+  # rate card rather than living inside it.
+  class ProfessionalTaxSlab < ApplicationRecord
+    include Audited
+
+    self.table_name = "hr_lite_professional_tax_slabs"
+
+    # A state that genuinely levies nothing. Distinct from a state nobody has
+    # configured — see `configured?`, which is what stops payroll quietly
+    # deducting zero for a state whose slabs simply were never entered.
+    NO_LEVY = "none".freeze
+
+    validates :state, presence: true
+    validates :effective_from, presence: true
+    validates :from_amount, :monthly, presence: true,
+                                      numericality: { greater_than_or_equal_to: 0 }
+    validates :feb_extra, numericality: { greater_than_or_equal_to: 0 }, allow_nil: true
+
+    scope :for_state, ->(state) { where(state: state.to_s) }
+
+    # The bands in force for a state in a given month: the newest effective
+    # date that is not in the future, and every band carrying it.
+    def self.effective_for(state, period_month)
+      dates = for_state(state).where(effective_from: ..period_month)
+      newest = dates.maximum(:effective_from)
+      return none if newest.nil?
+
+      for_state(state).where(effective_from: newest).order(:from_amount)
+    end
+
+    # The shape Calculators::ProfessionalTax reads.
+    def self.table_for(state, period_month)
+      effective_for(state, period_month).map do |slab|
+        { from: Money.d(slab.from_amount), monthly: Money.d(slab.monthly),
+          feb_extra: slab.feb_extra && Money.d(slab.feb_extra) }.compact
+      end
+    end
+  end
+end

data/app/models/hr_lite/statutory_rate_card_record.rb

@@ -0,0 +1,95 @@
+module HrLite
+  # A financial year's statutory figures, as data. Named for the table rather
+  # than the lookup module (HrLite::StatutoryRateCard) that reads it — hosts
+  # and specs call the module, not this.
+  class StatutoryRateCardRecord < ApplicationRecord
+    include Audited
+
+    self.table_name = "hr_lite_statutory_rate_cards"
+
+    validates :effective_from, presence: true, uniqueness: true
+    validate :effective_from_opens_a_financial_year
+    validate :carries_every_figure_payroll_reads
+
+    scope :chronological, -> { order(:effective_from) }
+
+    def self.effective_for(period_month)
+      where(effective_from: ..period_month).order(effective_from: :desc).first ||
+        chronological.first
+    end
+
+    def financial_year = FinancialYear.label(effective_from)
+
+    def verified? = verified_by.present? && verified_on.present?
+
+    # The shape SlipBuilder and the calculators expect: symbol keys and
+    # BigDecimal everywhere, because JSON gives back strings and floats and
+    # a float has no business in a PF calculation.
+    def to_card
+      {
+        pf: deep_decimalize(pf).symbolize_keys,
+        esi: deep_decimalize(esi).symbolize_keys,
+        pt: {}, # slabs live in their own table — resolved by state at use
+        income_tax: income_tax.transform_values { |regime| decimalize_regime(regime) }
+      }
+    end
+
+    private
+
+    def decimalize_regime(regime)
+      regime = regime.symbolize_keys
+      regime.merge(
+        standard_deduction: Money.d(regime[:standard_deduction]),
+        rebate_cap: Money.d(regime[:rebate_cap]),
+        cess_rate: Money.d(regime[:cess_rate]),
+        marginal_relief: !!regime[:marginal_relief],
+        slabs: Array(regime[:slabs]).map { |from, to, rate|
+          [ Money.d(from), to.nil? ? nil : Money.d(to), Money.d(rate) ]
+        }
+      )
+    end
+
+    def deep_decimalize(hash)
+      hash.to_h { |key, value| [ key, Money.d(value) ] }
+    end
+
+    # A card dated mid-year would mean two sets of slabs inside one financial
+    # year, and the TDS projector works on an annual figure — there is no
+    # sensible answer to "which slabs applied to this year's income" then.
+    def effective_from_opens_a_financial_year
+      return if effective_from.blank?
+      return if effective_from == FinancialYear.start_for(effective_from)
+
+      errors.add(:effective_from, "must be 1 April — a card covers a whole financial year")
+    end
+
+    REQUIRED = {
+      "pf" => %w[employee_rate employer_rate eps_rate wage_ceiling eps_wage_ceiling
+                 edli_rate edli_ceiling admin_rate],
+      "esi" => %w[employee_rate employer_rate gross_ceiling]
+    }.freeze
+
+    # A card missing a figure does not fail at save time; it fails halfway
+    # through computing somebody's salary, as a NoMethodError on nil.
+    def carries_every_figure_payroll_reads
+      REQUIRED.each do |attribute, keys|
+        missing = keys - Array(public_send(attribute)&.keys)
+        errors.add(attribute, "is missing #{missing.join(', ')}") if missing.any?
+      end
+
+      %w[new old].each do |regime|
+        table = income_tax[regime]
+        next errors.add(:income_tax, "is missing the #{regime} regime") if table.blank?
+
+        missing = %w[standard_deduction rebate_cap cess_rate slabs] - table.keys
+        next errors.add(:income_tax, "#{regime} regime is missing #{missing.join(', ')}") if missing.any?
+
+        # A present-but-empty slab list is the dangerous shape: it validates
+        # on key presence and then taxes everybody at zero.
+        if Array(table["slabs"]).empty?
+          errors.add(:income_tax, "#{regime} regime has no tax slabs — every salary would be taxed at zero")
+        end
+      end
+    end
+  end
+end

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

@@ -1,11 +1,16 @@
 module HrLite
   module Calculators
-    # State-slab professional tax on earned gross. Unknown states and
-    # states without PT (UP, Uttarakhand) simply yield zero. Slabs may
-    # carry a feb_extra for states that top up the February deduction.
+    # State-slab professional tax on earned gross. Slabs may carry a
+    # feb_extra for the states that top up the last month's deduction.
+    #
+    # Slabs come from `hr_lite_professional_tax_slabs`, dated per state,
+    # falling back to whatever `rates` hash the caller passes for a host that
+    # has not seeded yet. A state nobody configured yields zero — and
+    # `unconfigured?` is how payroll gets to SAY so, because a confident zero
+    # is the failure mode here, not an exception.
     module ProfessionalTax
-      def self.call(state:, gross_earned:, period_month:, rates:)
-        slabs = rates[state.to_s] || []
+      def self.call(state:, gross_earned:, period_month:, rates: {})
+        slabs = slabs_for(state, period_month, rates)
         earned = Money.d(gross_earned)
 
         # `from:` is an INCLUSIVE lower bound — ₹25,000 is taxed, ₹24,999.50 is
@@ -19,6 +24,30 @@ module HrLite
         amount += slab[:feb_extra] if slab[:feb_extra] && period_month.month == 2
         Money.round_rupee(amount)
       end
+
+      def self.slabs_for(state, period_month, rates = {})
+        stored = stored_slabs(state, period_month)
+        return stored if stored.present?
+
+        rates[state.to_s] || []
+      end
+
+      # A state with no stored slabs and none in the fallback table. That is
+      # NOT the same as a state with no professional tax: Karnataka was the
+      # only state ever entered in code, so every other one deducted nothing
+      # and nothing said so.
+      def self.unconfigured?(state, period_month, rates = {})
+        return false if state.to_s == ProfessionalTaxSlab::NO_LEVY
+
+        slabs_for(state, period_month, rates).empty?
+      end
+
+      def self.stored_slabs(state, period_month)
+        ProfessionalTaxSlab.table_for(state, period_month)
+      rescue ActiveRecord::ActiveRecordError
+        # Host mid-migration: gem upgraded, db:migrate not yet run.
+        []
+      end
     end
   end
 end

data/app/services/hr_lite/payroll_run_processor.rb

@@ -16,10 +16,12 @@ module HrLite
       # 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))
+      warnings.concat(Array(StatutoryRateCard.unverified_for(@run.period_month)))
 
       ActiveRecord::Base.transaction do
         eligible = EmployeeProfile.active_for(@run.period_month).includes(:user).to_a
         keep_ids = []
+        unconfigured_states = []
 
         eligible.each do |profile|
           user = profile.user
@@ -29,6 +31,14 @@ module HrLite
             next
           end
 
+          # Professional tax is a state levy, and a state nobody has entered
+          # slabs for deducts nothing — which looks exactly like a state that
+          # levies nothing. Collected per state rather than per employee so a
+          # forty-person office is one line, not forty.
+          if Calculators::ProfessionalTax.unconfigured?(structure.pt_state, @run.period_month)
+            unconfigured_states << structure.pt_state
+          end
+
           slip = @run.salary_slips.find_or_initialize_by(user_id: user.id)
           attributes = SlipBuilder.call(
             run: @run, user: user, structure: structure, profile: profile,
@@ -44,6 +54,13 @@ module HrLite
           keep_ids << slip.id
         end
 
+        unconfigured_states.uniq.sort.each do |state|
+          warnings << "No professional-tax slabs are configured for " \
+                      "#{state.to_s.humanize} — everybody there is being deducted ₹0. " \
+                      "Enter that state's bands, or set their structures to 'none' if " \
+                      "it genuinely levies no PT."
+        end
+
         @run.salary_slips.where.not(id: keep_ids).destroy_all
         @run.update!(warnings: warnings)
       end

data/app/views/hr_lite/admin/statutory_rate_cards/_form.html.erb

@@ -0,0 +1,109 @@
+<section class="hrl-card">
+  <% if local_assigns[:copied_from] %>
+    <p class="hrl-muted hrl-small">
+      Copied from FY <%= copied_from.financial_year %>. Most years carry PF and
+      ESI over untouched and move only the slabs — change what the Finance Act
+      changed, and leave the rest.
+    </p>
+  <% end %>
+
+  <%= form_with model: card, url: url, method: method, local: true,
+                scope: :statutory_rate_card do |f| %>
+    <%= render "hr_lite/shared/form_errors", record: card %>
+
+    <div class="hrl-field">
+      <%= f.label :effective_from, "Financial year starts (1 April)" %>
+      <%= f.date_field :effective_from %>
+    </div>
+
+    <fieldset>
+      <legend>Provident fund</legend>
+      <% { employee_rate: "Employee rate (0.12 = 12%)", employer_rate: "Employer rate",
+           eps_rate: "EPS rate", wage_ceiling: "PF wage ceiling (₹)",
+           eps_wage_ceiling: "EPS wage ceiling (₹)", edli_rate: "EDLI rate",
+           edli_ceiling: "EDLI ceiling (₹)", admin_rate: "PF admin rate" }.each do |key, label| %>
+        <div class="hrl-field">
+          <%= label_tag "statutory_rate_card_pf_#{key}", label %>
+          <%= text_field_tag "statutory_rate_card[pf][#{key}]", card.pf[key.to_s],
+                             id: "statutory_rate_card_pf_#{key}", inputmode: "decimal" %>
+        </div>
+      <% end %>
+    </fieldset>
+
+    <fieldset>
+      <legend>ESI</legend>
+      <% { employee_rate: "Employee rate", employer_rate: "Employer rate",
+           gross_ceiling: "Gross ceiling (₹)" }.each do |key, label| %>
+        <div class="hrl-field">
+          <%= label_tag "statutory_rate_card_esi_#{key}", label %>
+          <%= text_field_tag "statutory_rate_card[esi][#{key}]", card.esi[key.to_s],
+                             id: "statutory_rate_card_esi_#{key}", inputmode: "decimal" %>
+        </div>
+      <% end %>
+    </fieldset>
+
+    <% %w[new old].each do |regime| %>
+      <% table = card.income_tax[regime] || {} %>
+      <fieldset>
+        <legend><%= regime.capitalize %> regime</legend>
+        <% { "standard_deduction" => "Standard deduction (₹)",
+             "rebate_cap" => "§87A rebate cap (₹)",
+             "cess_rate" => "Cess rate (0.04 = 4%)" }.each do |key, label| %>
+          <div class="hrl-field">
+            <%= label_tag "statutory_rate_card_it_#{regime}_#{key}", label %>
+            <%= text_field_tag "statutory_rate_card[income_tax][#{regime}][#{key}]", table[key],
+                               id: "statutory_rate_card_it_#{regime}_#{key}", inputmode: "decimal" %>
+          </div>
+        <% end %>
+        <div class="hrl-field hrl-field--check">
+          <%= hidden_field_tag "statutory_rate_card[income_tax][#{regime}][marginal_relief]", "0" %>
+          <%= check_box_tag "statutory_rate_card[income_tax][#{regime}][marginal_relief]", "1",
+                            table["marginal_relief"] %>
+          <%= label_tag "statutory_rate_card_income_tax_#{regime}_marginal_relief",
+                        "Marginal relief just above the rebate cap" %>
+        </div>
+
+        <p class="hrl-small hrl-muted">
+          Slabs, lowest first. Leave the last band's "up to" empty — that is
+          the open-ended top rate.
+        </p>
+        <% slabs = Array(table["slabs"]) %>
+        <% (slabs + [ nil, nil ]).each_with_index do |row, index| %>
+          <div class="hrl-row">
+            <%= text_field_tag "statutory_rate_card[income_tax][#{regime}][slabs][#{index}][from]",
+                               row&.first, placeholder: "From ₹", inputmode: "decimal" %>
+            <%= text_field_tag "statutory_rate_card[income_tax][#{regime}][slabs][#{index}][to]",
+                               row&.at(1), placeholder: "Up to ₹ (blank = top)", inputmode: "decimal" %>
+            <%= text_field_tag "statutory_rate_card[income_tax][#{regime}][slabs][#{index}][rate]",
+                               row&.last, placeholder: "Rate (0.05)", inputmode: "decimal" %>
+          </div>
+        <% end %>
+      </fieldset>
+    <% end %>
+
+    <fieldset>
+      <legend>Sign-off</legend>
+      <p class="hrl-small hrl-muted">
+        Until a card is signed off, every payroll run computed on it carries a
+        warning. Record the person who actually checked the figures.
+      </p>
+      <div class="hrl-field">
+        <%= f.label :verified_by, "Checked by (name)" %>
+        <%= f.text_field :verified_by %>
+      </div>
+      <div class="hrl-field">
+        <%= f.label :verified_on, "Checked on" %>
+        <%= f.date_field :verified_on %>
+      </div>
+      <div class="hrl-field">
+        <%= f.label :notes, "Notes" %>
+        <%= f.text_field :notes %>
+      </div>
+    </fieldset>
+
+    <div class="hrl-form-actions">
+      <%= f.submit "Save", class: "hrl-btn hrl-btn--primary" %>
+      <a class="hrl-btn" href="<%= hr_lite.admin_statutory_rate_cards_path %>">Cancel</a>
+    </div>
+  <% end %>
+</section>

data/app/views/hr_lite/admin/statutory_rate_cards/edit.html.erb

@@ -0,0 +1,4 @@
+<% content_for(:page_title) { "FY #{@card.financial_year}" } %>
+<div class="hrl-page__head"><h1 class="hrl-page__title">FY <%= @card.financial_year %></h1></div>
+<%= render "form", card: @card,
+      url: hr_lite.admin_statutory_rate_card_path(@card), method: :patch %>

data/app/views/hr_lite/admin/statutory_rate_cards/index.html.erb

@@ -0,0 +1,59 @@
+<% content_for(:page_title) { "Statutory rates" } %>
+<div class="hrl-page__head">
+  <h1 class="hrl-page__title">Statutory rates</h1>
+  <div class="hrl-page__actions">
+    <a class="hrl-btn hrl-btn--primary" href="<%= hr_lite.new_admin_statutory_rate_card_path %>">Add a year</a>
+  </div>
+</div>
+
+<section class="hrl-card">
+  <p class="hrl-muted hrl-small">
+    PF, ESI and the income-tax slabs, per financial year. Payroll resolves the
+    card that was in force for the month it is computing, so correcting a year
+    never changes an earlier one.
+  </p>
+  <div class="hrl-table-wrap">
+    <table class="hrl-table hrl-table--stack">
+      <thead><tr><th>Year</th><th>PF ceiling</th><th>ESI ceiling</th><th>Verified</th><th></th></tr></thead>
+      <tbody>
+        <% @cards.each do |card| %>
+          <tr>
+            <td data-label="Year">
+              <strong>FY <%= card.financial_year %></strong>
+              <div class="hrl-small hrl-muted">from <%= card.effective_from.strftime("%d %b %Y") %></div>
+            </td>
+            <td data-label="PF ceiling" class="hrl-num"><%= HrLite::Money.format(card.to_card[:pf][:wage_ceiling]) %></td>
+            <td data-label="ESI ceiling" class="hrl-num"><%= HrLite::Money.format(card.to_card[:esi][:gross_ceiling]) %></td>
+            <td data-label="Verified">
+              <% if card.verified? %>
+                <span class="hrl-badge"><%= card.verified_by %></span>
+                <div class="hrl-small hrl-muted"><%= card.verified_on.strftime("%d %b %Y") %></div>
+              <% else %>
+                <span class="hrl-badge hrl-badge--muted">Not checked</span>
+              <% end %>
+            </td>
+            <td data-label="">
+              <a class="hrl-small" href="<%= hr_lite.edit_admin_statutory_rate_card_path(card) %>">Edit</a>
+            </td>
+          </tr>
+        <% end %>
+      </tbody>
+    </table>
+  </div>
+</section>
+
+<section class="hrl-card">
+  <h2 class="hrl-card__title">Professional tax</h2>
+  <% if @states.empty? %>
+    <p class="hrl-muted">
+      No state bands are configured. Everybody's professional tax is being
+      deducted at ₹0 — which is right only if no state you employ in levies it.
+    </p>
+  <% else %>
+    <p class="hrl-muted hrl-small">
+      Bands are configured for: <%= @states.map(&:humanize).to_sentence %>.
+      An employee whose salary structure names any other state is deducted ₹0,
+      and payroll says so on the run.
+    </p>
+  <% end %>
+</section>

data/app/views/hr_lite/admin/statutory_rate_cards/new.html.erb

@@ -0,0 +1,4 @@
+<% content_for(:page_title) { "Add a financial year" } %>
+<div class="hrl-page__head"><h1 class="hrl-page__title">Add a financial year</h1></div>
+<%= render "form", card: @card, copied_from: @copied_from,
+      url: hr_lite.admin_statutory_rate_cards_path, method: :post %>

data/config/routes.rb

@@ -49,6 +49,7 @@ HrLite::Engine.routes.draw do
     resources :roles, except: :show do
       resources :assignments, only: %i[create destroy], controller: "role_assignments"
     end
+    resources :statutory_rate_cards, only: %i[index new create edit update]
     resources :leave_types, except: :show
     resources :office_locations, except: :show
     resources :holidays, only: %i[index create update destroy] do

data/db/migrate/20260817190159_create_hr_lite_statutory_rate_cards.rb

@@ -0,0 +1,44 @@
+class CreateHrLiteStatutoryRateCards < ActiveRecord::Migration[8.1]
+  # Statutory rates lived in a frozen hash in Ruby, so adding a financial year
+  # meant a gem release. Every April that is a deadline the gem controls and
+  # the company does not — and 0.5.3 shipped a warning about exactly that
+  # because the FY2026-27 card did not exist.
+  #
+  # Rates are not secret (they are published by the government), so the
+  # figures are plain JSON. What matters is that they are EFFECTIVE-DATED and
+  # carry who checked them: a payroll rerun of an old month must resolve to
+  # the card that was in force for that month, not to today's.
+  def change
+    create_table :hr_lite_statutory_rate_cards do |t|
+      t.date :effective_from, null: false
+      t.json :pf, null: false, default: {}
+      t.json :esi, null: false, default: {}
+      t.json :income_tax, null: false, default: {}
+      # Who signed it off, and when. A card nobody has confirmed is a card
+      # payroll should say something about — see SlipBuilder's warnings.
+      t.string :verified_by
+      t.date :verified_on
+      t.text :notes
+      t.timestamps
+    end
+    # One card per date: two would make "which rates applied in June" a
+    # question about row order.
+    add_index :hr_lite_statutory_rate_cards, :effective_from, unique: true
+
+    create_table :hr_lite_professional_tax_slabs do |t|
+      # Professional tax is a STATE levy. Karnataka was the only state with
+      # real slabs in code; every other state silently computed zero, which
+      # is a wrong answer delivered confidently.
+      t.string :state, null: false
+      t.date :effective_from, null: false
+      # Inclusive lower bound on monthly earned gross.
+      t.decimal :from_amount, precision: 12, scale: 2, null: false
+      t.decimal :monthly, precision: 12, scale: 2, null: false
+      # Several states collect a larger amount in the last month of the year.
+      t.decimal :feb_extra, precision: 12, scale: 2
+      t.timestamps
+    end
+    add_index :hr_lite_professional_tax_slabs, %i[state effective_from from_amount],
+              unique: true, name: "index_hr_lite_pt_slabs_on_state_date_and_bound"
+  end
+end

data/lib/generators/hr_lite/install/templates/initializer.rb

@@ -18,7 +18,7 @@ HrLite.configure do |c|
   #
   # Upgrading from pre-0.6.0 and not ready to move? Uncomment this and keep
   # your leadership_emails / superadmin_emails / admin_check as they were.
-  # It is honoured until 0.7.0.
+  # It is honoured until 0.8.0.
   # c.legacy_tier_checks = true
 
   # Where the portal is reachable (subdomain or path). Enables email link

data/lib/hr_lite/configuration.rb

@@ -50,7 +50,7 @@ module HrLite
       # user's EMAIL — a mutable, host-owned, unverified column that a host
       # then had to remember never to let anyone edit. Roles replace them.
       # This flag hands authority back to the old lambdas for a host that has
-      # not finished migrating; honoured for one minor version, gone in 0.7.0.
+      # not finished migrating; honoured for one more minor version, gone in 0.8.0.
       @legacy_tier_checks    = false
       @leadership_emails     = []
       @leadership_check      = ->(user) { HrLite.email_listed?(user, HrLite.config.leadership_emails) }

data/lib/hr_lite/statutory_rate_card.rb

@@ -1,15 +1,19 @@
 module HrLite
-  # Config-driven statutory rates, keyed by effective date — a budget change
-  # is a one-hash edit that gets code review and a spec diff, never an
-  # inline-constant hunt.
+  # Where payroll asks "what were the statutory figures in this month".
   #
-  # 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.
+  # Cards live in the DATABASE (`hr_lite_statutory_rate_cards`), effective-
+  # dated, so adding a financial year is a screen an accountant fills in
+  # rather than a gem release. Every April used to be a deadline the gem
+  # controlled and the company did not.
   #
-  # 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.
+  # CARDS below is the SEED — the figures the gem ships with, copied into the
+  # table by `hr_lite:seed` and then owned by the install. It is also the
+  # fallback for a host that has not migrated or seeded yet, so the lookup
+  # never returns nil half-way through computing somebody's salary.
+  #
+  # When no card covers a run's financial year the lookup still answers —
+  # payroll cannot stop dead every 1 April — but `warning_for` says so, and
+  # `PayrollRunProcessor` puts that sentence above every other warning.
   module StatutoryRateCard
     def self.r(value) = BigDecimal(value.to_s)
     private_class_method :r
@@ -62,15 +66,44 @@ module HrLite
     }.freeze
 
     def self.for(period_month)
+      record = record_for(period_month)
+      return record.to_card if record
+
       CARDS[effective_date_for(period_month)]
     end
 
+    # The stored card a run resolves to, or nil when the table is empty (a
+    # host that has not run `hr_lite:seed` yet) and the shipped hash answers
+    # instead.
+    def self.record_for(period_month)
+      return nil unless stored?
+
+      StatutoryRateCardRecord.effective_for(period_month)
+    end
+
+    # Deliberately rescued: the lookup is called from payroll, and a host
+    # mid-migration — gem upgraded, `db:migrate` not yet run — must fall back
+    # to the shipped figures rather than 500.
+    def self.stored?
+      StatutoryRateCardRecord.table_exists? && StatutoryRateCardRecord.exists?
+    rescue ActiveRecord::ActiveRecordError
+      false
+    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)
+      if stored?
+        return StatutoryRateCardRecord.effective_for(period_month).effective_from
+      end
+
       CARDS.keys.sort.reverse.find { |date| date <= period_month } || CARDS.keys.min
     end
 
+    def self.earliest_date
+      stored? ? StatutoryRateCardRecord.chronological.first.effective_from : 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.
@@ -81,7 +114,19 @@ module HrLite
     # 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
+      period_month < earliest_date
+    end
+
+    # A card exists for the run's year but nobody has signed it off. Ranked
+    # below staleness because wrong-year figures are the worse problem, but
+    # still worth saying: these numbers decide what lands in a bank account.
+    def self.unverified_for(period_month)
+      record = record_for(period_month)
+      return nil if record.nil? || record.verified? || stale_for?(period_month)
+
+      "The FY #{record.financial_year} statutory card has not been marked " \
+      "verified. Check PF, ESI and the tax slabs with your accountant, then " \
+      "record who confirmed them on the rate-card screen."
     end
 
     # One sentence naming both the run's FY and the card's, or nil when they

data/lib/hr_lite/statutory_seeds.rb

@@ -0,0 +1,71 @@
+module HrLite
+  # Copies the figures the gem ships with into the tables that own them from
+  # then on. Idempotent, and it NEVER touches a card the install already has:
+  # once an accountant has corrected a number, a deploy must not put the
+  # gem's version back.
+  #
+  # Nothing here is invented. Every figure is lifted from
+  # StatutoryRateCard::CARDS, which is the same hash that has always shipped.
+  module StatutorySeeds
+    def self.call
+      seed_cards! + seed_pt_slabs!
+    end
+
+    def self.seed_cards!
+      StatutoryRateCard::CARDS.filter_map do |effective_from, card|
+        next if StatutoryRateCardRecord.exists?(effective_from: effective_from)
+
+        StatutoryRateCardRecord.create!(
+          effective_from: effective_from,
+          pf: stringify(card[:pf]),
+          esi: stringify(card[:esi]),
+          income_tax: card[:income_tax].transform_values { |regime| stringify_regime(regime) },
+          notes: "Shipped with hr_lite #{HrLite::VERSION}. Confirm with your " \
+                 "accountant, then record who verified it."
+        )
+        "rate card FY #{FinancialYear.label(effective_from)}"
+      end
+    end
+
+    def self.seed_pt_slabs!
+      created = []
+      StatutoryRateCard::CARDS.each do |effective_from, card|
+        card[:pt].each do |state, slabs|
+          # An empty slab list in the shipped hash meant "we know of no bands
+          # for this state" — which is exactly the silence the slab table is
+          # here to distinguish from a real zero. Nothing to copy.
+          next if slabs.empty?
+          next if ProfessionalTaxSlab.exists?(state: state, effective_from: effective_from)
+
+          slabs.each do |slab|
+            ProfessionalTaxSlab.create!(
+              state: state, effective_from: effective_from,
+              from_amount: slab[:from] || slab[:above],
+              monthly: slab[:monthly], feb_extra: slab[:feb_extra]
+            )
+          end
+          created << "#{state} PT slabs"
+        end
+      end
+      created
+    end
+
+    # JSON columns take strings so a BigDecimal survives the round trip
+    # intact — a float would not, and these figures decide deductions.
+    def self.stringify(hash)
+      hash.to_h { |key, value| [ key.to_s, value.to_s("F") ] }
+    end
+
+    def self.stringify_regime(regime)
+      {
+        "standard_deduction" => regime[:standard_deduction].to_s("F"),
+        "rebate_cap" => regime[:rebate_cap].to_s("F"),
+        "cess_rate" => regime[:cess_rate].to_s("F"),
+        "marginal_relief" => !!regime[:marginal_relief],
+        "slabs" => regime[:slabs].map { |from, to, rate|
+          [ from.to_s("F"), to&.to_s("F"), rate.to_s("F") ]
+        }
+      }
+    end
+  end
+end

data/lib/hr_lite/version.rb

@@ -1,3 +1,3 @@
 module HrLite
-  VERSION = "0.6.0"
+  VERSION = "0.7.0"
 end

data/lib/hr_lite.rb

@@ -6,6 +6,7 @@ require "hr_lite/leave_year"
 require "hr_lite/financial_year"
 require "hr_lite/permissions"
 require "hr_lite/role_seeds"
+require "hr_lite/statutory_seeds"
 require "hr_lite/mention_parser"
 require "hr_lite/notifications"
 require "hr_lite/seeds"

data/lib/tasks/hr_lite_tasks.rake

@@ -3,10 +3,18 @@ namespace :hr_lite do
   task seed: :environment do
     require "hr_lite/seeds"
     require "hr_lite/role_seeds"
-    created = HrLite::Seeds.run! + HrLite::RoleSeeds.call
+    require "hr_lite/statutory_seeds"
+    created = HrLite::Seeds.run! + HrLite::RoleSeeds.call + HrLite::StatutorySeeds.call
     puts created.any? ? "hr_lite:seed created: #{created.join(', ')}" : "hr_lite:seed — nothing to do"
   end
 
+  desc "Copy the shipped statutory figures into the rate-card tables (never overwrites)"
+  task statutory: :environment do
+    require "hr_lite/statutory_seeds"
+    created = HrLite::StatutorySeeds.call
+    puts created.any? ? "hr_lite:statutory created: #{created.join(', ')}" : "hr_lite:statutory — nothing to do"
+  end
+
   desc "Idempotently seed the built-in roles only (never overwrites a tuned role)"
   task roles: :environment do
     require "hr_lite/role_seeds"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hr_lite
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - kshitiz sinha
@@ -77,6 +77,7 @@ files:
 - app/controllers/hr_lite/admin/salary_slips_controller.rb
 - app/controllers/hr_lite/admin/salary_structures_controller.rb
 - app/controllers/hr_lite/admin/settings_controller.rb
+- app/controllers/hr_lite/admin/statutory_rate_cards_controller.rb
 - app/controllers/hr_lite/admin/superadmin_controller.rb
 - app/controllers/hr_lite/application_controller.rb
 - app/controllers/hr_lite/appraisals_controller.rb
@@ -120,6 +121,7 @@ files:
 - app/models/hr_lite/leave_type.rb
 - app/models/hr_lite/office_location.rb
 - app/models/hr_lite/payroll_run.rb
+- app/models/hr_lite/professional_tax_slab.rb
 - app/models/hr_lite/regularization_request.rb
 - app/models/hr_lite/resignation.rb
 - app/models/hr_lite/role.rb
@@ -128,6 +130,7 @@ files:
 - app/models/hr_lite/salary_slip.rb
 - app/models/hr_lite/salary_structure.rb
 - app/models/hr_lite/setting.rb
+- app/models/hr_lite/statutory_rate_card_record.rb
 - app/services/hr_lite/access.rb
 - app/services/hr_lite/attendance_puncher.rb
 - app/services/hr_lite/attendance_summary.rb
@@ -186,6 +189,10 @@ files:
 - app/views/hr_lite/admin/salary_structures/new.html.erb
 - app/views/hr_lite/admin/settings/edit.html.erb
 - app/views/hr_lite/admin/shared/_approvals_tabs.html.erb
+- app/views/hr_lite/admin/statutory_rate_cards/_form.html.erb
+- app/views/hr_lite/admin/statutory_rate_cards/edit.html.erb
+- app/views/hr_lite/admin/statutory_rate_cards/index.html.erb
+- app/views/hr_lite/admin/statutory_rate_cards/new.html.erb
 - app/views/hr_lite/appraisals/index.html.erb
 - app/views/hr_lite/appraisals/show.html.erb
 - app/views/hr_lite/attendance/_month_grid.html.erb
@@ -255,6 +262,7 @@ files:
 - db/migrate/20260817182124_add_status_constraints_and_appraisal_fk_to_hr_lite.rb
 - db/migrate/20260817183347_create_hr_lite_roles_and_grants.rb
 - db/migrate/20260817183629_seed_hr_lite_roles_from_email_tiers.rb
+- db/migrate/20260817190159_create_hr_lite_statutory_rate_cards.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
@@ -273,6 +281,7 @@ files:
 - lib/hr_lite/role_seeds.rb
 - lib/hr_lite/seeds.rb
 - lib/hr_lite/statutory_rate_card.rb
+- lib/hr_lite/statutory_seeds.rb
 - lib/hr_lite/version.rb
 - lib/tasks/hr_lite_tasks.rake
 homepage: https://github.com/kshtzkr/hr_lite