create and read ownership transfer

app/controllers/api/ownership_transfers_controller.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Api
+  class OwnershipTransfersController < ApiController
+    before_action :authorize_user
+    load_and_authorize_resource :school
+    authorize_resource :ownership_transfer, class: false
+
+    def show
+      @ownership_transfer = most_recent_ownership_transfer
+
+      if @ownership_transfer.blank? || cannot?(:read, @ownership_transfer)
+        head :not_found
+      elsif current_user_is_requester?
+        render json: { status: @ownership_transfer.status, you_are: 'owner', nominee_name: nominee_name }, status: :ok
+      else
+        render json: { status: @ownership_transfer.status, you_are: 'nominee' }, status: :ok
+      end
+    end
+
+    def create
+      result = OwnershipTransfer::Create.call(school: @school, nominated_user_id:, requested_by_user_id: current_user.id)
+
+      if result.success?
+        head :created
+      else
+        render json: { error: result[:error] }, status: :unprocessable_content
+      end
+    end
+
+    private
+
+    def ownership_transfer_params
+      params.expect(ownership_transfer: [:nominated_user_id])
+    end
+
+    def nominated_user_id
+      ownership_transfer_params[:nominated_user_id]
+    end
+
+    def most_recent_ownership_transfer
+      @school.ownership_transfers.order(created_at: :desc).first
+    end
+
+    def current_user_is_requester?
+      @ownership_transfer.requested_by_user_id == current_user.id
+    end
+
+    def nominee_name
+      User.from_userinfo(ids: @ownership_transfer.nominated_user_id).first&.name
+    end
+  end
+end

app/models/ability.rb

@@ -39,6 +39,9 @@ def define_authenticated_abilities(user)
         invitation.email_address.present? &&
         invitation.email_address.casecmp?(user.email)
     end
+    can :read, OwnershipTransfer do |transfer|
+      user.id == transfer.requested_by_user_id || user.id == transfer.nominated_user_id
+    end
   end
 
   def define_authenticated_non_student_abilities(user)
@@ -82,6 +85,7 @@ def define_school_owner_abilities(school:)
     can(%i[read create create_batch destroy], ClassStudent, school_class: { school: { id: school.id } })
     can(%i[read create destroy], :school_owner)
     can(%i[read create destroy], :school_teacher)
+    can(%i[read create], :ownership_transfer)
     can(%i[read create create_batch update destroy destroy_batch], :school_student)
     can(%i[create create_copy], Lesson, school_id: school.id)
     can(%i[read update destroy], Lesson, school_id: school.id, visibility: %w[teachers students public])
@@ -98,6 +102,7 @@ def define_school_teacher_abilities(user:, school:)
     can(%i[read create create_batch destroy], ClassStudent, school_class: { school: { id: school.id }, teachers: { teacher_id: user.id } })
     can(%i[read], :school_owner)
     can(%i[read], :school_teacher)
+    can(:read, :ownership_transfer)
     can(%i[read create create_batch update], :school_student)
     can(%i[create update destroy], Lesson) do |lesson|
       school_teacher_can_manage_lesson?(user:, school:, lesson:)

app/models/ownership_transfer.rb

@@ -13,6 +13,9 @@ class OwnershipTransfer < ApplicationRecord
   validates :requested_by_user_id, presence: true
   validates :email_address,
             format: { with: EmailValidator.regexp, message: I18n.t('validations.invitation.email_address') }
+  validates :school_id,
+            uniqueness: { conditions: -> { where(status: :pending) }, message: I18n.t('validations.ownership_transfer.school_pending') },
+            on: :create
   validate :nominee_has_the_school_owner_or_school_teacher_role_for_the_school
 
   after_create_commit :send_ownership_transfer_request_email
@@ -23,7 +26,7 @@ class OwnershipTransfer < ApplicationRecord
   def nominee_has_the_school_owner_or_school_teacher_role_for_the_school
     return unless nominated_user_id_changed? && errors.blank? && school
 
-    return if school.roles.exists?(user_id: nominated_user_id, role: %i[owner teacher])
+    return if school.owner_or_teacher?(nominated_user_id)
 
     msg = "'#{nominated_user_id}' does not have the 'owner' or 'teacher' role for school '#{school.id}'"
     errors.add(:nominated_user_id, msg)

app/models/school.rb

@@ -133,6 +133,10 @@ def student_count
     roles.student.count
   end
 
+  def owner_or_teacher?(user_id)
+    roles.exists?(user_id:, role: %i[owner teacher])
+  end
+
   def postal_code=(str)
     super(str.to_s.upcase)
   end

config/locales/en.yml

@@ -23,6 +23,8 @@ en:
       school_roll_number_exists: "School roll number already exists"
     invitation:
       email_address: "'%<value>s' is invalid"
+    ownership_transfer:
+      school_pending: "already has a pending ownership transfer"
   activerecord:
     attributes:
       school_class:

config/routes.rb

