hr_lite 0.9.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42a084897bd2831303410129ecaa25dac81fdb97b711bfe07071cf28496d58d1
-  data.tar.gz: 014663d43940503d5fa840f5bb0460b8fd3e20bfbaf07a1aa6821b491798d16d
+  metadata.gz: 655b4d27557dace6262528eb82af6912b4b7dfcdc3ff6b8274068876b8bb970c
+  data.tar.gz: ba15eee422c61704681db9d8d1194851f8c761459524844ade6e4cd054776f81
 SHA512:
-  metadata.gz: 40177d861f9579695084b3e0bca3fefd4dd9593d430d800c7c1bfed2c88d1de4820fd12c6c816c24cf29f0d70eb8db26efe2c9cc10870ec1f9be15b262c05f1d
-  data.tar.gz: 261892abb65e4ebb80f12cdfbdf7763d2e82f9040268efa796870ec6af413cc25079e9e124536e2eb0a4e1a937e0de6a98f98fde84901248a91a3ea944f684bf
+  metadata.gz: 4b4224f36f2cd4b3c256d440e6f439f59ce86e61436545f4f5a1afab97d827c64db86b4ee3b21f72003ea8864010b0369d6a719cd833a7194855adc1af10602c
+  data.tar.gz: 3de774d902610ab761c5794fe4f9eec3c404dac26ccf0fbea553bfe6bafe09e45c576e8264b07c70b6eef07af3f93f54c88aa43d3fd149921d4726456823a890

data/CHANGELOG.md

