hr_lite 0.31.0 → 0.35.1

data/app/services/hr_lite/attendance_puncher.rb

@@ -7,17 +7,23 @@ module HrLite
     # What the browser can legitimately report (geo_punch.js).
     GEO_STATUSES = %w[ok denied unavailable timeout insecure].freeze
     OFF_SITE_MESSAGE = "You are not within the office location. Please request Work From Home (WFH) approval from HR.".freeze
+    HOME_OFF_SITE_MESSAGE = "You are outside your registered WFH location. Please select an approved location " \
+                            "or switch to Travelling Mode if you are travelling.".freeze
+    NO_HOME_MESSAGE = "You have WFH today but no approved WFH location. Register one under WFH locations and ask HR to approve it.".freeze
+    FIELD_MODES = %w[travelling outside_meeting].freeze
 
     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
+    # field: { mode:, purpose:, place: } — a field-staff check-in away from the office.
+    def self.call(user:, kind:, lat: nil, lng: nil, accuracy_m: nil, geo_status: "ok", field: {})
+      new(user, kind.to_sym, lat, lng, accuracy_m, geo_status.to_s, field.to_h.symbolize_keys).call
     end
 
-    def initialize(user, kind, lat, lng, accuracy_m, geo_status)
+    def initialize(user, kind, lat, lng, accuracy_m, geo_status, field = {})
       @user = user
+      @field = field.transform_values { |v| v.to_s.strip.presence }.compact
       @kind = kind
       @lat = lat.presence
       @lng = lng.presence
@@ -48,8 +54,9 @@ module HrLite
           return Result.new(record: record, error: already_in_message(record)) if record.check_in_at.present?
 
           stamp(record, :check_in)
-          record.wfh = !!@remote
-          record.wfh_request_id = @wfh&.id if @remote
+          record.work_mode = @mode
+          record.work_location_id = @location&.id
+          record.wfh_request_id = @wfh&.id if @mode == "wfh"
         when :check_out
           return Result.new(record: record, error: "Check in first.") if record.check_in_at.blank?
 
@@ -61,6 +68,7 @@ module HrLite
         apply_geo_flags(record)
         record.save!
         apply_slot_rules(record) if @kind == :check_in && HrLite.config.attendance_slots
+        track_work_mode(record) if HrLite.config.office_geofence
       end
       notify_if_flagged(record)
       Result.new(record: record)
@@ -83,28 +91,61 @@ module HrLite
       retry
     end
 
-    # config.office_geofence: a check-in must be inside an office radius with
-    # a fix at least that precise, unless HR approved WFH for today or made
-    # the person permanent WFH. Inside the radius the day is office either way.
+    # config.office_geofence decides where a check-in may come from, and so
+    # the day's work_mode: inside an office radius is office (even on a WFH
+    # day); a field-staff check-in that says where and why is travelling or
+    # outside_meeting; approved WFH (dated or permanent) must be within the
+    # active approved home location's fence. Anything else is refused.
     def geofence_error
       return unless @kind == :check_in && HrLite.config.office_geofence && OfficeLocation.active.exists?
-      return if in_office?
+      return location_error unless @lat && @lng
+      if in_office?
+        @mode = "office"
+        return
+      end
+
+      profile = EmployeeProfile.find_by(user_id: @user.id)
+      if profile&.field_staff && FIELD_MODES.include?(@field[:mode])
+        return "Say why and where you are checking in from the field." unless @field[:purpose] && @field[:place]
+
+        @mode = @field[:mode]
+        return
+      end
 
       @wfh = WfhRequest.approved_for(@user.id, Date.current)
