hr_lite 0.1.0

data/app/mailers/hr_lite/event_mailer.rb

@@ -0,0 +1,33 @@
+module HrLite
+  # One mailer, two generic responsive templates. Per-event content (heading,
+  # body, detail lines, diff table) is assembled by the Notifications bus so
+  # adding an event never means adding a template.
+  class EventMailer < ApplicationMailer
+    def event(to:, subject:, heading:, body: nil, lines: [], path: nil)
+      @heading = heading
+      @body = body
+      @lines = Array(lines)
+      @cta_url = HrLite::EventMailer.link_for(path)
+      mail(to: to, from: HrLite.config.mailer_from, subject: subject)
+    end
+
+    def leadership(to:, subject:, heading:, body: nil, lines: [], diff: nil, path: nil, event: nil)
+      @heading = heading
+      @body = body
+      @lines = Array(lines)
+      @diff = diff.presence
+      @event = event
+      @cta_url = HrLite::EventMailer.link_for(path)
+      mail(to: to, from: HrLite.config.mailer_from, subject: subject)
+    end
+
+    # Emails need absolute URLs; the engine can't know its public mount.
+    # Hosts set config.public_url_base (e.g. "https://hr.example.com");
+    # unset => emails simply carry no link button.
+    def self.link_for(path)
+      return nil if path.blank?
+
+      HrLite.public_url(path)
+    end
+  end
+end

data/app/models/concerns/hr_lite/audited.rb

@@ -0,0 +1,70 @@
+module HrLite
+  # Include in every leadership-mutable model. Each create/update/destroy
+  # writes an append-only AuditLog row and publishes policy.changed to
+  # leadership. Encrypted attributes are logged as "[changed]" — plaintext
+  # PII never reaches the audit table or email.
+  module Audited
+    extend ActiveSupport::Concern
+
+    SKIPPED_ATTRIBUTES = %w[updated_at created_at].freeze
+    REDACTED = "[changed]".freeze
+
+    included do
+      after_create  { hr_lite_audit!("create") }
+      after_update  { hr_lite_audit!("update") }
+      after_destroy { hr_lite_audit!("destroy") }
+    end
+
+    private
+
+    def hr_lite_audit!(action)
+      changes = hr_lite_audited_changes(action)
+      return if action == "update" && changes.empty?
+
+      log = HrLite::AuditLog.create!(
+        actor: HrLite::Current.actor,
+        action: action,
+        subject_type: self.class.name,
+        subject_id: id,
+        audited_changes: changes
+      )
+      hr_lite_publish_policy_change(log)
+    rescue => e
+      # The trail is best-effort by design: an audit hiccup must never roll
+      # back the domain write it describes. Logged loudly instead.
+      Rails.logger.error("[hr_lite] audit failed: #{e.class}: #{e.message}")
+    end
+
+    def hr_lite_audited_changes(action)
+      encrypted = self.class.try(:encrypted_attributes)&.map(&:to_s) || []
+
+      case action
+      when "destroy"
+        { "_destroyed" => hr_lite_audit_label }
+      else
+        saved_changes.except(*SKIPPED_ATTRIBUTES).to_h do |attr, (from, to)|
+          if encrypted.include?(attr)
+            [ attr, REDACTED ]
+          else
+            [ attr, [ from, to ] ]
+          end
+        end
+      end
+    end
+
+    def hr_lite_audit_label
+      try(:name) || try(:title) || "#{self.class.name.demodulize} ##{id}"
+    end
+
+    def hr_lite_publish_policy_change(log)
+      actor_name = HrLite.display_name(HrLite::Current.actor)
+      subject = "#{self.class.name.demodulize.underscore.humanize} — #{hr_lite_audit_label}"
+      HrLite::Notifications.publish(
+        "policy.changed",
+        title: "#{actor_name.presence || 'Someone'} #{log.action}d #{subject}",
+        body: nil,
+        diff: log.audited_changes
+      )
+    end
+  end
+end

data/app/models/concerns/hr_lite/encrypted_money.rb

@@ -0,0 +1,32 @@
+module HrLite
+  # Money that must be encrypted at rest. Rails `encrypts` only works on
+  # text columns, so amounts are stored as canonical decimal strings and
+  # surfaced as BigDecimal. BigDecimal in, BigDecimal out; Float never.
+  #
+  # Accepted trade-off (documented): encrypted amounts cannot be aggregated
+  # in SQL — all totals are computed in Ruby. Fine well past 100 employees.
+  module EncryptedMoney
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def encrypted_money(*attributes)
+        attributes.each do |attribute|
+          encrypts attribute
+
+          define_method(attribute) do
+            raw = super()
+            raw.nil? ? nil : BigDecimal(raw)
+          end
+
+          define_method("#{attribute}=") do |value|
+            if value.nil? || (value.respond_to?(:blank?) && value.blank?)
+              super(nil)
+            else
+              super(BigDecimal(value.to_s).round(2).to_s("F"))
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/hr_lite/application_record.rb

