hr_lite 0.1.0

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

@@ -0,0 +1,44 @@
+module HrLite
+  module Admin
+    class SalarySlipsController < LeadershipController
+      def show
+        @slip = SalarySlip.includes(:payroll_run).find(params[:id])
+        @profile = @slip.user_profile
+      end
+
+      # Review-stage overrides (LOP days / monthly TDS) — the slip rebuilds
+      # immediately with the overrides applied.
+      def update
+        slip = SalarySlip.includes(:payroll_run).find(params[:id])
+        run = slip.payroll_run
+        unless run.review?
+          return redirect_to admin_salary_slip_path(slip),
+                             alert: "Overrides are only editable while the run is in review."
+        end
+
+        lop_override = params.dig(:salary_slip, :lop_override).presence
+        tds_override = params.dig(:salary_slip, :tds_override).presence
+        profile = EmployeeProfile.find_by(user_id: slip.user_id)
+        structure = SalaryStructure.effective_for(slip.user, run.period_month)
+
+        attributes = SlipBuilder.call(
+          run: run, user: slip.user, structure: structure, profile: profile,
+          lop_override: lop_override && BigDecimal(lop_override),
+          tds_override: tds_override && BigDecimal(tds_override)
+        )
+        slip.update!(attributes)
+
+        AuditLog.create!(
+          actor: hr_current_user, action: "override",
+          subject_type: slip.class.name, subject_id: slip.id,
+          audited_changes: { "period" => run.label, "employee" => HrLite.display_name(slip.user),
+                             "lop_override" => lop_override || "cleared",
+                             "tds_override" => tds_override ? "[changed]" : "cleared" }
+        )
+        redirect_to admin_salary_slip_path(slip), notice: "Slip recomputed with overrides."
+      rescue ArgumentError
+        redirect_to admin_salary_slip_path(params[:id]), alert: "Overrides must be numbers."
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+module HrLite
+  module Admin
+    class SalaryStructuresController < LeadershipController
+      before_action :set_profile
+
+      def new
+        @structure = SalaryStructure.new(user_id: @profile.user_id,
+                                         effective_from: Date.current.beginning_of_month)
+      end
+
+      def create
+        @structure = SalaryStructure.new(structure_params.merge(
+          user_id: @profile.user_id, created_by_id: hr_current_user.id
+        ))
+        if @structure.save
+          redirect_to admin_employee_path(@profile), notice: "Salary structure saved."
+        else
+          render :new, status: :unprocessable_entity
+        end
+      end
+
+      def edit
+        @structure = SalaryStructure.where(user_id: @profile.user_id).find(params[:id])
+      end
+
+      def update
+        @structure = SalaryStructure.where(user_id: @profile.user_id).find(params[:id])
+        if @structure.update(structure_params)
+          redirect_to admin_employee_path(@profile), notice: "Salary structure updated."
+        else
+          render :edit, status: :unprocessable_entity
+        end
+      end
+
+      private
+
+      def set_profile
+        @profile = EmployeeProfile.find(params[:employee_id])
+      end
+
+      def structure_params
+        params.require(:salary_structure).permit(
+          :effective_from, :basic, :hra, :special_allowance, :other_earnings,
+          :pf_applicable, :pf_on_full_basic, :esi_applicable, :pt_state, :notes
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+module HrLite
+  module Admin
+    class SettingsController < LeadershipController
+      def edit
+        @setting = Setting.instance
+      end
+
+      def update
+        @setting = Setting.instance
+        if @setting.update(params.require(:setting).permit(:weekend_policy))
+          redirect_to edit_admin_setting_path, notice: "Settings saved."
+        else
+          render :edit, status: :unprocessable_entity
+        end
+      end
+    end
+  end
+end

data/app/controllers/hr_lite/application_controller.rb

@@ -0,0 +1,76 @@
+module HrLite
+  # Inherits from the host-configured parent controller (set
+  # config.parent_controller in an initializer BEFORE boot; changing it needs
+  # a restart). Everything else — auth method, current user, admin/leadership
+  # checks — is resolved per request from the live config.
+  class ApplicationController < HrLite.config.parent_controller.constantize
+    layout "hr_lite/application"
+
+    before_action :hr_authenticate!
+    before_action :hr_set_current_actor
+    around_action :hr_use_time_zone
+
+    helper_method :hr_current_user, :hr_admin?, :hr_leadership?, :hr_display_name
+
+    private
+
+    def hr_authenticate!
+      send(HrLite.config.authenticate_method)
+    end
+
+    def hr_current_user
+      send(HrLite.config.current_user_method)
+    end
+
+    def hr_admin?
+      HrLite.admin?(hr_current_user)
+    end
+
+    def hr_leadership?
+      HrLite.leadership?(hr_current_user)
+    end
+
+    def hr_display_name(user)
+      HrLite.display_name(user)
+    end
+
+    def hr_set_current_actor
+      HrLite::Current.actor = hr_current_user
+    end
+
+    def hr_use_time_zone(&)
+      Time.use_zone(HrLite.config.time_zone, &)
+    end
+
+    def hr_access_denied
+      respond_to do |format|
+        format.html { redirect_to hr_lite.root_path, alert: "You do not have access to that area." }
+        format.any { head :forbidden }
+      end
+    end
+
+    # Strict param parsing: anything that isn't the exact expected format
+    # falls back to today (never 500s on a mangled URL).
+    def parse_month_param(value)
+      Date.strptime(value.to_s, "%Y-%m")
+    rescue ArgumentError, TypeError
+      Date.current.beginning_of_month
+    end
+
+    def parse_date_param(value)
+      Date.strptime(value.to_s, "%Y-%m-%d")
+    rescue ArgumentError, TypeError
+      Date.current
+    end
+
+    # Minimal LIMIT/OFFSET pagination — no host dependency.
+    def paginate(scope, per: 25)
+      @per = [ [ params.fetch(:per, per).to_i, 1 ].max, 100 ].min
+      @page = [ params.fetch(:page, 1).to_i, 1 ].max
+      @total_count = scope.count
+      @total_pages = [ (@total_count.to_f / @per).ceil, 1 ].max
+      @page = @total_pages if @page > @total_pages
+      scope.offset((@page - 1) * @per).limit(@per)
+    end
+  end
+end

data/app/controllers/hr_lite/appraisals_controller.rb

@@ -0,0 +1,18 @@
+module HrLite
+  # Employee view: shared appraisals only — drafts do not exist for them.
+  class AppraisalsController < ApplicationController
+    def index
+      @appraisals = paginate(own_shared.recent_first)
+    end
+
+    def show
+      @appraisal = own_shared.find(params[:id])
+    end
+
+    private
+
+    def own_shared
+      Appraisal.shared.where(user_id: hr_current_user.id)
+    end
+  end
+end

data/app/controllers/hr_lite/attendance_controller.rb

@@ -0,0 +1,37 @@
+module HrLite
+  # Employee self-service punch surface. Always operates on hr_current_user —
+  # there is no user param, so punching for someone else is structurally
+  # impossible.
+  class AttendanceController < ApplicationController
+    def show
+      @month = parse_month_param(params[:month])
+      @record = AttendanceRecord.find_by(user_id: hr_current_user.id, date: Date.current)
+      @day_status = DayStatus.new(user: hr_current_user, range: @month.beginning_of_month..@month.end_of_month)
+      @counts = @day_status.counts
+    end
+
+    def check_in
+      punch(:check_in)
+    end
+
+    def check_out
+      punch(:check_out)
+    end
+
+    private
+
+    def punch(kind)
+      result = AttendancePuncher.call(user: hr_current_user, kind: kind, **punch_params.to_h.symbolize_keys)
+      if result.ok?
+        time = Time.current.strftime("%H:%M")
+        redirect_to attendance_path, notice: "#{kind == :check_in ? 'Checked in' : 'Checked out'} at #{time}."
+      else
+        redirect_to attendance_path, alert: result.error
+      end
+    end
+
+    def punch_params
+      params.permit(:lat, :lng, :accuracy_m, :geo_status)
+    end
+  end
+end

data/app/controllers/hr_lite/calendar_controller.rb

@@ -0,0 +1,20 @@
+module HrLite
+  # Server-rendered company calendar: holidays, everyone's approved leaves
+  # and weekend shading for a month. No JS dependency — works everywhere
+  # the engine is mounted.
+  class CalendarController < ApplicationController
+    def show
+      @month = parse_month_param(params[:month])
+      range = @month.beginning_of_month..@month.end_of_month
+      @calendar = WorkingCalendar.new(range)
+      @holidays = Holiday.in_range(range).order(:date).group_by(&:date)
+      @leaves = LeaveRequest.approved.includes(:leave_type, :user)
+                            .overlapping_range(range.first, range.last)
+                            .each_with_object(Hash.new { |h, k| h[k] = [] }) do |request, acc|
+        (request.start_date..request.end_date).each do |date|
+          acc[date] << request if range.cover?(date)
+        end
+      end
+    end
+  end
+end

data/app/controllers/hr_lite/career_controller.rb

@@ -0,0 +1,9 @@
+module HrLite
+  class CareerController < ApplicationController
+    def show
+      @profile = EmployeeProfile.find_by(user_id: hr_current_user.id)
+      @changes = DesignationChange.where(user_id: hr_current_user.id).timeline
+      @appraisals = Appraisal.shared.where(user_id: hr_current_user.id).recent_first.limit(10)
+    end
+  end
+end

data/app/controllers/hr_lite/employee_profiles_controller.rb

@@ -0,0 +1,9 @@
+module HrLite
+  # Read-only masked view of one's own HR profile; edits go through
+  # leadership.
+  class EmployeeProfilesController < ApplicationController
+    def show
+      @profile = EmployeeProfile.find_by(user_id: hr_current_user.id)
+    end
+  end
+end

data/app/controllers/hr_lite/holidays_controller.rb

@@ -0,0 +1,9 @@
+module HrLite
+  class HolidaysController < ApplicationController
+    def index
+      year = params[:year].to_i
+      @year = year.between?(2000, 2100) ? year : Date.current.year
+      @holidays = Holiday.where(date: Date.new(@year, 1, 1)..Date.new(@year, 12, 31)).order(:date)
+    end
+  end
+end

data/app/controllers/hr_lite/home_controller.rb

@@ -0,0 +1,7 @@
+module HrLite
+  class HomeController < ApplicationController
+    def index
+      @latest_kudos = Kudo.recent.includes(:giver, kudo_mentions: :user).limit(3)
+    end
+  end
+end

data/app/controllers/hr_lite/kudos_controller.rb

@@ -0,0 +1,36 @@
+module HrLite
+  class KudosController < ApplicationController
+    def index
+      @kudos = paginate(Kudo.recent.includes(:giver, kudo_mentions: :user))
+      @kudo = Kudo.new
+    end
+
+    def create
+      @kudo = Kudo.new(kudo_params.merge(giver: hr_current_user))
+      if @kudo.save
+        @kudo.register_mentions!
+        redirect_to kudos_path, notice: "Kudos posted."
+      else
+        @kudos = paginate(Kudo.recent.includes(:giver, kudo_mentions: :user))
+        render :index, status: :unprocessable_entity
+      end
+    end
+
+    def destroy
+      kudo = Kudo.find(params[:id])
+      if kudo.deletable_by?(hr_current_user)
+        kudo.destroy!
+        redirect_to kudos_path, notice: "Kudos removed.", status: :see_other
+      else
+        redirect_to kudos_path, alert: "You can only remove your own kudos within 15 minutes.",
+                                status: :see_other
+      end
+    end
+
+    private
+
+    def kudo_params
+      params.require(:kudo).permit(:message, :badge)
+    end
+  end
+end

data/app/controllers/hr_lite/leave_balances_controller.rb

@@ -0,0 +1,11 @@
+module HrLite
+  class LeaveBalancesController < ApplicationController
+    def index
+      year = params[:year].to_i
+      @year = year.between?(2000, 2100) ? year : Date.current.year
+      @balances = LeaveType.active.where(paid: true).where.not(annual_quota: nil).map do |type|
+        LeaveBalance.for(hr_current_user, type, @year)
+      end
+    end
+  end
+end

data/app/controllers/hr_lite/leave_requests_controller.rb

@@ -0,0 +1,56 @@
+module HrLite
+  # Employee self-service: always scoped to hr_current_user — a foreign id
+  # 404s, never 403s.
+  class LeaveRequestsController < ApplicationController
+    def index
+      @requests = paginate(own_requests.recent_first.includes(:leave_type))
+      @balances = balance_cards
+    end
+
+    def show
+      @request = own_requests.find(params[:id])
+    end
+
+    def new
+      @request = LeaveRequest.new(start_date: Date.current, end_date: Date.current)
+      @balances = balance_cards
+    end
+
+    def create
+      @request = LeaveRequest.new(request_params.merge(user_id: hr_current_user.id))
+      if @request.save
+        redirect_to leave_requests_path, notice: "Leave request submitted."
+      else
+        @balances = balance_cards
+        render :new, status: :unprocessable_entity
+      end
+    end
+
+    def cancel
+      request = own_requests.find(params[:id])
+      if request.cancellable_by?(hr_current_user)
+        request.cancel!(actor: hr_current_user)
+        redirect_to leave_requests_path, notice: "Leave cancelled."
+      else
+        redirect_to leave_requests_path, alert: "This request can no longer be cancelled."
+      end
+    end
+
+    private
+
+    def own_requests
+      LeaveRequest.where(user_id: hr_current_user.id)
+    end
+
+    def balance_cards
+      year = Date.current.year
+      LeaveType.active.where(paid: true).where.not(annual_quota: nil).map do |type|
+        LeaveBalance.for(hr_current_user, type, year)
+      end
+    end
+
+    def request_params
+      params.require(:leave_request).permit(:leave_type_id, :start_date, :end_date, :half_day, :reason)
+    end
+  end
+end

data/app/controllers/hr_lite/salary_slips_controller.rb

@@ -0,0 +1,39 @@
+module HrLite
+  # Employee surface: strictly own PUBLISHED slips — a foreign or
+  # unpublished id 404s through the scoped relation, never 403s.
+  class SalarySlipsController < ApplicationController
+    def index
+      @slips = paginate(own_published.recent_first)
+    end
+
+    def show
+      @slip = own_published.find(params[:id])
+
+      respond_to do |format|
+        format.html
+        format.pdf { send_slip_pdf(@slip) }
+      end
+    end
+
+    private
+
+    def own_published
+      SalarySlip.published.where(user_id: hr_current_user.id)
+    end
+
+    def send_slip_pdf(slip)
+      pdf = PdfRenderer.render(
+        template: "hr_lite/salary_slips/pdf",
+        assigns: { slip: slip, profile: slip.user_profile },
+        cache_key: slip.pdf_cache_key
+      )
+      if pdf
+        send_data pdf, filename: "salary-slip-#{slip.period_month.strftime('%Y-%m')}.pdf",
+                       type: "application/pdf", disposition: "inline"
+      else
+        redirect_to salary_slip_path(slip),
+                    alert: "PDF downloads are not configured on this install."
+      end
+    end
+  end
+end

data/app/controllers/hr_lite/users_controller.rb

@@ -0,0 +1,9 @@
+module HrLite
+  # Mention autocomplete source. Available to any signed-in staff member.
+  class UsersController < ApplicationController
+    def search
+      users = HrLite.config.mentionable_users.call(params[:q].to_s)
+      render json: users.map { |u| { value: u.id, text: HrLite.display_name(u) } }
+    end
+  end
+end

data/app/helpers/hr_lite/application_helper.rb

@@ -0,0 +1,105 @@
+module HrLite
+  module ApplicationHelper
+    NAV_ITEMS = [
+      { label: "Home",       path: :root_path,           match: [ "/" ] },
+      { label: "Attendance", path: :attendance_path,     match: [ "/attendance" ] },
+      { label: "Leaves",     path: :leave_requests_path, match: [ "/leave_requests", "/leave_balances" ] },
+      { label: "Calendar",   path: :calendar_path,       match: [ "/calendar", "/holidays" ] },
+      { label: "Kudos",      path: :kudos_path,          match: [ "/kudos" ] },
+      { label: "Slips",      path: :salary_slips_path,   match: [ "/salary_slips" ] },
+      { label: "Career",     path: :career_path,         match: [ "/career", "/appraisals", "/profile" ] }
+    ].freeze
+
+    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" ] }
+    ].freeze
+
+    LEADERSHIP_NAV_ITEMS = [
+      { label: "Employees", path: :admin_employees_path,        match: [ "/admin/employees" ] },
+      { label: "Payroll",   path: :admin_payroll_runs_path,     match: [ "/admin/payroll_runs", "/admin/salary_slips" ] },
+      { label: "Settings",  path: :admin_leave_types_path,      match: [ "/admin/leave_types", "/admin/office_locations", "/admin/holidays", "/admin/setting" ] },
+      { label: "Audit",     path: :admin_audit_logs_path,       match: [ "/admin/audit_logs" ] }
+    ].freeze
+
+    # Only items whose routes exist yet (the nav grows with each phase).
+    def hrl_nav_items(items)
+      items.select { |item| hr_lite_route?(item[:path]) }
+    end
+
+    def hr_lite_route?(helper_name)
+      hr_lite.respond_to?(helper_name)
+    end
+
+    def hrl_nav_link(item)
+      href = hr_lite.public_send(item[:path])
+      active = item[:match].any? do |prefix|
+        prefix == "/" ? request.path == href : request.path.start_with?("#{hr_lite.root_path.chomp('/')}#{prefix}")
+      end
+      link_to item[:label], href, class: "hrl-nav__link #{'hrl-nav__link--active' if active}"
+    end
+
+    # Mention-marker-aware, XSS-safe kudos message rendering. Every literal
+    # chunk is escaped; only markers whose id has a mention row become
+    # highlighted chips (with the CURRENT display name — stale-name safe).
+    def render_kudo_message(kudo)
+      mentioned = kudo.kudo_mentions.index_by(&:user_id)
+      out = +""
+      rest = kudo.message.to_s
+      while (m = HrLite::MentionParser::MARKER.match(rest))
+        out << ERB::Util.html_escape(m.pre_match)
+        mention = mentioned[m[2].to_i]
+        if mention
+          out << %(<span class="hrl-mention">@#{ERB::Util.html_escape(HrLite.display_name(mention.user))}</span>)
+        else
+          out << ERB::Util.html_escape("@#{m[1]}")
+        end
+        rest = m.post_match
+      end
+      out << ERB::Util.html_escape(rest)
+      out.html_safe
+    end
+
+    def hrl_pagination
+      render "hr_lite/shared/pagination"
+    end
+
+    def hrl_money(amount)
+      return "—" if amount.nil?
+
+      whole, fraction = HrLite::Money.round2(amount).to_s("F").split(".")
+      sign = whole.delete_prefix!("-") ? "-" : ""
+      # Indian digit grouping: 12,34,567
+      grouped = whole.reverse.scan(/\d{1,2}(?=\d{2})|\d{1,3}/).join(",").reverse if whole.length > 3
+      grouped ||= whole
+      "#{sign}#{HrLite.config.currency_symbol}#{grouped}.#{fraction.ljust(2, '0')}"
+    end
+
+    ONES = %w[zero one two three four five six seven eight nine ten eleven twelve thirteen fourteen
+              fifteen sixteen seventeen eighteen nineteen].freeze
+    TENS = %w[zero ten twenty thirty forty fifty sixty seventy eighty ninety].freeze
+
+    # Indian-system amount in words for the slip footer.
+    def hrl_amount_in_words(amount)
+      rupees = HrLite::Money.round_rupee(amount).to_i
+      return "Zero rupees" if rupees.zero?
+
+      parts = []
+      [ [ 10_000_000, "crore" ], [ 100_000, "lakh" ], [ 1000, "thousand" ], [ 100, "hundred" ] ].each do |divisor, label|
+        next unless rupees >= divisor
+
+        parts << "#{hrl_two_digit_words(rupees / divisor)} #{label}"
+        rupees %= divisor
+      end
+      parts << hrl_two_digit_words(rupees) if rupees.positive?
+      "#{parts.join(' ').capitalize} rupees"
+    end
+
+    def hrl_two_digit_words(number)
+      return ONES[number] if number < 20
+
+      [ TENS[number / 10], number % 10 == 0 ? nil : ONES[number % 10] ].compact.join("-")
+    end
+  end
+end

data/app/jobs/hr_lite/application_job.rb

@@ -0,0 +1,4 @@
+module HrLite
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/jobs/hr_lite/daily_digest_job.rb

@@ -0,0 +1,33 @@
+module HrLite
+  # Morning leadership email: who's out, what's pending, what's flagged.
+  # Sends nothing on a quiet day.
+  class DailyDigestJob < ActiveJob::Base
+    queue_as :default
+
+    def perform(date: Date.current)
+      query = OverviewQuery.new(date: date)
+      return if query.empty?
+
+      lines = []
+      query.on_leave_today.each do |request|
+        lines << "On leave: #{HrLite.display_name(request.user)} — #{request.leave_type.name} (#{request.date_range_label})"
+      end
+      query.pending_requests.each do |request|
+        lines << "Pending approval: #{HrLite.display_name(request.user)} — #{request.leave_type.name} (#{request.date_range_label})"
+      end
+      query.flagged_today.each do |record|
+        lines << "Flagged punch: #{HrLite.display_name(record.user)} — #{record.flag_note}"
+      end
+      query.missing_checkout_yesterday.each do |record|
+        lines << "Missing checkout yesterday: #{HrLite.display_name(record.user)}"
+      end
+
+      Notifications.publish(
+        "digest.daily",
+        title: "HR daily digest — #{date.strftime('%d %b %Y')}",
+        lines: lines,
+        path: "/admin/overview"
+      )
+    end
+  end
+end

data/app/jobs/hr_lite/leave_year_rollover_job.rb

@@ -0,0 +1,29 @@
+module HrLite
+  # Jan-1 rollover: materialize carry-forward into the new year's balance
+  # rows. Idempotent — a balance whose carry has already been written is
+  # never touched again (manual adjustments stay safe).
+  class LeaveYearRolloverJob < ActiveJob::Base
+    queue_as :default
+
+    def perform(year: Date.current.year)
+      previous_year = year - 1
+
+      LeaveType.active.where(paid: true).where.not(annual_quota: nil).find_each do |type|
+        next unless type.carry_forward_cap.positive?
+
+        HrLite.employees.each do |user|
+          balance = LeaveBalance.for(user, type, year)
+          next if balance.persisted? && balance.carried_forward.positive?
+
+          carry = LeaveBalance.for(user, type, previous_year)
+                              .available(as_of: Date.new(previous_year, 12, 31))
+          carry = [ [ carry, type.carry_forward_cap ].min, 0 ].max
+          next if carry.zero? && balance.persisted?
+
+          balance.carried_forward = carry
+          balance.save!
+        end
+      end
+    end
+  end
+end

data/app/mailers/hr_lite/application_mailer.rb

@@ -0,0 +1,5 @@
+module HrLite
+  class ApplicationMailer < ActionMailer::Base
+    layout "hr_lite/mailer"
+  end
+end