hr_lite 0.1.0

data/app/models/hr_lite/leave_request.rb

@@ -0,0 +1,207 @@
+module HrLite
+  class LeaveRequest < ApplicationRecord
+    STATUSES = %w[pending approved rejected cancelled].freeze
+
+    belongs_to :user, class_name: HrLite.config.user_class
+    belongs_to :leave_type
+    belongs_to :decided_by, class_name: HrLite.config.user_class, optional: true
+
+    validates :start_date, :end_date, presence: true
+    validates :status, inclusion: { in: STATUSES }
+
+    with_options on: :create do
+      validate :end_after_start
+      validate :same_calendar_year
+      validate :half_day_single_day_only
+      validate :consumes_at_least_half_a_day
+      validate :no_overlap_with_own_requests
+      validate :no_punch_conflict
+      validate :sufficient_balance
+    end
+
+    before_validation :cache_days_count, on: :create
+    after_create :notify_requested
+
+    scope :pending, -> { where(status: "pending") }
+    scope :approved, -> { where(status: "approved") }
+    scope :active_on, ->(date) { approved.where(start_date: ..date).where(end_date: date..) }
+    scope :overlapping_range, ->(from, to) { where(start_date: ..to).where(end_date: from..) }
+    scope :recent_first, -> { order(start_date: :desc, id: :desc) }
+
+    STATUSES.each do |s|
+      define_method("#{s}?") { status == s }
+    end
+
+    def paid?
+      leave_type.paid
+    end
+
+    # --- transitions -------------------------------------------------------
+
+    # Returns false (leaving the request pending) when the balance no longer
+    # covers it — the re-check runs inside the row lock so two concurrent
+    # approvals cannot overdraw one balance.
+    def approve!(actor:, note: nil)
+      insufficient = false
+      transition!("approved", actor, note) do
+        if insufficient_balance_now?
+          insufficient = true
+          raise ActiveRecord::Rollback
+        end
+      end
+      return false if insufficient
+
+      notify_decision("Leave approved")
+      true
+    end
+
+    def reject!(actor:, note:)
+      transition!("rejected", actor, note)
+      notify_decision("Leave rejected")
+      true
+    end
+
+    # Owner may cancel while pending, or an approved future leave (quota
+    # returns automatically because `used` is computed). Admins may cancel
+    # any pending/approved future leave.
+    def cancellable_by?(actor)
+      return false unless pending? || (approved? && start_date > Date.current)
+
+      user_id == actor.id || HrLite.admin?(actor) || HrLite.leadership?(actor)
+    end
+
+    def cancel!(actor:)
+      was_approved = approved?
+      self.status = "cancelled"
+      self.decided_by_id = actor.id
+      self.decided_at = Time.current
+      save!
+
+      Notifications.publish(
+        "leave.cancelled",
+        title: "#{HrLite.display_name(user)} cancelled #{was_approved ? 'approved ' : ''}leave " \
+               "(#{date_range_label})",
+        path: "/admin/leave_requests",
+        bell_to: HrLite.admin_users
+      )
+      true
+    end
+
+    def date_range_label
+      if start_date == end_date
+        "#{start_date.strftime('%d %b')}#{half_day ? ' (half day)' : ''}"
+      else
+        "#{start_date.strftime('%d %b')} – #{end_date.strftime('%d %b')}"
+      end
+    end
+
+    def balance
+      LeaveBalance.for(user, leave_type, start_date.year)
+    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
+
+    # This request is still pending here, so balance.used excludes it:
+    # approving is valid iff the request fits the remaining balance.
+    def insufficient_balance_now?
+      return false if leave_type.unlimited?
+
+      LeaveDayCounter.count(self) > balance.available
+    end
+
+    def notify_requested
+      Notifications.publish(
+        "leave.requested",
+        title: "#{HrLite.display_name(user)} applied for #{leave_type.name} (#{date_range_label})",
+        body: reason.presence,
+        path: "/admin/leave_requests/#{id}",
+        bell_to: HrLite.admin_users
+      )
+    end
+
+    def notify_decision(title)
+      Notifications.publish(
+        status == "approved" ? "leave.approved" : "leave.rejected",
+        title: "#{title} — #{leave_type.name} (#{date_range_label})",
+        body: decision_note.presence,
+        path: "/leave_requests/#{id}",
+        bell_to: [ user ],
+        email_to: [ user ]
+      )
+    end
+
+    def cache_days_count
+      self.days_count = LeaveDayCounter.count(self) if start_date && end_date
+      self.days_count ||= 0
+    end
+
+    def end_after_start
+      return unless start_date && end_date
+
+      errors.add(:end_date, "must be on or after the start date") if end_date < start_date
+    end
+
+    def same_calendar_year
+      return unless start_date && end_date
+
+      if start_date.year != end_date.year
+        errors.add(:base, "Split requests at the year boundary")
+      end
+    end
+
+    def half_day_single_day_only
+      errors.add(:half_day, "is only for single-day requests") if half_day && start_date != end_date
+    end
+
+    def consumes_at_least_half_a_day
+      return unless start_date && end_date
+      return if errors.any?
+
+      if LeaveDayCounter.count(self) <= 0
+        errors.add(:base, "Selected dates are all holidays or weekends")
+      end
+    end
+
+    def no_overlap_with_own_requests
+      return unless start_date && end_date
+
+      clash = self.class.where(user_id: user_id, status: %w[pending approved])
+                  .where.not(id: id)
+                  .overlapping_range(start_date, end_date)
+      errors.add(:base, "You already have leave overlapping these dates") if clash.exists?
+    end
+
+    # A full-day leave over a day that already has a check-in makes no
+    # sense; a half-day alongside a punch is legitimate (worked half).
+    def no_punch_conflict
+      return unless start_date && end_date
+      return if half_day
+
+      punched = AttendanceRecord.where(user_id: user_id, date: start_date..end_date)
+                                .where.not(check_in_at: nil)
+      errors.add(:base, "You have marked attendance in this period") if punched.exists?
+    end
+
+    def sufficient_balance
+      return unless start_date && end_date && leave_type
+      return if leave_type.unlimited? || errors.any?
+
+      if LeaveDayCounter.count(self) > balance.available(as_of: start_date)
+        errors.add(:base, "Not enough #{leave_type.name} balance")
+      end
+    end
+  end
+end