@@ -0,0 +1,5 @@
+module HrLite
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/hr_lite/appraisal.rb

@@ -0,0 +1,89 @@
+module HrLite
+  # Individual performance review. Drafted and edited by leadership,
+  # invisible to the employee until shared; sharing locks it permanently —
+  # a shared review is a record, corrections go in the next appraisal.
+  # A promotion outcome records a DesignationChange at share time.
+  class Appraisal < ApplicationRecord
+    include Audited
+
+    OUTCOMES = %w[none increment promotion].freeze
+    STATUSES = %w[draft shared].freeze
+
+    belongs_to :user, class_name: HrLite.config.user_class
+    belongs_to :reviewer, class_name: HrLite.config.user_class
+    has_one :designation_change, dependent: :nullify
+
+    validates :period_start, :period_end, presence: true
+    validates :rating, inclusion: { in: 1..5 }, allow_nil: true
+    validates :outcome, inclusion: { in: OUTCOMES }
+    validates :status, inclusion: { in: STATUSES }
+    validates :effective_date, presence: true, unless: -> { outcome == "none" }
+    validates :new_designation, presence: true, if: -> { outcome == "promotion" }
+    validate :period_order
+    validate :locked_after_share
+    before_destroy :draft_only_destroy
+
+    scope :shared, -> { where(status: "shared") }
+    scope :recent_first, -> { order(period_end: :desc, id: :desc) }
+
+    def draft? = status == "draft"
+    def shared? = status == "shared"
+
+    def share!(actor:)
+      raise ActiveRecord::RecordInvalid.new(self), "already shared" unless draft?
+
+      transaction do
+        update!(status: "shared", shared_at: Time.current)
+        record_promotion!(actor) if outcome == "promotion"
+      end
+
+      Notifications.publish(
+        "appraisal.shared",
+        title: "Your appraisal for #{period_label} has been shared",
+        body: rating ? "Rating: #{rating}/5" : nil,
+        path: "/appraisals/#{id}",
+        bell_to: [ user ],
+        email_to: [ user ]
+      )
+      true
+    end
+
+    def period_label
+      "#{period_start.strftime('%b %Y')} – #{period_end.strftime('%b %Y')}"
+    end
+
+    private
+
+    def record_promotion!(actor)
+      DesignationChange.create!(
+        user_id: user_id,
+        to_designation: new_designation,
+        effective_date: effective_date,
+        note: "Promotion via appraisal #{period_label}",
+        appraisal_id: id,
+        created_by_id: actor.id
+      )
+    end
+
+    def draft_only_destroy
+      return if draft?
+
+      errors.add(:base, "Shared appraisals are permanent records")
+      throw :abort
+    end
+
+    def period_order
+      return unless period_start && period_end
+
+      errors.add(:period_end, "must be after the start") if period_end < period_start
+    end
+
+    def locked_after_share
+      return if new_record? || draft?
+      # The share! transition itself sets status/shared_at; any other change
+      # to a shared appraisal is tampering.
+      changed_keys = changes.keys - %w[status shared_at updated_at]
+      errors.add(:base, "A shared appraisal cannot be edited") if changed_keys.any? && status_was == "shared"
+    end
+  end
+end

data/app/models/hr_lite/attendance_record.rb

@@ -0,0 +1,41 @@
+module HrLite
+  class AttendanceRecord < ApplicationRecord
+    STATUSES = %w[present half_day].freeze
+
+    belongs_to :user, class_name: HrLite.config.user_class
+    belongs_to :regularized_by, class_name: HrLite.config.user_class, optional: true
+
+    validates :date, presence: true, uniqueness: { scope: :user_id }
+    validates :status, inclusion: { in: STATUSES }
+    validate :check_out_after_check_in
+
+    scope :for_date, ->(date) { where(date: date) }
+    scope :for_month, ->(month) { where(date: month.beginning_of_month..month.end_of_month) }
+    scope :flagged, -> { where(flagged: true) }
+    scope :missing_checkout, -> { where.not(check_in_at: nil).where(check_out_at: nil) }
+
+    def regularized?
+      regularized_at.present?
+    end
+
+    def worked_duration
+      return nil unless check_in_at && check_out_at
+
+      check_out_at - check_in_at
+    end
+
+    def add_flag!(note)
+      self.flagged = true
+      self.flag_note = [ flag_note.presence, note ].compact.join("; ")
+    end
+
+    private
+
+    def check_out_after_check_in
+      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
+  end
+end

