Screening phase 1

app/controllers/api/v3/medical_histories_controller.rb

@@ -24,7 +24,12 @@ def merge_if_valid(medical_history_params)
         .merge(metadata)
 
       medical_history = MedicalHistory.merge(record_params)
-      {record: medical_history}
+
+      if medical_history.errors.any?
+        {errors_hash: errors_hash(medical_history)}
+      else
+        {record: medical_history}
+      end
     end
   end
 
@@ -48,6 +53,8 @@ def medical_histories_params
         :smoking,
         :smokeless_tobacco,
         :cholesterol,
+        :htn_diagnosed_at,
+        :dm_diagnosed_at,
         :created_at,
         :updated_at
       )

app/models/concerns/diagnosed_confirmed_at_sync.rb

@@ -0,0 +1,42 @@
+module DiagnosedConfirmedAtSync
+  extend ActiveSupport::Concern
+
+  included do
+    after_commit :sync_diagnosed_confirmed_at, on: [:create, :update]
+  end
+
+  private
+
+  def sync_diagnosed_confirmed_at
+    patient = extract_patient
+    return unless patient
+
+    mh = patient.medical_history
+    return unless mh
+
+    valid_htn = mh.htn_diagnosed_at.present? && %w[yes no].include?(mh.hypertension)
+    valid_dm = mh.dm_diagnosed_at.present? && %w[yes no].include?(mh.diabetes)
+
+    return unless valid_htn || valid_dm
+
+    earliest = [
+      (mh.htn_diagnosed_at if valid_htn),
+      (mh.dm_diagnosed_at if valid_dm)
+    ].compact.min
+
+    return if earliest.blank?
+
+    if patient.diagnosed_confirmed_at.nil?
+      patient.update_columns(diagnosed_confirmed_at: earliest)
+    end
+  end
+
+  def extract_patient
+    case self
+    when Patient
+      self
+    when MedicalHistory
+      patient
+    end
+  end
+end

app/models/medical_history.rb

@@ -1,5 +1,7 @@
 class MedicalHistory < ApplicationRecord
   include Mergeable
+  include DiagnosedConfirmedAtSync
+
   belongs_to :patient, optional: true
   belongs_to :user, optional: true
 
@@ -29,15 +31,92 @@ class MedicalHistory < ApplicationRecord
   enum chronic_kidney_disease: MEDICAL_HISTORY_ANSWERS, _prefix: true
   enum receiving_treatment_for_hypertension: MEDICAL_HISTORY_ANSWERS, _prefix: true
   enum receiving_treatment_for_diabetes: MEDICAL_HISTORY_ANSWERS, _prefix: true
-  enum diabetes: MEDICAL_HISTORY_ANSWERS, _prefix: true
-  enum hypertension: MEDICAL_HISTORY_ANSWERS, _prefix: true
-  enum diagnosed_with_hypertension: MEDICAL_HISTORY_ANSWERS, _prefix: true
   enum smoking: MEDICAL_HISTORY_ANSWERS, _prefix: true
   enum smokeless_tobacco: MEDICAL_HISTORY_ANSWERS, _prefix: true
+  enum diabetes: MEDICAL_HISTORY_ANSWERS.merge(suspected: "suspected"), _prefix: true
+  enum hypertension: MEDICAL_HISTORY_ANSWERS.merge(suspected: "suspected"), _prefix: true
+  enum diagnosed_with_hypertension: MEDICAL_HISTORY_ANSWERS.merge(suspected: "suspected"), _prefix: true
 
   scope :for_sync, -> { with_discarded }
 
+  before_validation :backfill_diagnosed_dates
+  before_validation :silently_enforce_medical_history_rules
+
   def indicates_hypertension_risk?
     prior_heart_attack_yes? || prior_stroke_yes?
   end
