hr_lite 0.2.1 → 0.4.0

data/app/models/hr_lite/comp_off_request.rb

@@ -0,0 +1,177 @@
+module HrLite
+  # "I worked on a weekend/holiday — credit me a day off." Approval credits
+  # the comp-off leave type's balance (an adjustment, so it shows up in the
+  # normal balance chips and can be spent through the ordinary leave flow).
+  class CompOffRequest < ApplicationRecord
+    STATUSES = %w[pending approved rejected cancelled].freeze
+
+    belongs_to :user, class_name: HrLite.config.user_class
+    belongs_to :decided_by, class_name: HrLite.config.user_class, optional: true
+
+    validates :date_worked, :reason, presence: true
+    validates :status, inclusion: { in: STATUSES }
+
+    with_options on: :create do
+      validate :date_not_in_future
+      validate :date_was_an_off_day
+      validate :no_duplicate_for_date
+    end
+
+    after_create :notify_requested
+
+    scope :pending, -> { where(status: "pending") }
+    scope :recent_first, -> { order(date_worked: :desc, id: :desc) }
+
+    STATUSES.each do |s|
+      define_method("#{s}?") { status == s }
+    end
+
+    def credit_days
+      half_day ? BigDecimal("0.5") : BigDecimal("1")
+    end
+
+    # Shown to the approver: proof the person actually punched that day.
+    def punch
+      AttendanceRecord.find_by(user_id: user_id, date: date_worked)
+    end
+
+    # --- transitions -------------------------------------------------------
+
+    # Credits the comp-off balance inside the row lock, so a double-tap
+    # cannot credit twice. Fails loudly when no comp-off type is configured
+    # or the day stopped being an off day (holiday edited away).
+    def approve!(actor:, note: nil)
+      type = LeaveType.comp_off_type
+      raise MissingCompOffType if type.nil?
+
+      transition!("approved", actor, note) do
+        raise StaleOffDay if WorkingCalendar.new(date_worked..date_worked).working_day?(date_worked)
+
+        # (A duplicate live request for the same date cannot exist — the
+        # partial unique index on [user_id, date_worked] guarantees it.)
+        credit_balance!(type)
+      end
+
+      Notifications.publish(
+        "comp_off.approved",
+        title: "Comp-off approved — #{credit_days.to_f} day#{'s' if credit_days > 1} credited for #{date_worked.strftime('%d %b')}",
+        body: decision_note.presence,
+        path: "/comp_off_requests",
+        bell_to: [ user ], email_to: [ user ]
+      )
+      true
+    end
+
+    def reject!(actor:, note:)
+      transition!("rejected", actor, note)
+      Notifications.publish(
+        "comp_off.rejected",
+        title: "Comp-off rejected — #{date_worked.strftime('%d %b')}",
+        body: decision_note.presence,
+        path: "/comp_off_requests",
+        bell_to: [ user ], email_to: [ user ]
+      )
+      true
+    end
+
+    def cancel!(actor:)
+      transition!("cancelled", actor, nil)
+      Notifications.publish(
+        "comp_off.cancelled",
+        title: "#{HrLite.display_name(user)} cancelled a comp-off request (#{date_worked.strftime('%d %b')})",
+        path: "/admin/comp_off_requests",
+        bell_to: HrLite.admin_users
+      )
+      true
+    end
+
+    class MissingCompOffType < StandardError
+      def message
+        "No active leave type is marked as comp-off — enable one under Settings → Leave types first."
+      end
+    end
+
+    class StaleOffDay < StandardError
+      def message
+        "That date is now a regular working day (the calendar changed since the request) — " \
+          "reject it and ask them to re-file if it still applies."
+      end
+    end
+
+    private
+
+    # The credit goes into the leave year it can actually be SPENT (the
+    # current one at approval time) — crediting date_worked's leave year
+    # would strand a year-end day approved after rollover on a dead
+    # balance. The balance row is locked for the increment; two admins
+    # approving two different requests for one person cannot lose an update.
+    def credit_balance!(type)
+      year = LeaveYear.current_key
+      balance = LeaveBalance.for(user, type, year)
+      if balance.new_record?
+        begin
+          balance.save!
+        rescue ActiveRecord::RecordNotUnique
+          balance = LeaveBalance.for(user, type, year)
+        end
+      end
+      balance.with_lock do
+        balance.adjustment += credit_days
+        balance.adjustment_note = [ balance.adjustment_note.presence,
+                                    "+#{credit_days.to_f} comp-off for #{date_worked} (request ##{id})" ].compact.join("; ")
+        balance.save!
+      end
+    end
+
+    def transition!(new_status, actor, note)
+      with_lock do
+        raise ActiveRecord::RecordInvalid.new(self), "not pending" unless pending?
+
+        yield if block_given?
+        self.status = new_status
+        self.decided_by_id = actor.id
+        self.decided_at = Time.current
+        self.decision_note = note
+        save!
+      end
+    end
+
+    def date_not_in_future
+      return unless date_worked
+
+      errors.add(:date_worked, "cannot be in the future") if date_worked > Date.current
+    end
+
+    # Comp-off is for working on a day you were NOT supposed to — a weekend
+    # or a holiday (per the company calendar). Extra hours on a working day
+    # are not comp-off under the policy.
+    def date_was_an_off_day
+      return unless date_worked
+      return if date_worked > Date.current
+
+      calendar = WorkingCalendar.new(date_worked..date_worked)
+      if calendar.working_day?(date_worked)
+        errors.add(:date_worked, "was a regular working day — comp-off is for working on a weekend or holiday")
+      end
+    end
+
+    def no_duplicate_for_date
+      return unless date_worked
+
+      clash = self.class.where(user_id: user_id, date_worked: date_worked,
+                               status: %w[pending approved]).where.not(id: id)
+      errors.add(:date_worked, "already has a comp-off request") if clash.exists?
+    end
+
+    def notify_requested
+      Notifications.publish(
+        "comp_off.requested",
+        title: "#{HrLite.display_name(user)} requested comp-off for #{date_worked.strftime('%d %b')} " \
+               "(#{half_day ? 'half' : 'full'} day)",
+        body: reason.presence,
+        path: "/admin/comp_off_requests/#{id}",
+        bell_to: HrLite.admin_users
+      )
+    end
+  end
+end

