Add remaining tracking events (#877)

## Status

- Closes
RaspberryPiFoundation/digital-editor-issues#1486

### What have changed?

This PR introduces a centralized EventTracker service and instruments
multiple API endpoints/jobs to record consistent analytics events
(project lifecycle events within classroom context, and school/class
membership events). It extends student batch creation to attribute
“Student - Created” events to the initiating user, and adds broad spec
coverage to assert the new event records.

Changes:

Added EventTracker service with helper logic to derive classroom
metadata (school_id, class_id, lesson_id, project_type, user_role,
optional student_id) and record Event rows.
Instrumented controllers and CreateStudentsJob to emit events such as
“Project - Opened/Saved/Created”, “Project - Submitted for review/Marked
as completed/Made visible”, “Student - Created”, and “Class - Student
added”.
Added/updated request/feature/job/service specs to validate recorded
event names, users, properties, and timestamps.

## Events not tracked:

- Student - Log in
Login likely needs to be tracked where authentication/session creation
actually happens.
- Project - Ran code - Explicitly excluded because it is covered by a
separate issue.
  - School - Created- Explicitly excluded from this PR.
- School - Created metadata for landing page / campaign parameters - Not
implemented because the issue notes that data is not currently captured
and needs a separate story.

## Events Tracked
Implemented:

- `Project - Created`
- `Project - Made visible`
- `Student - Created`
- `Class - Student added`
- `Project - Feedback given`
- `Project - Marked as completed`
- `Project - Opened`
- `Project - Saved`
- `Project - Submitted for review`

Metadata coverage:

- All new events go through `EventTracker`, so they get `user_id` and
`time`.
- All include `school_id`.
- Project events include `class_id`, `lesson_id`, and `project_type`.
- Project events also include `user_role` where relevant.
- Teacher/educator interactions with student projects include
`student_id`.
- `Student - Created` includes `student_id`; it includes `class_id` when
created through a class import, but standalone/batch student creation
has no class context available.

Author: abcampo-iry

app/controllers/api/class_members_controller.rb

@@ -37,6 +37,7 @@ def create
 
       if result.success?
         @class_member = result[:class_members].first
+        track_class_students_added([@class_member])
         render :show, formats: [:json], status: :created
       else
         render json: result.slice(:error, :errors), status: :unprocessable_content
@@ -55,6 +56,7 @@ def create_batch
       if result.failure? && result[:error].include?('No valid school members provided')
         render json: result, status: :unprocessable_content
       else
+        track_class_students_added(result[:class_members])
         successful = result[:class_members].map { |m| { success: true, user_id: m.user_id } }
         errors = result[:errors].map { |user_id, error| { success: false, user_id:, error: } }
         render json: successful + errors
@@ -115,5 +117,19 @@ def list_teachers(school, teacher_ids)
         { school_teachers: [] }
       end
     end
+
+    def track_class_students_added(class_members)
+      Array(class_members).grep(ClassStudent).each do |class_student|
+        student_id = class_student.student_id || class_student.student&.id
+        next if student_id.blank?
+
+        track_event(
+          'Class - Student added',
+          school_id: @school.id,
+          class_id: @school_class.id,
+          student_id:
+        )
+      end
+    end
   end
 end

app/controllers/api/feedback_controller.rb

@@ -24,6 +24,7 @@ def create
 
       if result.success?
         @feedback = result[:feedback]
+        track_project_event('Project - Feedback given', project)
         render :show, formats: [:json], status: :created
       else
         render json: { error: result[:error] }, status: :unprocessable_content

app/controllers/api/lessons/batch_controller.rb

@@ -18,6 +18,7 @@ def create_batch
           lessons_params: batch_lessons_params
         )
         @user = current_user
+        @results.select(&:success?).each { |result| track_project_event('Project - Created', result[:lesson].project) }
         render :create_batch, formats: [:json], status: :created
       end
 

app/controllers/api/lessons_controller.rb

@@ -33,6 +33,7 @@ def show
     def create
       result = Lesson::Create.call(lesson_params: create_params)
       if result.success?
+        track_project_event('Project - Created', result[:lesson].project)
         @lesson_with_user = result[:lesson].with_user
         render :show, formats: [:json], status: :created
       else
@@ -54,9 +55,11 @@ def create_copy
     def update
       # TODO: Consider removing user_id from the lesson_params for update so users can update other users' lessons without changing ownership
       # OR consider dropping user_id on lessons and using teacher id/ids on the class instead
+      previous_visibility = @lesson.visibility
       result = Lesson::Update.call(lesson: @lesson, lesson_params: update_params)
 
       if result.success?
+        track_project_event('Project - Made visible', result[:lesson].project) if previous_visibility != 'students' && result[:lesson].visibility == 'students'
         @lesson_with_user = result[:lesson].with_user
         render :show, formats: [:json], status: :ok
       else

app/controllers/api/projects/remixes_controller.rb

@@ -36,6 +36,7 @@ def create
 
         if result.success?
           @project = result[:project]
+          track_project_event('Project - Saved', @project)
           render '/api/projects/show', formats: [:json]
         else
           render json: { error: result[:error] }, status: :bad_request

app/controllers/api/projects_controller.rb

