School project statuses (#607)

## Status

closes
RaspberryPiFoundation/digital-editor-issues#985
closes
RaspberryPiFoundation/digital-editor-issues#986
closes
RaspberryPiFoundation/digital-editor-issues#988
closes
RaspberryPiFoundation/digital-editor-issues#995

## Points for consideration:

- Use of state machine

## What's changed?

- Added state machine to handle and log school project status changes

Author: loiswells97

Gemfile

@@ -37,6 +37,7 @@ gem 'rack-cors'
 gem 'rails', '~> 7.1'
 gem 'scout_apm'
 gem 'sentry-rails'
+gem 'statesman'
 
 group :development, :test do
   gem 'awesome_print'

Gemfile.lock

@@ -522,6 +522,7 @@ GEM
       actionpack (>= 6.1)
       activesupport (>= 6.1)
       sprockets (>= 3.0.0)
+    statesman (13.1.0)
     stringio (3.1.7)
     thor (1.4.0)
     tilt (2.6.1)
@@ -617,6 +618,7 @@ DEPENDENCIES
   sentry-rails
   shoulda-matchers (~> 5.0)
   simplecov
+  statesman
   webdrivers
   webmock
 

app/controllers/api/school_projects_controller.rb

@@ -5,17 +5,63 @@ class SchoolProjectsController < ApiController
     before_action :authorize_user
     load_and_authorize_resource :project
 
+    def show_status
+      authorize! :show_status, school_project
+      render :show_status, formats: [:json], status: :ok
+    end
+
+    def unsubmit
+      authorize! :unsubmit, school_project
+      result = SchoolProject::SetStatus.call(school_project:, status: :unsubmitted, user_id: current_user.id)
+      if result.success?
+        @school_project = result[:school_project]
+        render :show_status, formats: [:json], status: :ok
+      else
+        render json: { error: result[:error] }, status: :unprocessable_entity
+      end
+    end
+
+    def submit
+      authorize! :submit, school_project
+      result = SchoolProject::SetStatus.call(school_project:, status: :submitted, user_id: current_user.id)
+      if result.success?
+        @school_project = result[:school_project]
+        render :show_status, formats: [:json], status: :ok
+      else
+        render json: { error: result[:error] }, status: :unprocessable_entity
+      end
+    end
+
+    def return
+      authorize! :return, school_project
+      result = SchoolProject::SetStatus.call(school_project:, status: :returned, user_id: current_user.id)
+      if result.success?
+        @school_project = result[:school_project]
+        render :show_status, formats: [:json], status: :ok
+      else
+        render json: { error: result[:error] }, status: :unprocessable_entity
+      end
+    end
+
+    def complete
+      authorize! :complete, school_project
+      result = SchoolProject::SetStatus.call(school_project:, status: :complete, user_id: current_user.id)
+      if result.success?
+        @school_project = result[:school_project]
+        render :show_status, formats: [:json], status: :ok
+      else
+        render json: { error: result[:error] }, status: :unprocessable_entity
+      end
+    end
+
     def show_finished
-      @school_project = Project.find_by!(identifier: params[:id]).school_project
-      authorize! :show_finished, @school_project
+      authorize! :show_finished, school_project
       render :finished, formats: [:json], status: :ok
     end
 
     def set_finished
-      project = Project.find_by!(identifier: params[:id])
-      @school_project = project.school_project
-      authorize! :set_finished, @school_project
-      result = SchoolProject::SetFinished.call(school_project: @school_project, finished: params[:finished])
+      authorize! :set_finished, school_project
+      result = SchoolProject::SetFinished.call(school_project:, finished: params[:finished])
 
       if result.success?
         @school_project = result[:school_project]
@@ -24,5 +70,19 @@ def set_finished
         render json: { error: result[:error] }, status: :unprocessable_entity
       end
     end
+
+    private
+
+    def project
+      @project ||= Project.find_by!(identifier: params[:id])
+    end
+
+    def school_project
+      @school_project ||= project.school_project
+    end
+
+    def school_project_params
+      params.permit(:finished)
+    end
   end
 end

app/models/ability.rb

@@ -96,6 +96,7 @@ def define_school_teacher_abilities(user:, school:)
       )
     ).pluck(:id)
     can(%i[read], Project, remixed_from_id: teacher_project_ids)
+    can(%i[show_status unsubmit return complete], SchoolProject, project: { remixed_from_id: teacher_project_ids })
     can(%i[read create], Feedback, school_project: { project: { remixed_from_id: teacher_project_ids } })
   end
 