data/app/models/hr_lite/leave_type.rb

@@ -0,0 +1,22 @@
+module HrLite
+  class LeaveType < ApplicationRecord
+    include Audited
+
+    ACCRUALS = %w[yearly_upfront monthly].freeze
+
+    has_many :leave_requests, dependent: :restrict_with_error
+    has_many :leave_balances, dependent: :restrict_with_error
+
+    validates :name, :code, presence: true, uniqueness: true
+    validates :color, format: { with: /\A#\h{6}\z/ }
+    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 }
+
+    scope :active, -> { where(active: true).order(:position, :id) }
+
+    def unlimited?
+      annual_quota.nil?
+    end
+  end
+end

data/app/models/hr_lite/office_location.rb

@@ -0,0 +1,21 @@
+module HrLite
+  class OfficeLocation < ApplicationRecord
+    include Audited
+
+    validates :name, presence: true
+    validates :lat, presence: true, numericality: { greater_than_or_equal_to: -90, less_than_or_equal_to: 90 }
+    validates :lng, presence: true, numericality: { greater_than_or_equal_to: -180, less_than_or_equal_to: 180 }
+    validates :radius_m, presence: true, numericality: { only_integer: true, greater_than: 0 }
+
+    scope :active, -> { where(active: true) }
+
+    def self.covering?(lat, lng)
+      active.any? { |office| Geo.distance_m(office.lat, office.lng, lat, lng) <= office.radius_m }
+    end
+
+    # For flag notes: "1.2 km from Head Office". Nil when no offices exist.
+    def self.nearest(lat, lng)
+      active.min_by { |office| Geo.distance_m(office.lat, office.lng, lat, lng) }
+    end
+  end
+end

data/app/models/hr_lite/payroll_run.rb

