hr_lite 0.60.0 → 0.61.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 051c3d4efb869bb1c40f819e884e245c5d45462c2664a62464c84ec2686b750e
-  data.tar.gz: 263dbc61a8861a69b06b0b6597542e496feac6fd3bb6eb78cadd04a947681f41
+  metadata.gz: d57f2981c5062477e62d5cf7518fb074dfedccd73de6338d3263ce57143dd824
+  data.tar.gz: eb27ceb943445189d60db425d2fd7250d89fbb6e118f48b456d0a33eb22dfc4b
 SHA512:
-  metadata.gz: c4b151e5a71926157f4976df9ad3fd55f3b60468c6f0d10f7877d2fc9c2363e1ebe7d5d9a86961660848744a840e9b96f597cc1207d86168f20dd7410096ba60
-  data.tar.gz: c457f267dc96c0b89278bf870f431174204cb258879cb68e90b152ef37d224354068732b2b118678e6b1329cf24351c5a26dca8672e120549d83c3b906e622a1
+  metadata.gz: 128a548490e3eb5c3028c197eb352e14419d200bbff36c79c7237bb4f355b666dd525ad7a0e54a7d1c8f6814d3b8165e3311215ab8f17dd81ac20460ae47b926
+  data.tar.gz: 84179555ec4cf9ea6623071e0f72da671ff3f17f69f9d4771fbe6a833e6ba77ca6edcab85bbeebbf835d6aee2d2a23ee1f61d1cba42f7f26186e6d61d246ca14

data/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.61.0] - 2026-10-21
+
+Hiring panel. Six migrations: five new tables and one that grants `hiring.manage` to HR, Leadership and Super Admin and seeds the first outreach email.
+
+- **Campaigns.** One per opening. Position, programme, stipend, CTC, location and schedule live on the campaign and fill the email's @placeholders.
+- **Sheet import with a preview.** Headers are matched through an alias list after case-folding and dropping punctuation, so each university's spelling works. Unknown columns are kept as extra data and usable as @placeholders. Two columns claiming one field wait for HR to pick one. Every skipped row says why, a repeat upload updates instead of duplicating, and nothing is saved before confirm. Phone and date of birth are encrypted. `config.read_sheet` reads the file (default: .csv only).
+- **Bulk email from one mailbox.** A confirm page names everyone left out (already sent, or a placeholder empty or unknown). One spaced job per recipient goes through `config.hiring.send_email`, and a unique index plus a claimed row stop double sends. An answer that never came is marked for a person to check, never resent. Sends are limited to ten an hour per person.
+- **Pipeline and timeline.** The stages are imported, invited, interested, not interested, interview (round N), selected, rejected and on hold. Moves the pipeline does not allow are refused, a rejection needs a listed reason, and every change goes on the candidate's timeline with who made it.
+- **Interview invites.** Rounds go on the hiring mailbox's Google Calendar through `config.hiring`, with reschedule and cancel. Each round is its own row.
+
 ## [0.60.0] - 2026-10-21
 
 Background failures reach a person. No migrations.

data/README.md