@@ -7,6 +7,90 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.11.0] - 2026-08-18
+
+Documents, and a tax declaration that is more than one number. **Adds one
+migration.** Requires Active Storage on the host (`rails active_storage:install`).
+
+### Added
+
+- **`hr_lite_documents`** — there was nowhere to keep an employee's documents
+  at all. Files attach through Active Storage, which content-sniffs via
+  Marcel, so the type allowlist checks real bytes rather than what the client
+  claimed. SVG and HTML stay out: both carry script and both render in a
+  browser. 10 MB cap.
+- **Visibility is a property of the row**, and an identity document defaults
+  to the tightest setting rather than the convenient one — an Aadhaar, PAN,
+  passport or bank mandate is money-tier by default, not HR's to browse. A
+  default nobody thinks about is the one that leaks. An explicit choice always
+  wins, which is why the column carries no default of its own.
+- Verification with a named checker, and expiry with a job that warns at 30
+  days and again at 7 — not daily, because a warning that arrives every day
+  is one nobody reads by the third.
+- **`hr_lite_tax_declarations`** and items, replacing
+  `declared_annual_deductions`: ONE opaque figure an admin typed in, that
+  nobody could see the makeup of, that the employee could not submit
+  themselves, and that had nowhere to keep the proof. It is the number the
+  whole year's TDS is projected from.
+- Sections (80C, 80D, 80CCD(1B), 24(b), HRA), each with what was **declared**
+  and what the proof actually **supported**. Until HR has looked, the declared
+  figure stands — asking somebody to overpay tax all year because paperwork is
+  slow is its own kind of wrong. Once verified, only the supported figure
+  counts.
+- The regime follows the declaration, because choosing one is a per-YEAR
+  decision and the profile column cannot express that.
+- Permissions `document.view`, `document.manage`, `tax.view`, `tax.manage`,
+  granted to the roles that should hold them.
+
+### Changed
+
+- `SlipBuilder` reads the declaration when one exists for the run's financial
+  year, falling back to the profile figure otherwise. A DRAFT declaration is
+  ignored — a draft is not a claim.
+
+## [0.10.0] - 2026-08-18
+
+Payroll gets heads, arrears and loans. **Adds one migration.** Existing
+payslips compute identically — every new head is opt-in data.
+
+### Added
+
+- **`hr_lite_salary_components`** — earning and deduction heads as DATA.
+  Payroll knew exactly four earnings because they were columns on the salary
+  structure, so a bonus, an incentive, an LTA or a reimbursement had nowhere
+  to go but "other": one number on a payslip that should have said what it
+  was for. Seeded with bonus, incentive, arrears, LTA, reimbursement, loan
+  repayment and other-deduction; an install adds its own.
+- Each head declares whether it is **prorated** (a bonus is not halved
+  because somebody joined on the 16th), **taxable**, and whether it
+  **counts toward the ESI gross** — a reimbursement is not a wage, and
+  counting it could push somebody over the ceiling and out of cover.
+- **`hr_lite_payroll_line_items`** — one-offs for a single month, including
+  arrears after a backdated revision. Dated to the MONTH rather than the run,
+  so deleting a draft and computing it again does not lose them. Refused on a
+  month already published: that slip is immutable, and a later line would
+  show on no payslip while quietly moving the year-to-date the TDS projector
+  reads.
+- **`hr_lite_loans`** and repayments. The outstanding balance is DERIVED from
+  the repayments actually taken, never stored — a stored balance and a
+  recomputed run disagree the first time somebody deletes a draft. The last
+  instalment takes only what is left.
+- Repayments are booked when a run is **finalized**, not at compute: a draft
+  is recomputed as often as the operator likes, and each pass would otherwise
+  take another instalment. Unlocking a run gives them back, and reopens a
+  loan that had closed.
+
+### Changed
+
+- Branch coverage is now a **floor at 90%, not a ratchet**, with the reasoning
+  written into `spec_helper.rb`. Its denominator grows with every subsystem,
+  so ratcheting it charges each feature PR a tax for branches in files it
+  never touched. Line coverage remains the ratchet at 100% overall and 90%
+  per file — that is the gate that has actually caught defects.
+- Paid down some of the branch debt named in 0.9.0: the status predicates
+  across six models, the UAN format validation, and the holiday bulk-import
+  paths (blank lines, an empty paste, a line that cannot be read).
+
 ## [0.9.0] - 2026-08-18
 
 A reusable approval engine. **Adds one migration** (flows, steps, approvals,
@@ -610,7 +694,9 @@ 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.9.0...HEAD
+[Unreleased]: https://github.com/kshtzkr/hr_lite/compare/v0.11.0...HEAD
+[0.11.0]: https://github.com/kshtzkr/hr_lite/compare/v0.10.0...v0.11.0
+[0.10.0]: https://github.com/kshtzkr/hr_lite/compare/v0.9.0...v0.10.0
 [0.9.0]: https://github.com/kshtzkr/hr_lite/compare/v0.8.0...v0.9.0
 [0.8.0]: https://github.com/kshtzkr/hr_lite/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/kshtzkr/hr_lite/compare/v0.6.0...v0.7.0

data/app/jobs/hr_lite/document_expiry_job.rb

@@ -0,0 +1,28 @@
+module HrLite
+  # Tells people before a document lapses. A passport or a visa is somebody's
+  # right to work, and the whole problem with an expiry date is finding out
+  # about it late.
+  #
+  # Warns at 30 days and again at 7, rather than every day for a month.
+  class DocumentExpiryJob < ApplicationJob
+    WINDOWS = [ 30, 7 ].freeze
+
+    def perform(today: Date.current)
+      WINDOWS.each do |days|
+        Document.where(expires_on: today + days).includes(:user).find_each do |document|
+          Notifications.publish(
+            "document.expiring",
+            title: "#{document.title} expires in #{days} days",
+            body: "#{HrLite.display_name(document.user)} — #{document.category.humanize}, " \
+                  "expiring #{document.expires_on.strftime('%d %b %Y')}.",
+            path: "/profile",
+            bell_to: [ document.user ],
+            email_to: [ document.user ],
+            leadership: { title: "#{HrLite.display_name(document.user)}'s #{document.title} " \
+                                 "expires in #{days} days" }
+          )
+        end
+      end
+    end
+  end
+end

data/app/models/hr_lite/document.rb

@@ -0,0 +1,95 @@
+module HrLite
+  # An employee's document: an Aadhaar scan, a PAN, an offer letter, a
+  # certificate. The FILE is the sensitive part, so visibility is a property
+  # of the row and every read goes through `readable_by?`.
+  class Document < ApplicationRecord
+    include Audited
+
+    VISIBILITIES = %w[self hr money].freeze
+    VERIFICATIONS = %w[pending verified rejected].freeze
+
+    # Categories the engine knows how to reason about. An install may store
+    # any string; these are the ones with an opinion attached.
+    SENSITIVE_CATEGORIES = %w[aadhaar pan passport bank].freeze
+
+    # Active Storage content-sniffs via Marcel, so this checks the real bytes
+    # rather than whatever the client claimed. SVG and HTML stay out — both
+    # can carry script and both render in a browser.
+    ALLOWED_TYPES = %w[
+      application/pdf image/jpeg image/png image/heic image/webp
+    ].freeze
+    MAX_BYTES = 10.megabytes
+
+    has_one_attached :file
+
+    belongs_to :user, class_name: HrLite.config.user_class
+    belongs_to :verified_by, class_name: HrLite.config.user_class, optional: true
+    belongs_to :uploaded_by, class_name: HrLite.config.user_class, optional: true
+
+    validates :category, :title, presence: true
+    validates :visibility, inclusion: { in: VISIBILITIES }
+    validates :verification, inclusion: { in: VERIFICATIONS }
+    validate :file_is_an_allowed_kind
+    validate :file_is_not_too_large
+    before_validation :default_visibility_from_category, on: :create
+
+    scope :for_user, ->(user) { where(user_id: user.id) }
+    scope :expiring_before, ->(date) { where.not(expires_on: nil).where(expires_on: ..date) }
+    scope :recent_first, -> { order(created_at: :desc) }
+
+    VERIFICATIONS.each { |v| define_method("#{v}?") { verification == v } }
+
+    def expired?(on = Date.current) = expires_on.present? && expires_on < on
+
+    # Who may open the FILE. The owner always may; beyond that it is the
+    # permission the row's visibility names. A passport is not a payslip and
+    # neither is HR's to browse by default.
+    def readable_by?(reader)
+      return false if reader.nil?
+      return true if reader.id == user_id
+
+      case visibility
+      when "self" then false
+      when "hr" then HrLite.reaches?(reader, "document.view", user)
+      when "money" then HrLite.can?(reader, "document.manage", scope: :all)
+      end
+    end
+
+    def verify!(actor:, note: nil)
+      update!(verification: "verified", verified_by_id: actor.id,
+              verified_at: Time.current, verification_note: note.presence)
+    end
+
+    def reject!(actor:, note:)
+      raise ArgumentError, "a rejection needs a reason" if note.blank?
+
+      update!(verification: "rejected", verified_by_id: actor.id,
+              verified_at: Time.current, verification_note: note)
+    end
+
+    private
+
+    # An Aadhaar or a bank mandate defaults to the tightest setting rather
+    # than the convenient one — a default nobody thinks about is the one that
+    # leaks. An explicit choice always wins, which is why the column carries
+    # no default of its own.
+    def default_visibility_from_category
+      return if visibility.present?
+
+      self.visibility = SENSITIVE_CATEGORIES.include?(category.to_s) ? "money" : "hr"
+    end
+
+    def file_is_an_allowed_kind
+      return unless file.attached?
+      return if ALLOWED_TYPES.include?(file.blob.content_type)
+
+      errors.add(:file, "must be a PDF or an image — #{file.blob.content_type} is not accepted")
+    end
+
+    def file_is_not_too_large
+      return unless file.attached? && file.blob.byte_size > MAX_BYTES
+
+      errors.add(:file, "must be under #{MAX_BYTES / 1.megabyte} MB")
+    end
+  end
+end

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/slip_builder.rb

@@ -33,8 +33,17 @@ module HrLite
       earnings = Calculators::Proration.call(
         structure: @structure, payable_days: payable, days_in_month: days_in_month
       )
+      # One-off heads for this month: a bonus, arrears after a backdated
+      # revision, a reimbursement. A prorated head is scaled like basic; a
+      # bonus is not halved because somebody joined mid-month.
+      extra_earnings, extra_deductions = one_off_lines(payable, days_in_month)
+      earnings += extra_earnings
+
       gross_earned = earnings.sum(BigDecimal(0)) { |row| row[:amount] }
       basic_earned = earnings.find { |row| row[:code] == "basic" }&.fetch(:amount) || BigDecimal(0)
+      # ESI is assessed on wages, and a reimbursement is not one. Heads that
+      # opt out are excluded from the gross it reads.
+      esi_gross = gross_earned - earnings.sum(BigDecimal(0)) { |row| row[:excluded_from_esi] ? row[:amount] : 0 }
 
       deductions = []
       employer_costs = {}
@@ -50,7 +59,7 @@ module HrLite
         )
       end
 