@@ -0,0 +1,112 @@
+module HrLite
+  # Monthly run lifecycle: draft -> processing -> review -> finalized ->
+  # published (terminal). Compute is synchronous (pure-Ruby math over a
+  # small team; the seam for a background job is one perform_later away).
+  class PayrollRun < ApplicationRecord
+    STATUSES = %w[draft processing review finalized published].freeze
+
+    has_many :salary_slips, dependent: :destroy
+    belongs_to :created_by, class_name: HrLite.config.user_class, optional: true
+    belongs_to :finalized_by, class_name: HrLite.config.user_class, optional: true
+    belongs_to :published_by, class_name: HrLite.config.user_class, optional: true
+
+    validates :period_month, presence: true, uniqueness: true
+    validates :status, inclusion: { in: STATUSES }
+    validate :period_is_first_of_month
+    before_destroy :draft_only_destroy
+
+    scope :recent_first, -> { order(period_month: :desc) }
+
+    STATUSES.each { |s| define_method("#{s}?") { status == s } }
+
+    def editable?
+      draft? || processing? || review?
+    end
+
+    def label
+      period_month.strftime("%B %Y")
+    end
+
+    def compute!(actor:)
+      raise_unless %w[draft review]
+
+      update!(status: "processing")
+      PayrollRunProcessor.call(self)
+      update!(status: "review", processed_at: Time.current)
+      true
+    rescue => e
+      update_columns(status: "draft") # rubocop:disable Rails/SkipsModelValidations
+      raise e
+    end
+
+    def finalize!(actor:)
+      raise_unless %w[review]
+      raise ActiveRecord::RecordInvalid.new(self), "no slips" if salary_slips.none?
+
+      update!(status: "finalized", finalized_at: Time.current, finalized_by_id: actor.id)
+      Notifications.publish(
+        "payroll.finalized",
+        title: "Payroll #{label} finalized — #{salary_slips.count} slips, net #{Money.round2(total_net).to_s('F')}",
+        path: "/admin/payroll_runs/#{id}"
+      )
+      true
+    end
+
+    def unlock!(actor:)
+      raise_unless %w[finalized]
+      update!(status: "review")
+      true
+    end
+
+    def publish!(actor:)
+      raise_unless %w[finalized]
+      update!(status: "published", published_at: Time.current, published_by_id: actor.id)
+
+      slips = salary_slips.includes(:user).to_a
+      Notifications.publish(
+        "payroll.published",
+        title: "Your salary slip for #{label} is ready",
+        body: "Open Earthly HR to view or download it.",
+        path: "/salary_slips",
+        bell_to: slips.map(&:user),
+        email_to: slips.map(&:user)
+      )
+      true
+    end
+
+    # Ruby-side aggregates (amounts are encrypted — no SQL sums).
+    def total_gross = sum_slips(:gross_earnings)
+    def total_deductions = sum_slips(:total_deductions)
+    def total_net = sum_slips(:net_pay)
+
+    def total_employer_cost
+      salary_slips.sum(BigDecimal(0)) do |slip|
+        slip.employer_costs_hash.values.sum(BigDecimal(0)) { |v| Money.d(v) }
+      end
+    end
+
+    private
+
+    def sum_slips(attribute)
+      salary_slips.sum(BigDecimal(0)) { |slip| slip.public_send(attribute) || BigDecimal(0) }
+    end
+
+    def raise_unless(allowed)
+      raise ActiveRecord::RecordInvalid.new(self), "invalid transition" unless allowed.include?(status)
+    end
+
+    def period_is_first_of_month
+      return unless period_month
+      return if period_month.day == 1
+
+      errors.add(:period_month, "must be the 1st of a month")
+    end
+
+    def draft_only_destroy
+      return if draft?
+
+      errors.add(:base, "Only draft runs can be deleted")
+      throw :abort
+    end
+  end
+end

data/app/models/hr_lite/salary_slip.rb