data/app/models/hr_lite/audit_log.rb

@@ -0,0 +1,17 @@
+module HrLite
+  # Append-only trail of every governing-tier mutation. Rows are never
+  # updated or deleted; the leadership audit screen and the policy.changed
+  # email diff both read from here.
+  class AuditLog < ApplicationRecord
+    belongs_to :actor, class_name: HrLite.config.user_class, optional: true
+    belongs_to :subject, polymorphic: true, optional: true
+
+    validates :action, :subject_type, :subject_id, presence: true
+
+    scope :recent, -> { order(created_at: :desc) }
+
+    def readonly?
+      persisted?
+    end
+  end
+end

data/app/models/hr_lite/designation_change.rb

@@ -0,0 +1,52 @@
+module HrLite
+  # One promotion / role change. Creating it stamps the employee profile's
+  # current designation and tells the host (so e.g. the CMS job title stays
+  # in sync). Rows are the career timeline — never edited or deleted.
+  class DesignationChange < ApplicationRecord
+    include Audited
+
+    belongs_to :user, class_name: HrLite.config.user_class
+    belongs_to :appraisal, optional: true
+    belongs_to :created_by, class_name: HrLite.config.user_class, optional: true
+
+    validates :to_designation, :effective_date, presence: true
+
+    scope :timeline, -> { order(effective_date: :desc, id: :desc) }
+
+    before_create :capture_from_designation
+    after_create :apply_to_profile
+    after_create :notify
+
+    def readonly?
+      persisted? && !destroyed?
+    end
+
+    private
+
+    def capture_from_designation
+      self.from_designation ||= EmployeeProfile.find_by(user_id: user_id)&.designation
+    end
+
+    def apply_to_profile
+      profile = EmployeeProfile.find_by(user_id: user_id)
+      profile&.update!(designation: to_designation)
+
+      begin
+        HrLite.config.on_designation_change.call(user, to_designation)
+      rescue => e
+        Rails.logger.error("[hr_lite] on_designation_change failed: #{e.class}: #{e.message}")
+      end
+    end
+
+    def notify
+      Notifications.publish(
+        "promotion.recorded",
+        title: "New role: #{to_designation}",
+        body: "Effective #{effective_date.strftime('%d %b %Y')}.",
+        path: "/career",
+        bell_to: [ user ],
+        email_to: [ user ]
+      )
+    end
+  end
+end

data/app/models/hr_lite/employee_profile.rb

@@ -0,0 +1,72 @@
+module HrLite
+  # Statutory identity + employment window. PII columns are encrypted at
+  # rest; masked readers feed the employee-facing view (full values render
+  # only in the leadership edit form). Records are never destroyed —
+  # exits are a date, payroll history is a statutory record.
+  class EmployeeProfile < ApplicationRecord
+    include EncryptedMoney
+    include Audited
+
+    belongs_to :user, class_name: HrLite.config.user_class
+
+    encrypts :pan_number, :pf_uan, :esi_number, :bank_account_number, :bank_ifsc
+    encrypted_money :declared_annual_deductions
+
+    TAX_REGIMES = %w[new old].freeze
+
+    validates :employee_code, presence: true, uniqueness: true
+    validates :user_id, uniqueness: true
+    validates :date_of_joining, presence: true
+    validates :tax_regime, inclusion: { in: TAX_REGIMES }
+    validates :pan_number, format: { with: /\A[A-Z]{5}[0-9]{4}[A-Z]\z/, message: "is not a valid PAN" },
+                           allow_blank: true
+    validates :bank_ifsc, format: { with: /\A[A-Z]{4}0[A-Z0-9]{6}\z/, message: "is not a valid IFSC" },
+                          allow_blank: true
+    validates :pf_uan, format: { with: /\A\d{12}\z/, message: "must be 12 digits" }, allow_blank: true
+    validate :exit_after_joining
+
+    scope :active_for, ->(month) {
+      where(date_of_joining: ..month.end_of_month)
+        .where("date_of_exit IS NULL OR date_of_exit >= ?", month.beginning_of_month)
+    }
+
+    def active_on?(date)
+      date_of_joining <= date && (date_of_exit.nil? || date_of_exit >= date)
+    end
+
+    def employment_range_in(month)
+      from = [ date_of_joining, month.beginning_of_month ].max
+      to = [ date_of_exit || month.end_of_month, month.end_of_month ].min
+      from <= to ? (from..to) : nil
+    end
+
+    def masked_pan
+      mask_middle(pan_number)
+    end
+
+    def masked_account
+      value = bank_account_number
+      value.blank? ? nil : "•••• #{value.last(4)}"
+    end
+
+    def masked_uan
+      mask_middle(pf_uan)
+    end
+
+    private
+
+    def mask_middle(value)
+      return nil if value.blank?
+      return "•" * value.length if value.length <= 4
+
+      "#{value.first(2)}#{'•' * (value.length - 4)}#{value.last(2)}"
+    end
+
+    def exit_after_joining
+      return unless date_of_exit && date_of_joining
+      return if date_of_exit >= date_of_joining
+
+      errors.add(:date_of_exit, "must be after joining")
+    end
+  end
+end

