hr_lite 0.8.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ddcf4d252c3b0830d1b345dd44f63dc997cab9db77a408249cd8940ad2256c1
-  data.tar.gz: d525ae88d6a0b5c12ca68caff325bb655cd2ff7dfa0ac9afb7f178cbc8d362de
+  metadata.gz: 655b4d27557dace6262528eb82af6912b4b7dfcdc3ff6b8274068876b8bb970c
+  data.tar.gz: ba15eee422c61704681db9d8d1194851f8c761459524844ade6e4cd054776f81
 SHA512:
-  metadata.gz: 155c04f716bbf5907b17ce1dd86c06f44de4f3f8021afda1e2ed3570db8cf14aed2373db7791d4c65441e96b6d4e0318faeb8dc1116b35bea235ed4cb31775d8
-  data.tar.gz: be25c7f77087ae53dccb3e991167cc78282de562c5ef9f12739db9bc2bece99ad8b1e743577dc21d3aeb935cd1ca270ae64652bd036459c8c704b438db1ed8c0
+  metadata.gz: 4b4224f36f2cd4b3c256d440e6f439f59ce86e61436545f4f5a1afab97d827c64db86b4ee3b21f72003ea8864010b0369d6a719cd833a7194855adc1af10602c
+  data.tar.gz: 3de774d902610ab761c5794fe4f9eec3c404dac26ccf0fbea553bfe6bafe09e45c576e8264b07c70b6eef07af3f93f54c88aa43d3fd149921d4726456823a890

data/CHANGELOG.md

@@ -7,6 +7,151 @@ 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,
+delegations). Nothing changes for a module until a flow is configured for it,
+which is what lets the four existing ones migrate one at a time.
+
+### Fixed
+
+- **Cancelling a leave request left its approval sitting in somebody's
+  inbox.** Found by the coverage floor, which flagged `cancel_all!` as
+  unreachable — it was written and never called.
+
+### Added
+
+- `HrLite::ApprovalFlow` / `ApprovalStep` / `Approval` / `ApprovalDelegation`.
+  A flow is "leave needs the manager, then HR". A step names its approver by
+  RULE — manager, manager's manager, anyone holding a permission, or one named
+  person — so a flow survives somebody leaving; the rule resolves against the
+  subject when the request is raised.
+- Multi-level, sequential routing, with a `unanimous` step for the rungs where
+  everybody has to answer rather than the first person to look.
+- **A rung nobody occupies is skipped**, not left waiting. An employee with no
+  manager recorded would otherwise have a request no living person could
+  decide.
+- **Delegation.** "I am away until the 14th — Priya decides for me." The
+  approval does not move; a stand-in may answer it, and the row records both
+  who it was addressed to and who actually decided. Two hops, so a stand-in
+  who is also away is covered, and a loop cannot hand somebody their own
+  approvals back.
+- **SLA and escalation.** A step may carry a deadline; `ApprovalEscalationJob`
+  tells an approver once per overdue row, grouped into one message per person,
+  and stamps the rows so a daily run does not nag daily. Escalation TELLS
+  somebody — it does not reassign, because a decision made by somebody who
+  never saw the request is worse than a late one.
+- **One approval inbox** (`/approvals`) replacing four places to look. Employee
+  tier: holding an approval is the authorisation, so a manager, a stand-in and
+  a director reach the same screen and each sees only their own rows. It sits
+  after Calendar in the nav — the phone tab bar shows the first four, and this
+  screen is empty for anybody who is not an approver.
+- `HrLite::Approvable` — opts a model in WITHOUT taking over what its decisions
+  mean. `LeaveRequest` keeps its own `approve!`, including the balance lock;
+  the concern only answers "is it this person's turn, and does their answer
+  settle it". A settling decision runs the ordinary transition, so routing
+  never becomes a second path that can drift from the first.
+
+### Changed
+
+- `LeaveRequest` is the first module routed. With no flow it behaves exactly
+  as before, and somebody outside the current rung who holds `leave.approve`
+  at `all` can still settle it outright — the routed path is the normal one,
+  not the only one.
+- Branch-coverage floor 90.8% -> 90.3%, deliberately, with the arithmetic
+  written into `spec_helper.rb`: the engine added ~90 branches at once, and
+  holding the percentage would have meant contriving specs for untouched
+  files. Line coverage stayed at 100%.
+
+### Not yet
+
+- Comp-off, regularization and resignation still use their own single
+  decision. They are declared approvable and migrate next, one release each.
+
 ## [0.8.0] - 2026-08-18
 
 The deprecation 0.6.0 opened, closed. **Breaking** only for an install still
@@ -549,7 +694,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.8.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
 [0.6.0]: https://github.com/kshtzkr/hr_lite/compare/v0.5.3...v0.6.0