+
+  private
+
+  def silently_enforce_medical_history_rules
+    enforce_date_rules_silently
+    enforce_one_way_enums_silently
+  end
+
+  def backfill_diagnosed_dates
+    return if htn_diagnosed_at.present? || dm_diagnosed_at.present?
+    return if hypertension_suspected? || diabetes_suspected?
+
+    source = patient&.recorded_at
+    return unless source.present?
+
+    if %w[yes no].include?(hypertension&.to_s)
+      self.htn_diagnosed_at ||= source
+    end
+
+    if %w[yes no].include?(diabetes&.to_s)
+      self.dm_diagnosed_at ||= source
+    end
+  end
+
+  def enforce_one_way_enums_silently
+    %i[hypertension diabetes diagnosed_with_hypertension].each do |attr|
+      prev = send("#{attr}_was")
+      curr = send(attr)
+
+      next if prev.blank? || prev.to_s == curr.to_s
+
+      prev_s = prev.to_s
+      curr_s = curr.to_s
+
+      if prev_s == "suspected"
+        next
+      end
+
+      if %w[yes no].include?(prev_s) && curr_s == "suspected"
+        write_attribute(attr, prev_s)
+
+        case attr
+        when :hypertension
+          write_attribute(:htn_diagnosed_at, htn_diagnosed_at_was)
+        when :diabetes
+          write_attribute(:dm_diagnosed_at, dm_diagnosed_at_was)
+        end
+
+        Rails.logger.info(
+          "[MedicalHistory] Prevented change of #{attr} from #{curr_s} -> #{prev_s} for medical_history_id=#{id || "new"}"
+        )
+        next
+      end
+    end
+  end
+
+  def enforce_date_rules_silently
+    self.htn_diagnosed_at = nil unless %w[yes no].include?(hypertension&.to_s)
+    self.dm_diagnosed_at = nil unless %w[yes no].include?(diabetes&.to_s)
+
+    if htn_diagnosed_at_was.present? && !timestamps_equal?(htn_diagnosed_at, htn_diagnosed_at_was)
+      write_attribute(:htn_diagnosed_at, htn_diagnosed_at_was)
+      Rails.logger.info("[MedicalHistory] Silently preserved existing htn_diagnosed_at for id=#{id || "new"}")
+    end
+
+    if dm_diagnosed_at_was.present? && !timestamps_equal?(dm_diagnosed_at, dm_diagnosed_at_was)
+      write_attribute(:dm_diagnosed_at, dm_diagnosed_at_was)
+      Rails.logger.info("[MedicalHistory] Silently preserved existing dm_diagnosed_at for id=#{id || "new"}")
+    end
+  end
+
+  def timestamps_equal?(a, b)
+    a&.change(usec: 0) == b&.change(usec: 0)
+  end
 end

app/models/patient.rb

@@ -3,6 +3,7 @@ class Patient < ApplicationRecord
   include Mergeable
   include Hashable
   include PatientReportable
+  include DiagnosedConfirmedAtSync
 
   GENDERS = Rails.application.config.country[:supported_genders].freeze
   STATUSES = %w[active dead migrated unresponsive inactive].freeze

app/schema/api/v3/models.rb

@@ -304,12 +304,14 @@ def medical_history
          chronic_kidney_disease: {type: :string, enum: MedicalHistory::MEDICAL_HISTORY_ANSWERS.keys},
          receiving_treatment_for_hypertension: {type: :string, enum: MedicalHistory::MEDICAL_HISTORY_ANSWERS.keys},
          receiving_treatment_for_diabetes: {type: :string, enum: MedicalHistory::MEDICAL_HISTORY_ANSWERS.keys},
-         diabetes: {type: :string, enum: MedicalHistory::MEDICAL_HISTORY_ANSWERS.keys},
-         hypertension: {type: :string, enum: MedicalHistory::MEDICAL_HISTORY_ANSWERS.keys},
-         diagnosed_with_hypertension: {type: :string, enum: MedicalHistory::MEDICAL_HISTORY_ANSWERS.keys},
+         diabetes: {type: :string, enum: MedicalHistory::MEDICAL_HISTORY_ANSWERS.keys + ["suspected"]},
+         hypertension: {type: :string, enum: MedicalHistory::MEDICAL_HISTORY_ANSWERS.keys + ["suspected"]},
+         diagnosed_with_hypertension: {type: :string, enum: MedicalHistory::MEDICAL_HISTORY_ANSWERS.keys + ["suspected"]},
          smoking: {type: :string, enum: MedicalHistory::MEDICAL_HISTORY_ANSWERS.keys},
          smokeless_tobacco: {type: :string, enum: MedicalHistory::MEDICAL_HISTORY_ANSWERS.keys},
          cholesterol_value: {type: :number},