data/app/models/hr_lite/holiday.rb

@@ -0,0 +1,18 @@
+module HrLite
+  class Holiday < ApplicationRecord
+    include Audited
+
+    validates :date, presence: true, uniqueness: true
+    validates :name, presence: true
+
+    scope :company_wide, -> { where(optional: false) }
+    scope :in_range, ->(range) { where(date: range) }
+    scope :upcoming, -> { where(date: Date.current..).order(:date) }
+
+    # Company-wide holiday dates only — optional holidays never exclude
+    # working days.
+    def self.dates_for(range)
+      company_wide.in_range(range).pluck(:date).to_set
+    end
+  end
+end

data/app/models/hr_lite/kudo.rb

@@ -0,0 +1,54 @@
+module HrLite
+  class Kudo < ApplicationRecord
+    belongs_to :giver, class_name: HrLite.config.user_class
+    has_many :kudo_mentions, dependent: :destroy
+    has_many :mentioned_users, through: :kudo_mentions, source: :user
+
+    # Text-labelled badges (rendered with an inline SVG icon, never emoji).
+    BADGES = {
+      "team_player"      => "Team player",
+      "above_and_beyond" => "Going above and beyond",
+      "customer_hero"    => "Customer hero",
+      "problem_solver"   => "Problem solver",
+      "culture_champion" => "Culture champion"
+    }.freeze
+
+    DELETE_WINDOW = 15.minutes
+
+    validates :message, presence: true, length: { maximum: 1000 }
+    validates :badge, inclusion: { in: BADGES.keys }, allow_blank: true
+
+    scope :recent, -> { order(created_at: :desc, id: :desc) }
+
+    # Praise is immutable; the giver gets a short window to undo a mistake,
+    # admins/leadership can moderate any time.
+    def deletable_by?(user)
+      return false if user.nil?
+      return true if HrLite.admin?(user) || HrLite.leadership?(user)
+
+      giver_id == user.id && created_at > DELETE_WINDOW.ago
+    end
+
+    def badge_label
+      BADGES[badge]
+    end
+
+    # Creates mention rows from the message markers (existing users only,
+    # giver excluded) and notifies them. Called once, right after create.
+    def register_mentions!
+      ids = HrLite::MentionParser.user_ids(message) - [ giver_id ]
+      users = HrLite.user_klass.where(id: ids)
+      users.each { |u| kudo_mentions.create!(user_id: u.id) }
+
+      HrLite::Notifications.publish(
+        "kudos.mentioned",
+        title: "#{HrLite.display_name(giver)} gave you kudos",
+        body: HrLite::MentionParser.strip_markers(message).truncate(140),
+        path: "/kudos",
+        bell_to: users.to_a,
+        email_to: users.to_a
+      )
+      users
+    end
+  end
+end

data/app/models/hr_lite/kudo_mention.rb

@@ -0,0 +1,8 @@
+module HrLite
+  class KudoMention < ApplicationRecord
+    belongs_to :kudo
+    belongs_to :user, class_name: HrLite.config.user_class
+
+    validates :user_id, uniqueness: { scope: :kudo_id }
+  end
+end

data/app/models/hr_lite/leave_balance.rb

@@ -0,0 +1,42 @@
+module HrLite
+  # Hybrid balance: only carry-in and manual adjustments are stored;
+  # 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.
+  class LeaveBalance < ApplicationRecord
+    belongs_to :user, class_name: HrLite.config.user_class
+    belongs_to :leave_type
+
+    validates :year, presence: true,
+                     uniqueness: { scope: %i[user_id leave_type_id] }
+
+    def self.for(user, leave_type, year)
+      find_or_initialize_by(user_id: user.id, leave_type: leave_type, year: year)
+    end
+
+    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
+    end
+
+    def used
+      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))
+      requests.sum { |request| LeaveDayCounter.count(request) }
+    end
+
+    def available(as_of: Date.current)
+      entitled(as_of: as_of) - used
+    end
+  end
+end