@@ -376,6 +376,20 @@ permission reaches (`leave.view`, `payroll.view`, `expense.approve`,
 Leadership picks Employee of the Month, Quarter and Year at `/admin/awards`,
 and Home shows the current winners to everyone.
 
+## Hiring
+
+Admin › Hiring (`hiring.manage`): campaigns, candidate sheet import, bulk email, interview rounds and decisions. The engine never talks to Google itself. Set `config.hiring` to an object with:
+
+```ruby
+sender                      # => { email:, name:, ready:, connect_url: }
+send_email(to:, subject:, body:)               # => { message_id:, thread_id: } (plain text)
+create_event(summary:, description:, attendee:, starts_at:, ends_at:) # => { event_id:, meet_link: }
+update_event(event_id:, starts_at:, ends_at:)
+cancel_event(event_id:)
+```
+
+Raise `HrLite::HiringDeliveryFailed` when nothing was sent and `HrLite::HiringDeliveryUnknown` when the provider may have acted (timeouts, 5xx). Never put the recipient in the error text: it is stored. `config.read_sheet = ->(path, filename) { rows }` reads uploads (default: .csv).
+
 ## Recurring jobs
 
 Schedule these on the host's job scheduler (cron, GoodJob, Sidekiq-cron,

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

@@ -653,3 +653,23 @@ a.hrl-tree__name { display: inline-flex; align-items: center; min-height: var(--
 .hrl-search__close { display: flex; justify-content: flex-end; margin: 0 0 var(--hrl-s-2); }
 .hrl-search::backdrop { background: rgb(15 23 42 / .4); }
 .hrl-search__list { list-style: none; margin: var(--hrl-s-1) 0 0; padding: 0; display: grid; gap: var(--hrl-s-2); }
+/* Hiring email preview: plain text, so its line breaks are the email's. */
+.hrl-hiring-preview { white-space: pre-line; overflow-wrap: anywhere; padding: var(--hrl-s-4); border: 1px solid var(--hrl-line); border-radius: var(--hrl-radius-sm); background: var(--hrl-bg); }
+/* Hiring candidate: actions first on a phone, a right-hand column on desktop. */
+@media (min-width: 1024px) {
+  .hrl-grid--side { grid-template-columns: 2fr 1fr; align-items: start; }
+  .hrl-grid--side > .hrl-grid__aside { grid-column: 2; grid-row: 1 / span 9; }
+}
+.hrl-card--next { background: var(--hrl-info-bg); border-color: transparent; }
+.hrl-hiring-decide > .button_to { flex: 1 1 8rem; }
+.hrl-hiring-decide > .button_to .hrl-btn { width: 100%; }
+.hrl-hiring-person { display: flex; align-items: center; gap: var(--hrl-s-3); width: 100%; }
+.hrl-hiring-avatar { flex: none; width: 52px; height: 52px; border-radius: var(--hrl-radius-pill); background: var(--hrl-info-bg); color: var(--hrl-accent); display: grid; place-items: center; font: 700 var(--hrl-t-lead) var(--hrl-font-head); }
+/* Pipeline stepper: a number until reached, a tick once passed. */
+.hrl-steps { list-style: none; margin: 0; padding: 0; display: grid; grid-template-columns: repeat(5, minmax(0, 1fr)); gap: var(--hrl-s-1); text-align: center; }
+.hrl-steps li { display: grid; justify-items: center; gap: var(--hrl-s-1); font-size: var(--hrl-t-micro); color: var(--hrl-ink-2); }
+.hrl-steps__dot { width: 28px; height: 28px; border-radius: var(--hrl-radius-pill); display: grid; place-items: center; font-weight: 700; border: 1px solid var(--hrl-line); background: var(--hrl-card); color: var(--hrl-muted); }
+.hrl-steps .is-done .hrl-steps__dot { background: var(--hrl-ok); border-color: var(--hrl-ok); color: var(--hrl-accent-ink); }
+.hrl-steps .is-now .hrl-steps__dot { background: var(--hrl-accent); border-color: var(--hrl-accent); color: var(--hrl-accent-ink); }
+.hrl-steps .is-now { font-weight: 700; color: var(--hrl-accent); }
+.hrl-mail__head { display: grid; gap: var(--hrl-s-2); padding-bottom: var(--hrl-s-3); margin-bottom: var(--hrl-s-3); border-bottom: 1px solid var(--hrl-line); overflow-wrap: anywhere; }

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

@@ -0,0 +1,88 @@
+module HrLite
+  module Admin
+    # Hiring drives: the list, one campaign's pipeline, and its sheet import.
+    class HiringCampaignsController < ApplicationController
+      FIELDS = %i[title position programme stipend ctc location schedule status].freeze
+
+      before_action { hr_require_permission!("hiring.manage", scope: :all) }
+      before_action :set_campaign, except: %i[index new create]
+
+      def index
+        @campaigns = paginate(HiringCampaign.newest_first)
+        @counts = HiringCandidate.where(campaign_id: @campaigns.map(&:id)).group(:campaign_id, :stage).count
+      end
+
+      def show
+        @stage = params[:stage].presence_in(HiringCandidate::STAGES)
+        @campus = params[:campus].presence
+        @stage_counts = @campaign.candidates.group(:stage).count
+        @campuses = @campaign.candidates.where.not(campus: [ nil, "" ]).distinct.order(:campus).pluck(:campus)
+        @candidates = paginate(@campaign.pipeline(stage: @stage, campus: @campus))
+        @templates = HiringTemplate.alphabetical
+        @attention = HiringMessage.joins(:candidate).where(hr_lite_hiring_candidates: { campaign_id: @campaign.id })
+                                  .where(status: %w[failed unknown sending]).includes(:candidate, :template).limit(50)
+      end
+
+      # A new campaign starts from the last one's offer: HR edits what changed.
+      def new
+        @campaign = HiringCampaign.new(HiringCampaign.newest_first.first&.slice(*FIELDS.excluding(:title, :status)))
+      end
+
+      def create
+        @campaign = HiringCampaign.new(campaign_params)
+        return render(:new, status: :unprocessable_entity) unless @campaign.save
+
+        redirect_to hr_lite.admin_hiring_campaign_path(@campaign), notice: "Campaign created. Upload the candidate sheet next."
+      end
+
+      def edit; end
+
+      def update
+        return render(:edit, status: :unprocessable_entity) unless @campaign.update(campaign_params)
+
+        redirect_to hr_lite.admin_hiring_campaign_path(@campaign), notice: "Saved."
+      end
+
+      # GET: the upload form. POST with a file: the preview. POST with the
+      # sealed rows and confirm: the import. Nothing is saved before confirm.
+      def import
+        return if request.get?
+
+        rows = params[:sheet].present? ? read_sheet(params[:sheet]) : sealer.decrypt_and_verify(params[:rows].to_s)
+        @import = HiringImport.new(@campaign, rows, picks: params.fetch(:picks, {}).permit!.to_h)
+        if params[:confirm].present? && @import.import!
+          counts = @import.counts
+          return redirect_to hr_lite.admin_hiring_campaign_path(@campaign),
+                             notice: "#{counts['create']} added, #{counts['update']} updated, #{counts['skip']} skipped."
+        end
+        @sealed = sealer.encrypt_and_sign(rows, expires_in: 1.hour)
+        render :preview
+      rescue ArgumentError => e
+        redirect_to hr_lite.import_admin_hiring_campaign_path(@campaign), alert: e.message
+      rescue ActiveSupport::MessageEncryptor::InvalidMessage
+        redirect_to hr_lite.import_admin_hiring_campaign_path(@campaign), alert: "That preview expired. Upload the sheet again."
+      rescue ActiveRecord::RecordNotUnique
+        redirect_to hr_lite.import_admin_hiring_campaign_path(@campaign), alert: "Another import ran at the same time. Upload the sheet again."
+      end
+
+      private
+
+      def set_campaign = @campaign = HiringCampaign.find(params[:id])
+      def campaign_params = params.require(:hiring_campaign).permit(*FIELDS)
+
+      def read_sheet(file)
+        rows = HrLite.config.read_sheet.call(file.tempfile.path, file.original_filename)
+        Array(rows).map { |row| Array(row).map { |cell| HiringImport.text(cell) } }
+      rescue ArgumentError
+        raise
+      rescue StandardError
+        raise ArgumentError, "That file could not be read. Save it as .xlsx or .csv with the headers in the first row."
+      end
+
+      # The previewed rows ride in the form, encrypted, so nothing touches disk.
+      def sealer
+        ActiveSupport::MessageEncryptor.new(Rails.application.key_generator.generate_key("hr_lite.hiring_import", 32))
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+module HrLite
+  module Admin
+    # One candidate: what we know, every email and interview, the timeline,
+    # and the decisions HR makes by hand.
+    class HiringCandidatesController < ApplicationController
+      # Invited and interview come from sending and scheduling, never a button.
+      MANUAL = %w[interested not_interested selected rejected on_hold].freeze
+
+      before_action { hr_require_permission!("hiring.manage", scope: :all) }
+      before_action { @candidate = HiringCandidate.includes(:campaign).find(params[:id]) }
+
+      def show
+        @messages = @candidate.messages.includes(:template).order(:created_at)
+        @interviews = @candidate.interviews.order(:round, :created_at)
+        @timeline = @candidate.timeline.limit(100)
+      end
+
+      def stage
+        to = params[:to].presence_in(MANUAL) or raise ArgumentError, "That is not a decision HR makes here."
+        @candidate.move_to!(to, reason: params[:reason], note: params[:note])
+        redirect_to hr_lite.admin_hiring_candidate_path(@candidate), notice: "Moved to #{@candidate.stage_label}."
+      rescue ArgumentError => e
+        redirect_to hr_lite.admin_hiring_candidate_path(@candidate), alert: e.message
+      end
+    end
+  end
+end

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

@@ -0,0 +1,77 @@
+module HrLite
+  module Admin
+    # Interview rounds on the hiring mailbox's Google Calendar. The row is
+    # written before Google is called, so an answer that never arrives still
+    # leaves a record ("unknown") for HR to check.
+    class HiringInterviewsController < ApplicationController
+      LENGTHS = [ 30, 45, 60 ].freeze
+
+      before_action { hr_require_permission!("hiring.manage", scope: :all) }
+      before_action { @candidate = HiringCandidate.includes(:campaign).find(params[:hiring_candidate_id]) }
+      before_action(except: :create) { @interview = @candidate.interviews.find(params[:id]) }
+      before_action :require_calendar!
+
+      def create
+        return back(alert: "#{@candidate.stage_label} cannot be interviewed.") unless HiringCandidate::MOVES.fetch(@candidate.stage).include?("interview")
+        return back(alert: "Pick a date and time in the future.") unless (starts, ends = slot)
+
+        round = @candidate.interviews.where(status: %w[scheduled unknown]).maximum(:round).to_i + 1
+        @interview = @candidate.interviews.create!(round: round, starts_at: starts, ends_at: ends)
+        ids = adapter.create_event(summary: "Interview: #{@candidate.campaign.position} (round #{round})",
+                                   description: "#{@candidate.campaign.title}. Join with the Google Meet link in this invite.",
+                                   attendee: @candidate.email, starts_at: starts, ends_at: ends)
+        @interview.update!(status: "scheduled", event_id: ids[:event_id], meet_link: ids[:meet_link])
+        @candidate.move_to!("interview", round: round)
+        @candidate.log!("interview_scheduled", round: round, starts_at: starts.iso8601)
+        back(notice: "Invite sent for round #{round}.")
+      rescue HrLite::HiringDeliveryUnknown, HrLite::HiringDeliveryFailed => e
+        google_trouble(e, "interview_scheduled")
+      end
+
+      def update
+        return back(alert: "Pick a date and time in the future.") unless (starts, ends = slot)
+        adapter.update_event(event_id: @interview.event_id, starts_at: starts, ends_at: ends)
+        @interview.update!(starts_at: starts, ends_at: ends)
+        @candidate.log!("interview_rescheduled", round: @interview.round, starts_at: starts.iso8601)
+        back(notice: "Round #{@interview.round} moved. Google told the candidate.")
+      rescue HrLite::HiringDeliveryUnknown, HrLite::HiringDeliveryFailed => e
+        google_trouble(e, "interview_rescheduled")
+      end
+
+      def destroy
+        adapter.cancel_event(event_id: @interview.event_id) if @interview.event_id
+        @interview.update!(status: "cancelled")
+        @candidate.log!("interview_cancelled", round: @interview.round)
+        back(notice: "Round #{@interview.round} cancelled. Google told the candidate.")
+      rescue HrLite::HiringDeliveryUnknown, HrLite::HiringDeliveryFailed => e
+        google_trouble(e, "interview_cancelled")
+      end
+
+      private
+
+      def adapter = HrLite.config.hiring
+      def back(**flash) = redirect_to(hr_lite.admin_hiring_candidate_path(@candidate), **flash)
+
+      def require_calendar!
+        back(alert: "Connect the hiring mailbox before scheduling.") unless adapter&.sender&.dig(:ready)
+      end
+
+      def slot
+        starts = Time.zone.parse("#{params[:date]} #{params[:time]}")
+        return unless starts&.future?
+
+        minutes = LENGTHS.include?(params[:minutes].to_i) ? params[:minutes].to_i : LENGTHS.first
+        [ starts, starts + minutes.minutes ]
+      rescue ArgumentError
+        nil
+      end
+
+      def google_trouble(error, action)
+        unknown = error.is_a?(HrLite::HiringDeliveryUnknown)
+        @interview.update!(status: unknown ? "unknown" : "failed", error: error.message.to_s.truncate(200)) if action == "interview_scheduled"
+        @candidate.log!("#{action}_#{unknown ? 'unknown' : 'failed'}", round: @interview.round)
+        back(alert: unknown ? "Google did not confirm. Check the hiring calendar before trying again." : "Google refused: #{error.message}")
+      end
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+module HrLite
+  module Admin
+    # Bulk email: a confirm page that says exactly who gets it and who is
+    # left out (and why), then one queued job per recipient, spaced out.
+    class HiringSendsController < ApplicationController
+      SPACING = 3.seconds
+
+      before_action { hr_require_permission!("hiring.manage", scope: :all) }
+      rate_limit to: 10, within: 1.hour, only: :create, name: "hiring_send", by: -> { hr_current_user.id },
+                 with: -> { redirect_to hr_lite.admin_hiring_campaigns_path, alert: "Ten sends in an hour is the limit. Try again later." }
+
+      def new
+        load_recipients
+      end
+
+      def create
+        load_recipients
+        unless @sender&.dig(:ready)
+          return redirect_to hr_lite.admin_hiring_campaign_path(@campaign), alert: "Connect the hiring mailbox before sending."
+        end
+
+        batch = SecureRandom.uuid
+        queued = @recipients.filter_map do |candidate|
+          HiringMessage.create!(candidate: candidate, template: @template, batch: batch, sent_by: hr_current_user)
+        rescue ActiveRecord::RecordNotUnique
+          nil # already queued by another click
+        end
+        queued.each_with_index { |message, i| HiringSendJob.set(wait: SPACING * i).perform_later(message.id) }
+        AuditLog.record!(action: "hiring.batch", subject: @campaign,
+                         changes: { "template" => @template.name, "recipients" => queued.size, "batch" => batch })
+        redirect_to hr_lite.admin_hiring_campaign_path(@campaign), notice: "#{queued.size} emails queued from #{@sender[:email]}."
+      end
+
+      # Only a definite failure is sent again; "unknown" may already be in Gmail.
+      def retry
+        message = HiringMessage.find(params[:id])
+        if message.status == "failed"
+          message.update!(status: "queued", error: nil, sent_by: hr_current_user)
+          HiringSendJob.perform_later(message.id)
+        end
+        redirect_to hr_lite.admin_hiring_campaign_path(message.candidate.campaign_id), notice: "Queued again."
+      end
+
+      private
+
+      # Recomputed on every request from the ids: the confirm page is never trusted.
+      def load_recipients
+        @campaign = HiringCampaign.find(params[:hiring_campaign_id])
+        @template = HiringTemplate.find(params[:template_id])
+        @sender = HrLite.config.hiring&.sender
+        scope = params[:all].present? ? @campaign.pipeline(stage: params[:stage], campus: params[:campus]) : @campaign.pipeline.where(id: Array(params[:candidate_ids]))
+        already = HiringMessage.where(template: @template, candidate_id: scope.select(:id)).pluck(:candidate_id).to_set
+        @recipients, @left_out = [], []
+        scope.includes(:campaign, :interviews).each do |candidate|
+          missing = HiringMerge.new(candidate, sender_name: @sender&.dig(:name)).render(@template).missing
+          reason = already.include?(candidate.id) ? "already sent this template" : (missing.join(", ") if missing.any?)
+          reason ? @left_out << [ candidate, reason ] : @recipients << candidate
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+module HrLite
+  module Admin
+    # Hiring emails HR writes once and sends to many, with a preview filled
+    # for a real candidate.
+    class HiringTemplatesController < ApplicationController
+      before_action { hr_require_permission!("hiring.manage", scope: :all) }
+      before_action(only: %i[edit update]) { @template = HiringTemplate.find(params[:id]) }
+
+      def index = @templates = HiringTemplate.alphabetical
+      def new = @template = HiringTemplate.new
+
+      def create
+        @template = HiringTemplate.new(template_params)
+        return render(:new, status: :unprocessable_entity) unless @template.save
+
+        redirect_to hr_lite.edit_admin_hiring_template_path(@template), notice: "Saved."
+      end
+
+      def edit = load_preview
+
+      def update
+        return load_preview && render(:edit, status: :unprocessable_entity) unless @template.update(template_params)
+
+        redirect_to hr_lite.edit_admin_hiring_template_path(@template), notice: "Saved."
+      end
+
+      private
+
+      def load_preview
+        @sample = HiringCandidate.includes(:campaign, :interviews).order(updated_at: :desc).limit(200).to_a
+        @preview_for = @sample.find { |c| c.id == params[:candidate_id].to_i } || @sample.first
+        return true unless @preview_for
+
+        sender_name = HrLite.config.hiring&.sender&.dig(:name)
+        @preview = HiringMerge.new(@preview_for, sender_name:).render(@template)
+        # Readiness across the previewed candidate's campaign: who a send would reach.
+        @campaign_size = @preview_for.campaign.candidates.count
+        @ready = @preview_for.campaign.candidates.includes(:campaign, :interviews).count { |c| HiringMerge.new(c, sender_name:).render(@template).missing.empty? }
+        true
+      end
+
+      def template_params = params.require(:hiring_template).permit(:name, :subject, :body)
+    end
+  end
+end

data/app/helpers/hr_lite/application_helper.rb

@@ -88,6 +88,10 @@ module HrLite
         { label: "Help desk", path: :admin_hr_requests_path, match: [ "/admin/hr_requests" ], if: -> { hr_can?("hr_request.manage", scope: :all) } },
         { label: "Manage policies", path: :admin_policies_path, match: [ "/admin/policies" ], if: -> { hr_can?("policy.manage", scope: :all) } }
       ] },
+      { label: "Hiring", tabs: [
+        { label: "Campaigns", path: :admin_hiring_campaigns_path, match: [ "/admin/hiring_campaigns", "/admin/hiring_candidates" ], if: -> { hr_can?("hiring.manage", scope: :all) } },
+        { label: "Email templates", path: :admin_hiring_templates_path, match: [ "/admin/hiring_templates" ], if: -> { hr_can?("hiring.manage", scope: :all) } }
+      ] },
       { label: "Admin", divider: true, tabs: [
         { label: "Settings", path: :admin_leave_types_path, match: [ "/admin/leave_types", "/admin/office_locations", "/admin/holidays", "/admin/expense_categories" ], if: LEAD },
         { label: "HR settings", path: :edit_admin_setting_path, match: [ "/admin/setting" ], if: LEAD },
@@ -194,6 +198,7 @@ module HrLite
       "People" => '<path d="M16 21v-2a4 4 0 0 0-4-4H6a4 4 0 0 0-4 4v2"/><circle cx="9" cy="7" r="4"/><path d="M22 21v-2a4 4 0 0 0-3-3.9M16 3.1a4 4 0 0 1 0 7.8"/>',
       "Me" => '<circle cx="12" cy="8" r="4"/><path d="M4 21a8 8 0 0 1 16 0"/>',
       "Help" => '<circle cx="12" cy="12" r="9"/><path d="M9.1 9a3 3 0 0 1 5.8 1c0 2-3 3-3 3M12 17h.01"/>',
+      "Hiring" => '<rect x="2" y="7" width="20" height="14" rx="2"/><path d="M16 21V5a2 2 0 0 0-2-2h-4a2 2 0 0 0-2 2v16"/>',
       "Admin" => '<path d="M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z"/>',
       "More" => '<circle cx="5" cy="12" r="1.5"/><circle cx="12" cy="12" r="1.5"/><circle cx="19" cy="12" r="1.5"/>',
       "Search" => '<circle cx="11" cy="11" r="7"/><path d="m20 20-3.5-3.5"/>'
@@ -253,6 +258,39 @@ module HrLite
       hr_lite.public_send(helper, approval.subject_id)
     end
 
+    HIRING_BADGES = { "imported" => "muted", "invited" => "info", "interested" => "ok", "not_interested" => "bad",
+                      "interview" => "warn", "selected" => "ok", "rejected" => "bad", "on_hold" => "muted" }.freeze
+
+    def hrl_hiring_badge(candidate)
+      modifier = HIRING_BADGES.fetch(candidate.stage)
+      tag.span(candidate.stage_label, class: [ "hrl-badge", ("hrl-badge--#{modifier}" unless modifier == "info") ])
+    end
+
+    # The five steps of the candidate stepper: [label, :done|:now|:todo].
+    HIRING_STEPS = %w[Imported Invited Interested Interview Decision].freeze
+    HIRING_STEP_OF = { "imported" => 0, "invited" => 1, "interested" => 2, "not_interested" => 2, "interview" => 3,
+                       "selected" => 4, "rejected" => 4, "on_hold" => 4 }.freeze
+
+    def hrl_hiring_steps(candidate)
+      at = HIRING_STEP_OF.fetch(candidate.stage)
+      HIRING_STEPS.each_with_index.map do |label, i|
+        label = candidate.stage_label if i == at && %w[not_interested interview selected rejected on_hold].include?(candidate.stage)
+        [ label, i < at ? :done : (i == at ? :now : :todo) ]
+      end
+    end
+
+    # One line per hiring timeline row, from the whitelisted changes it stored.
+    def hrl_hiring_event(log)
+      c = log.audited_changes.to_h
+      at = c["starts_at"] && Time.zone.parse(c["starts_at"]).strftime("%-d %b %Y, %-l:%M %p")
+      case log.action.delete_prefix("hiring.")
+      when "stage" then [ "Moved to #{c['to'].to_s.humanize}", c["reason"] ].compact.join(": ")
+      when /\Aemail_(\w+)\z/ then "Email #{Regexp.last_match(1)}: #{c['template']}"
+      when /\Ainterview_(\w+)\z/ then [ "Round #{c['round']} #{Regexp.last_match(1).tr('_', ' ')}", at ].compact.join(" for ")
+      else log.action.delete_prefix("hiring.").humanize
+      end
+    end
+
     def hrl_pagination
       render "hr_lite/shared/pagination"
     end

data/app/jobs/hr_lite/hiring_send_job.rb

@@ -0,0 +1,42 @@
+module HrLite
+  # Sends one queued hiring email through the host's mail adapter. The first
+  # step claims the row, so a redelivered or parallel job finds it taken and
+  # stops: a send is attempted at most once. A crash after the claim leaves
+  # "sending", which the screens show as "check Gmail", never as "send again".
+  # Adapter errors must not quote the recipient: their text is stored.
+  class HiringSendJob < ApplicationJob
+    queue_as :default
+
+    def perform(message_id)
+      return unless HiringMessage.where(id: message_id, status: "queued").update_all(status: "sending", updated_at: Time.current) == 1
+
+      message = HiringMessage.find(message_id)
+      HrLite::Current.set(actor: message.sent_by) { deliver(message) }
+    end
+
+    private
+
+    def deliver(message)
+      candidate = message.candidate
+      adapter = HrLite.config.hiring
+      sender = adapter&.sender
+      return finish(message, "failed", error: "No sender mailbox is connected") unless sender&.dig(:ready)
+
+      mail = HiringMerge.new(candidate, sender_name: sender[:name]).render(message.template)
+      return finish(message, "failed", error: "Missing #{mail.missing.join(', ')}") if mail.missing.any?
+
+      ids = adapter.send_email(to: candidate.email, subject: mail.subject, body: mail.body)
+      finish(message, "sent", sent_at: Time.current, gmail_message_id: ids[:message_id], gmail_thread_id: ids[:thread_id])
+      candidate.move_to!("invited") if candidate.stage == "imported"
+    rescue HrLite::HiringDeliveryUnknown => e
+      finish(message, "unknown", error: e.message.to_s.truncate(200))
+    rescue HrLite::HiringDeliveryFailed => e
+      finish(message, "failed", error: e.message.to_s.truncate(200))
+    end
+
+    def finish(message, status, **attributes)
+      message.update!(status: status, **attributes)
+      message.candidate.log!("email_#{status}", template: message.template.name)
+    end
+  end
+end

data/app/models/hr_lite/hiring_campaign.rb

@@ -0,0 +1,21 @@
+module HrLite
+  # One hiring drive for one opening. Its fields fill the @placeholders in
+  # every email, so the offer lives here, never in template copy.
+  class HiringCampaign < ApplicationRecord
+    has_many :candidates, class_name: "HrLite::HiringCandidate", foreign_key: :campaign_id,
+                          inverse_of: :campaign, dependent: :restrict_with_error
+
+    validates :title, :position, presence: true
+    validates :status, inclusion: { in: %w[open closed] }
+
+    scope :newest_first, -> { order(created_at: :desc) }
+
+    # The pipeline list and "select all" on it are the same filter.
+    def pipeline(stage: nil, campus: nil)
+      scope = candidates
+      scope = scope.where(stage: stage) if stage.presence_in(HiringCandidate::STAGES)
+      scope = scope.where(campus: campus) if campus.present?
+      scope.order(:name, :id)
+    end
+  end
+end

data/app/models/hr_lite/hiring_candidate.rb

@@ -0,0 +1,52 @@
+module HrLite
+  # A person from a university's sheet, moving through one campaign. Every
+  # change goes on their timeline (AuditLog rows whose subject is them).
+  class HiringCandidate < ApplicationRecord
+    STAGES = %w[imported invited interested not_interested interview selected rejected on_hold].freeze
+    # Where a stage may go next. Sending moves imported → invited; scheduling moves to interview.
+    MOVES = {
+      "imported" => %w[invited interested not_interested],
+      "invited" => %w[interested not_interested],
+      "interested" => %w[interview not_interested on_hold rejected],
+      "not_interested" => %w[interested],
+      "interview" => %w[interview selected rejected on_hold],
+      "on_hold" => %w[interview selected rejected],
+      "selected" => [], "rejected" => []
+    }.freeze
+    REJECTION_REASONS = [ "Communication skills", "Not available for 6 months", "Location / relocation",
+                          "Stipend not acceptable", "Did not attend interview", "Other" ].freeze
+
+    belongs_to :campaign, class_name: "HrLite::HiringCampaign", inverse_of: :candidates
+    has_many :messages, class_name: "HrLite::HiringMessage", foreign_key: :candidate_id, dependent: :restrict_with_error
+    has_many :interviews, class_name: "HrLite::HiringInterview", foreign_key: :candidate_id, dependent: :restrict_with_error
+
+    encrypts :phone, :date_of_birth
+    normalizes :email, with: ->(email) { email.to_s.strip.downcase }
+
+    validates :name, presence: true
+    validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }, uniqueness: { scope: :campaign_id }
+    validates :stage, inclusion: { in: STAGES }
+
+    def first_name = name.to_s.split.first
+    def stage_label = stage == "interview" ? "Interview · round #{round}" : stage.humanize
+    def timeline = AuditLog.where(subject_type: self.class.name, subject_id: id).includes(:actor).order(created_at: :desc, id: :desc)
+
+    # The one door for a stage change: refuses a move the pipeline does not
+    # allow, needs a listed reason to reject, and writes the timeline row.
+    def move_to!(to, reason: nil, note: nil, round: self.round)
+      raise ArgumentError, "#{stage_label} cannot move to #{to.humanize}." unless MOVES.fetch(stage).include?(to)
+      raise ArgumentError, "Pick a rejection reason." if to == "rejected" && !REJECTION_REASONS.include?(reason)
+      raise ArgumentError, "Write a note for “Other”." if reason == "Other" && note.blank?
+
+      transaction do
+        from = stage
+        update!(stage: to, round: round, rejection_reason: (to == "rejected" ? [ reason, note.presence ].compact.join(": ") : rejection_reason))
+        log!("stage", from: from, to: to, reason: (reason if to == "rejected"))
+      end
+    end
+
+    def log!(action, actor: HrLite::Current.actor, **changes)
+      AuditLog.record!(action: "hiring.#{action}", subject: self, actor: actor, changes: changes.compact)
+    end
+  end
+end

data/app/models/hr_lite/hiring_interview.rb

@@ -0,0 +1,13 @@
+module HrLite
+  # One interview round on the sender's Google Calendar. A new round is a new
+  # row, so earlier rounds keep their own history.
+  class HiringInterview < ApplicationRecord
+    STATUSES = %w[unknown scheduled failed cancelled].freeze
+
+    belongs_to :candidate, class_name: "HrLite::HiringCandidate"
+
+    validates :status, inclusion: { in: STATUSES }
+    validates :round, numericality: { greater_than: 0 }
+    validates :starts_at, :ends_at, presence: true
+  end
+end

data/app/models/hr_lite/hiring_message.rb

@@ -0,0 +1,14 @@
+module HrLite
+  # One template sent (or being sent) to one candidate. The unique index on
+  # candidate + template is what makes a repeated click or job a no-op.
+  # "sending" left behind by a crash, and "unknown", both mean: look in Gmail.
+  class HiringMessage < ApplicationRecord
+    STATUSES = %w[queued sending sent failed unknown].freeze
+
+    belongs_to :candidate, class_name: "HrLite::HiringCandidate"
+    belongs_to :template, class_name: "HrLite::HiringTemplate"
+    belongs_to :sent_by, class_name: HrLite.config.user_class, optional: true
+
+    validates :status, inclusion: { in: STATUSES }
+  end
+end

data/app/models/hr_lite/hiring_template.rb

@@ -0,0 +1,11 @@
+module HrLite
+  # An email HR writes once and sends to many. @placeholders are filled per
+  # candidate by HiringMerge at send time.
+  class HiringTemplate < ApplicationRecord
+    has_many :messages, class_name: "HrLite::HiringMessage", foreign_key: :template_id, dependent: :restrict_with_error
+
+    validates :name, :subject, :body, presence: true
+
+    scope :alphabetical, -> { order(:name) }
+  end
+end