data/app/controllers/hr_lite/approvals_controller.rb

@@ -0,0 +1,31 @@
+module HrLite
+  # Everything waiting on the signed-in person, in one place. Before this,
+  # an approver had to visit four screens to find out whether anybody was
+  # waiting on them, and nothing told them if a request had gone stale.
+  #
+  # Employee tier on purpose: holding an approval IS the authorisation. A
+  # manager, a stand-in covering for one, and a director all reach the same
+  # screen and each sees only their own rows.
+  class ApprovalsController < ApplicationController
+    def index
+      @approvals = paginate(mine.includes(:step, :subject).order(:created_at))
+      @delegations = ApprovalDelegation.live_on(Date.current)
+                                       .where(from_user_id: hr_current_user.id)
+                                       .includes(:to_user)
+      @covering_for = ApprovalDelegation.live_on(Date.current)
+                                        .where(to_user_id: hr_current_user.id)
+                                        .includes(:from_user)
+    end
+
+    private
+
+    # Rows addressed to this person, plus rows belonging to anybody who has
+    # delegated to them while they are away.
+    def mine
+      standing_in_for = ApprovalDelegation.live_on(Date.current)
+                                          .where(to_user_id: hr_current_user.id)
+                                          .pluck(:from_user_id)
+      Approval.pending.where(approver_id: [ hr_current_user.id, *standing_in_for ])
+    end
+  end
+end

data/app/helpers/hr_lite/application_helper.rb

@@ -6,6 +6,12 @@ module HrLite
       { label: "Leaves",     path: :leave_requests_path, match: [ "/leave_requests", "/leave_balances", "/comp_off_requests" ] },
       { label: "Team",       path: :team_path,           match: [ "/team" ] },
       { label: "Calendar",   path: :calendar_path,       match: [ "/calendar", "/holidays" ] },
+      # After Calendar deliberately: the phone tab bar shows the first four
+      # and this screen is empty for everybody who is not an approver, so it
+      # belongs in "More" rather than displacing something everybody uses.
+      # Employee tier all the same — holding an approval IS the authorisation,
+      # so a manager and a stand-in covering for one reach the same screen.
+      { label: "Approvals",  path: :approvals_path,      match: [ "/approvals" ] },
       { label: "Org",        path: :org_path,            match: [ "/org" ] },
       { label: "Kudos",      path: :kudos_path,          match: [ "/kudos" ] },
       { label: "Slips",      path: :salary_slips_path,   match: [ "/salary_slips" ] },
@@ -71,6 +77,21 @@ module HrLite
       out.html_safe
     end
 
+    # Where an approval row actually leads. Each subject type has its own
+    # decision screen; the inbox only gathers them.
+    APPROVAL_PATHS = {
+      "HrLite::LeaveRequest" => :admin_leave_request_path,
+      "HrLite::CompOffRequest" => :admin_comp_off_request_path,
+      "HrLite::RegularizationRequest" => :admin_regularization_request_path
+    }.freeze
+
+    def hrl_approval_path(approval)
+      helper = APPROVAL_PATHS[approval.subject_type]
+      return nil unless helper && hr_lite_route?(helper)
+
+      hr_lite.public_send(helper, approval.subject_id)
+    end
+
     def hrl_pagination
       render "hr_lite/shared/pagination"
     end

data/app/jobs/hr_lite/approval_escalation_job.rb

@@ -0,0 +1,39 @@
+module HrLite
+  # Nudges approvals that have sat past their step's SLA. Escalation here
+  # means TELLING SOMEBODY, not reassigning: silently moving a decision to
+  # another person is how an approval ends up made by somebody who never saw
+  # the request.
+  #
+  # Each row is stamped once, so a daily run does not re-nag every day.
+  class ApprovalEscalationJob < ApplicationJob
+    def perform(now: Time.current)
+      overdue = Approval.pending.where(escalated_at: nil).includes(:step, :approver)
+                        .select { |approval| approval.overdue?(now) }
+      return if overdue.empty?
+
+      overdue.group_by(&:approver_id).each do |approver_id, rows|
+        approver = rows.first.approver
+        next if approver.nil?
+
+        Notifications.publish(
+          "approval.escalated",
+          title: "#{rows.size} approval#{'s' unless rows.size == 1} waiting on you past its deadline",
+          lines: rows.map { |row| "#{row.label} — waiting #{waited(row, now)}" },
+          path: "/approvals",
+          bell_to: [ approver ],
+          email_to: [ approver ],
+          leadership: { title: "#{HrLite.display_name(approver)} has #{rows.size} overdue approval#{'s' unless rows.size == 1}" }
+        )
+      end
+
+      Approval.where(id: overdue.map(&:id)).update_all(escalated_at: now) # rubocop:disable Rails/SkipsModelValidations
+    end
+
+    private
+
+    def waited(approval, now)
+      hours = ((now - approval.created_at) / 1.hour).floor
+      hours < 48 ? "#{hours}h" : "#{(hours / 24)} days"
+    end
+  end
+end

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/concerns/hr_lite/approvable.rb

