hr_lite 0.9.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42a084897bd2831303410129ecaa25dac81fdb97b711bfe07071cf28496d58d1
-  data.tar.gz: 014663d43940503d5fa840f5bb0460b8fd3e20bfbaf07a1aa6821b491798d16d
+  metadata.gz: a035599be75b81c0d2f3d1fc1b8f95328df845445f6c93d997a9906f9b43846e
+  data.tar.gz: 8a840cc6c1af2ef49af660859fc6edf0f2ccec4b59377017c9cc0467793e8396
 SHA512:
-  metadata.gz: 40177d861f9579695084b3e0bca3fefd4dd9593d430d800c7c1bfed2c88d1de4820fd12c6c816c24cf29f0d70eb8db26efe2c9cc10870ec1f9be15b262c05f1d
-  data.tar.gz: 261892abb65e4ebb80f12cdfbdf7763d2e82f9040268efa796870ec6af413cc25079e9e124536e2eb0a4e1a937e0de6a98f98fde84901248a91a3ea944f684bf
+  metadata.gz: 9bef92ea728cc960bc548c37fe3a8a34090ad531bec3ab248dc572ce9931f44fb5bf2591b1578df0c22f68ffd5ab7c02e6e7a8ed43445b1087524fc59584889b
+  data.tar.gz: 2598075e1f67e8e2c9e7fa4142db5e7561f42f17e32a9be6207ca560116a8e9d3ac7b7876c02e4bc77c250df6ef0ec0b05592ad9c073b22aaa8f01158129276f

data/CHANGELOG.md