-      esi = Calculators::Esi.call(monthly_gross: esi_reference_gross, gross_earned: gross_earned,
+      esi = Calculators::Esi.call(monthly_gross: esi_reference_gross, gross_earned: esi_gross,
                                   applicable: @structure.esi_applicable, rates: @rates[:esi])
       if esi.applicable?
         deductions << { code: "esi_employee", label: "ESI", amount: esi.employee }
@@ -61,9 +70,13 @@ module HrLite
                                              period_month: @run.period_month, rates: @rates[:pt])
       deductions << { code: "pt", label: "Professional tax", amount: pt } if pt.positive?
 
+      deductions.concat(extra_deductions)
+      loan = loan_instalment
+      deductions << loan if loan
+
       fy = SalarySlip.fy_to_date(@user, @run.period_month)
       tds = Calculators::Tds.call(
-        regime: @profile.tax_regime,
+        regime: tax_regime,
         structure_monthly_gross: @structure.monthly_gross,
         gross_earned_this_month: gross_earned,
         # Plus anything paid this FY that this install never ran — a previous
@@ -73,7 +86,7 @@ module HrLite
         fy_gross_paid: fy[:gross] + Money.d(@profile.fy_opening_gross),
         fy_tds_paid: fy[:tds] + Money.d(@profile.fy_opening_tds),
         months_remaining: months_remaining_in_fy,
-        declared_annual_deductions: @profile.declared_annual_deductions,
+        declared_annual_deductions: annual_deductions,
         rates: @rates[:income_tax],
         override: @tds_override
       )
