Merge branch 'develop' into fixes/annotaterb

lib/tasks/assignment_v2_migration.rake

@@ -0,0 +1,81 @@
+# Migrate max_assignment_limit to Agent Capacity Policies
+#
+# Converts legacy per-inbox max_assignment_limit settings into
+# AgentCapacityPolicy records used by Assignment V2.
+#
+# Usage Examples:
+#   # Migrate a single account
+#   ACCOUNT_ID=1 bundle exec rake assignment_v2:migrate
+#
+#   # Migrate all accounts in the installation
+#   bundle exec rake assignment_v2:migrate
+#
+# Parameters:
+#   ACCOUNT_ID: (optional) ID of the account to migrate. If omitted, migrates all accounts.
+#
+# rubocop:disable Metrics/BlockLength
+namespace :assignment_v2 do
+  desc 'Migrate max_assignment_limit inbox settings to agent capacity policies'
+  task migrate: :environment do
+    int_max = (2**31) - 1
+    policy_name = 'Auto Assignment Capacity'
+
+    account_id = ENV.fetch('ACCOUNT_ID', nil)
+    accounts = account_id.present? ? Account.where(id: account_id) : Account.all
+
+    if account_id.blank?
+      print 'No ACCOUNT_ID specified. This will migrate ALL accounts. Continue? [y/N] '
+      abort 'Aborted.' unless $stdin.gets.chomp.casecmp('y').zero?
+    end
+
+    if account_id.present? && accounts.empty?
+      puts "Error: Account with ID #{account_id} not found"
+      exit(1)
+    end
+
+    total = accounts.count
+    puts "Migrating assignment policies for #{total} account(s)..."
+    puts "Started at: #{Time.current}"
+
+    migrated = 0
+    skipped = 0
+    errored = 0
+
+    accounts.find_each do |account|
+      inboxes_with_limit = account.inboxes.where("auto_assignment_config->>'max_assignment_limit' ~ '[1-9]'")
+
+      if inboxes_with_limit.empty?
+        skipped += 1
+        puts "  [#{migrated + skipped + errored}/#{total}] Account #{account.id} — skipped (no inboxes with limit)"
+        next
+      end
+
+      ActiveRecord::Base.transaction do
+        policy = AgentCapacityPolicy.find_or_create_by!(account: account, name: policy_name) do |p|
+          p.description = 'Migrated from inbox settings'
+        end
+
+        inboxes_with_limit.each do |inbox|
+          next if InboxCapacityLimit.exists?(agent_capacity_policy_id: policy.id, inbox_id: inbox.id)
+
+          limit = [inbox.auto_assignment_config['max_assignment_limit'].to_i, int_max].min
+          InboxCapacityLimit.create!(agent_capacity_policy: policy, inbox: inbox, conversation_limit: limit)
+        end
+
+        member_user_ids = InboxMember.where(inbox_id: inboxes_with_limit.select(:id)).distinct.pluck(:user_id)
+        account.account_users
+               .where(user_id: member_user_ids, agent_capacity_policy_id: nil)
+               .find_each { |au| au.update!(agent_capacity_policy_id: policy.id) }
+      end
+
+      migrated += 1
+      puts "  [#{migrated + skipped + errored}/#{total}] Account #{account.id} — migrated"
+    rescue StandardError => e
+      errored += 1
+      puts "  [#{migrated + skipped + errored}/#{total}] Account #{account.id} — error: #{e.message}"
+    end
+
+    puts "\nDone! Migrated: #{migrated}, Skipped: #{skipped}, Errored: #{errored}, Total: #{total}"
+  end
+end
+# rubocop:enable Metrics/BlockLength

lib/tasks/companies.rake

@@ -1,12 +0,0 @@
-namespace :companies do
-  desc 'Backfill companies from existing contact email domains'
-  task backfill: :environment do
-    puts 'Starting company backfill migration...'
-    puts 'This will process all accounts and create companies from contact email domains.'
-    puts 'The job will run in the background via Sidekiq'
-    puts ''
-    Migration::CompanyBackfillJob.perform_later
-    puts 'Company backfill job has been enqueued.'
-    puts 'Monitor progress in logs or Sidekiq dashboard.'
-  end
-end

lib/tasks/download_report.rake