@@ -7,6 +7,125 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.12.0] - 2026-08-18
+
+The four things an employee had to leave the system to do. **Adds one
+migration.**
+
+### Added
+
+- **Expenses**, with categories carrying a monthly cap and a receipt rule.
+  The cap is checked when the claim is MADE, not at approval — telling
+  somebody they are over it after a week of waiting is the wrong moment to
+  find out. A claim awaiting a decision counts against the cap; a rejected
+  one gives the room back.
+- Expenses route through the approval engine from 0.9.0 rather than growing a
+  fifth approve/reject. Configure a flow and a claim gets manager-then-finance
+  for free. `reimbursed` is a separate state from `approved`, because agreeing
+  to pay somebody and paying them are different days and the person waiting
+  cares about the second one.
+- **Benefits and enrolments.** Dependants are a COUNT, not a list — names and
+  dates of birth of somebody's family are data this engine has no reason to
+  hold, and holding them would mean protecting them.
+- **An HR help desk**: raise, assign, resolve, with the answer going back to
+  the person who asked instead of dying in somebody's inbox.
+- **Policies, versioned.** Re-issuing asks everybody again, because an
+  acknowledgement of v1 says nothing about v2 — that is the whole point of
+  versioning it. Acknowledgements are `readonly?` once written: evidence that
+  can be edited afterwards is not evidence. Clicking twice is not an error.
+- Permissions for all four, granted to the roles that should hold them, and
+  nine notification events.
+
+### Changed
+
+- `HrLite::Expense` is the second module on the approval engine, which is the
+  first real test of the claim made in 0.9.0 that a new module gets
+  multi-level approval without touching the engine. It did.
+
+## [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 +729,10 @@ 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.12.0...HEAD
+[0.12.0]: https://github.com/kshtzkr/hr_lite/compare/v0.11.0...v0.12.0
+[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/approval_flow.rb

@@ -22,7 +22,7 @@ module HrLite
     def self.approvable_types
       %w[
         HrLite::LeaveRequest HrLite::CompOffRequest
-        HrLite::RegularizationRequest HrLite::Resignation
+        HrLite::RegularizationRequest HrLite::Resignation HrLite::Expense
       ].freeze
     end
 

data/app/models/hr_lite/benefit.rb

@@ -0,0 +1,37 @@
+module HrLite
+  # An insurance policy or other benefit the company provides. Employees can
+  # finally see what they are covered for without emailing somebody.
+  class Benefit < ApplicationRecord
+    include EncryptedMoney
+    include Audited
+
+    KINDS = %w[health life accident other].freeze
+
+    encrypted_money :coverage, :employer_premium, :employee_premium
+
+    has_many :benefit_enrolments, class_name: "HrLite::BenefitEnrolment", dependent: :destroy
+    has_many :enrolled_users, through: :benefit_enrolments, source: :user
+
+    validates :name, presence: true
+    validates :kind, inclusion: { in: KINDS }
+    validate :expiry_is_after_the_start
+
+    scope :active, -> { where(active: true) }
+    scope :live_on, ->(date) {
+      active.where("effective_from IS NULL OR effective_from <= ?", date)
+            .where("expires_on IS NULL OR expires_on >= ?", date)
+    }
+
+    def expiring?(within: 30, on: Date.current)
+      expires_on.present? && expires_on <= on + within && expires_on >= on
+    end
+
+    private
+
+    def expiry_is_after_the_start
+      return if effective_from.nil? || expires_on.nil? || expires_on >= effective_from
+
+      errors.add(:expires_on, "must be on or after the start date")
+    end
+  end
+end

data/app/models/hr_lite/benefit_enrolment.rb

@@ -0,0 +1,30 @@
+module HrLite
+  # Who is covered, from when. Dependants are a COUNT, not a list — names and
+  # dates of birth of somebody's family are data this engine has no reason to
+  # hold, and holding them would mean protecting them.
+  class BenefitEnrolment < ApplicationRecord
+    include Audited
+
+    belongs_to :benefit, class_name: "HrLite::Benefit"
+    belongs_to :user, class_name: HrLite.config.user_class
+
+    validates :enrolled_on, presence: true
+    validates :user_id, uniqueness: { scope: :benefit_id }
+    validates :dependants, numericality: { greater_than_or_equal_to: 0 }
+    validate :ended_after_it_started
+
+    scope :live_on, ->(date) {
+      where(enrolled_on: ..date).where("ended_on IS NULL OR ended_on >= ?", date)
+    }
+
+    def live?(on = Date.current) = enrolled_on <= on && (ended_on.nil? || ended_on >= on)
+
+    private
+
+    def ended_after_it_started
+      return if ended_on.nil? || enrolled_on.nil? || ended_on >= enrolled_on
+
+      errors.add(:ended_on, "must be on or after the enrolment date")
+    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/expense.rb

@@ -0,0 +1,142 @@
+module HrLite
+  # A claim. Routed through the approval engine rather than growing a fifth
+  # approve/reject of its own — configure a flow for it and it gets manager
+  # then finance for free.
+  class Expense < ApplicationRecord
+    include EncryptedMoney
+    include Audited
+    include Approvable
+
+    STATUSES = %w[draft submitted approved rejected reimbursed cancelled].freeze
+
+    encrypted_money :amount
+
+    belongs_to :category, class_name: "HrLite::ExpenseCategory"
+    belongs_to :user, class_name: HrLite.config.user_class
+
+    has_one_attached :receipt
+
+    validates :status, inclusion: { in: STATUSES }
+    validates :description, presence: true
+    validates :spent_on, presence: true
+    validate :amount_is_positive
+    validate :spent_on_is_not_in_the_future
+    validate :within_the_category_cap, on: :create
+    validate :receipt_is_present_when_the_category_demands_one
+
+    scope :awaiting_reimbursement, -> { where(status: "approved") }
+    scope :recent_first, -> { order(spent_on: :desc, id: :desc) }
+
+    STATUSES.each { |s| define_method("#{s}?") { status == s } }
+
+    def submit!(actor:)
+      raise ActiveRecord::RecordInvalid.new(self), "not a draft" unless draft? || rejected?
+
+      update!(status: "submitted", submitted_at: Time.current)
+      notify_deciders
+      true
+    end
+
+    def approve!(actor:, note: nil)
+      return record_routed!(actor, note, :approved) if awaiting?(actor)
+
+      settle!("approved", actor, note)
+    end
+
+    def reject!(actor:, note:)
+      raise ArgumentError, "a rejection needs a reason" if note.blank?
+      return record_routed!(actor, note, :rejected) if awaiting?(actor)
+
+      settle!("rejected", actor, note)
+    end
+
+    # Paid out with a payroll month. Kept separate from `approved` because
+    # agreeing to pay somebody and actually paying them are different days,
+    # and the person waiting cares about the second one.
+    def reimburse!(actor:, period_month:)
+      raise ActiveRecord::RecordInvalid.new(self), "not approved" unless approved?
+
+      transaction do
+        update!(status: "reimbursed", reimbursed_in: period_month.beginning_of_month)
+        AuditLog.record!(action: "expense.reimbursed", subject: self, actor: actor,
+                         changes: { "employee" => HrLite.display_name(user),
+                                    "period" => period_month.strftime("%B %Y") })
+      end
+      Notifications.publish(
+        "expense.reimbursed",
+        title: "Your #{category.name} claim was reimbursed with #{period_month.strftime('%B %Y')} payroll",
+        path: "/expenses", bell_to: [ user ], email_to: [ user ]
+      )
+      true
+    end
+
+    private
+
+    def record_routed!(actor, note, intent)
+      approval = approval_for(actor)
+      result = approval_route.decide!(approval, status: intent.to_s, actor: actor, note: note)
+
+      case result.outcome
+      when :approved then settle!("approved", actor, note)
+      # `reject!` already refuses a blank note, so there is nothing to
+      # default to here.
+      when :rejected then settle!("rejected", actor, note)
+      else
+        notify_deciders
+        true
+      end
+    end
+
+    def settle!(new_status, actor, note)
+      update!(status: new_status, decision_note: note.presence)
+      Notifications.publish(
+        new_status == "approved" ? "expense.approved" : "expense.rejected",
+        title: "Your #{category.name} claim was #{new_status}",
+        body: note.presence, path: "/expenses", bell_to: [ user ], email_to: [ user ]
+      )
+      true
+    end
+
+    def notify_deciders
+      deciders = pending_approvals.map(&:approver).compact.uniq
+      deciders = HrLite.users_holding("expense.approve").to_a if deciders.empty?
+      return if deciders.empty?
+
+      Notifications.publish(
+        "expense.submitted",
+        title: "#{HrLite.display_name(user)} claimed #{Money.format(amount)} — #{category.name}",
+        body: description, path: "/admin/expenses", bell_to: deciders
+      )
+    end
+
+    def amount_is_positive
+      errors.add(:amount, "must be more than zero") unless amount&.positive?
+    end
+
+    def spent_on_is_not_in_the_future
+      return if spent_on.nil? || spent_on <= Date.current
+
+      errors.add(:spent_on, "cannot be in the future")
+    end
+
+    # Checked at claim time rather than at approval: telling somebody they
+    # are over the cap after they have waited a week for an answer is the
+    # wrong moment to find out.
+    def within_the_category_cap
+      return if category.nil? || amount.nil? || spent_on.nil?
+
+      remaining = category.remaining_for(user, spent_on.beginning_of_month)
+      return if remaining.nil? || amount <= remaining
+
+      errors.add(:amount, "is over the #{category.name} cap for #{spent_on.strftime('%B')} " \
+                          "— #{Money.format(remaining)} left")
+    end
+
+    def receipt_is_present_when_the_category_demands_one
+      return unless category&.receipt_required
+      return if receipt.attached?
+
+      errors.add(:receipt, "is required for #{category.name}")
+    end
+  end
+end

data/app/models/hr_lite/expense_category.rb

@@ -0,0 +1,33 @@
+module HrLite
+  # "Travel", "Client entertainment", "Home office" — with the cap and the
+  # receipt rule that go with each.
+  class ExpenseCategory < ApplicationRecord
+    include EncryptedMoney
+    include Audited
+
+    encrypted_money :monthly_cap
+
+    has_many :expenses, class_name: "HrLite::Expense", foreign_key: :category_id,
+                        dependent: :restrict_with_error
+
+    validates :name, presence: true, uniqueness: { case_sensitive: false }
+
+    scope :active, -> { where(active: true) }
+    scope :alphabetical, -> { order(:name) }
+
+    def uncapped? = monthly_cap.nil?
+
+    # What is left of this month's cap for one person, or nil when uncapped.
+    # Counts everything not refused: a claim awaiting a decision has still
+    # been spent against the cap.
+    def remaining_for(user, month = Date.current.beginning_of_month)
+      return nil if uncapped?
+
+      spent = expenses.where(user_id: user.id)
+                      .where(spent_on: month..month.end_of_month)
+                      .where.not(status: %w[rejected cancelled])
+                      .sum(BigDecimal(0)) { |e| e.amount || BigDecimal(0) }
+      [ monthly_cap - spent, BigDecimal(0) ].max
+    end
+  end
+end

data/app/models/hr_lite/hr_request.rb

@@ -0,0 +1,75 @@
+module HrLite
+  # "Can I have a salary certificate?" — the questions that were going to
+  # somebody's inbox and getting lost there.
+  class HrRequest < ApplicationRecord
+    include Audited
+
+    STATUSES = %w[open in_progress resolved closed cancelled].freeze
+
+    CATEGORIES = %w[
+      salary_certificate employment_certificate address_change bank_change
+      document_request payroll_query tax_query insurance_query policy_query other
+    ].freeze
+
+    belongs_to :user, class_name: HrLite.config.user_class
+    belongs_to :assigned_to, class_name: HrLite.config.user_class, optional: true
+
+    validates :subject, presence: true
+    validates :category, inclusion: { in: CATEGORIES }
+    validates :status, inclusion: { in: STATUSES }
+
+    scope :open_requests, -> { where(status: %w[open in_progress]) }
+    scope :recent_first, -> { order(created_at: :desc) }
+
+    STATUSES.each { |s| define_method("#{s}?") { status == s } }
+
+    after_create_commit :notify_desk
+
+    def category_label = category.humanize
+
+    def assign!(actor:, assignee:)
+      update!(assigned_to_id: assignee.id, status: "in_progress")
+      Notifications.publish(
+        "hr_request.assigned",
+        title: "#{category_label}: #{subject}",
+        body: "Assigned to you by #{HrLite.display_name(actor)}.",
+        path: "/admin/hr_requests/#{id}", bell_to: [ assignee ]
+      )
+      true
+    end
+
+    def resolve!(actor:, resolution:)
+      raise ArgumentError, "a resolution needs an answer" if resolution.blank?
+
+      update!(status: "resolved", resolution: resolution, resolved_at: Time.current,
+              assigned_to_id: assigned_to_id || actor.id)
+      Notifications.publish(
+        "hr_request.resolved",
+        title: "Your request was answered — #{subject}",
+        body: resolution, path: "/hr_requests/#{id}",
+        bell_to: [ user ], email_to: [ user ]
+      )
+      true
+    end
+
+    def cancel!(actor:)
+      raise ActiveRecord::RecordInvalid.new(self), "already settled" unless open? || in_progress?
+
+      update!(status: "cancelled")
+      true
+    end
+
+    private
+
+    def notify_desk
+      desk = HrLite.users_holding("hr_request.manage").to_a
+      return if desk.empty?
+
+      Notifications.publish(
+        "hr_request.raised",
+        title: "#{HrLite.display_name(user)} asked: #{subject}",
+        body: body.presence, path: "/admin/hr_requests/#{id}", bell_to: desk
+      )
+    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