@@ -107,6 +120,66 @@ module HrLite
 
     private
 
+    # The declaration if the employee filed one, else the single figure an
+    # admin typed on the profile. Old-regime deductions came from that one
+    # opaque number, with nothing to show what it was made of and nowhere to
+    # keep the proof; a filed declaration supersedes it, and once HR has
+    # verified the proof only what the proof supported counts.
+    # A declaration names the regime the employee chose for that year, which
+    # is a per-YEAR decision; the profile column is only the fallback for
+    # somebody who never filed one.
+    def tax_regime
+      TaxDeclaration.for(@user, @run.period_month)&.regime || @profile.tax_regime
+    end
+
+    def annual_deductions
+      declaration = TaxDeclaration.for(@user, @run.period_month)
+      return @profile.declared_annual_deductions if declaration.nil?
+      return @profile.declared_annual_deductions if declaration.draft?
+
+      declaration.allowable_total
+    end
+
+    # Splits this month's one-off lines into earnings and deductions, in the
+    # component order an install configured. Returns [earnings, deductions].
+    def one_off_lines(payable, days_in_month)
+      rows = PayrollLineItem.for_slip(@user, @run.period_month)
+                            .sort_by { |item| [ item.component.position, item.component.label ] }
+      earnings = []
+      deductions = []
+
+      rows.each do |item|
+        component = item.component
+        amount = if component.prorated
+          Money.round2(item.amount * (Money.d(payable) / Money.d(days_in_month)))
+        else
+          item.amount
+        end
+        next unless amount.positive?
+
+        row = { code: component.code, label: component.label, amount: amount }
+        if component.earning?
+          earnings << row.merge(excluded_from_esi: !component.counts_for_esi)
+        else
+          deductions << row
+        end
+      end
+
+      [ earnings, deductions ]
+    end
+
+    # The month's loan instalment, as one deduction line. Computed here and
+    # BOOKED only when the run is finalized — a draft is recomputed freely,
+    # and booking at compute would take a repayment on every pass.
+    def loan_instalment
+      total = Loan.active.where(user_id: @user.id).sum(BigDecimal(0)) do |loan|
+        loan.instalment_for(@run.period_month)
+      end
+      return nil unless total.positive?
+
+      { code: "loan_repayment", label: "Loan repayment", amount: total }
+    end
+
     # Months left in the Indian FY (Apr–Mar) including the run month itself:
     # April = 12, December = 4, January = 3, March = 1. Capped at the exit
     # month for a leaver, so a final settlement is not spread over months

