Add ImportSchoolsJob to track imports.

This commit introduces an ImportSchoolsJob type of GoodJob job to allow
for enqueueing imports and tracking their asynchronous completion.

The controller will return to the caller a Job ID which can be used to
track the progress of these jobs and retrieve their results when done.

The SchoolImportResult class tracks the job and provides access to the
results.

There are structured error codes for possible issues in
SchoolImportError.

Author: fspeirs

app/jobs/import_schools_job.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+class ImportSchoolsJob < ApplicationJob
+  retry_on StandardError, wait: :polynomially_longer, attempts: 3 do |_job, e|
+    Sentry.capture_exception(e)
+    raise e
+  end
+
+  queue_as :import_schools_job
+
+  def perform(schools_data:, user_id:, token:)
+    @results = {
+      successful: [],
+      failed: []
+    }
+
+    schools_data.each do |school_data|
+      import_school(school_data, user_id, token)
+    end
+
+    # Store results in dedicated table
+    store_results(@results, user_id)
+
+    @results
+  end
+
+  private
+
+  def store_results(results, user_id)
+    SchoolImportResult.create!(
+      job_id: job_id,
+      user_id: user_id,
+      results: results
+    )
+  rescue StandardError => e
+    Sentry.capture_exception(e)
+    # Don't fail the job if we can't store results
+  end
+
+  def import_school(school_data, _user_id, token)
+    owner = find_owner(school_data[:owner_email], token)
+
+    unless owner
+      @results[:failed] << {
+        name: school_data[:name],
+        error_code: SchoolImportError::CODES[:owner_not_found],
+        error: "Owner not found: #{school_data[:owner_email]}",
+        owner_email: school_data[:owner_email]
+      }
+      return
+    end
+
+    # Check if this owner already has a school as creator
+    existing_school = School.find_by(creator_id: owner[:id])
+    if existing_school
+      @results[:failed] << {
+        name: school_data[:name],
+        error_code: SchoolImportError::CODES[:owner_already_creator],
+        error: "Owner #{school_data[:owner_email]} is already the creator of school '#{existing_school.name}'",
+        owner_email: school_data[:owner_email],
+        existing_school_id: existing_school.id
+      }
+      return
+    end
+
+    school_params = build_school_params(school_data)
+
+    # Use transaction for atomicity
+    School.transaction do
+      result = School::Create.call(
+        school_params: school_params,
+        creator_id: owner[:id]
+      )
+
+      if result.success?
+        school = result[:school]
+
+        # Auto-verify the imported school
+        school.verify!
+
+        # Create owner role
+        Role.owner.create!(school_id: school.id, user_id: owner[:id])
+
+        @results[:successful] << {
+          name: school.name,
+          id: school.id,
+          code: school.code,
+          owner_email: school_data[:owner_email]
+        }
+      else
+        @results[:failed] << {
+          name: school_data[:name],
+          error_code: SchoolImportError::CODES[:school_validation_failed],
+          error: format_errors(result[:error]),
+          owner_email: school_data[:owner_email]
+        }
+      end
+    end
+  rescue StandardError => e
+    @results[:failed] << {
+      name: school_data[:name],
+      error_code: SchoolImportError::CODES[:unknown_error],
+      error: e.message,
+      owner_email: school_data[:owner_email]
+    }
+    Sentry.capture_exception(e)
+  end
+
+  def find_owner(email, _token)
+    return nil if email.blank?
+
+    users = UserInfoApiClient.search_by_email(email)
+    users&.first
+  rescue StandardError => e
+    Sentry.capture_exception(e)
+    nil
+  end
+
+  def build_school_params(school_data)
+    {
+      name: school_data[:name],
+      website: school_data[:website],
+      address_line_1: school_data[:address_line_1],
+      address_line_2: school_data[:address_line_2],
+      municipality: school_data[:municipality],
+      administrative_area: school_data[:administrative_area],
+      postal_code: school_data[:postal_code],
+      country_code: school_data[:country_code].upcase,
+      reference: school_data[:reference],
+      creator_agree_authority: true,
+      creator_agree_terms_and_conditions: true,
+      creator_agree_responsible_safeguarding: true,
+      user_origin: 'experience_cs'
+    }.compact
+  end
+
+  def format_errors(errors)
+    return errors.to_s unless errors.respond_to?(:full_messages)
+
+    errors.full_messages.join(', ')
+  end
+end

app/models/school_import_error.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module SchoolImportError
+  CODES = {
+    csv_invalid_format: 'CSV_INVALID_FORMAT',
+    csv_malformed: 'CSV_MALFORMED',
+    csv_validation_failed: 'CSV_VALIDATION_FAILED',
+    owner_not_found: 'OWNER_NOT_FOUND',
+    owner_already_creator: 'OWNER_ALREADY_CREATOR',
+    duplicate_owner_email: 'DUPLICATE_OWNER_EMAIL',
+    school_validation_failed: 'SCHOOL_VALIDATION_FAILED',
+    job_not_found: 'JOB_NOT_FOUND',
+    csv_file_required: 'CSV_FILE_REQUIRED',
+    unknown_error: 'UNKNOWN_ERROR'
+  }.freeze
+
+  class << self
+    def format_error(code, message, details = {})
+      {
+        error_code: CODES[code] || CODES[:unknown_error],
+        message: message,
+        details: details
+      }.compact
+    end
+
+    def format_row_errors(errors_array)
+      {
+        error_code: CODES[:csv_validation_failed],
+        message: 'CSV validation failed',
+        details: {
+          row_errors: errors_array
+        }
+      }
+    end
+  end
+end

app/models/school_import_result.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class SchoolImportResult < ApplicationRecord
+  validates :job_id, presence: true, uniqueness: true
+  validates :user_id, presence: true
+  validates :results, presence: true
+end

config/initializers/good_job.rb

@@ -18,5 +18,5 @@ def authenticate_admin
   # The create_students_job queue is a serial queue that allows only one job at a time.
   # DO NOT change the value of create_students_job:1 without understanding the implications
   # of processing more than one user creation job at once.
-  config.good_job.queues = 'create_students_job:1;default:5'
+  config.good_job.queues = 'create_students_job:1;import_schools_job:1;default:5'
 end

db/migrate/20251120092548_create_school_import_results.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+class CreateSchoolImportResults < ActiveRecord::Migration[7.1]
+  def change
+    create_table :school_import_results, id: :uuid do |t|
+      t.uuid :job_id, null: false
+      t.uuid :user_id, null: false
+      t.jsonb :results, null: false, default: {}
+      t.timestamps
+    end
+
+    add_index :school_import_results, :job_id, unique: true
+    add_index :school_import_results, :user_id
+  end
+end