@@ -0,0 +1,48 @@
+module HrLite
+  # Opts a model into the routed, multi-step approval flow — WITHOUT taking
+  # over what its decisions mean.
+  #
+  # The model keeps its own `approve!` / `reject!`: those are the domain
+  # actions, and for leave one of them credits a balance inside a row lock.
+  # This concern only asks "is it this person's turn, and does their answer
+  # settle it?" and hands back an outcome for the model to act on.
+  #
+  # A subject type with no active flow behaves exactly as it did before —
+  # single decision, whoever holds the permission. That is what lets the four
+  # existing modules migrate one at a time instead of all at once.
+  module Approvable
+    extend ActiveSupport::Concern
+
+    included do
+      has_many :approvals, as: :subject, class_name: "HrLite::Approval", dependent: :destroy
+      after_create_commit :open_approval_route
+    end
+
+    def approval_route = @approval_route ||= ApprovalRoute.new(self)
+
+    def routed_for_approval? = approval_route.routed?
+
+    # The rows still waiting, newest rung first — what the show screen lists.
+    def pending_approvals = approvals.pending.order(:position)
+
+    def approval_for(user)
+      return nil if user.nil?
+
+      pending_approvals.detect { |approval| approval.answerable_by?(user) }
+    end
+
+    # Whether this person is the one being waited on. Unrouted subjects fall
+    # back to the permission check the module already used.
+    def awaiting?(user) = approval_for(user).present?
+
+    # The whole story, for the approval screen: who decided what, in order,
+    # including the rungs that were skipped and why.
+    def approval_history = approvals.order(:position, :id)
+
+    private
+
+    def open_approval_route
+      approval_route.open! if approval_route.routed?
+    end
+  end
+end

data/app/models/hr_lite/approval.rb

@@ -0,0 +1,46 @@
+module HrLite
+  # One person's outstanding decision on one record. The row is the unit the
+  # inbox lists and the escalation job reads.
+  class Approval < ApplicationRecord
+    STATUSES = %w[pending approved rejected returned skipped cancelled].freeze
+
+    belongs_to :step, class_name: "HrLite::ApprovalStep"
+    belongs_to :subject, polymorphic: true
+    belongs_to :approver, class_name: HrLite.config.user_class
+    belongs_to :decided_by, class_name: HrLite.config.user_class, optional: true
+
+    validates :status, inclusion: { in: STATUSES }
+
+    scope :pending, -> { where(status: "pending") }
+    scope :at_position, ->(position) { where(position: position) }
+    scope :recent_first, -> { order(created_at: :desc) }
+
+    STATUSES.each { |s| define_method("#{s}?") { status == s } }
+
+    # Whether `user` may answer this — the approver themselves, or somebody
+    # they have delegated to while they are away.
+    def answerable_by?(user)
+      return false if user.nil? || !pending?
+
+      approver_id == user.id ||
+        ApprovalDelegation.stand_ins_for(approver_id).include?(user.id)
+    end
+
+    def decide!(status:, actor:, note: nil)
+      raise ArgumentError, "unknown decision #{status}" unless STATUSES.include?(status.to_s)
+
+      update!(status: status.to_s, note: note.presence, decided_at: Time.current,
+              decided_by_id: actor&.id)
+    end
+
+    # True once this row's SLA has run out. Computed rather than stored so
+    # editing a step's SLA takes effect on the rows already waiting.
+    def overdue?(now = Time.current)
+      return false unless pending? && step.sla_hours
+
+      created_at + step.sla_hours.hours <= now
+    end
+
+    def label = "#{subject_type.demodulize.underscore.humanize} ##{subject_id}"
+  end
+end

data/app/models/hr_lite/approval_delegation.rb

