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/data/20260422120100_backfill_nhs_number_first_added_at_for_patients.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+class BackfillNHSNumberFirstAddedAtForPatients < ActiveRecord::Migration[8.1]
+  disable_ddl_transaction!
+
+  BATCH_SIZE = 1000
+
+  def up
+    migration = self.class.name
+    started_at = Time.zone.now
+    scope = Patient.where(nhs_number_first_added_at: nil).where.not(nhs_number: nil)
+    total_records = scope.count
+    total_batches = (total_records.to_f / BATCH_SIZE).ceil
+    records_updated = 0
+
+    Rails.logger.info(
+      event: "data_migration_start",
+      migration:,
+      total_records:,
+      batch_size: BATCH_SIZE,
+      total_batches:
+    )
+
+    scope.in_batches(of: BATCH_SIZE).each_with_index do |batch, index|
+      updated_count = batch.update_all("nhs_number_first_added_at = created_at")
+      records_updated += updated_count
+
+      Rails.logger.info(
+        event: "data_migration_batch",
+        migration:,
+        batch_number: index + 1,
+        total_batches:,
+        updated_count:,
+        records_updated:
+      )
+    end
+
+    duration_minutes = ((Time.zone.now - started_at) / 60.0).round
+
+    Rails.logger.info(
+      event: "data_migration_finish",
+      migration:,
+      duration_minutes:,
+      records_updated:
+    )
+  end
+
+  def down
+    raise ActiveRecord::IrreversibleMigration
+  end
+end

db/data_schema.rb

@@ -1 +1 @@
-DataMigrate::Data.define(version: 2026_04_22_155320)
+DataMigrate::Data.define(version: 2026_04_22_120100)

db/migrate/20260422120000_add_nhs_number_first_added_at_for_patient.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class AddNHSNumberFirstAddedAtForPatient < ActiveRecord::Migration[8.1]
+  def change
+    add_column :patients, :nhs_number_first_added_at, :datetime
+  end
+end

db/migrate/20260422120500_add_index_on_patients_nhs_number_first_added_at.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class AddIndexOnPatientsNHSNumberFirstAddedAt < ActiveRecord::Migration[8.1]
+  disable_ddl_transaction!
+
+  def change
+    add_index :patients, :nhs_number_first_added_at, algorithm: :concurrently
+  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_28_080729) do
+ActiveRecord::Schema[8.1].define(version: 2026_04_22_121000) do
   # These are extensions that must be enabled in order to support this database
   enable_extension "pg_catalog.plpgsql"
   enable_extension "pg_trgm"
@@ -162,7 +162,6 @@
     t.bigint "class_import_id", null: false
     t.bigint "parent_relationship_id", null: false
     t.index ["class_import_id", "parent_relationship_id"], name: "idx_on_class_import_id_parent_relationship_id_8225058195", unique: true
-    t.index ["parent_relationship_id", "class_import_id"], name: "idx_on_parent_relationship_id_class_import_id_d7c05d6c2c", unique: true
   end
 
   create_table "class_imports_parents", id: false, force: :cascade do |t|
@@ -220,7 +219,6 @@
     t.bigint "cohort_import_id", null: false
     t.bigint "parent_relationship_id", null: false
     t.index ["cohort_import_id", "parent_relationship_id"], name: "idx_on_cohort_import_id_parent_relationship_id_c65e20d1f8", unique: true
-    t.index ["parent_relationship_id", "cohort_import_id"], name: "idx_on_parent_relationship_id_cohort_import_id_40fb9846d6", unique: true
   end
 
   create_table "cohort_imports_parents", id: false, force: :cascade do |t|
@@ -457,7 +455,6 @@
     t.bigint "immunisation_import_id", null: false
     t.bigint "vaccination_record_id", null: false
     t.index ["immunisation_import_id", "vaccination_record_id"], name: "idx_on_immunisation_import_id_vaccination_record_id_588e859772", unique: true
-    t.index ["vaccination_record_id", "immunisation_import_id"], name: "idx_on_vaccination_record_id_immunisation_import_id_813c516ad7", unique: true
   end
 
   create_table "important_notices", force: :cascade do |t|
@@ -760,6 +757,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"
@@ -781,6 +779,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/features/cli_reports_send_to_careplus_spec.rb

@@ -115,7 +115,7 @@
         )
 
         then_the_error_output_includes(
-          "does not have CarePlus credentials configured"
+          "needs the CarePlus username, password, and namespace configured to send reports."
         )
         and_no_request_was_made
       end

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?)