hr_lite 0.11.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 655b4d27557dace6262528eb82af6912b4b7dfcdc3ff6b8274068876b8bb970c
-  data.tar.gz: ba15eee422c61704681db9d8d1194851f8c761459524844ade6e4cd054776f81
+  metadata.gz: 8202157b6f35309884c9df17895d711553e114a57925c8c2e381e51a7be863ba
+  data.tar.gz: 3cb55e413c6bcc70bd3aa39a5c212690a21c9cf747b17bfdf5894ef6d73945de
 SHA512:
-  metadata.gz: 4b4224f36f2cd4b3c256d440e6f439f59ce86e61436545f4f5a1afab97d827c64db86b4ee3b21f72003ea8864010b0369d6a719cd833a7194855adc1af10602c
-  data.tar.gz: 3de774d902610ab761c5794fe4f9eec3c404dac26ccf0fbea553bfe6bafe09e45c576e8264b07c70b6eef07af3f93f54c88aa43d3fd149921d4726456823a890
+  metadata.gz: 0ddf504c20a84c58a712fd4efe695e9b90b27eea8acc8883bfb37d33df398778169c35eb2c11f37830e91c9ceec63560df57c631246b2b22381b52df5ce30144
+  data.tar.gz: 4a724d4a55068129237e010aca71ce94c392656bb56953a6f1ec5329ddf5d33b6ffd91f76c82229a152f85d134a60ca29308634133f0a3a72779cff3cc6dafdb

data/CHANGELOG.md