data/db/migrate/20260818002627_create_hr_lite_payroll_components_and_loans.rb

@@ -0,0 +1,72 @@
+class CreateHrLitePayrollComponentsAndLoans < ActiveRecord::Migration[8.1]
+  # Payroll knew exactly four earning heads — basic, HRA, special allowance,
+  # "other" — because they were columns on the salary structure. A bonus, an
+  # incentive, an LTA or a reimbursement had nowhere to go but "other", which
+  # is one number on a payslip that should have said what it was for.
+  #
+  # Heads are DATA now. Amounts stay encrypted for the same reason every
+  # amount in this engine is: a payslip line is somebody's pay.
+  def change
+    create_table :hr_lite_salary_components do |t|
+      t.string :code, null: false
+      t.string :label, null: false
+      # earning | deduction
+      t.string :kind, null: false, default: "earning"
+      # Prorated by attendance like basic, or paid whole (a bonus is not
+      # halved because somebody joined mid-month).
+      t.boolean :prorated, null: false, default: true
+      t.boolean :taxable, null: false, default: true
+      # Counts toward the gross ESI is assessed on.
+      t.boolean :counts_for_esi, null: false, default: true
+      t.integer :position, null: false, default: 0
+      t.boolean :active, null: false, default: true
+      t.timestamps
+    end
+    add_index :hr_lite_salary_components, :code, unique: true
+    add_check_constraint :hr_lite_salary_components, "kind IN ('earning', 'deduction')",
+                         name: "hr_lite_salary_components_kind_check"
+
+    # A one-off on a single month's payslip: a bonus, an incentive, an
+    # arrears line after a backdated revision, a reimbursement. Dated to the
+    # month rather than to the run, so it survives a run being deleted and
+    # recomputed.
+    create_table :hr_lite_payroll_line_items do |t|
+      t.bigint :user_id, null: false
+      t.date :period_month, null: false
+      t.references :component, null: false, index: true,
+                   foreign_key: { to_table: :hr_lite_salary_components }
+      t.text :amount, null: false # encrypted BigDecimal
+      t.string :note
+      t.bigint :created_by_id
+      t.timestamps
+    end
+    add_index :hr_lite_payroll_line_items, %i[user_id period_month]
+
+    create_table :hr_lite_loans do |t|
+      t.bigint :user_id, null: false
+      t.text :principal, null: false      # encrypted
+      t.text :monthly_instalment, null: false # encrypted
+      t.date :starts_on, null: false
+      t.string :reason
+      # active | closed | cancelled
+      t.string :status, null: false, default: "active"
+      t.bigint :approved_by_id
+      t.timestamps
+    end
+    add_index :hr_lite_loans, %i[user_id status]
+    add_check_constraint :hr_lite_loans, "status IN ('active', 'closed', 'cancelled')",
+                         name: "hr_lite_loans_status_check"
+
+    # One row per month actually deducted. The outstanding balance is derived
+    # from these rather than stored, so a recompute cannot double-count and a
+    # deleted run cannot leave the balance wrong.
+    create_table :hr_lite_loan_repayments do |t|
+      t.references :loan, null: false, index: true,
+                   foreign_key: { to_table: :hr_lite_loans, on_delete: :cascade }
+      t.date :period_month, null: false
+      t.text :amount, null: false # encrypted
+      t.timestamps
+    end
+    add_index :hr_lite_loan_repayments, %i[loan_id period_month], unique: true
+  end
+end