@@ -0,0 +1,78 @@
+module HrLite
+  # One employee-month. All MONEY is snapshotted (encrypted JSON line items +
+  # encrypted totals); identity numbers (PAN/UAN/bank) render live from the
+  # profile — a typo fix must flow to old slips, and duplicating encrypted
+  # PII per month multiplies liability. Visibility and immutability delegate
+  # to the run's lifecycle.
+  class SalarySlip < ApplicationRecord
+    include EncryptedMoney
+
+    belongs_to :payroll_run
+    belongs_to :user, class_name: HrLite.config.user_class
+
+    encrypts :earnings, :deductions, :employer_costs, :tax_details
+    encrypted_money :tds_override, :gross_earnings, :total_deductions, :net_pay
+
+    validates :period_month, presence: true, uniqueness: { scope: :user_id }
+    validates :user_id, uniqueness: { scope: :payroll_run_id }
+    before_save :ensure_run_editable
+
+    scope :published, -> { joins(:payroll_run).where(hr_lite_payroll_runs: { status: "published" }) }
+    scope :recent_first, -> { order(period_month: :desc) }
+
+    def published?
+      payroll_run.published?
+    end
+
+    def earnings_rows = parse_json(earnings)
+    def deductions_rows = parse_json(deductions)
+    def employer_costs_hash = parse_json(employer_costs, fallback: {})
+    def tax_details_hash = parse_json(tax_details, fallback: {})
+
+    def effective_lop_days
+      lop_override || lop_days
+    end
+
+    # Indian FY (Apr 1) to-date sums of PUBLISHED slips before this period —
+    # feeds the TDS projector and the slip's YTD table.
+    def self.fy_to_date(user, period_month)
+      fy_start = period_month.month >= 4 ? Date.new(period_month.year, 4, 1)
+                                         : Date.new(period_month.year - 1, 4, 1)
+      slips = published.where(user_id: user.id)
+                       .where(period_month: fy_start...period_month)
+      {
+        gross: slips.sum(BigDecimal(0)) { |s| s.gross_earnings || BigDecimal(0) },
+        tds: slips.sum(BigDecimal(0)) { |s| Money.d(s.deduction_amount("tds")) },
+        months: slips.count
+      }
+    end
+
+    def deduction_amount(code)
+      row = deductions_rows.find { |r| r["code"] == code }
+      row ? Money.d(row["amount"]) : BigDecimal(0)
+    end
+
+    def pdf_cache_key
+      [ "hr_lite_slip", id, updated_at.to_i, payroll_run.status,
+        user_profile&.updated_at.to_i ].join("/")
+    end
+
+    def user_profile
+      @user_profile ||= EmployeeProfile.find_by(user_id: user_id)
+    end
+
+    private
+
+    def parse_json(raw, fallback: [])
+      raw.blank? ? fallback : JSON.parse(raw)
+    end
+
+    def ensure_run_editable
+      return if payroll_run.nil? || payroll_run.editable?
+      # The lifecycle transitions themselves touch only the run row, never
+      # slip attributes — any slip write outside draft/processing/review is
+      # a bug or tampering.
+      raise ActiveRecord::ReadOnlyRecord, "slips are immutable once the run is finalized"
+    end
+  end
+end

data/app/models/hr_lite/salary_structure.rb

@@ -0,0 +1,49 @@
+module HrLite
+  # Versioned by effective_from (always the 1st — mid-month revisions and
+  # their blended-rate complexity are deliberately unsupported). Structures
+  # are never destroyed; a new revision supersedes. Slips snapshot every
+  # computed number, so editing a structure cannot corrupt history.
+  class SalaryStructure < ApplicationRecord
+    include EncryptedMoney
+    include Audited
+
+    belongs_to :user, class_name: HrLite.config.user_class
+    belongs_to :created_by, class_name: HrLite.config.user_class, optional: true
+
+    encrypted_money :basic, :hra, :special_allowance, :other_earnings
+
+    validates :effective_from, presence: true, uniqueness: { scope: :user_id }
+    validates :basic, presence: true
+    validate :basic_positive
+    validate :effective_from_is_first_of_month
+    validates :pt_state, presence: true
+
+    def self.effective_for(user, period_month)
+      where(user_id: user.id)
+        .where(effective_from: ..period_month.beginning_of_month)
+        .order(effective_from: :desc)
+        .first
+    end
+
+    def monthly_gross
+      [ basic, hra, special_allowance, other_earnings ].compact.sum(BigDecimal(0))
+    end
+
+    def annual_gross
+      monthly_gross * 12
+    end
+
+    private
+
+    def basic_positive
+      errors.add(:basic, "must be greater than zero") if basic && basic <= 0
+    end
+
+    def effective_from_is_first_of_month
+      return unless effective_from
+      return if effective_from.day == 1
+
+      errors.add(:effective_from, "must be the 1st of a month")
+    end
+  end
+end

data/app/models/hr_lite/setting.rb