@@ -0,0 +1,183 @@
+# Download Report Rake Tasks
+#
+# Usage:
+#   POSTGRES_STATEMENT_TIMEOUT=600s NEW_RELIC_AGENT_ENABLED=false bundle exec rake download_report:agent
+#   POSTGRES_STATEMENT_TIMEOUT=600s NEW_RELIC_AGENT_ENABLED=false bundle exec rake download_report:inbox
+#   POSTGRES_STATEMENT_TIMEOUT=600s NEW_RELIC_AGENT_ENABLED=false bundle exec rake download_report:label
+#
+# The task will prompt for:
+#   - Account ID
+#   - Start Date (YYYY-MM-DD)
+#   - End Date (YYYY-MM-DD)
+#   - Timezone Offset (e.g., 0, 5.5, -5)
+#   - Business Hours (y/n) - whether to use business hours for time metrics
+#
+# Output: <account_id>_<type>_<start_date>_<end_date>.csv
+
+require 'csv'
+
+# rubocop:disable Metrics/CyclomaticComplexity
+# rubocop:disable Metrics/AbcSize
+# rubocop:disable Metrics/MethodLength
+# rubocop:disable Metrics/ModuleLength
+module DownloadReportTasks
+  def self.prompt(message)
+    print "#{message}: "
+    $stdin.gets.chomp
+  end
+
+  def self.collect_params
+    account_id = prompt('Enter Account ID')
+    abort 'Error: Account ID is required' if account_id.blank?
+
+    account = Account.find_by(id: account_id)
+    abort "Error: Account with ID '#{account_id}' not found" unless account
+
+    start_date = prompt('Enter Start Date (YYYY-MM-DD)')
+    abort 'Error: Start date is required' if start_date.blank?
+
+    end_date = prompt('Enter End Date (YYYY-MM-DD)')
+    abort 'Error: End date is required' if end_date.blank?
+
+    timezone_offset = prompt('Enter Timezone Offset (e.g., 0, 5.5, -5)')
+    timezone_offset = timezone_offset.blank? ? 0 : timezone_offset.to_f
+
+    business_hours = prompt('Use Business Hours? (y/n)')
+    business_hours = business_hours.downcase == 'y'
+
+    begin
+      tz = ActiveSupport::TimeZone[timezone_offset]
+      abort "Error: Invalid timezone offset '#{timezone_offset}'" unless tz
+
+      since = tz.parse("#{start_date} 00:00:00").to_i.to_s
+      until_date = tz.parse("#{end_date} 23:59:59").to_i.to_s
+    rescue StandardError => e
+      abort "Error parsing dates: #{e.message}"
+    end
+
+    {
+      account: account,
+      params: { since: since, until: until_date, timezone_offset: timezone_offset, business_hours: business_hours },
+      start_date: start_date,
+      end_date: end_date
+    }
+  end
+
+  def self.save_csv(filename, headers, rows)
+    CSV.open(filename, 'w') do |csv|
+      csv << headers
+      rows.each { |row| csv << row }
+    end
+    puts "Report saved to: #{filename}"
+  end
+
+  def self.format_time(seconds)
+    return '' if seconds.nil? || seconds.zero?
+
+    seconds.round(2)
+  end
+
+  def self.download_agent_report
+    data = collect_params
+    account = data[:account]
+
+    puts "\nGenerating agent report..."
+    builder = V2::Reports::AgentSummaryBuilder.new(account: account, params: data[:params])
+    report = builder.build
+
+    users = account.users.index_by(&:id)
+    headers = %w[id name email conversations_count resolved_conversations_count avg_resolution_time avg_first_response_time avg_reply_time]
+
+    rows = report.map do |row|
+      user = users[row[:id]]
+      [
+        row[:id],
+        user&.name || 'Unknown',
+        user&.email || 'Unknown',
+        row[:conversations_count],
+        row[:resolved_conversations_count],
+        format_time(row[:avg_resolution_time]),
+        format_time(row[:avg_first_response_time]),
+        format_time(row[:avg_reply_time])
+      ]
+    end
+
+    filename = "#{account.id}_agent_#{data[:start_date]}_#{data[:end_date]}.csv"
+    save_csv(filename, headers, rows)
+  end
+
+  def self.download_inbox_report
+    data = collect_params
+    account = data[:account]
+
+    puts "\nGenerating inbox report..."
+    builder = V2::Reports::InboxSummaryBuilder.new(account: account, params: data[:params])
+    report = builder.build
+
+    inboxes = account.inboxes.index_by(&:id)
+    headers = %w[id name conversations_count resolved_conversations_count avg_resolution_time avg_first_response_time avg_reply_time]
+
+    rows = report.map do |row|
+      inbox = inboxes[row[:id]]
+      [
+        row[:id],
+        inbox&.name || 'Unknown',
+        row[:conversations_count],
+        row[:resolved_conversations_count],
+        format_time(row[:avg_resolution_time]),
+        format_time(row[:avg_first_response_time]),
+        format_time(row[:avg_reply_time])
+      ]
+    end
+
+    filename = "#{account.id}_inbox_#{data[:start_date]}_#{data[:end_date]}.csv"
+    save_csv(filename, headers, rows)
+  end
+
+  def self.download_label_report
+    data = collect_params
+    account = data[:account]
+
+    puts "\nGenerating label report..."
+    builder = V2::Reports::LabelSummaryBuilder.new(account: account, params: data[:params])
+    report = builder.build
+
+    headers = %w[id name conversations_count resolved_conversations_count avg_resolution_time avg_first_response_time avg_reply_time]
+
+    rows = report.map do |row|
+      [
+        row[:id],
+        row[:name],
+        row[:conversations_count],
+        row[:resolved_conversations_count],
+        format_time(row[:avg_resolution_time]),
+        format_time(row[:avg_first_response_time]),
+        format_time(row[:avg_reply_time])
+      ]
+    end
+
+    filename = "#{account.id}_label_#{data[:start_date]}_#{data[:end_date]}.csv"
+    save_csv(filename, headers, rows)
+  end
+end
+# rubocop:enable Metrics/CyclomaticComplexity
+# rubocop:enable Metrics/AbcSize
+# rubocop:enable Metrics/MethodLength
+# rubocop:enable Metrics/ModuleLength
+
+namespace :download_report do
+  desc 'Download agent summary report as CSV'
+  task agent: :environment do
+    DownloadReportTasks.download_agent_report
+  end
+
+  desc 'Download inbox summary report as CSV'
+  task inbox: :environment do
+    DownloadReportTasks.download_inbox_report
+  end
+
+  desc 'Download label summary report as CSV'
+  task label: :environment do
+    DownloadReportTasks.download_label_report
+  end
+end

