Add "nhs_number_first_added_at" field to Patient

* Will be used by Automated Careplus reports

Jira-Issue: MAV-7091

Author: jf-x-dev

app/models/patient.rb

@@ -22,6 +22,7 @@
 #  invalidated_at             :datetime
 #  local_authority_mhclg_code :string
 #  nhs_number                 :string
+#  nhs_number_first_added_at  :datetime
 #  pending_changes            :jsonb            not null
 #  preferred_family_name      :string
 #  preferred_given_name       :string
@@ -47,6 +48,7 @@
 #  index_patients_on_names_family_first                   (family_name,given_name)
 #  index_patients_on_names_given_first                    (given_name,family_name)
 #  index_patients_on_nhs_number                           (nhs_number) UNIQUE
+#  index_patients_on_nhs_number_first_added_at            (nhs_number_first_added_at)
 #  index_patients_on_pending_changes_not_empty            (id) WHERE (pending_changes <> '{}'::jsonb)
 #  index_patients_on_school_id                            (school_id)
 #
@@ -495,6 +497,8 @@ class Patient < ApplicationRecord
                it.blank? ? nil : it.normalise_whitespace.gsub(/\s/, "")
              end
 
+  before_validation :set_nhs_number_first_added_at,
+                    if: :will_save_change_to_nhs_number?
   after_update :sync_vaccinations_to_nhs_immunisations_api
   after_commit :generate_important_notice_if_needed, on: :update
   after_commit :search_vaccinations_from_nhs_immunisations_api, on: :update
@@ -835,6 +839,14 @@ def destroy_childless_parents
     end
   end
 
+  def set_nhs_number_first_added_at
+    old_nhs_number, new_nhs_number = nhs_number_change_to_be_saved
+
+    return unless old_nhs_number.blank? && new_nhs_number.present?
+
+    self.nhs_number_first_added_at ||= Time.current
+  end
+
   def archive_due_to_deceased!
     archive_reasons =
       teams.map do |team|

db/migrate/20260422120000_add_nhs_number_first_added_at_for_patient.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class AddNHSNumberFirstAddedAtForPatient < ActiveRecord::Migration[8.1]
+  def up
+    add_column :patients, :nhs_number_first_added_at, :datetime
+    add_index :patients, :nhs_number_first_added_at
+
+    execute <<~SQL
+      UPDATE patients
+      SET nhs_number_first_added_at = created_at
+      WHERE nhs_number IS NOT NULL
+        AND nhs_number_first_added_at IS NULL
+    SQL
+  end
+
+  def down
+    remove_index :patients, :nhs_number_first_added_at
+    remove_column :patients, :nhs_number_first_added_at
+  end
+end

db/schema.rb

@@ -10,7 +10,7 @@
 #
 # It's strongly recommended that you check this file into your version control system.
 
-ActiveRecord::Schema[8.1].define(version: 2026_04_19_122121) do
+ActiveRecord::Schema[8.1].define(version: 2026_04_22_120000) do
   # These are extensions that must be enabled in order to support this database
   enable_extension "pg_catalog.plpgsql"
   enable_extension "pg_trgm"
@@ -755,6 +755,7 @@
     t.datetime "invalidated_at"
     t.string "local_authority_mhclg_code"
     t.string "nhs_number"
+    t.datetime "nhs_number_first_added_at"
     t.jsonb "pending_changes", default: {}, null: false
     t.string "preferred_family_name"
     t.string "preferred_given_name"
@@ -776,6 +777,7 @@
     t.index ["id"], name: "index_patients_on_pending_changes_not_empty", where: "(pending_changes <> '{}'::jsonb)"
     t.index ["local_authority_mhclg_code"], name: "index_patients_on_local_authority_mhclg_code"
     t.index ["nhs_number"], name: "index_patients_on_nhs_number", unique: true
+    t.index ["nhs_number_first_added_at"], name: "index_patients_on_nhs_number_first_added_at"
     t.index ["school_id"], name: "index_patients_on_school_id"
   end
 

spec/factories/patients.rb

@@ -22,6 +22,7 @@
 #  invalidated_at             :datetime
 #  local_authority_mhclg_code :string
 #  nhs_number                 :string
+#  nhs_number_first_added_at  :datetime
 #  pending_changes            :jsonb            not null
 #  preferred_family_name      :string
 #  preferred_given_name       :string
@@ -47,6 +48,7 @@
 #  index_patients_on_names_family_first                   (family_name,given_name)
 #  index_patients_on_names_given_first                    (given_name,family_name)
 #  index_patients_on_nhs_number                           (nhs_number) UNIQUE
+#  index_patients_on_nhs_number_first_added_at            (nhs_number_first_added_at)
 #  index_patients_on_pending_changes_not_empty            (id) WHERE (pending_changes <> '{}'::jsonb)
 #  index_patients_on_school_id                            (school_id)
 #
@@ -91,6 +93,7 @@
         "#{base}#{check_digit}"
       end
     end
+    nhs_number_first_added_at { nhs_number.present? ? Time.current : nil }
 
     given_name { Faker::Name.first_name }
     family_name { Faker::Name.last_name }

spec/models/patient_spec.rb

@@ -22,6 +22,7 @@
 #  invalidated_at             :datetime
 #  local_authority_mhclg_code :string
 #  nhs_number                 :string
+#  nhs_number_first_added_at  :datetime
 #  pending_changes            :jsonb            not null
 #  preferred_family_name      :string
 #  preferred_given_name       :string
@@ -47,6 +48,7 @@
 #  index_patients_on_names_family_first                   (family_name,given_name)
 #  index_patients_on_names_given_first                    (given_name,family_name)
 #  index_patients_on_nhs_number                           (nhs_number) UNIQUE
+#  index_patients_on_nhs_number_first_added_at            (nhs_number_first_added_at)
 #  index_patients_on_pending_changes_not_empty            (id) WHERE (pending_changes <> '{}'::jsonb)
 #  index_patients_on_school_id                            (school_id)
 #
@@ -1307,6 +1309,38 @@
     end
   end
 
+  describe "NHS number first added timestamp" do
+    it "sets nhs_number_first_added_at when an NHS number is first added" do
+      patient =
+        create(:patient, nhs_number: nil, nhs_number_first_added_at: nil)
+
+      freeze_time do
+        expect { patient.update!(nhs_number: "9449310475") }.to change {
+          patient.reload.nhs_number_first_added_at
+        }.from(nil).to(Time.current)
+      end
+    end
+
+    it "does not clear nhs_number_first_added_at when an NHS number is removed" do
+      patient = create(:patient)
+
+      expect { patient.update!(nhs_number: nil) }.not_to(
+        change { patient.reload.nhs_number_first_added_at }
+      )
+    end
+
+    it "does not overwrite nhs_number_first_added_at when an NHS number is re-added" do
+      patient = create(:patient)
+      first_added_at = patient.nhs_number_first_added_at
+
+      patient.update!(nhs_number: nil)
+
+      expect { patient.update!(nhs_number: "9449310475") }.not_to change {
+        patient.reload.nhs_number_first_added_at
+      }.from(first_added_at)
+    end
+  end
+
   describe "#should_search_vaccinations_from_nhs_immunisations_api?" do
     subject(:should_search_vaccinations_from_nhs_immunisations_api?) do
       patient.send(:should_search_vaccinations_from_nhs_immunisations_api?)