@@ -113,7 +114,7 @@ def define_school_student_abilities(user:, school:)
     can(%i[read create update], Project, school_id: school.id, user_id: user.id, lesson_id: nil, remixed_from_id: visible_lesson_project_ids)
     can(%i[read show_context], Project, lesson: { school_id: school.id, visibility: 'students', school_class: { students: { student_id: user.id } } })
     can(%i[read], Feedback, school_project: { project: { school_id: school.id, user_id: user.id, lesson_id: nil, remixed_from_id: visible_lesson_project_ids } })
-    can(%i[show_finished set_finished], SchoolProject, project: { user_id: user.id, lesson_id: nil }, school_id: school.id)
+    can(%i[show_finished set_finished show_status unsubmit submit], SchoolProject, project: { user_id: user.id, lesson_id: nil }, school_id: school.id)
   end
 
   def define_experience_cs_admin_abilities(user)

app/models/school_project.rb

@@ -4,4 +4,43 @@ class SchoolProject < ApplicationRecord
   belongs_to :school
   belongs_to :project
   has_many :feedback, dependent: :destroy
+  has_many :school_project_transitions, autosave: false, dependent: :nullify
+
+  include Statesman::Adapters::ActiveRecordQueries[
+    transition_class: ::SchoolProjectTransition,
+    initial_state: :unsubmitted
+  ]
+
+  def status
+    state_machine.current_state
+  end
+
+  def transition_status_to!(new_status, user_id)
+    state_machine.transition_to!(new_status, metadata: { changed_by: user_id })
+  end
+
+  # Add convenience methods for each state
+  def unsubmitted?
+    state_machine.in_state?(:unsubmitted)
+  end
+
+  def submitted?
+    state_machine.in_state?(:submitted)
+  end
+
+  def complete?
+    state_machine.in_state?(:complete)
+  end
+
+  def returned?
+    state_machine.in_state?(:returned)
+  end
+
+  delegate :can_transition_to?, :history, to: :state_machine
+
+  private
+
+  def state_machine
+    @state_machine ||= SchoolProjectStateMachine.new(self, transition_class: SchoolProjectTransition)
+  end
 end

app/models/school_project_transition.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+class SchoolProjectTransition < ApplicationRecord
+  include Statesman::Adapters::ActiveRecordTransition
+
+  belongs_to :school_project, inverse_of: :school_project_transitions
+
+  after_destroy :update_most_recent, if: :most_recent?
+
+  private
+
+  def update_most_recent
+    last_transition = school_project.school_project_transitions.order(:sort_key).last
+    return if last_transition.blank?
+
+    last_transition.update!(most_recent: true)
+  end
+end

app/state_machines/school_project_state_machine.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+class SchoolProjectStateMachine
+  include Statesman::Machine
+
+  # Define all possible states
+  state :unsubmitted, initial: true
+  state :submitted
+  state :returned
+  state :complete
+
+  # Define transition rules
+  transition from: :unsubmitted, to: %i[submitted complete]
+  transition from: :submitted, to: %i[unsubmitted returned complete]
+  transition from: :returned, to: %i[submitted complete]
+  transition from: :complete, to: [:unsubmitted]
+end

app/views/api/school_projects/show_status.json.jbuilder

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+json.call(
+  @school_project,
+  :id,
+  :school_id,
+  :project_id,
+  :status
+)
+
+json.identifier(@school_project.project.identifier)

config/initializers/statesman.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+Statesman.configure do
+  storage_adapter(Statesman::Adapters::ActiveRecord)
+end

config/routes.rb

@@ -38,6 +38,11 @@
       get :finished, on: :member, to: 'school_projects#show_finished'
       get :context, on: :member, to: 'projects#show_context'
       put :finished, on: :member, to: 'school_projects#set_finished'
+      get :status, on: :member, to: 'school_projects#show_status'
+      post :unsubmit, on: :member, to: 'school_projects#unsubmit'
+      post :submit, on: :member, to: 'school_projects#submit'
+      post :return, on: :member, to: 'school_projects#return'
+      post :complete, on: :member, to: 'school_projects#complete'
       resource :remix, only: %i[show create], controller: 'projects/remixes'
       resources :remixes, only: %i[index], controller: 'projects/remixes'
       resource :images, only: %i[show create], controller: 'projects/images'