lib/tasks/ops/cleanup_orphan_conversations.rake

@@ -15,13 +15,13 @@ namespace :chatwoot do
       days_input = $stdin.gets.strip
       days = days_input.empty? ? 7 : days_input.to_i
 
-      # Build a common base relation with identical joins for OR compatibility
+      service = Internal::RemoveOrphanConversationsService.new(account: account, days: days)
+
+      # Preview count using the same query logic
       base = account
              .conversations
-             .where('conversations.created_at > ?', days.days.ago)
+             .where('conversations.last_activity_at > ?', days.days.ago)
              .left_outer_joins(:contact, :inbox)
-
-      # Find conversations whose associated contact or inbox record is missing
       conversations = base.where(contacts: { id: nil }).or(base.where(inboxes: { id: nil }))
 
       count = conversations.count
@@ -31,8 +31,8 @@ namespace :chatwoot do
         print 'Do you want to delete these conversations? (y/N): '
         confirm = $stdin.gets.strip.downcase
         if %w[y yes].include?(confirm)
-          conversations.destroy_all
-          puts 'Conversations deleted.'
+          total_deleted = service.perform
+          puts "#{total_deleted} conversations deleted."
         else
           puts 'No conversations were deleted.'
         end

lib/tasks/reporting_events_rollup.rake