-      @remote = @wfh.present? || EmployeeProfile.where(user_id: @user.id).pick(:permanent_wfh)
-      return if @remote
-      return OFF_SITE_MESSAGE if @lat && @lng
+      return OFF_SITE_MESSAGE unless @wfh || profile&.permanent_wfh
+
+      @location = WorkLocation.active_for(@user.id)
+      return NO_HOME_MESSAGE unless @location
+      return HOME_OFF_SITE_MESSAGE unless precise_within?(WorkLocation::FENCE_M) && @location.covers?(@lat, @lng)
+
+      @mode = "wfh"
+      nil
+    end
+
+    # Check-in opens the day's system-set mode; check-out ends everything and
+    # opens Offline. The timeline keeps every earlier row.
+    def track_work_mode(record)
+      if @kind == :check_in
+        WorkModeEvent.start!(user_id: @user.id, mode: record.work_mode || "office", source: "system",
+                             attendance_record: record, wfh_request_id: record.wfh_request_id,
+                             work_location_id: record.work_location_id, title: @field[:purpose], destination: @field[:place])
+      else
+        WorkModeEvent.close_all!(@user.id, "checked_out")
+        WorkModeEvent.start!(user_id: @user.id, mode: "offline", source: "system", attendance_record: record)
+      end
+    end
 
+    def location_error
       "We could not read your location (#{@geo_status}). Turn location on and try again, " \
         "or request Work From Home (WFH) approval from HR."
     end
 
-    def in_office?
-      return false unless @lat && @lng && @accuracy_m.to_f.positive?
+    def precise_within?(metres) = @accuracy_m.to_f.positive? && @accuracy_m.to_f <= metres
 
+    def in_office?
       OfficeLocation.active.any? do |office|
-        @accuracy_m.to_f <= office.radius_m &&
-          Geo.distance_m(office.lat, office.lng, @lat.to_f, @lng.to_f) <= office.radius_m
+        precise_within?(office.radius_m) && Geo.distance_m(office.lat, office.lng, @lat.to_f, @lng.to_f) <= office.radius_m
       end
     end
 
@@ -128,7 +169,7 @@ module HrLite
       penalize(record, record.date, late, "late") if late.positive?
       return if arrived <= AttendanceSlot::CARRY_AFTER_MINUTE
 
-      AttendancePenalty.next_working_days(record.date, 2).each { |day| penalize(record, day, 60, "late_carry") }
+      AttendancePenalty.next_working_days(record.user_id, record.date, 2).each { |day| penalize(record, day, 60, "late_carry") }
       return if arrived <= AttendanceSlot::HALF_DAY_AFTER_MINUTE
 
       record.update!(status: "half_day", regularization_note: AttendanceRecord::LATE_HALF_DAY_NOTE)
@@ -144,8 +185,8 @@ module HrLite
       if @lat.nil? || @lng.nil?
         reason = @geo_status == "ok" ? "unavailable" : @geo_status
         record.add_flag!("#{label} without GPS (#{reason})")
-      elsif record.wfh
-        nil # WFH: off-site is the point
+      elsif record.work_mode && record.work_mode != "office"
+        nil # WFH or field work: off-site is the point
       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)

data/app/services/hr_lite/day_status.rb

@@ -13,7 +13,7 @@ module HrLite
     def initialize(user:, range:)
       @range = range
       @records = AttendanceRecord.where(user_id: user.id, date: range).index_by(&:date)
-      @calendar = WorkingCalendar.new(range)
+      @calendar = WorkingCalendar.for_user(user.id, range)
       @leaves = LeaveRequest.approved.includes(:leave_type)
                             .where(user_id: user.id)
                             .overlapping_range(range.first, range.last).to_a

data/app/services/hr_lite/leave_day_counter.rb

@@ -1,19 +1,17 @@
 module HrLite
   # How many working days a leave request actually consumes. Weekends and
   # company-wide holidays inside the range are free; a half-day (single-day
-  # requests only) consumes 0.5.
+  # requests only) consumes 0.5. Holidays are the requester's office's.
   module LeaveDayCounter
     # `calendar:` lets a caller counting many requests over the same span
     # build ONE calendar and reuse it. Each one costs a Holiday query and a
     # Setting query, and the balances grid counts every approved request of
     # every employee for every leave type.
+    # Without a calendar, the requester's own (their office's holidays count).
     def self.count(leave_request, calendar: nil)
-      count_range(
-        start_date: leave_request.start_date,
-        end_date: leave_request.end_date,
-        half_day: leave_request.half_day,
-        calendar: calendar
-      )
+      start_date, end_date = leave_request.start_date, leave_request.end_date
+      calendar ||= WorkingCalendar.for_user(leave_request.user_id, start_date..end_date) if start_date && end_date && end_date >= start_date
+      count_range(start_date: start_date, end_date: end_date, half_day: leave_request.half_day, calendar: calendar)
     end
 
     def self.count_range(start_date:, end_date:, half_day: false, calendar: nil)