@@ -17,6 +17,8 @@ def index
     end
 
     def show
+      track_project_event('Project - Opened', @project) if current_user.present?
+
       if !@project.school_id.nil? && @project.lesson_id.nil?
         project_with_user = @project.with_student(current_user)
         @user = project_with_user[1]
@@ -31,6 +33,7 @@ def create
 
       if result.success?
         @project = result[:project]
+        track_project_event('Project - Created', @project)
         render :show, formats: [:json], status: :created
       else
         render json: { error: result[:error] }, status: :unprocessable_content
@@ -41,6 +44,7 @@ def update
       result = Project::Update.call(project: @project, update_hash: project_params, current_user:)
 
       if result.success?
+        track_project_event('Project - Saved', @project)
         render :show, formats: [:json]
       else
         render json: { error: result[:error] }, status: :unprocessable_content

app/controllers/api/school_classes_controller.rb

@@ -157,7 +157,7 @@ def create_school_students(school_students_params, school_class)
       {
         school_students: school_students_result[:school_students],
         errors: school_students_result[:errors]
-      }
+      }.tap { track_created_school_students(school_students_result[:school_students], class_id: school_class.id) }
     end
 
     def assign_students_to_class(school_class, school_students)
@@ -172,6 +172,7 @@ def assign_students_to_class(school_class, school_students)
         { success: false, student_id: user_id, school_class_id: school_class.id, error: error }
       end
 
+      track_imported_class_students_added(school_class, class_members_result[:class_members])
       class_members_result[:class_members] + class_members_errors
     end
 
@@ -221,5 +222,32 @@ def import_school_students_params
     def school_owner?
       current_user.school_owner?(@school)
     end
+
+    def track_created_school_students(school_students, class_id: nil)
+      Array(school_students).each do |school_student|
+        next unless school_student[:success] && school_student[:created]
+
+        track_event(
+          'Student - Created',
+          school_id: @school.id,
+          class_id:,
+          student_id: school_student[:student].id
+        )
+      end
+    end
+
+    def track_imported_class_students_added(school_class, class_members)
+      Array(class_members).grep(ClassStudent).each do |class_student|
+        student_id = class_student.student_id || class_student.student&.id
+        next if student_id.blank?
+
+        track_event(
+          'Class - Student added',
+          school_id: @school.id,
+          class_id: school_class.id,
+          student_id:
+        )
+      end
+    end
   end
 end

app/controllers/api/school_projects_controller.rb

@@ -23,9 +23,11 @@ def unsubmit
 
     def submit
       authorize! :submit, school_project
+      previous_status = school_project.status
       result = SchoolProject::SetStatus.call(school_project:, status: :submitted, user_id: current_user.id)
       if result.success?
         @school_project = result[:school_project]
+        track_project_event('Project - Submitted for review', @school_project.project) if previous_status != 'submitted'
         render :show_status, formats: [:json], status: :ok
       else
         render json: { error: result[:error] }, status: :unprocessable_content
@@ -45,9 +47,11 @@ def return
 
     def complete
       authorize! :complete, school_project
+      previous_status = school_project.status
       result = SchoolProject::SetStatus.call(school_project:, status: :complete, user_id: current_user.id)
       if result.success?
         @school_project = result[:school_project]
+        track_project_event('Project - Marked as completed', @school_project.project) if previous_status != 'complete'
         render :show_status, formats: [:json], status: :ok
       else
         render json: { error: result[:error] }, status: :unprocessable_content

app/controllers/api/school_students_controller.rb

@@ -27,6 +27,7 @@ def create
       )
 
       if result.success?
+        track_event('Student - Created', school_id: @school.id, student_id: result[:student_id]) if result[:student_id].present?
         head :no_content
       else
         render json: { error: result[:error] }, status: :unprocessable_content
@@ -86,7 +87,10 @@ def enqueue_batches(students)
       @batch.enqueue do
         students.each_slice(MAX_BATCH_CREATION_SIZE) do |student_batch|
           SchoolStudent::CreateBatch.call(
-            school: @school, school_students_params: student_batch, token: current_user.token
+            school: @school,
+            school_students_params: student_batch,
+            token: current_user.token,
+            actor_user_id: current_user.id
           )
         end
       end

app/controllers/api/scratch/projects_controller.rb

@@ -27,6 +27,7 @@ def create
           scratch_component.content = scratch_content_params
           existing_remix.save!
           move_assets_uploaded_by_current_user_before_remix(original_project:, remix_project: existing_remix)
+          track_project_event('Project - Saved', existing_remix)
 
           return render json: { status: 'ok', 'content-name': existing_remix.identifier }, status: :ok
         end
@@ -42,6 +43,7 @@ def create
 
         if result.success?
           move_assets_uploaded_by_current_user_before_remix(original_project:, remix_project: result[:project])
+          track_project_event('Project - Saved', result[:project])
           render json: { status: 'ok', 'content-name': result[:project].identifier }, status: :ok
         else
           render json: { error: result[:error] }, status: :bad_request
@@ -51,6 +53,7 @@ def create
       def update
         @project.scratch_component&.content = scratch_content_params
         @project.save!
+        track_project_event('Project - Saved', @project)
         render json: { status: 'ok' }, status: :ok
       end