@@ -0,0 +1,268 @@
+# frozen_string_literal: true
+
+namespace :reporting_events_rollup do
+  desc 'Backfill rollup table from historical reporting events'
+  task backfill: :environment do
+    ReportingEventsRollupBackfill.new.run
+  end
+end
+
+class ReportingEventsRollupBackfill # rubocop:disable Metrics/ClassLength
+  def run
+    print_header
+    account = prompt_account
+    timezone = resolve_timezone(account)
+    first_event, last_event = discover_events(account)
+    start_date, end_date, total_days = resolve_date_range(account, timezone, first_event, last_event)
+    dry_run = prompt_dry_run?
+    print_plan(account, timezone, start_date, end_date, total_days, first_event, last_event, dry_run)
+    return if dry_run
+
+    confirm_and_execute(account, start_date, end_date, total_days)
+  end
+
+  private
+
+  def print_header
+    puts ''
+    puts color('=' * 70, :cyan)
+    puts color('Reporting Events Rollup Backfill', :bold, :cyan)
+    puts color('=' * 70, :cyan)
+    puts color('Plan:', :bold, :yellow)
+    puts '1. Ensure account.reporting_timezone is set before running this task.'
+    puts '2. Wait for the current day to end in that account timezone.'
+    puts '3. Run backfill for closed days only (today is skipped by default).'
+    puts '4. Verify parity, then enable reporting_events_rollup read path.'
+    puts ''
+    puts color('Note:', :bold, :yellow)
+    puts '- This task always uses account.reporting_timezone.'
+    puts '- Default range is first event day -> yesterday (in account timezone).'
+    puts ''
+  end
+
+  def prompt_account
+    print 'Enter Account ID: '
+    account_id = $stdin.gets.chomp
+    abort color('Error: Account ID is required', :red, :bold) if account_id.blank?
+
+    account = Account.find_by(id: account_id)
+    abort color("Error: Account with ID #{account_id} not found", :red, :bold) unless account
+
+    puts color("Found account: #{account.name}", :gray)
+    puts ''
+    account
+  end
+
+  def resolve_timezone(account)
+    timezone = account.reporting_timezone
+    abort color("Error: Account #{account.id} must have reporting_timezone set", :red, :bold) if timezone.blank?
+    abort color("Error: Account #{account.id} has invalid reporting_timezone '#{timezone}'", :red, :bold) if ActiveSupport::TimeZone[timezone].blank?
+
+    puts color("Using account reporting timezone: #{timezone}", :gray)
+    puts ''
+    timezone
+  end
+
+  def discover_events(account)
+    first_event = account.reporting_events.order(:created_at).first
+    last_event = account.reporting_events.order(:created_at).last
+
+    if first_event.nil?
+      puts ''
+      puts "No reporting events found for account #{account.id}"
+      puts 'Nothing to backfill.'
+      exit(0)
+    end
+
+    [first_event, last_event]
+  end
+
+  def resolve_date_range(account, timezone, first_event, last_event)
+    dates = discovered_dates(timezone, first_event, last_event)
+    print_discovered_date_range(account, dates)
+    build_date_range(dates)
+  end
+
+  def prompt_dry_run?
+    print 'Dry run? (y/N): '
+    input = $stdin.gets.chomp.downcase
+    puts ''
+    %w[y yes].include?(input)
+  end
+
+  # rubocop:disable Metrics/ParameterLists
+  def print_plan(account, timezone, start_date, end_date, total_days, first_event, last_event, dry_run)
+    zone = ActiveSupport::TimeZone[timezone]
+    print_plan_summary(account, timezone, start_date, end_date, total_days, zone, first_event, last_event, dry_run)
+
+    return unless dry_run
+
+    puts color("DRY RUN MODE: Would process #{total_days} days", :yellow, :bold)
+    puts "Would use account reporting_timezone '#{timezone}'"
+    puts 'Run without dry run to execute backfill'
+  end
+  # rubocop:enable Metrics/ParameterLists
+
+  def print_plan_summary(account, timezone, start_date, end_date, total_days, zone, first_event, last_event, dry_run) # rubocop:disable Metrics/ParameterLists
+    puts color('=' * 70, :cyan)
+    puts color('Backfill Plan Summary', :bold, :cyan)
+    puts color('=' * 70, :cyan)
+    puts "Account:     #{account.name} (ID: #{account.id})"
+    puts "Timezone:    #{timezone}"
+    puts "Date Range:  #{start_date} to #{end_date} (#{total_days} days)"
+    puts "First Event: #{format_event_time(first_event, zone)}"
+    puts "Last Event:  #{format_event_time(last_event, zone)}"
+    puts "Dry Run:     #{dry_run ? 'YES (no data will be written)' : 'NO'}"
+    puts color('=' * 70, :cyan)
+    puts ''
+  end
+
+  def format_event_time(event, zone)
+    event.created_at.in_time_zone(zone).strftime('%Y-%m-%d %H:%M:%S %Z')
+  end
+
+  def discovered_dates(timezone, first_event, last_event)
+    tz = ActiveSupport::TimeZone[timezone]
+    discovered_start = first_event.created_at.in_time_zone(tz).to_date
+    discovered_end = last_event.created_at.in_time_zone(tz).to_date
+
+    {
+      discovered_start: discovered_start,
+      discovered_end: discovered_end,
+      discovered_days: (discovered_end - discovered_start).to_i + 1,
+      default_end: [discovered_end, Time.current.in_time_zone(tz).to_date - 1.day].min
+    }
+  end
+
+  def print_discovered_date_range(account, dates)
+    message = "Discovered date range: #{dates[:discovered_start]} to #{dates[:discovered_end]} " \
+              "(#{dates[:discovered_days]} days) [Account: #{account.name}]"
+    puts color(message, :gray)
+    puts color("Default end date (excluding today): #{dates[:default_end]}", :gray)
+    puts ''
+  end
+
+  def build_date_range(dates)
+    start_date = dates[:discovered_start]
+    end_date = dates[:default_end]
+    total_days = (end_date - start_date).to_i + 1
+
+    abort_no_closed_days if total_days <= 0
+
+    [start_date, end_date, total_days]
+  end
+
+  def abort_no_closed_days
+    puts 'No closed days available to backfill in the default range.'
+    exit(0)
+  end
+
+  def confirm_and_execute(account, start_date, end_date, total_days)
+    if total_days > 730
+      puts color("WARNING: Large backfill detected (#{total_days} days / #{(total_days / 365.0).round(1)} years)", :yellow, :bold)
+      puts ''
+    end
+
+    print 'Proceed with backfill? (y/N): '
+    confirm = $stdin.gets.chomp.downcase
+    abort 'Backfill cancelled' unless %w[y yes].include?(confirm)
+
+    puts ''
+    execute_backfill(account, start_date, end_date, total_days)
+  end
+
+  def execute_backfill(account, start_date, end_date, total_days)
+    puts 'Processing dates...'
+    puts ''
+
+    start_time = Time.current
+    days_processed = 0
+
+    (start_date..end_date).each do |date|
+      ReportingEvents::BackfillService.backfill_date(account, date)
+      days_processed += 1
+      percentage = (days_processed.to_f / total_days * 100).round(1)
+      print "\r#{date} | #{days_processed}/#{total_days} days | #{percentage}%    "
+      $stdout.flush
+    end
+
+    print_success(account, days_processed, total_days, Time.current - start_time)
+  rescue StandardError => e
+    print_failure(e, days_processed, total_days)
+  else
+    prompt_enable_rollup_read_path(account)
+  end
+
+  def print_success(account, days_processed, _total_days, elapsed_time)
+    puts "\n\n"
+    puts color('=' * 70, :green)
+    puts color('BACKFILL COMPLETE', :bold, :green)
+    puts color('=' * 70, :green)
+    puts "Total Days Processed: #{days_processed}"
+    puts "Total Time:           #{elapsed_time.round(2)} seconds"
+    puts "Average per Day:      #{(elapsed_time / days_processed).round(3)} seconds"
+    puts ''
+    puts 'Next steps:'
+    puts '1. Verify parity before enabling the reporting_events_rollup read path.'
+    puts '2. Verify rollups in database:'
+    puts "   ReportingEventsRollup.where(account_id: #{account.id}).count"
+    puts '3. Test reports to compare rollup vs raw performance'
+    puts color('=' * 70, :green)
+  end
+
+  def prompt_enable_rollup_read_path(account)
+    if account.feature_enabled?(:report_rollup)
+      puts color('report_rollup is already enabled for this account.', :yellow, :bold)
+      return
+    end
+
+    print 'Enable report_rollup read path now? Only do this after parity verification. (y/N): '
+    confirm = $stdin.gets.to_s.chomp.downcase
+    puts ''
+    return unless %w[y yes].include?(confirm)
+
+    account.enable_features!('report_rollup')
+    puts color("Enabled report_rollup for account #{account.id}", :green, :bold)
+  end
+
+  def print_failure(error, days_processed, total_days)
+    puts "\n\n"
+    puts color('=' * 70, :red)
+    puts color('BACKFILL FAILED', :bold, :red)
+    puts color('=' * 70, :red)
+    print_error_details(error)
+    print_progress(days_processed, total_days)
+    exit(1)
+  end
+
+  def print_error_details(error)
+    puts color("Error: #{error.class.name} - #{error.message}", :red, :bold)
+    puts ''
+    puts 'Stack trace:'
+    puts error.backtrace.first(10).map { |line| "  #{line}" }.join("\n")
+    puts ''
+  end
+
+  def print_progress(days_processed, total_days)
+    percentage = (days_processed.to_f / total_days * 100).round(1)
+    puts "Processed: #{days_processed}/#{total_days} days (#{percentage}%)"
+    puts color('=' * 70, :red)
+  end
+
+  ANSI_COLORS = {
+    reset: "\e[0m",
+    bold: "\e[1m",
+    red: "\e[31m",
+    green: "\e[32m",
+    yellow: "\e[33m",
+    cyan: "\e[36m",
+    gray: "\e[90m"
+  }.freeze
+
+  def color(text, *styles)
+    return text unless $stdout.tty?
+
+    codes = styles.filter_map { |style| ANSI_COLORS[style] }.join
+    "#{codes}#{text}#{ANSI_COLORS[:reset]}"
+  end
+end