data/db/migrate/20260818003616_create_hr_lite_documents_and_declarations.rb

@@ -0,0 +1,73 @@
+class CreateHrLiteDocumentsAndDeclarations < ActiveRecord::Migration[8.1]
+  # Two gaps that were table stakes and simply absent: nowhere to keep an
+  # employee's documents, and a tax declaration that was ONE opaque number.
+  #
+  # `declared_annual_deductions` on the profile is a single figure an admin
+  # types in. Nobody can see what it is made of, the employee cannot submit
+  # their own, and there is nowhere to put the proof. That is the number the
+  # whole year's TDS is projected from.
+  def change
+    create_table :hr_lite_documents do |t|
+      t.bigint :user_id, null: false
+      # aadhaar | pan | passport | bank | offer_letter | ... — data, so an
+      # install can add its own without a release.
+      t.string :category, null: false
+      t.string :title, null: false
+      t.string :reference_number
+      t.date :issued_on
+      t.date :expires_on
+      # self | hr | money — who may open the file. A payslip and a passport
+      # are not the same kind of secret.
+      #
+      # No column default on purpose: the model derives one from the category
+      # when none was chosen, and a column default would make "unset" and
+      # "deliberately hr" indistinguishable.
+      t.string :visibility, null: false
+      # pending | verified | rejected
+      t.string :verification, null: false, default: "pending"
+      t.bigint :verified_by_id
+      t.datetime :verified_at
+      t.string :verification_note
+      t.bigint :uploaded_by_id
+      t.timestamps
+    end
+    add_index :hr_lite_documents, %i[user_id category]
+    add_index :hr_lite_documents, :expires_on
+    add_check_constraint :hr_lite_documents, "visibility IN ('self', 'hr', 'money')",
+                         name: "hr_lite_documents_visibility_check"
+    add_check_constraint :hr_lite_documents,
+                         "verification IN ('pending', 'verified', 'rejected')",
+                         name: "hr_lite_documents_verification_check"
+
+    create_table :hr_lite_tax_declarations do |t|
+      t.bigint :user_id, null: false
+      # 1 April of the financial year it covers.
+      t.date :financial_year, null: false
+      t.string :regime, null: false, default: "new"
+      # draft | submitted | verified | rejected
+      t.string :status, null: false, default: "draft"
+      t.datetime :submitted_at
+      t.bigint :verified_by_id
+      t.datetime :verified_at
+      t.string :note
+      t.timestamps
+    end
+    add_index :hr_lite_tax_declarations, %i[user_id financial_year], unique: true
+    add_check_constraint :hr_lite_tax_declarations,
+                         "status IN ('draft', 'submitted', 'verified', 'rejected')",
+                         name: "hr_lite_tax_declarations_status_check"
+
+    create_table :hr_lite_tax_declaration_items do |t|
+      t.references :declaration, null: false, index: true,
+                   foreign_key: { to_table: :hr_lite_tax_declarations, on_delete: :cascade }
+      # 80c | 80d | hra | 80ccd_1b | 24b | other
+      t.string :section, null: false
+      t.string :label
+      t.text :declared_amount, null: false # encrypted
+      # What proof actually supported, once HR has looked. Null until then.
+      t.text :verified_amount
+      t.timestamps
+    end
+    add_index :hr_lite_tax_declaration_items, %i[declaration_id section]
+  end
+end