@@ -0,0 +1,38 @@
+module HrLite
+  # "I am away until the 14th — Priya decides for me." Delegation does not
+  # move the approval; it lets somebody else answer it, and the row records
+  # who actually did.
+  class ApprovalDelegation < ApplicationRecord
+    include Audited
+
+    belongs_to :from_user, class_name: HrLite.config.user_class
+    belongs_to :to_user, class_name: HrLite.config.user_class
+
+    validates :starts_on, :ends_on, presence: true
+    validate :ends_after_it_starts
+    validate :not_to_themselves
+
+    scope :live_on, ->(date) { where(starts_on: ..date).where(ends_on: date..) }
+
+    # Who may answer on `user`'s behalf today, including a chain of two —
+    # A delegates to B, B is also away and delegates to C. Capped at two
+    # hops: past that it is quicker to reassign the flow than to follow it.
+    def self.stand_ins_for(user_id, on: Date.current)
+      first = live_on(on).where(from_user_id: user_id).pluck(:to_user_id)
+      second = live_on(on).where(from_user_id: first).pluck(:to_user_id)
+      (first + second - [ user_id ]).uniq
+    end
+
+    private
+
+    def ends_after_it_starts
+      return unless starts_on && ends_on
+
+      errors.add(:ends_on, "must be on or after the start date") if ends_on < starts_on
+    end
+
+    def not_to_themselves
+      errors.add(:to_user_id, "cannot be the person delegating") if from_user_id == to_user_id
+    end
+  end
+end

data/app/models/hr_lite/approval_flow.rb

@@ -0,0 +1,39 @@
+module HrLite
+  # "Leave needs the manager, then HR." One active flow per subject type;
+  # a type with no flow keeps whatever single-decision behaviour it had.
+  class ApprovalFlow < ApplicationRecord
+    include Audited
+
+    has_many :approval_steps, -> { order(:position) },
+             class_name: "HrLite::ApprovalStep", foreign_key: :flow_id, dependent: :destroy
+    accepts_nested_attributes_for :approval_steps, allow_destroy: true
+
+    validates :subject_type, :name, presence: true
+    validate :subject_type_is_approvable
+
+    scope :active, -> { where(active: true) }
+
+    def self.for(subject_type)
+      active.find_by(subject_type: subject_type.to_s)
+    end
+
+    # Subject types that have opted in. Declared rather than derived so a
+    # flow cannot be pointed at a model that has no idea it is approvable.
+    def self.approvable_types
+      %w[
+        HrLite::LeaveRequest HrLite::CompOffRequest
+        HrLite::RegularizationRequest HrLite::Resignation
+      ].freeze
+    end
+
+    def subject_label = subject_type.demodulize.underscore.humanize
+
+    private
+
+    def subject_type_is_approvable
+      return if self.class.approvable_types.include?(subject_type)
+
+      errors.add(:subject_type, "is not a type this engine can route for approval")
+    end
+  end
+end

data/app/models/hr_lite/approval_step.rb

@@ -0,0 +1,62 @@
+module HrLite
+  # One rung. The approver is named by RULE, not by person, so a flow
+  # survives somebody leaving the company — the rule is resolved against the
+  # subject at the moment the request is raised.
+  class ApprovalStep < ApplicationRecord
+    RULES = %w[manager manager_of_manager permission user].freeze
+
+    belongs_to :flow, class_name: "HrLite::ApprovalFlow"
+
+    validates :position, presence: true, uniqueness: { scope: :flow_id }
+    validates :approver_rule, inclusion: { in: RULES }
+    validates :sla_hours, numericality: { greater_than: 0 }, allow_nil: true
+    validate :approver_key_matches_the_rule
+
+    scope :ordered, -> { order(:position) }
+
+    # Everybody who must (or may) decide this rung for `subject`. Empty means
+    # nobody fits — `ApprovalRoute` treats that as a rung to skip rather than
+    # a request nobody can ever answer.
+    # Array(...) rather than an `else` arm: `approver_rule` is held to the
+    # four RULES by a validation AND a database check constraint, so an
+    # unmatched `case` cannot happen — and a defensive branch nothing can
+    # reach is a line that never gets tested and quietly rots.
+    def approvers_for(subject)
+      Array(
+        case approver_rule
+        when "manager" then manager_of(subject.user_id)
+        when "manager_of_manager" then manager_of(manager_of(subject.user_id)&.id)
+        when "permission" then HrLite.users_holding(approver_key, scope: :all).to_a
+        when "user" then HrLite.user_klass.find_by(id: approver_key)
+        end
+      )
+    end
+
+    def label
+      case approver_rule
+      when "manager" then "Their manager"
+      when "manager_of_manager" then "Their manager's manager"
+      when "permission" then "Anyone who can #{Permissions.description(approver_key).downcase}"
+      when "user" then HrLite.display_name(HrLite.user_klass.find_by(id: approver_key))
+      end
+    end
+
+    private
+
+    def manager_of(user_id)
+      return nil if user_id.nil?
+
+      manager_id = EmployeeProfile.where(user_id: user_id).pick(:manager_id)
+      manager_id && HrLite.user_klass.find_by(id: manager_id)
+    end
+
+    def approver_key_matches_the_rule
+      case approver_rule
+      when "permission"
+        errors.add(:approver_key, "must be a known permission") unless Permissions.valid?(approver_key.to_s)
+      when "user"
+        errors.add(:approver_key, "must name a user") if approver_key.blank?
+      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