@@ -87,6 +87,7 @@
 
       resources :owners, only: %i[index], controller: 'school_owners'
       resources :teachers, only: %i[index create], controller: 'school_teachers'
+      resource :ownership_transfer, only: %i[show create], controller: 'ownership_transfers'
       resources :students, only: %i[index create update destroy], controller: 'school_students' do
         post :batch, on: :collection, to: 'school_students#create_batch'
         delete :batch, on: :collection, to: 'school_students#destroy_batch'

db/migrate/20260915100000_add_unique_pending_index_to_ownership_transfers.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+class AddUniquePendingIndexToOwnershipTransfers < ActiveRecord::Migration[8.1]
+  disable_ddl_transaction!
+
+  def change
+    add_index :ownership_transfers, :school_id,
+              unique: true,
+              where: "status = 'pending'",
+              name: 'index_ownership_transfers_on_school_id_when_pending',
+              algorithm: :concurrently
+  end
+end

lib/concepts/ownership_transfer/create.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+class OwnershipTransfer
+  class Create
+    class << self
+      def call(school:, nominated_user_id:, requested_by_user_id:)
+        response = OperationResponse.new
+        ownership_transfer = build_ownership_transfer(school:, nominated_user_id:, requested_by_user_id:)
+
+        if ownership_transfer.save
+          response[:ownership_transfer] = ownership_transfer
+        else
+          response[:error] = ownership_transfer.errors
+        end
+
+        response
+      rescue ActiveRecord::RecordNotUnique
+        response ||= OperationResponse.new
+        ownership_transfer.errors.add(:school_id, I18n.t('validations.ownership_transfer.school_pending'))
+        response[:error] = ownership_transfer.errors
+        response
+      rescue StandardError => e
+        response ||= OperationResponse.new
+        Sentry.capture_exception(e)
+        response[:error] = "Error creating ownership transfer: #{e}"
+        response
+      end
+
+      private
+
+      def build_ownership_transfer(school:, nominated_user_id:, requested_by_user_id:)
+        email_address = nominee_email(school:, nominated_user_id:)
+        OwnershipTransfer.new(school:, nominated_user_id:, requested_by_user_id:, email_address:)
+      end
+
+      def nominee_email(school:, nominated_user_id:)
+        return unless school.owner_or_teacher?(nominated_user_id)
+
+        User.from_userinfo(ids: nominated_user_id).first&.email
+      end
+    end
+  end
+end

spec/concepts/ownership_transfer/create_spec.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+
+RSpec.describe OwnershipTransfer::Create, type: :unit do
+  let(:school) { create(:verified_school) }
+  let(:owner) { create(:owner, school:) }
+  let(:nominee) { create(:teacher, school:) }
+
+  before { stub_user_info_api_for(nominee) }
+
+  it 'returns a successful response and creates the transfer' do
+    response = described_class.call(school:, nominated_user_id: nominee.id, requested_by_user_id: owner.id)
+
+    expect(response.success?).to be(true)
+    expect(response[:ownership_transfer]).to have_attributes(
+      school:,
+      nominated_user_id: nominee.id,
+      requested_by_user_id: owner.id,
+      email_address: nominee.email
+    )
+  end
+
+  it 'returns a failure response when the nominee has no role at the school' do
+    response = described_class.call(school:, nominated_user_id: SecureRandom.uuid, requested_by_user_id: owner.id)
+
+    expect(response.failure?).to be(true)
+    expect(response[:error]).to be_present
+  end
+
+  context 'when a duplicate pending transfer is created concurrently' do
+    before do
+      allow(OwnershipTransfer).to receive(:new).and_wrap_original do |method, *args|
+        method.call(*args).tap do |ownership_transfer|
+          allow(ownership_transfer).to receive(:save).and_raise(ActiveRecord::RecordNotUnique)
+        end
+      end
+    end
+
+    it 'returns the same friendly error a non-concurrent duplicate would get, not the raw exception' do
+      response = described_class.call(school:, nominated_user_id: nominee.id, requested_by_user_id: owner.id)
+
+      expect(response.failure?).to be(true)
+      expect(response[:error][:school_id]).to include('already has a pending ownership transfer')
+    end
+
+    it 'does not report the race to Sentry, since it is an expected, handled outcome' do
+      allow(Sentry).to receive(:capture_exception)
+
+      described_class.call(school:, nominated_user_id: nominee.id, requested_by_user_id: owner.id)
+
+      expect(Sentry).not_to have_received(:capture_exception)
+    end
+  end
+
+  context 'when an unexpected error occurs' do
+    before do
+      allow(OwnershipTransfer).to receive(:new).and_raise(StandardError, 'boom')
+      allow(Sentry).to receive(:capture_exception)
+    end
+
+    it 'reports it to Sentry and returns a generic error' do
+      response = described_class.call(school:, nominated_user_id: nominee.id, requested_by_user_id: owner.id)
+
+      expect(Sentry).to have_received(:capture_exception)
+      expect(response.failure?).to be(true)
+      expect(response[:error]).to include('Error creating ownership transfer')
+    end
+  end
+end