lib/tasks/reporting_events_rollup_timezone_setup.rake

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+namespace :reporting_events_rollup do
+  desc 'Interactively set account.reporting_timezone and show recommended backfill run times'
+  task set_timezone: :environment do
+    ReportingEventsRollupTimezoneSetup.new.run
+  end
+end
+
+class ReportingEventsRollupTimezoneSetup
+  def run
+    print_header
+    account = prompt_account
+    print_current_timezone(account)
+    timezone = prompt_timezone
+    confirm_and_update(account, timezone)
+    print_next_steps(account, timezone)
+  end
+
+  private
+
+  def print_header
+    puts ''
+    puts color('=' * 70, :cyan)
+    puts color('Reporting Events Rollup Timezone Setup', :bold, :cyan)
+    puts color('=' * 70, :cyan)
+    puts color('Help:', :bold, :yellow)
+    puts '1. This task writes a valid account.reporting_timezone.'
+    puts '2. Backfill uses this timezone and skips today by default.'
+    puts '3. Run backfill only after the account timezone day closes.'
+    puts ''
+  end
+
+  def prompt_account
+    print 'Enter Account ID: '
+    account_id = $stdin.gets.chomp
+    abort color('Error: Account ID is required', :red, :bold) if account_id.blank?
+
+    account = Account.find_by(id: account_id)
+    abort color("Error: Account with ID #{account_id} not found", :red, :bold) unless account
+
+    puts color("Found account: #{account.name}", :gray)
+    puts ''
+    account
+  end
+
+  def print_current_timezone(account)
+    current_timezone = account.reporting_timezone.presence || '(not set)'
+    puts color("Current reporting_timezone: #{current_timezone}", :gray)
+    puts ''
+  end
+
+  def prompt_timezone
+    loop do
+      print 'Enter UTC offset to pick timezone (e.g., +5:30, -8, 0): '
+      offset_input = $stdin.gets.chomp
+      abort color('Error: UTC offset is required', :red, :bold) if offset_input.blank?
+
+      matching_zones = find_matching_zones(offset_input)
+      abort color("Error: No timezones found for offset '#{offset_input}'", :red, :bold) if matching_zones.empty?
+
+      display_matching_zones(matching_zones, offset_input)
+      timezone = select_timezone(matching_zones)
+      return timezone if timezone.present?
+    end
+  end
+
+  def find_matching_zones(offset_input)
+    total_seconds = utc_offset_in_seconds(offset_input)
+    return [] unless total_seconds
+
+    ActiveSupport::TimeZone.all.select { |tz| tz.utc_offset == total_seconds }
+  end
+
+  def utc_offset_in_seconds(offset_input)
+    normalized = offset_input.strip
+    return unless normalized.match?(/\A[+-]?\d{1,2}(:\d{2})?\z/)
+
+    sign = normalized.start_with?('-') ? -1 : 1
+    raw = normalized.delete_prefix('+').delete_prefix('-')
+    hours_part, minutes_part = raw.split(':', 2)
+
+    hours = Integer(hours_part, 10)
+    minutes = Integer(minutes_part || '0', 10)
+    return unless minutes.between?(0, 59)
+
+    total_minutes = (hours * 60) + minutes
+    return if total_minutes > max_utc_offset_minutes(sign)
+
+    sign * total_minutes * 60
+  rescue ArgumentError
+    nil
+  end
+
+  def max_utc_offset_minutes(sign)
+    sign.negative? ? 12 * 60 : 14 * 60
+  end
+
+  def display_matching_zones(zones, offset_input)
+    puts ''
+    puts color("Timezones matching UTC#{offset_input}:", :yellow, :bold)
+    puts ''
+    zones.each_with_index do |tz, index|
+      puts "  #{index + 1}. #{tz.name} (#{tz.tzinfo.identifier})"
+    end
+    puts '  0. Re-enter UTC offset'
+    puts ''
+  end
+
+  def select_timezone(zones)
+    print "Select timezone (1-#{zones.size}, 0 to go back): "
+    selection = $stdin.gets.chomp.to_i
+    return if selection.zero?
+
+    abort color('Error: Invalid selection', :red, :bold) if selection < 1 || selection > zones.size
+
+    timezone = zones[selection - 1].tzinfo.identifier
+    puts color("Selected timezone: #{timezone}", :gray)
+    puts ''
+    timezone
+  end
+
+  def confirm_and_update(account, timezone)
+    print "Update account #{account.id} reporting_timezone to '#{timezone}'? (y/N): "
+    confirm = $stdin.gets.chomp.downcase
+    abort 'Timezone setup cancelled' unless %w[y yes].include?(confirm)
+
+    account.update!(reporting_timezone: timezone)
+    puts ''
+    puts color("Updated reporting_timezone for account '#{account.name}' to '#{timezone}'", :green, :bold)
+    puts ''
+  end
+
+  def print_next_steps(account, timezone)
+    run_times = recommended_run_times(timezone)
+    print_next_steps_header
+    print_next_steps_schedule(timezone, run_times)
+    print_next_steps_backfill(account)
+    puts color('=' * 70, :green)
+  end
+
+  def print_next_steps_header
+    puts color('=' * 70, :green)
+    puts color('Next Steps', :bold, :green)
+    puts color('=' * 70, :green)
+  end
+
+  def print_next_steps_schedule(timezone, run_times)
+    puts "1. Wait for today's day-boundary to pass in #{timezone}."
+    puts '2. Recommended earliest backfill start time:'
+    puts "   - #{timezone}: #{format_time(run_times[:account_tz])}"
+    puts "   - UTC:        #{format_time(run_times[:utc])}"
+    puts "   - IST:        #{format_time(run_times[:ist])}"
+    puts "   - PCT/PT:     #{format_time(run_times[:pct])}"
+  end
+
+  def print_next_steps_backfill(account)
+    puts '3. Run backfill:'
+    puts '   bundle exec rake reporting_events_rollup:backfill'
+    puts "4. Backfill will use account.reporting_timezone and skip today by default for account #{account.id}."
+  end
+
+  def recommended_run_times(timezone)
+    account_zone = ActiveSupport::TimeZone[timezone]
+    next_day = Time.current.in_time_zone(account_zone).to_date + 1.day
+    account_time = account_zone.parse(next_day.to_s) + 30.minutes
+
+    {
+      account_tz: account_time,
+      utc: account_time.in_time_zone('UTC'),
+      ist: account_time.in_time_zone('Asia/Kolkata'),
+      pct: account_time.in_time_zone('Pacific Time (US & Canada)')
+    }
+  end
+
+  def format_time(time)
+    time.strftime('%Y-%m-%d %H:%M:%S %Z')
+  end
+
+  ANSI_COLORS = {
+    reset: "\e[0m",
+    bold: "\e[1m",
+    red: "\e[31m",
+    green: "\e[32m",
+    yellow: "\e[33m",
+    cyan: "\e[36m",
+    gray: "\e[90m"
+  }.freeze
+
+  def color(text, *styles)
+    return text unless $stdout.tty?
+
+    codes = styles.filter_map { |style| ANSI_COLORS[style] }.join
+    "#{codes}#{text}#{ANSI_COLORS[:reset]}"
+  end
+end