data/app/models/hr_lite/employee_profile.rb

@@ -8,6 +8,9 @@ module HrLite
     include Audited
 
     belongs_to :user, class_name: HrLite.config.user_class
+    # Reporting line (L1). Optional; the org chart treats manager-less
+    # profiles as roots (founders/directors).
+    belongs_to :manager, class_name: HrLite.config.user_class, optional: true
 
     encrypts :pan_number, :pf_uan, :esi_number, :bank_account_number, :bank_ifsc
     encrypted_money :declared_annual_deductions
@@ -28,6 +31,8 @@ module HrLite
                           allow_blank: true
     validates :pf_uan, format: { with: /\A\d{12}\z/, message: "must be 12 digits" }, allow_blank: true
     validate :exit_after_joining
+    validate :manager_chain_acyclic
+    validate :manager_is_active_staff, if: :manager_id_changed?
 
     scope :active_for, ->(month) {
       where(date_of_joining: ..month.end_of_month)
@@ -44,6 +49,31 @@ module HrLite
       from <= to ? (from..to) : nil
     end
 
+    # The manager as shown to the employee — an exited manager reads as
+    # "no manager" until leadership reassigns (matches the org chart).
+    def active_manager
+      return nil if manager.nil?
+
+      boss_exit = EmployeeProfile.where(user_id: manager_id).pick(:date_of_exit)
+      boss_exit && boss_exit < Date.current ? nil : manager
+    end
+
+    # [L1 user, L2 user, ...] walking manager_id upward. Cycle-safe.
+    def reporting_chain
+      chain = []
+      seen = { user_id => true }
+      current = manager_id
+      while current && !seen[current]
+        seen[current] = true
+        boss = HrLite.user_klass.find_by(id: current)
+        break if boss.nil?
+
+        chain << boss
+        current = EmployeeProfile.where(user_id: boss.id).pick(:manager_id)
+      end
+      chain
+    end
+
     def masked_pan
       mask_middle(pan_number)
     end
@@ -59,6 +89,31 @@ module HrLite
 
     private
 
+    # A newly-assigned manager must be a real, still-employed staff member.
+    def manager_is_active_staff
+      return if manager_id.nil?
+      return errors.add(:manager_id, "is not a staff account") if HrLite.user_klass.find_by(id: manager_id).nil?
+
+      boss_exit = EmployeeProfile.where(user_id: manager_id).pick(:date_of_exit)
+      errors.add(:manager_id, "has already exited") if boss_exit && boss_exit < Date.current
+    end
+
+    # Walking up from the proposed manager must never reach this person.
+    def manager_chain_acyclic
+      return if manager_id.nil?
+      return errors.add(:manager_id, "cannot be yourself") if manager_id == user_id
+
+      seen = {}
+      current = manager_id
+      while current
+        return errors.add(:manager_id, "creates a reporting loop") if current == user_id
+        break if seen[current]
+
+        seen[current] = true
+        current = EmployeeProfile.where(user_id: current).pick(:manager_id)
+      end
+    end
+
     def mask_middle(value)
       return nil if value.blank?
       return "•" * value.length if value.length <= 4

data/app/models/hr_lite/leave_balance.rb

@@ -3,6 +3,11 @@ module HrLite
   # entitlement accrues as a pure function of the policy and `used` is
   # recomputed live from approved requests — so a holiday added after an
   # approval self-heals both the quota and payroll.
+  #
+  # `year` is a LeaveYear key (calendar year by default; with
+  # config.leave_year_start_month = 7, key 2026 = Jul 2026 – Jun 2027).
+  # Entitlement prorates from the joining date, Keka-style: joined on or
+  # before the 15th → that month counts; after the 15th → from next month.
   class LeaveBalance < ApplicationRecord
     belongs_to :user, class_name: HrLite.config.user_class
     belongs_to :leave_type
@@ -17,26 +22,54 @@ module HrLite
     def entitled(as_of: Date.current)
       return Float::INFINITY if leave_type.unlimited?
 
-      quota = leave_type.annual_quota
-      base =
-        if leave_type.accrual == "monthly"
-          months = as_of.year == year ? as_of.month : (as_of.year > year ? 12 : 0)
-          ((quota / 12) * months).round(1)
-        else
-          quota
-        end
-      base + carried_forward + adjustment
+      (accrued_base(as_of) + carried_forward + adjustment).round(1)
     end
 
     def used
+      range = LeaveYear.range(year)
       requests = LeaveRequest.approved
                              .where(user_id: user_id, leave_type_id: leave_type_id)
-                             .where(start_date: Date.new(year, 1, 1)..Date.new(year, 12, 31))
+                             .where(start_date: range)
       requests.sum { |request| LeaveDayCounter.count(request) }
     end
 
     def available(as_of: Date.current)
       entitled(as_of: as_of) - used
     end
+
+    private
+
+    # Quota earned by as_of, before carry/adjustments. Monthly accrual
+    # drips quota/12 per month from the accrual start (leave-year start,
+    # or the prorated joining month for mid-year joiners); yearly_upfront
+    # grants all months from the accrual start to the year's end at once.
+    def accrued_base(as_of)
+      range = LeaveYear.range(year)
+      start = accrual_start(range)
+      return 0 if start.nil?
+
+      monthly_rate = leave_type.annual_quota / 12
+      months =
+        if leave_type.accrual == "monthly"
+          cap = [ as_of, range.last ].min
+          start > cap ? 0 : months_between(start, cap)
+        else
+          months_between(start, range.last)
+        end
+      monthly_rate * months
+    end
+
+    # nil when the person joins only after this leave year ends.
+    def accrual_start(range)
+      doj = EmployeeProfile.where(user_id: user_id).pick(:date_of_joining)
+      return range.first if doj.nil? || doj <= range.first
+
+      start = doj.day <= 15 ? doj.beginning_of_month : doj.next_month.beginning_of_month
+      start > range.last ? nil : start
+    end
+
+    def months_between(from, to)
+      (to.year * 12 + to.month) - (from.year * 12 + from.month) + 1
+    end
   end
 end

data/app/models/hr_lite/leave_request.rb

@@ -11,7 +11,7 @@ module HrLite
 
     with_options on: :create do
       validate :end_after_start
-      validate :same_calendar_year
+      validate :same_leave_year
       validate :half_day_single_day_only
       validate :consumes_at_least_half_a_day
       validate :no_overlap_with_own_requests
@@ -52,6 +52,7 @@ module HrLite
       return false if insufficient
 
       notify_decision("Leave approved")
+      notify_team
       true
     end
 
@@ -96,7 +97,7 @@ module HrLite
     end
 
     def balance
-      LeaveBalance.for(user, leave_type, start_date.year)
+      LeaveBalance.for(user, leave_type, LeaveYear.key_for(start_date))
     end
 
     private
@@ -132,6 +133,23 @@ module HrLite
       )
     end
 