@@ -0,0 +1,14 @@
+module HrLite
+  # Engine-owned singleton settings row.
+  class Setting < ApplicationRecord
+    include Audited
+
+    WEEKEND_POLICIES = %w[sun_only sat_sun second_fourth_sat_sun].freeze
+
+    validates :weekend_policy, inclusion: { in: WEEKEND_POLICIES }
+
+    def self.instance
+      first_or_create!
+    end
+  end
+end

data/app/services/hr_lite/attendance_puncher.rb

@@ -0,0 +1,103 @@
+module HrLite
+  # The single write path for employee punches. Race-safe (DB unique index +
+  # row lock + in-lock re-check), never blocked by geolocation: a punch
+  # without GPS or outside every office radius is recorded AND flagged —
+  # denying GPS must not stop anyone from working.
+  class AttendancePuncher
+    Result = Struct.new(:record, :error, keyword_init: true) do
+      def ok? = error.nil?
+    end
+
+    def self.call(user:, kind:, lat: nil, lng: nil, accuracy_m: nil, geo_status: "ok")
+      new(user, kind.to_sym, lat, lng, accuracy_m, geo_status.to_s).call
+    end
+
+    def initialize(user, kind, lat, lng, accuracy_m, geo_status)
+      @user = user
+      @kind = kind
+      @lat = lat.presence
+      @lng = lng.presence
+      @accuracy_m = accuracy_m.presence
+      @geo_status = geo_status
+    end
+
+    def call
+      record = resolve_record
+      return Result.new(error: "No open check-in to close.") if record.nil?
+
+      record.with_lock do
+        case @kind
+        when :check_in
+          return Result.new(record: record, error: already_in_message(record)) if record.check_in_at.present?
+
+          stamp(record, :check_in)
+        when :check_out
+          return Result.new(record: record, error: "Check in first.") if record.check_in_at.blank?
+
+          stamp(record, :check_out) # repeat check-out overwrites: last out wins
+        else
+          return Result.new(error: "Unknown punch #{@kind}.")
+        end
+
+        apply_geo_flags(record)
+        record.save!
+      end
+      notify_if_flagged(record)
+      Result.new(record: record)
+    end
+
+    private
+
+    def resolve_record
+      if @kind == :check_out
+        today = AttendanceRecord.find_by(user_id: @user.id, date: Date.current)
+        return today if today&.check_in_at.present?
+
+        # Post-midnight close of yesterday's open punch (office night, IST).
+        return AttendanceRecord.for_date(Date.current - 1)
+                               .missing_checkout.find_by(user_id: @user.id)
+      end
+
+      AttendanceRecord.find_or_create_by!(user_id: @user.id, date: Date.current)
+    rescue ActiveRecord::RecordNotUnique
+      retry
+    end
+
+    def stamp(record, side)
+      record.public_send("#{side}_at=", Time.current)
+      record.public_send("#{side}_lat=", @lat)
+      record.public_send("#{side}_lng=", @lng)
+      record.public_send("#{side}_accuracy_m=", @accuracy_m)
+    end
+
+    def already_in_message(record)
+      "Already checked in at #{record.check_in_at.in_time_zone(HrLite.config.time_zone).strftime('%H:%M')}."
+    end
+
+    def apply_geo_flags(record)
+      label = @kind == :check_in ? "Check-in" : "Check-out"
+
+      if @lat.nil? || @lng.nil?
+        reason = @geo_status == "ok" ? "unavailable" : @geo_status
+        record.add_flag!("#{label} without GPS (#{reason})")
+      elsif OfficeLocation.active.exists? && !OfficeLocation.covering?(@lat, @lng)
+        office = OfficeLocation.nearest(@lat, @lng)
+        distance_km = (Geo.distance_m(office.lat, office.lng, @lat, @lng) / 1000.0).round(1)
+        accuracy = @accuracy_m ? " (±#{@accuracy_m} m)" : ""
+        record.add_flag!("#{label} #{distance_km} km from #{office.name}#{accuracy}")
+      end
+    end
+
+    def notify_if_flagged(record)
+      return unless record.saved_changes.key?("flag_note") && record.flagged?
+
+      Notifications.publish(
+        "attendance.flagged",
+        title: "Flagged punch — #{HrLite.display_name(@user)}",
+        body: record.flag_note,
+        path: "/admin/attendances?date=#{record.date}",
+        bell_to: HrLite.admin_users
+      )
+    end
+  end
+end