data/lib/hr_lite/notifications.rb

@@ -27,6 +27,13 @@ module HrLite
       # An approval past its deadline. Leadership hears too — a decision
       # nobody is making is a process problem, not just one person's inbox.
       "approval.escalated"    => { bell: true,  email: true,  leadership_email: true,  leadership_bell: false },
+      # Tax declarations. The submission bells whoever verifies them; the
+      # decision goes back to the employee, whose year's TDS depends on it.
+      "tax.declaration_submitted" => { bell: true, email: false, leadership_email: false, leadership_bell: false },
+      "tax.declaration_decided"   => { bell: true, email: true,  leadership_email: false, leadership_bell: false },
+      # A document about to lapse — a passport or a visa is somebody's right
+      # to work, and finding out late is the whole problem.
+      "document.expiring"     => { bell: true,  email: true,  leadership_email: true,  leadership_bell: false },
       "digest.daily"          => { bell: false, email: false, leadership_email: true,  leadership_bell: false },
       "resignation.submitted" => { bell: true,  email: false, leadership_email: true,  leadership_bell: true  },
       "resignation.accepted"  => { bell: true,  email: true,  leadership_email: true,  leadership_bell: false },

data/lib/hr_lite/permissions.rb

@@ -43,6 +43,10 @@ module HrLite
       "appraisal.manage" => [ "Growth", "Write, share and act on appraisals and promotions" ],
       "resignation.view" => [ "Lifecycle", "See resignations" ],
       "resignation.manage" => [ "Lifecycle", "Accept resignations and set the last working day" ],
+      "document.view" => [ "Documents", "Open other people's documents" ],
+      "document.manage" => [ "Documents", "Upload, verify and open identity and bank documents" ],
+      "tax.view" => [ "Payroll", "See tax declarations" ],
+      "tax.manage" => [ "Payroll", "Verify tax declarations and the proof behind them" ],
       "settings.manage" => [ "Administration", "Change company settings, offices and policy" ],
       "audit.view" => [ "Administration", "Read the audit trail" ],
       "audit.view_money" => [ "Administration", "Read audit rows about pay, appraisals and promotions" ],

data/lib/hr_lite/role_seeds.rb

@@ -17,7 +17,7 @@ module HrLite
           "leave.request" => "self", "leave.view" => "self",
           "attendance.view" => "self", "payroll.view" => "self",
           "profile.view" => "self", "appraisal.view" => "self",
-          "resignation.view" => "self"
+          "resignation.view" => "self", "document.view" => "self", "tax.view" => "self"
         }
       },
       Role::MANAGER => {
@@ -35,7 +35,8 @@ module HrLite
           "leave.request" => "self", "leave.view" => "all", "leave.approve" => "all",
           "leave.manage" => "all", "attendance.view" => "all", "attendance.manage" => "all",
           "profile.view" => "all", "payroll.view" => "self",
-          "appraisal.view" => "self", "resignation.view" => "all"
+          "appraisal.view" => "self", "resignation.view" => "all",
+          "document.view" => "all", "tax.view" => "self"
         }
       },
       Role::FINANCE => {
@@ -45,6 +46,7 @@ module HrLite
           "attendance.view" => "all", "profile.view" => "all",
           "payroll.view" => "all", "payroll.manage" => "all", "payroll.export" => "all",
           "salary.view" => "all", "salary.manage" => "all",
+          "tax.view" => "all", "tax.manage" => "all",
           "audit.view" => "all", "audit.view_money" => "all"
         }
       },