+    # Everyone should know a colleague will be away — bell + email to the
+    # whole team (matrix row "leave.team_notice"; hosts can mute either
+    # channel). Deliberately excludes the reason: dates are team-relevant,
+    # the why is not.
+    def notify_team
+      team = HrLite.active_employees.reject { |member| member.id == user_id }
+      return if team.empty?
+
+      Notifications.publish(
+        "leave.team_notice",
+        title: "#{HrLite.display_name(user)} is on leave — #{leave_type.name} (#{date_range_label})",
+        path: "/team",
+        bell_to: team,
+        email_to: team
+      )
+    end
+
     def notify_decision(title)
       Notifications.publish(
         status == "approved" ? "leave.approved" : "leave.rejected",
@@ -154,11 +172,11 @@ module HrLite
       errors.add(:end_date, "must be on or after the start date") if end_date < start_date
     end
 
-    def same_calendar_year
+    def same_leave_year
       return unless start_date && end_date
 
-      if start_date.year != end_date.year
-        errors.add(:base, "Split requests at the year boundary")
+      if LeaveYear.key_for(start_date) != LeaveYear.key_for(end_date)
+        errors.add(:base, "Split requests at the leave-year boundary")
       end
     end
 

data/app/models/hr_lite/leave_type.rb

@@ -12,11 +12,28 @@ module HrLite
     validates :accrual, inclusion: { in: ACCRUALS }
     validates :annual_quota, numericality: { greater_than_or_equal_to: 0 }, allow_nil: true
     validates :carry_forward_cap, numericality: { greater_than_or_equal_to: 0 }
+    validate :single_comp_off_type
 
     scope :active, -> { where(active: true).order(:position, :id) }
 
+    # The type approved comp-off requests credit into (Settings marks it).
+    def self.comp_off_type
+      active.find_by(comp_off: true)
+    end
+
     def unlimited?
       annual_quota.nil?
     end
+
+    private
+
+    # Approvals credit into THE comp-off type — two flagged types would
+    # make the credit target position-order roulette.
+    def single_comp_off_type
+      return unless comp_off
+
+      clash = self.class.where(comp_off: true).where.not(id: id)
+      errors.add(:comp_off, "is already set on #{clash.first.name}") if clash.exists?
+    end
   end
 end

data/app/models/hr_lite/regularization_request.rb

@@ -0,0 +1,181 @@
+module HrLite
+  # "I forgot to punch — please fix that day." The employee proposes the
+  # times; an admin approves, which applies them to the attendance record
+  # with the full regularization audit trail (same fields the manual admin
+  # fix writes), or rejects with a note.
+  class RegularizationRequest < ApplicationRecord
+    STATUSES = %w[pending approved rejected cancelled].freeze
+
+    belongs_to :user, class_name: HrLite.config.user_class
+    belongs_to :decided_by, class_name: HrLite.config.user_class, optional: true
+
+    validates :date, :reason, presence: true
+    validates :status, inclusion: { in: STATUSES }
+
+    with_options on: :create do
+      validate :date_not_in_future
+      validate :at_least_one_time
+      validate :times_fall_on_date
+      validate :checkout_after_checkin
+      validate :no_duplicate_pending
+      validate :no_approved_leave_conflict
+    end
+
+    after_create :notify_requested
+
+    scope :pending, -> { where(status: "pending") }
+    scope :recent_first, -> { order(date: :desc, id: :desc) }
+
+    STATUSES.each do |s|
+      define_method("#{s}?") { status == s }
+    end
+
+    def times_label
+      [ check_in_at&.strftime("%H:%M"), check_out_at&.strftime("%H:%M") ].compact.join(" – ").presence || "—"
+    end
+
+    # Current punch state for the approver's context.
+    def punch
+      AttendanceRecord.find_by(user_id: user_id, date: date)
+    end
+
+    # --- transitions -------------------------------------------------------
+
+    # Applies the proposed times to the day's record (creating it if the
+    # person never punched at all). Only the provided times overwrite —
+    # a forgot-checkout ticket keeps the genuine GPS check-in untouched.
+    # A merge that would produce a nonsense record (checkout before the
+    # existing check-in, or a checkout with no check-in at all) raises
+    # InvalidMerge with the real story so the admin knows what to fix.
+    def approve!(actor:, note: nil)
+      transition!("approved", actor, note) do
+        record = AttendanceRecord.find_or_initialize_by(user_id: user_id, date: date)
+        record.check_in_at = check_in_at if check_in_at
+        record.check_out_at = check_out_at if check_out_at
+        if record.check_in_at.nil?
+          raise InvalidMerge, "the day has no check-in — the ticket needs a check-in time too"
+        end
+
+        record.status = "present" if record.status.blank?
+        record.regularized_by_id = actor.id
+        record.regularized_at = Time.current
+        record.regularization_note = "Ticket ##{id}: #{reason}"
+        raise InvalidMerge, record.errors.full_messages.to_sentence unless record.valid?
+
+        record.save!
+        AuditLog.create!(
+          actor: actor, action: "regularize",
+          subject_type: record.class.name, subject_id: record.id,
+          audited_changes: { "date" => record.date.to_s, "ticket" => id, "note" => reason }
+        )
+      end
+
+      Notifications.publish(
+        "regularization.approved",
+        title: "Attendance fixed for #{date.strftime('%d %b')} (#{times_label})",
+        body: decision_note.presence,
+        path: "/regularization_requests",
+        bell_to: [ user ], email_to: [ user ]
+      )
+      true
+    end
+
+    def reject!(actor:, note:)
+      transition!("rejected", actor, note)
+      Notifications.publish(
+        "regularization.rejected",
+        title: "Regularization rejected — #{date.strftime('%d %b')}",
+        body: decision_note.presence,
+        path: "/regularization_requests",
+        bell_to: [ user ], email_to: [ user ]
+      )
+      true
+    end
+
+    def cancel!(actor:)
+      transition!("cancelled", actor, nil)
+      Notifications.publish(
+        "regularization.cancelled",
+        title: "#{HrLite.display_name(user)} cancelled a regularization ticket (#{date.strftime('%d %b')})",
+        path: "/admin/regularization_requests",
+        bell_to: HrLite.admin_users
+      )
+      true
+    end
+
+    # The merged attendance record would be invalid — surfaced to the
+    # deciding admin verbatim; the ticket stays pending.
+    class InvalidMerge < StandardError; end
+
+    private
+
+    def transition!(new_status, actor, note)
+      with_lock do
+        raise ActiveRecord::RecordInvalid.new(self), "not pending" unless pending?
+
+        yield if block_given?
+        self.status = new_status
+        self.decided_by_id = actor.id
+        self.decided_at = Time.current
+        self.decision_note = note
+        save!
+      end
+    end
+
+    def date_not_in_future
+      return unless date
+
+      errors.add(:date, "cannot be in the future") if date > Date.current
+    end
+
+    def at_least_one_time
+      return if check_in_at || check_out_at
+
+      errors.add(:base, "Propose a check-in time, a check-out time, or both")
+    end
+
+    def times_fall_on_date
+      return unless date
+
+      [ [ :check_in_at, check_in_at ], [ :check_out_at, check_out_at ] ].each do |attr, time|
+        next unless time
+
+        errors.add(attr, "must be on #{date.strftime('%d %b')}") unless time.to_date == date
+      end
+    end
+
+    def checkout_after_checkin
+      return unless check_in_at && check_out_at
+      return if check_out_at > check_in_at
+
+      errors.add(:check_out_at, "must be after check-in")
+    end
+
+    def no_duplicate_pending
+      return unless date
+
+      clash = self.class.pending.where(user_id: user_id, date: date).where.not(id: id)
+      errors.add(:date, "already has a pending ticket") if clash.exists?
+    end
+
+    # A punch on a day covered by approved full-day leave would contradict
+    # the leave (which wins in every display and still burns the balance).
+    def no_approved_leave_conflict
+      return unless date
+
+      leave = LeaveRequest.active_on(date).where(user_id: user_id, half_day: false)
+      errors.add(:date, "is covered by your approved leave — cancel the leave first") if leave.exists?
+    end
+
+    def notify_requested
+      Notifications.publish(
+        "regularization.requested",
+        title: "#{HrLite.display_name(user)} raised a regularization ticket for #{date.strftime('%d %b')} " \
+               "(#{times_label})",
+        body: reason.presence,
+        path: "/admin/regularization_requests/#{id}",
+        bell_to: HrLite.admin_users
+      )
+    end
+  end
+end

data/app/services/hr_lite/team_day.rb

@@ -0,0 +1,84 @@
+module HrLite
+  # One row per staff member for a single date — powers the everyone-visible
+  # Team board: who's in, who's out, who's on leave, hours worked. Batch
+  # queries (five total, regardless of team size); the per-day precedence
+  # mirrors DayStatus (holiday > weekend > leave > punch > absent/upcoming).
+  class TeamDay
+    Row = Struct.new(:user, :profile, :kind, :record, :leave,
+                     :day_seconds, :month_seconds, :date, keyword_init: true) do
+      def date_today?
+        date == Date.current
+      end
+    end
+
+    def initialize(date: Date.current)
+      @date = date
+      @calendar = WorkingCalendar.new(date..date)
+    end
+
+    attr_reader :date, :calendar
+
+    def rows
+      @rows ||= build_rows
+    end
+
+    def kpis
+      {
+        checked_in: rows.count { |r| r.record&.check_in_at },
+        on_leave: rows.count { |r| %i[leave half_day_leave].include?(r.kind) },
+        not_in: rows.count { |r| r.kind == :absent }
+      }
+    end
+
+    private
+
+    def build_rows
+      users = HrLite.employees
+      ids = users.map(&:id)
+      profiles = EmployeeProfile.where(user_id: ids).index_by(&:user_id)
+      records = AttendanceRecord.for_date(@date).where(user_id: ids).index_by(&:user_id)
+      leaves = LeaveRequest.active_on(@date).includes(:leave_type)
+                           .where(user_id: ids).index_by(&:user_id)
+      month_records = AttendanceRecord.for_month(@date).where(user_id: ids).group_by(&:user_id)
+
+      users.filter_map do |user|
+        profile = profiles[user.id]
+        next if profile && !profile.active_on?(@date)
+
+        record = records[user.id]
+        leave = leaves[user.id]
+        Row.new(
+          user: user, profile: profile,
+          kind: kind_for(record, leave),
+          record: record, leave: leave,
+          day_seconds: seconds_worked(record),
+          month_seconds: (month_records[user.id] || []).sum { |r| seconds_worked(r) || 0 },
+          date: @date
+        )
+      end
+    end
+
+    def kind_for(record, leave)
+      return :holiday if @calendar.holiday?(@date)
+      return :weekend if @calendar.weekend?(@date)
+      return (leave.half_day ? :half_day_leave : :leave) if leave
+
+      if record&.check_in_at
+        record.status.to_sym
+      elsif @date > Date.current
+        :upcoming
+      else
+        :absent
+      end
+    end
+
+    # Finished punch → actual duration; still checked in today → running
+    # clock, so the board answers "how long have they been in so far".
+    def seconds_worked(record)
+      return nil unless record&.check_in_at
+      return record.worked_duration if record.check_out_at
+
+      record.date == Date.current ? Time.current - record.check_in_at : nil
+    end
+  end
+end