@@ -7,6 +7,74 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.13.0] - 2026-08-18
+
+The screens. No migration.
+
+### Added
+
+- **Employee self-service for everything built since 0.11.0**: claim an
+  expense (with what is left of each cap shown before you type an amount),
+  see what you are covered for, read and acknowledge a policy, ask HR a
+  question and read the answer.
+- **A reports hub** — headcount, joiners and leavers, leave balances,
+  attendance and expenses — each with a CSV download, and each **scoped by
+  the same permission that guards the screen its data comes from**. A report
+  is not a side door into rows somebody cannot otherwise reach: a manager's
+  headcount is their own team. The hub lists only the reports the reader can
+  actually open, since a list of links that turn you away is worse than a
+  short list.
+- CSV downloads are audited, the same way the payout register is.
+
+### Fixed
+
+- **The reports hub locked Finance out of the expense report.** It inherited
+  the operations gate, and Finance approves expenses but runs none of the
+  operations screens. Found by writing the spec for it.
+
+### Changed
+
+- `.hrl-prose` for long-form policy text, capped at 68 characters a line — a
+  policy read across the full width of a laptop is a policy nobody finishes.
+- The demo sandbox seeds an expense claim, a benefit enrolment, a policy
+  awaiting acknowledgement and an open HR request, so the new screens have
+  something on them at first boot.
+
+## [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
@@ -694,7 +762,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.11.0...HEAD
+[Unreleased]: https://github.com/kshtzkr/hr_lite/compare/v0.13.0...HEAD
+[0.13.0]: https://github.com/kshtzkr/hr_lite/compare/v0.12.0...v0.13.0
+[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

data/app/assets/stylesheets/hr_lite/hr_lite.css

@@ -318,3 +318,9 @@
 .hrl-mt { margin-top: .85rem; }
 .hrl-right { margin-left: auto; }
 .hrl-row { display: flex; align-items: center; gap: .6rem; flex-wrap: wrap; }
+
+/* Long-form policy text. Constrained measure — a policy read across the
+   full width of a laptop is a policy nobody finishes. */
+.hrl-prose { max-width: 68ch; }
+.hrl-prose p { margin: 0 0 .8rem; line-height: 1.6; }
+.hrl-prose p:last-child { margin-bottom: 0; }

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

@@ -0,0 +1,151 @@
+module HrLite
+  module Admin
+    # The numbers somebody asks for at the end of a month, and the CSV they
+    # ask for straight afterwards.
+    #
+    # Every report is scoped by the SAME permission that guards the screens
+    # its data comes from — a report is not a side door into rows somebody
+    # cannot otherwise reach.
+    class ReportsController < BaseController
+      # Finance can approve expenses but runs none of the operations screens,
+      # so the operations gate would have shut them out of their own expense
+      # report. The hub is reachable by anybody who can see AT LEAST ONE
+      # report; each report then checks its own permission.
+      skip_before_action :require_operations_access!
+      before_action :require_any_report!
+
+      REPORTS = {
+        "headcount" => "Headcount by department",
+        "joiners_and_leavers" => "Joiners and leavers",
+        "leave_balances" => "Leave balances",
+        "attendance" => "Attendance summary",
+        "expenses" => "Expense claims"
+      }.freeze
+
+      def index
+        # Only the reports this person could actually open — a list of links
+        # that turn you away is worse than a shorter list.
+        @reports = REPORTS.select { |name, _| permitted?(name) }
+        @month = parse_month_param(params[:month])
+      end
+
+      def show
+        @month = parse_month_param(params[:month])
+        @name = params[:id]
+        return hr_access_denied unless REPORTS.key?(@name)
+        return hr_access_denied unless permitted?(@name)
+
+        @rows = rows_for(@name)
+        respond_to do |format|
+          format.html
+          format.csv do
+            AuditLog.record!(action: "report.exported", subject: hr_current_user,
+                             actor: hr_current_user,
+                             changes: { "report" => @name, "rows" => @rows.size,
+                                        "month" => @month.strftime("%Y-%m") })
+            send_data to_csv(@rows), filename: "#{@name}-#{@month.strftime('%Y-%m')}.csv",
+                                     type: "text/csv"
+          end
+        end
+      end
+
+      private
+
+      def require_any_report!
+        hr_access_denied if REPORTS.keys.none? { |name| permitted?(name) }
+      end
+
+      # A report reaches exactly as far as the screen it summarises.
+      def permitted?(name)
+        case name
+        when "expenses" then hr_can?("expense.approve", scope: :all)
+        when "leave_balances" then hr_can?("leave.view", scope: :team)
+        when "attendance" then hr_can?("attendance.view", scope: :team)
+        else hr_can?("profile.view", scope: :team)
+        end
+      end
+
+      def visible_users
+        ids = hr_access.visible_user_ids("profile.view")
+        employees = HrLite.employees
+        ids.nil? ? employees : employees.select { |user| ids.include?(user.id) }
+      end
+
+      def rows_for(name)
+        case name
+        when "headcount" then headcount_rows
+        when "joiners_and_leavers" then joiners_and_leavers_rows
+        when "leave_balances" then leave_balance_rows
+        when "attendance" then attendance_rows
+        when "expenses" then expense_rows
+        end
+      end
+
+      def headcount_rows
+        profiles = EmployeeProfile.where(user_id: visible_users.map(&:id))
+                                  .active_for(@month)
+        profiles.group_by { |p| p.department.presence || "Unassigned" }
+                .sort_by(&:first)
+                .map { |department, rows| { "Department" => department, "People" => rows.size } }
+      end
+
+      def joiners_and_leavers_rows
+        window = @month..@month.end_of_month
+        EmployeeProfile.where(user_id: visible_users.map(&:id))
+                       .where("date_of_joining BETWEEN ? AND ? OR date_of_exit BETWEEN ? AND ?",
+                              window.first, window.last, window.first, window.last)
+                       .includes(:user)
+                       .map do |profile|
+          { "Employee" => HrLite.display_name(profile.user),
+            "Department" => profile.department,
+            "Joined" => profile.date_of_joining&.to_s,
+            "Left" => profile.date_of_exit&.to_s }
+        end
+      end
+
+      def leave_balance_rows
+        year = LeaveYear.key_for(@month)
+        types = LeaveType.active.where(paid: true).where.not(annual_quota: nil)
+        visible_users.flat_map do |user|
+          types.map do |type|
+            balance = LeaveBalance.for(user, type, year)
+            { "Employee" => HrLite.display_name(user), "Type" => type.code,
+              "Entitled" => balance.entitled.to_f, "Used" => balance.used.to_f,
+              "Available" => balance.available.to_f }
+          end
+        end
+      end
+
+      def attendance_rows
+        visible_users.map do |user|
+          summary = AttendanceSummary.for(user: user, month: @month)
+          { "Employee" => HrLite.display_name(user),
+            "Payable days" => summary[:payable_days].to_f,
+            "LOP" => summary[:lop_days].to_f,
+            "Days in month" => summary[:days_in_month] }
+        end
+      end
+
+      def expense_rows
+        Expense.where(spent_on: @month..@month.end_of_month)
+               .includes(:user, :category).recent_first.map do |expense|
+          { "Employee" => HrLite.display_name(expense.user),
+            "Category" => expense.category.name,
+            "Spent on" => expense.spent_on.to_s,
+            "Amount" => expense.amount.to_s("F"),
+            "Status" => expense.status }
+        end
+      end
+
+      def to_csv(rows)
+        require "csv"
+        return "" if rows.empty?
+
+        CSV.generate do |csv|
+          csv << rows.first.keys
+          rows.each { |row| csv << row.values }
+        end
+      end
+    end
+  end
+end

data/app/controllers/hr_lite/benefits_controller.rb

@@ -0,0 +1,17 @@
+module HrLite
+  # What the signed-in person is actually covered for — previously something
+  # you had to email somebody to find out.
+  class BenefitsController < ApplicationController
+    before_action :require_viewing!
+
+    def index
+      @enrolments = BenefitEnrolment.live_on(Date.current)
+                                    .where(user_id: hr_current_user.id)
+                                    .includes(:benefit)
+    end
+
+    private
+
+    def require_viewing! = hr_require_permission!("benefit.view")
+  end
+end

data/app/controllers/hr_lite/expenses_controller.rb

@@ -0,0 +1,50 @@
+module HrLite
+  # An employee's own claims. Scoped to the signed-in person the same way
+  # every other self-service screen is: a foreign id 404s through the
+  # relation rather than 403ing.
+  class ExpensesController < ApplicationController
+    before_action :require_claiming!
+
+    def index
+      @expenses = paginate(own.includes(:category).recent_first)
+      @categories = ExpenseCategory.active.alphabetical
+    end
+
+    def new
+      @expense = Expense.new(spent_on: Date.current)
+      @categories = ExpenseCategory.active.alphabetical
+    end
+
+    def create
+      @expense = Expense.new(expense_params.merge(user_id: hr_current_user.id))
+      if @expense.save
+        @expense.submit!(actor: hr_current_user)
+        redirect_to expenses_path, notice: "Claim submitted."
+      else
+        @categories = ExpenseCategory.active.alphabetical
+        render :new, status: :unprocessable_entity
+      end
+    end
+
+    def cancel
+      expense = own.find(params[:id])
+      if expense.draft? || expense.submitted?
+        expense.update!(status: "cancelled")
+        expense.approval_route.cancel_all!
+        redirect_to expenses_path, notice: "Claim withdrawn."
+      else
+        redirect_to expenses_path, alert: "Only a claim still waiting can be withdrawn."
+      end
+    end
+
+    private
+
+    def require_claiming! = hr_require_permission!("expense.claim")
+
+    def own = Expense.where(user_id: hr_current_user.id)
+
+    def expense_params
+      params.require(:expense).permit(:category_id, :amount, :spent_on, :description, :receipt)
+    end
+  end
+end

data/app/controllers/hr_lite/hr_requests_controller.rb

@@ -0,0 +1,43 @@
+module HrLite
+  # The employee's side of the help desk.
+  class HrRequestsController < ApplicationController
+    before_action :require_raising!
+
+    def index
+      @requests = paginate(own.recent_first)
+    end
+
+    def show
+      @request = own.find(params[:id])
+    end
+
+    def new
+      @request = HrRequest.new
+    end
+
+    def create
+      @request = HrRequest.new(request_params.merge(user_id: hr_current_user.id))
+      if @request.save
+        redirect_to hr_requests_path, notice: "Sent to HR."
+      else
+        render :new, status: :unprocessable_entity
+      end
+    end
+
+    def cancel
+      request = own.find(params[:id])
+      request.cancel!(actor: hr_current_user)
+      redirect_to hr_requests_path, notice: "Request withdrawn."
+    rescue ActiveRecord::RecordInvalid
+      redirect_to hr_requests_path, alert: "That request has already been answered."
+    end
+
+    private
+
+    def require_raising! = hr_require_permission!("hr_request.raise")
+
+    def own = HrRequest.where(user_id: hr_current_user.id)
+
+    def request_params = params.require(:hr_request).permit(:category, :subject, :body)
+  end
+end

data/app/controllers/hr_lite/policies_controller.rb

@@ -0,0 +1,26 @@
+module HrLite
+  # What people are held to, and the button that says they have read it.
+  class PoliciesController < ApplicationController
+    before_action :require_reading!
+
+    def index
+      @policies = Policy.current.sort_by(&:title)
+      @acknowledged = PolicyAcknowledgement.where(user_id: hr_current_user.id)
+                                           .pluck(:policy_id).to_set
+    end
+
+    def show
+      @policy = Policy.published.find(params[:id])
+    end
+
+    def acknowledge
+      policy = Policy.published.find(params[:id])
+      policy.acknowledge!(hr_current_user)
+      redirect_to policies_path, notice: "Thank you — recorded against #{policy.title} v#{policy.version}."
+    end
+
+    private
+
+    def require_reading! = hr_require_permission!("policy.view", scope: :all)
+  end
+end

data/app/helpers/hr_lite/application_helper.rb

@@ -12,6 +12,10 @@ module HrLite
       # 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: "Expenses",   path: :expenses_path,       match: [ "/expenses" ] },
+      { label: "Benefits",   path: :benefits_path,       match: [ "/benefits" ] },
+      { label: "Policies",   path: :policies_path,       match: [ "/policies" ] },
+      { label: "Ask HR",     path: :hr_requests_path,    match: [ "/hr_requests" ] },
       { label: "Org",        path: :org_path,            match: [ "/org" ] },
       { label: "Kudos",      path: :kudos_path,          match: [ "/kudos" ] },
       { label: "Slips",      path: :salary_slips_path,   match: [ "/salary_slips" ] },
@@ -21,7 +25,8 @@ module HrLite
     ADMIN_NAV_ITEMS = [
       { label: "Overview",        path: :admin_overview_path,        match: [ "/admin/overview" ] },
       { label: "Team attendance", path: :admin_attendances_path,     match: [ "/admin/attendances" ] },
-      { label: "Approvals",       path: :admin_leave_requests_path,  match: [ "/admin/leave_requests", "/admin/leave_balances", "/admin/comp_off_requests", "/admin/regularization_requests" ] }
+      { label: "Approvals",       path: :admin_leave_requests_path,  match: [ "/admin/leave_requests", "/admin/leave_balances", "/admin/comp_off_requests", "/admin/regularization_requests" ] },
+      { label: "Reports",         path: :admin_reports_path,         match: [ "/admin/reports" ] }
     ].freeze
 
     LEADERSHIP_NAV_ITEMS = [

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/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