@@ -55,7 +57,8 @@ module HrLite
           "leave.manage" => "all", "attendance.view" => "all", "attendance.manage" => "all",
           "profile.view" => "all", "profile.manage" => "all",
           "resignation.view" => "all", "resignation.manage" => "all",
-          "settings.manage" => "all", "audit.view" => "all", "payroll.view" => "self"
+          "settings.manage" => "all", "audit.view" => "all", "payroll.view" => "self",
+          "document.view" => "all"
         }
       },
       Role::SUPER_ADMIN => {

data/lib/hr_lite/version.rb

@@ -1,3 +1,3 @@
 module HrLite
-  VERSION = "0.9.0"
+  VERSION = "0.11.0"
 end

data/lib/tasks/hr_lite_tasks.rake

@@ -4,7 +4,8 @@ namespace :hr_lite do
     require "hr_lite/seeds"
     require "hr_lite/role_seeds"
     require "hr_lite/statutory_seeds"
-    created = HrLite::Seeds.run! + HrLite::RoleSeeds.call + HrLite::StatutorySeeds.call
+    created = HrLite::Seeds.run! + HrLite::RoleSeeds.call + HrLite::StatutorySeeds.call +
+              HrLite::SalaryComponent.seed_defaults!
     puts created.any? ? "hr_lite:seed created: #{created.join(', ')}" : "hr_lite:seed — nothing to do"
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hr_lite
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.11.0
 platform: ruby
 authors:
 - kshitiz sinha
@@ -102,6 +102,7 @@ files:
 - app/jobs/hr_lite/application_job.rb
 - app/jobs/hr_lite/approval_escalation_job.rb
 - app/jobs/hr_lite/daily_digest_job.rb
+- app/jobs/hr_lite/document_expiry_job.rb
 - app/jobs/hr_lite/leave_year_rollover_job.rb
 - app/jobs/hr_lite/payroll_auto_draft_job.rb
 - app/mailers/hr_lite/application_mailer.rb
@@ -119,6 +120,7 @@ files:
 - app/models/hr_lite/audit_log.rb
 - app/models/hr_lite/comp_off_request.rb
 - app/models/hr_lite/designation_change.rb
+- app/models/hr_lite/document.rb
 - app/models/hr_lite/employee_profile.rb
 - app/models/hr_lite/holiday.rb
 - app/models/hr_lite/kudo.rb
@@ -126,7 +128,10 @@ files:
 - app/models/hr_lite/leave_balance.rb
 - app/models/hr_lite/leave_request.rb
 - app/models/hr_lite/leave_type.rb
+- app/models/hr_lite/loan.rb
+- app/models/hr_lite/loan_repayment.rb
 - app/models/hr_lite/office_location.rb
+- app/models/hr_lite/payroll_line_item.rb
 - app/models/hr_lite/payroll_run.rb
 - app/models/hr_lite/professional_tax_slab.rb
 - app/models/hr_lite/regularization_request.rb
@@ -134,10 +139,13 @@ files:
 - app/models/hr_lite/role.rb
 - app/models/hr_lite/role_assignment.rb
 - app/models/hr_lite/role_grant.rb
+- app/models/hr_lite/salary_component.rb
 - 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/models/hr_lite/tax_declaration.rb
+- app/models/hr_lite/tax_declaration_item.rb
 - app/services/hr_lite/access.rb
 - app/services/hr_lite/approval_route.rb
 - app/services/hr_lite/attendance_puncher.rb
@@ -273,6 +281,8 @@ files:
 - db/migrate/20260817183629_seed_hr_lite_roles_from_email_tiers.rb
 - db/migrate/20260817190159_create_hr_lite_statutory_rate_cards.rb
 - db/migrate/20260818001151_create_hr_lite_approvals.rb
+- db/migrate/20260818002627_create_hr_lite_payroll_components_and_loans.rb
+- db/migrate/20260818003616_create_hr_lite_documents_and_declarations.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