data/app/services/hr_lite/team_day.rb

@@ -13,10 +13,10 @@ module HrLite
 
     def initialize(date: Date.current)
       @date = date
-      @calendar = WorkingCalendar.new(date..date)
+      @calendars = WorkingCalendar.by_office(date..date)
     end
 
-    attr_reader :date, :calendar
+    attr_reader :date
 
     def rows
       @rows ||= build_rows
@@ -49,7 +49,7 @@ module HrLite
         leave = leaves[user.id]
         Row.new(
           user: user, profile: profile,
-          kind: kind_for(record, leave),
+          kind: kind_for(record, leave, @calendars[profile&.office_location_id]),
           record: record, leave: leave,
           day_seconds: seconds_worked(record),
           month_seconds: (month_records[user.id] || []).sum { |r| seconds_worked(r) || 0 },
@@ -58,9 +58,9 @@ module HrLite
       end
     end
 
-    def kind_for(record, leave)
-      return :holiday if @calendar.holiday?(@date)
-      return :weekend if @calendar.weekend?(@date)
+    def kind_for(record, leave, calendar)
+      return :holiday if calendar.holiday?(@date)
+      return :weekend if calendar.weekend?(@date)
       return (leave.half_day ? :half_day_leave : :leave) if leave
 
       if record&.check_in_at

data/app/services/hr_lite/today_checkins.rb

@@ -0,0 +1,41 @@
+module HrLite
+  # Who is in today and whether on time, for the Home card. "On time" uses
+  # each person's own slot plus their HR buffer and the grace minutes — the
+  # same rule as the late penalty. Leave, holidays and weekends are left out.
+  class TodayCheckins
+    Person = Struct.new(:user, :record, :late_minutes, keyword_init: true) do
+      def late? = late_minutes.to_i.positive?
+    end
+
+    def initialize(board = TeamDay.new(date: Date.current), now: Time.current)
+      @board = board
+      @now = now
+    end
+
+    def groups
+      @groups ||= begin
+        rows = @board.rows.reject { |r| %i[holiday weekend leave].include?(r.kind) }
+        ids = rows.map { |r| r.user.id }
+        starts = AttendanceSlot.where(user_id: ids).overlapping(@board.date, @board.date).order(:created_at)
+                               .each_with_object({}) { |s, h| h[s.user_id] = s.start_minute }
+        buffers = EmployeeProfile.where(user_id: ids).pluck(:user_id, :buffer_minutes).to_h
+        people = rows.map do |r|
+          Person.new(user: r.user, record: r.record&.check_in_at ? r.record : nil,
+                     late_minutes: late(r.record, starts[r.user.id], buffers[r.user.id]))
+        end
+        in_now, not_in = people.partition(&:record)
+        { on_time: in_now.reject(&:late?), late: in_now.select(&:late?), not_in: not_in }
+      end
+    end
+
+    private
+
+    def late(record, start, buffer)
+      return 0 unless record&.check_in_at
+
+      local = record.check_in_at.in_time_zone(HrLite.config.time_zone)
+      over = local.hour * 60 + local.min - (start || AttendanceSlot::DEFAULT_START_MINUTE) - buffer.to_i
+      over > AttendanceSlot::GRACE_MINUTES ? over : 0
+    end
+  end
+end

data/app/services/hr_lite/work_mode_durations.rb

@@ -0,0 +1,237 @@
+module HrLite
+  # Time spent per work mode, worked out from the mode timeline every time it
+  # is asked (no cache, so a correction shows at once). A break sitting on top
+  # of a work mode counts as the break only: each moment belongs to the
+  # overlay if one is running, else to the primary mode. Open rows run to now,
+  # or to their end time if that has already passed.
+  class WorkModeDurations
+    WORKING = %w[office wfh travelling outside_meeting meeting busy].freeze
+    BREAKS = %w[lunch short_break].freeze
+    OTHER = %w[out_of_office].freeze
+
+    # A reporting window in the company time zone, with the bucket its charts use.
+    class Period
+      KINDS = %w[day week month quarter year custom].freeze
+      MAX_DAYS = 366
+
+      attr_reader :kind, :from, :to
+
+      def self.build(kind, date, from: nil, to: nil)
+        kind = KINDS.include?(kind.to_s) ? kind.to_s : "week"
+        case kind
+        when "day" then new(kind, date, date)
+        when "week" then new(kind, date.beginning_of_week(:monday), date.end_of_week(:monday))
+        when "month" then new(kind, date.beginning_of_month, date.end_of_month)
+        when "quarter" then new(kind, date.beginning_of_quarter, date.end_of_quarter)
+        when "year" then new(kind, date.beginning_of_year, date.end_of_year)
+        else
+          raise ArgumentError, "Pick a start and an end date." unless from && to
+          raise ArgumentError, "The start date is after the end date." if from > to
+          raise ArgumentError, "Pick at most #{MAX_DAYS} days." if (to - from).to_i + 1 > MAX_DAYS
+
+          new(kind, from, to)
+        end
+      end
+
+      # From request params: period=, date=, from=, to=. Returns [period, error].
+      def self.from_params(params, today)
+        date = [ parse_date(params[:date]) || today, today ].min
+        [ build(params[:period], date, from: parse_date(params[:from]), to: parse_date(params[:to])), nil ]
+      rescue ArgumentError => e
+        [ build("week", today), e.message ]
+      end
+
+      def self.parse_date(value)
+        Date.iso8601(value.to_s)
+      rescue Date::Error
+        nil
+      end
+
+      def initialize(kind, from, to)
+        @kind, @from, @to = kind, from, to
+      end
+
+      def bucket
+        case kind
+        when "day" then :hour
+        when "quarter" then :week
+        when "year" then :month
+        when "custom" then (to - from).to_i + 1 > 62 ? :week : :day
+        else :day
+        end
+      end
+
+      def label
+        case kind
+        when "day" then from.strftime("%A %-d %B %Y")
+        when "month" then from.strftime("%B %Y")
+        when "quarter" then "Q#{(from.month - 1) / 3 + 1} #{from.year}"
+        when "year" then from.year.to_s
+        else "#{from.strftime('%-d %b %Y')} – #{to.strftime('%-d %b %Y')}"
+        end
+      end
+
+      def shift(direction)
+        step = { "day" => 1.day, "week" => 1.week, "month" => 1.month, "quarter" => 3.months, "year" => 1.year }[kind]
+        step ? from + (direction * step) : from
+      end
+    end
+
+    Segment = Struct.new(:user_id, :mode, :from, :to, :source, :event_id) do
+      def seconds = to - from
+    end
+
+    Result = Struct.new(:segments, :by_mode, :by_bucket, :by_source, :attendance, :working, :breaks, :other,
+                        :offline, :days_with_data, :gaps, keyword_init: true) do
+      def tracked = working + breaks + other
+    end
+
+    # A period that is over is cached under a key built from the newest change
+    # to its events and check-ins, so a correction is picked up on the next
+    # read. A period that includes today is always worked out live.
+    def self.call(user_ids, period, now: Time.current)
+      ids = Array(user_ids)
+      return new(ids, period, now).call if period.to >= now.in_time_zone(HrLite.config.time_zone).to_date
+
+      Rails.cache.fetch(cache_key(ids, period)) { new(ids, period, now).call }
+    end
+
+    def self.cache_key(ids, period)
+      zone = Time.find_zone!(HrLite.config.time_zone)
+      start = zone.local(period.from.year, period.from.month, period.from.day)
+      finish = zone.local(period.to.year, period.to.month, period.to.day).end_of_day
+      events = WorkModeEvent.where(user_id: ids).where("started_at <= ? AND (ended_at IS NULL OR ended_at >= ?)", finish, start)
+      records = AttendanceRecord.where(user_id: ids, date: period.from..period.to)
+      [ "hr_lite/work_time/v1", Digest::SHA256.hexdigest(ids.sort.join(",")), period.kind, period.from, period.to,
+        events.count, events.maximum(:updated_at)&.to_f, records.count, records.maximum(:updated_at)&.to_f ].join("/")
+    end
+
+    def initialize(user_ids, period, now)
+      @ids = user_ids
+      @period = period
+      @now = now
+      @zone = Time.find_zone!(HrLite.config.time_zone)
+      @start = @zone.local(period.from.year, period.from.month, period.from.day)
+      @finish = [ @zone.local(period.to.year, period.to.month, period.to.day).end_of_day, now ].min
+    end
+
+    def call
+      events = @finish > @start ? overlapping_events.group_by(&:user_id) : {}
+      segments = @ids.flat_map { |id| flatten(id, events.fetch(id, [])) }
+      records = AttendanceRecord.where(user_id: @ids, date: @period.from..@period.to).where.not(check_in_at: nil).to_a
+
+      by_mode = Hash.new(0)
+      by_source = Hash.new(0)
+      by_bucket = bucket_keys.index_with { Hash.new(0) }
+      segments.each do |seg|
+        by_mode[seg.mode] += seg.seconds
+        by_source[seg.source] += seg.seconds unless seg.mode == "offline"
+        split(seg).each { |key, secs| by_bucket[key][seg.mode] += secs if by_bucket.key?(key) }
+      end
+
+      Result.new(
+        segments: segments, by_mode: by_mode, by_bucket: by_bucket, by_source: by_source,
+        attendance: records.sum { |r| attended(r) },
+        working: WORKING.sum { |m| by_mode[m] }, breaks: BREAKS.sum { |m| by_mode[m] },
+        other: OTHER.sum { |m| by_mode[m] }, offline: by_mode["offline"],
+        days_with_data: (records.map(&:date) + segments.reject { |s| s.mode == "offline" }.map { |s| s.from.in_time_zone(@zone).to_date }).to_set,
+        gaps: gaps(records, segments)
+      )
+    end
+
+    private
+
+    def overlapping_events
+      WorkModeEvent.where(user_id: @ids).where("started_at < ? AND (ended_at IS NULL OR ended_at > ?)", @finish, @start)
+                   .order(:started_at, :id).to_a
+    end
+
+    # Each layer is a sorted, non-overlapping list (one open row per layer is
+    # enforced by the database), so one sweep over the boundaries assigns
+    # every slice to its overlay or its primary without counting it twice.
+    def flatten(user_id, events)
+      layers = events.group_by(&:layer).transform_values { |list| list.map { |e| [ clip_start(e), clip_end(e), e ] }.select { |s, f, _| f > s } }
+      primaries = layers.fetch("primary", [])
+      overlays = layers.fetch("overlay", [])
+      points = (primaries + overlays).flat_map { |s, f, _| [ s, f ] }.uniq.sort
+      pi = oi = 0
+      out = []
+      points.each_cons(2) do |a, b|
+        pi += 1 while pi < primaries.size && primaries[pi][1] <= a
+        oi += 1 while oi < overlays.size && overlays[oi][1] <= a
+        event = [ overlays[oi], primaries[pi] ].compact.find { |s, f, _| s <= a && f >= b }&.last
+        next unless event
+
+        if out.last&.event_id == event.id && out.last.to == a
+          out.last.to = b
+        else
+          out << Segment.new(user_id, event.mode, a, b, event.source, event.id)
+        end
+      end
+      out
+    end
+
+    def clip_start(event) = [ event.started_at, @start ].max
+
+    def clip_end(event)
+      ended = event.ended_at || (event.ends_at && event.ends_at <= @now ? event.ends_at : @now)
+      [ ended, @finish ].min
+    end
+
+    # Check-in to check-out; today's open punch runs to now, an older open one counts nothing.
+    def attended(record)
+      return record.check_out_at - record.check_in_at if record.check_out_at
+      return [ @now - record.check_in_at, 0 ].max if record.date == @now.in_time_zone(@zone).to_date
+
+      0
+    end
+
+    def bucket_keys
+      days = (@period.from..[ @period.to, @now.in_time_zone(@zone).to_date ].min).to_a
+      case @period.bucket
+      when :hour then (0..23).to_a
+      when :day then days
+      when :week then days.map { |d| d.beginning_of_week(:monday) }.uniq
+      when :month then days.map(&:beginning_of_month).uniq
+      end
+    end
+
+    def key_for(time)
+      local = time.in_time_zone(@zone)
+      case @period.bucket
+      when :hour then local.hour
+      when :day then local.to_date
+      when :week then local.to_date.beginning_of_week(:monday)
+      when :month then local.to_date.beginning_of_month
+      end
+    end
+
+    # Seconds of a segment per bucket, cut at hour or day boundaries.
+    def split(seg)
+      step = @period.bucket == :hour ? 1.hour : 1.day
+      out = Hash.new(0)
+      cursor = seg.from
+      while cursor < seg.to
+        edge = step == 1.hour ? cursor.in_time_zone(@zone).beginning_of_hour + 1.hour : cursor.in_time_zone(@zone).beginning_of_day + 1.day
+        stop = [ edge, seg.to ].min
+        out[key_for(cursor)] += stop - cursor
+        cursor = stop
+      end
+      out
+    end
+
+    # What a reviewer should look at: no modes on a worked day, modes with no
+    # check-in, a check-out that never happened.
+    def gaps(records, segments)
+      today = @now.in_time_zone(@zone).to_date
+      worked = segments.reject { |s| s.mode == "offline" }.group_by { |s| [ s.user_id, s.from.in_time_zone(@zone).to_date ] }
+      punched = records.index_by { |r| [ r.user_id, r.date ] }
+      out = records.filter_map do |r|
+        if r.check_out_at.nil? && r.date < today then [ r.user_id, r.date, "Check-out missing" ]
+        elsif !worked.key?([ r.user_id, r.date ]) then [ r.user_id, r.date, "Checked in, but no work mode recorded" ]
+        end
+      end
+      out + worked.keys.reject { |key| punched.key?(key) }.map { |id, date| [ id, date, "Work modes recorded without a check-in" ] }
+    end
+  end
+end

data/app/services/hr_lite/work_mode_switch.rb

@@ -0,0 +1,144 @@
+module HrLite
+  # The one write path for a chosen work mode (employee or HR). A mode is a
+  # status: it never changes where the day's attendance was authorised, and
+  # nothing here touches the attendance record.
+  class WorkModeSwitch
+    SELECTABLE = %w[office wfh travelling outside_meeting meeting lunch short_break busy out_of_office].freeze
+    OUT_OF_OFFICE_REASONS = { "personal" => "Personal errand", "medical" => "Medical", "family" => "Family",
+                              "official" => "Official work", "other" => "Other" }.freeze
+
+    Result = Struct.new(:event, :error) do
+      def ok? = error.nil?
+    end
+
+    def self.call(...) = new(...).call
+
+    CLEAR_AFTER = { "30" => 30.minutes, "60" => 1.hour, "240" => 4.hours, "today" => :today, "never" => nil }.freeze
+
+    # A person's own status, Slack-style: works with or without a check-in
+    # and clears itself on the chosen timer.
+    def self.set_status(user:, text:, emoji:, clear_after:)
+      now = Time.current
+      span = CLEAR_AFTER.fetch(clear_after.to_s, :today)
+      ends_at = span == :today ? now.in_time_zone(HrLite.config.time_zone).end_of_day : (span && now + span)
+      event = WorkModeEvent.start!(user_id: user.id, mode: "custom", source: "employee", actor: user, at: now,
+                                   title: text.to_s.strip.truncate(100).presence, emoji: emoji.to_s.strip.presence, ends_at: ends_at)
+      WorkModeExpireJob.set(wait_until: ends_at).perform_later(event.id) if ends_at
+      Result.new(event, nil)
+    rescue ActiveRecord::RecordInvalid => e
+      Result.new(nil, e.record.errors.full_messages.to_sentence)
+    end
+
+    # params: title, client, destination, reason, minutes, until ("HH:MM" today)
+    def initialize(user:, mode:, source:, actor:, params: {})
+      @user = user
+      @mode = mode.to_s
+      @source = source
+      @actor = actor
+      @p = params.to_h.symbolize_keys.transform_values { |v| v.to_s.strip.presence }.compact
+      @now = Time.current
+    end
+
+    def call
+      return fail!("Pick a work mode.") unless SELECTABLE.include?(@mode)
+      return fail!("A reason is required for an HR change.") if @source == "hr" && @p[:reason].blank?
+
+      status = WorkStatus.for(@user.id, at: @now)
+      return fail!("#{status.primary.label} today — work modes are off. Use the leave screen to change it.") if %w[holiday on_leave sick_leave].include?(status.primary.mode)
+      return fail!("Check in first; your mode starts with your check-in.") unless checked_in?
+
+      attrs = send("#{@mode}_attrs")
+      return fail!(attrs) if attrs.is_a?(String)
+
+      event = WorkModeEvent.start!(user_id: @user.id, mode: @mode, source: @source, actor: @actor, at: @now,
+                                   attendance_record: @record, **attrs)
+      WorkModeExpireJob.set(wait_until: event.ends_at).perform_later(event.id) if event.ends_at
+      Result.new(event, nil)
+    rescue ActiveRecord::RecordInvalid => e
+      fail!(e.record.errors.full_messages.to_sentence)
+    end
+
+    private
+
+    def fail!(message) = Result.new(nil, message)
+
+    def checked_in?
+      @record = AttendanceRecord.find_by(user_id: @user.id, date: @now.in_time_zone(HrLite.config.time_zone).to_date)
+      @record&.check_in_at.present? && @record.check_out_at.nil?
+    end
+
+    def base = { reason: @p[:reason] }
+
+    def office_attrs = base
+
+    def wfh_attrs
+      approved = WfhRequest.approved_for(@user.id, @record.date) ||
+                 EmployeeProfile.where(user_id: @user.id).pick(:permanent_wfh)
+      return "WFH needs an approved WFH request for today." unless approved
+
+      base.merge(work_location_id: WorkLocation.active_for(@user.id)&.id)
+    end
+
+    def travelling_attrs
+      return "Say where you are going and why." unless @p[:destination] && @p[:title]
+
+      with_lead(base.merge(destination: @p[:destination], title: @p[:title], client: @p[:client])) { |a| timed(a, required: false) }
+    end
+
+    def outside_meeting_attrs
+      return "Say who you are meeting and why." unless (@p[:client] || @p[:crm_ref]) && @p[:title]
+
+      with_lead(base.merge(client: @p[:client], title: @p[:title], destination: @p[:destination])) { |a| timed(a, required: false) }
+    end
+
+    def meeting_attrs
+      return "Give the meeting a title." unless @p[:title]
+
+      with_lead(base.merge(title: @p[:title], client: @p[:client])) { |a| timed(a) }
+    end
+
+    # A picked CRM lead must exist (config.crm_find); its name fills the client.
+    def with_lead(attrs)
+      return yield(attrs) unless @p[:crm_ref]
+
+      lead = HrLite.config.crm_find&.call(@p[:crm_ref])
+      return "That lead was not found." unless lead
+
+      yield(attrs.merge(crm_ref: @p[:crm_ref], client: attrs[:client] || lead[:label].to_s.truncate(120)))
+    end
+
+    def busy_attrs = timed(base)
+
+    def out_of_office_attrs
+      return "Pick a reason for being out." unless OUT_OF_OFFICE_REASONS.key?(@p[:category])
+
+      timed(base.merge(title: OUT_OF_OFFICE_REASONS[@p[:category]]))
+    end
+
+    # One lunch a day: a fresh start can never reset the clock.
+    def lunch_attrs
+      day = @now.in_time_zone(HrLite.config.time_zone).all_day
+      return "You have already taken lunch today." if WorkModeEvent.where(user_id: @user.id, mode: "lunch", started_at: day).exists?
+
+      base.merge(ends_at: @now + Setting.instance.lunch_break_minutes.minutes)
+    end
+
+    def short_break_attrs = base.merge(ends_at: @now + Setting.instance.short_break_minutes.minutes)
+
+    def parse_until
+      Time.zone.parse("#{@now.to_date} #{@p[:until]}") if @p[:until]
+    rescue ArgumentError
+      nil
+    end
+
+    # minutes (30/60/…) or until "HH:MM" today; must be in the future, today.
+    def timed(attrs, required: true)
+      ends_at = @p[:minutes] ? @now + @p[:minutes].to_i.minutes : parse_until
+      return attrs unless ends_at || required
+      return "Pick when it ends." unless ends_at
+      return "The end time must be later today." unless ends_at > @now && ends_at <= @now.end_of_day
+
+      attrs.merge(ends_at: ends_at)
+    end
+  end
+end