lib/tasks/search_test_data.rake

@@ -0,0 +1,183 @@
+# rubocop:disable Metrics/BlockLength
+namespace :search do
+  desc 'Create test messages for advanced search manual testing across multiple inboxes'
+  task setup_test_data: :environment do
+    puts '🔍 Setting up test data for advanced search...'
+
+    account = Account.first
+    unless account
+      puts '❌ No account found. Please create an account first.'
+      exit 1
+    end
+
+    agents = account.users.to_a
+    unless agents.any?
+      puts '❌ No agents found. Please create users first.'
+      exit 1
+    end
+
+    puts "✅ Using account: #{account.name} (ID: #{account.id})"
+    puts "✅ Found #{agents.count} agent(s)"
+
+    # Create missing inbox types for comprehensive testing
+    puts "\n📥 Checking and creating inboxes..."
+
+    # API inbox
+    unless account.inboxes.exists?(channel_type: 'Channel::Api')
+      puts '  Creating API inbox...'
+      account.inboxes.create!(
+        name: 'Search Test API',
+        channel: Channel::Api.create!(account: account)
+      )
+    end
+
+    # Web Widget inbox
+    unless account.inboxes.exists?(channel_type: 'Channel::WebWidget')
+      puts '  Creating WebWidget inbox...'
+      account.inboxes.create!(
+        name: 'Search Test WebWidget',
+        channel: Channel::WebWidget.create!(account: account, website_url: 'https://example.com')
+      )
+    end
+
+    # Email inbox
+    unless account.inboxes.exists?(channel_type: 'Channel::Email')
+      puts '  Creating Email inbox...'
+      account.inboxes.create!(
+        name: 'Search Test Email',
+        channel: Channel::Email.create!(
+          account: account,
+          email: 'search-test@example.com',
+          imap_enabled: false,
+          smtp_enabled: false
+        )
+      )
+    end
+
+    inboxes = account.inboxes.to_a
+    puts "✅ Using #{inboxes.count} inbox(es):"
+    inboxes.each { |i| puts "   - #{i.name} (ID: #{i.id}, Type: #{i.channel_type})" }
+
+    # Create 10 test contacts
+    contacts = []
+    10.times do |i|
+      contacts << account.contacts.find_or_create_by!(
+        email: "test-customer-#{i}@example.com"
+      ) do |c|
+        c.name = Faker::Name.name
+      end
+    end
+    puts "✅ Created/found #{contacts.count} test contacts"
+
+    target_messages = 50_000
+    messages_per_conversation = 100
+    total_conversations = target_messages / messages_per_conversation
+
+    puts "\n📝 Creating #{target_messages} messages across #{total_conversations} conversations..."
+    puts "   Distribution: #{inboxes.count} inboxes × #{total_conversations / inboxes.count} conversations each"
+
+    start_time = 2.years.ago
+    end_time = Time.current
+    time_range = end_time - start_time
+
+    created_count = 0
+    failed_count = 0
+    conversations_per_inbox = total_conversations / inboxes.count
+    conversation_statuses = [:open, :resolved]
+
+    inboxes.each do |inbox|
+      conversations_per_inbox.times do
+        # Pick random contact and agent for this conversation
+        contact = contacts.sample
+        agent = agents.sample
+
+        # Create or find ContactInbox
+        contact_inbox = ContactInbox.find_or_create_by!(
+          contact: contact,
+          inbox: inbox
+        ) do |ci|
+          ci.source_id = "test_#{SecureRandom.hex(8)}"
+        end
+
+        # Create conversation
+        conversation = inbox.conversations.create!(
+          account: account,
+          contact: contact,
+          inbox: inbox,
+          contact_inbox: contact_inbox,
+          status: conversation_statuses.sample
+        )
+
+        # Create messages for this conversation (50 incoming, 50 outgoing)
+        50.times do
+          random_time = start_time + (rand * time_range)
+
+          # Incoming message from contact
+          begin
+            Message.create!(
+              content: Faker::Movie.quote,
+              account: account,
+              inbox: inbox,
+              conversation: conversation,
+              message_type: :incoming,
+              sender: contact,
+              created_at: random_time,
+              updated_at: random_time
+            )
+            created_count += 1
+          rescue StandardError => e
+            failed_count += 1
+            puts "❌ Failed to create message: #{e.message}" if failed_count <= 5
+          end
+
+          # Outgoing message from agent
+          begin
+            Message.create!(
+              content: Faker::Movie.quote,
+              account: account,
+              inbox: inbox,
+              conversation: conversation,
+              message_type: :outgoing,
+              sender: agent,
+              created_at: random_time + rand(60..600),
+              updated_at: random_time + rand(60..600)
+            )
+            created_count += 1
+          rescue StandardError => e
+            failed_count += 1
+            puts "❌ Failed to create message: #{e.message}" if failed_count <= 5
+          end
+
+          print "\r🔄 Progress: #{created_count}/#{target_messages} messages created..." if (created_count % 500).zero?
+        end
+      end
+    end
+
+    puts "\n\n✅ Successfully created #{created_count} messages!"
+    puts "❌ Failed: #{failed_count}" if failed_count.positive?
+
+    puts "\n📊 Summary:"
+    puts "  - Total messages: #{Message.where(account: account).count}"
+    puts "  - Total conversations: #{Conversation.where(account: account).count}"
+
+    min_date = Message.where(account: account).minimum(:created_at)&.strftime('%Y-%m-%d')
+    max_date = Message.where(account: account).maximum(:created_at)&.strftime('%Y-%m-%d')
+    puts "  - Date range: #{min_date} to #{max_date}"
+    puts "\nBreakdown by inbox:"
+    inboxes.each do |inbox|
+      msg_count = Message.where(inbox: inbox).count
+      conv_count = Conversation.where(inbox: inbox).count
+      puts "  - #{inbox.name} (#{inbox.channel_type}): #{msg_count} messages, #{conv_count} conversations"
+    end
+    puts "\nBreakdown by sender type:"
+    puts "  - Incoming (from contacts): #{Message.where(account: account, message_type: :incoming).count}"
+    puts "  - Outgoing (from agents): #{Message.where(account: account, message_type: :outgoing).count}"
+
+    puts "\n🔧 Next steps:"
+    puts '  1. Ensure OpenSearch is running: mise elasticsearch-start'
+    puts '  2. Reindex messages: rails runner "Message.search_index.import Message.all"'
+    puts "  3. Enable feature: rails runner \"Account.find(#{account.id}).enable_features('advanced_search')\""
+    puts "\n💡 Then test the search with filters via API or Rails console!"
+  end
+end
+# rubocop:enable Metrics/BlockLength