+         htn_diagnosed_at: {"$ref" => "#/definitions/nullable_timestamp"},
+         dm_diagnosed_at: {"$ref" => "#/definitions/nullable_timestamp"},
          deleted_at: {"$ref" => "#/definitions/nullable_timestamp"},
          created_at: {"$ref" => "#/definitions/timestamp"},
          updated_at: {"$ref" => "#/definitions/timestamp"}

app/validators/api/v3/medical_history_payload_validator.rb

@@ -13,6 +13,8 @@ class Api::V3::MedicalHistoryPayloadValidator < Api::V3::PayloadValidator
     :smoking,
     :smokeless_tobacco,
     :cholesterol,
+    :htn_diagnosed_at,
+    :dm_diagnosed_at,
     :created_at,
     :updated_at
   )

app/validators/api/v3/patient_payload_validator.rb

@@ -23,6 +23,7 @@ class Api::V3::PatientPayloadValidator < Api::V3::PayloadValidator
     :reminder_consent,
     :deleted_reason,
     :skip_facility_authorization,
+    :diagnosed_confirmed_at,
     :eligible_for_reassignment
   )
 

config/initializers/filter_parameter_logging.rb

@@ -22,6 +22,7 @@ module ParameterFiltering
     status
     updated_at
     v2
+    diagnosed_confirmed_at
   ].freeze
 
   ALLOWED_REGEX = /(^|_)ids?|#{Regexp.union(ALLOWED_ATTRIBUTES)}/.freeze

config/schema_descriptions.yml

@@ -194,6 +194,7 @@ reporting_patient_states:
     diabetes_treatment_outcome_in_last_2_months: "For the visiting period of the last 2 months, is this patient's diabetes treatment outcome bs_under_200, bs_200_to_300, bs_over_300, missed_visit, or visited_no_bp?"
     diabetes_treatment_outcome_in_quarter: "For the visiting period of the current quarter, is this patient's diabetes treatment outcome bs_under_200, bs_200_to_300, bs_over_300, missed_visit, or visited_no_bp?"
     titrated: "True, if the patient had an increase in dosage of any hypertension drug in a visit this month."
+    diagnosed_confirmed_at: "Time (in UTC) at which the patient had it's first diagnosis completed, also differentiating him from screened patients."
 reporting_facilities:
   description: "List of Simple facililities with size, type, and geographical information. These facilities are used to segment reports by region."
   columns:

db/migrate/20251112085230_add_diagnosed_confirmed_at_to_patients.rb

@@ -0,0 +1,16 @@
+class AddDiagnosedConfirmedAtToPatients < ActiveRecord::Migration[6.1]
+  def up
+    add_column :patients, :diagnosed_confirmed_at, :datetime
+
+    execute <<~SQL.squish
+      UPDATE patients
+      SET diagnosed_confirmed_at = recorded_at
+      WHERE diagnosed_confirmed_at IS NULL
+        AND recorded_at IS NOT NULL;
+    SQL
+  end
+
+  def down
+    remove_column :patients, :diagnosed_confirmed_at
+  end
+end

db/migrate/20251112091000_add_diagnosis_timestamps_to_medical_histories.rb

@@ -0,0 +1,35 @@
+class AddDiagnosisTimestampsToMedicalHistories < ActiveRecord::Migration[6.1]
+  def up
+    add_column :medical_histories, :htn_diagnosed_at, :datetime
+    add_column :medical_histories, :dm_diagnosed_at, :datetime
+
+    say_with_time "Backfilling diagnosis timestamps for existing medical histories" do
+      MedicalHistory.includes(:patient).find_each(batch_size: 1000) do |mh|
+        next unless mh.patient
+
+        htn_time =
+          if %w[yes no].include?(mh.diagnosed_with_hypertension) ||
+              %w[yes no].include?(mh.hypertension)
+            mh.patient.recorded_at
+          end
+
+        dm_time =
+          if %w[yes no].include?(mh.diabetes)
+            mh.patient.recorded_at
+          end
+
+        next unless htn_time || dm_time
+
+        mh.update_columns(
+          htn_diagnosed_at: htn_time,
+          dm_diagnosed_at: dm_time
+        )
+      end
+    end
+  end
+
+  def down
+    remove_column :medical_histories, :htn_diagnosed_at
+    remove_column :medical_histories, :dm_diagnosed_at
+  end
+end