feat(siret_champ): converge technical fetch failures to degraded mode

Exhausted retries or a non-retryable non-404 failure now create a
degraded etablissement (champ fetched) so acceptance stays blocked and
backfill jobs recover the data. Only a 404 ends in external_error.

Author: E-L-T

app/jobs/champ_fetch_external_data_job.rb

@@ -6,7 +6,7 @@ class ChampFetchExternalDataJob < ApplicationJob
 
   retry_on RetryableFetchError, attempts: 3, wait: :polynomially_longer do |job, err|
     champ = job.arguments.first
-    champ.external_data_error!
+    champ.handle_exhausted_external_data_retries!
 
     # Don't raise, otherwise it will pop forever as "working" queue without doing anything
     Sentry.capture_exception(err.cause)

app/models/champs/siret_champ.rb

@@ -60,11 +60,25 @@ def fetch_external_data
       Success(etablissement:, value: external_id)
     in Failure(type: :not_found, **)
       Failure(retryable: false, error: StandardError.new('NotFound'), code: 404)
-    in Failure(type:, code:, retryable:, **)
-      Failure(retryable:, error: StandardError.new("API Entreprise: #{type}"), code:)
+    in Failure(type:, code:, retryable: true, **)
+      Failure(retryable: true, error: StandardError.new("API Entreprise: #{type}"), code:)
+    in Failure(type:, code:, **)
+      # Any other technical error also converges to degraded mode: only a 404
+      # (nonexistent SIRET) leaves the champ in external_error.
+      Sentry.capture_message("SiretChamp: degraded mode fallback after API Entreprise error", extra: { champ: id, type:, code: })
+      Success(etablissement: create_degraded_etablissement, value: external_id)
     end
   end
 
+  # Retries exhausted (API Entreprise flapping while the health checker still
+  # reports it up): converge to a degraded etablissement instead of
+  # external_error, so that Dossier#any_etablissement_as_degraded_mode? blocks
+  # acceptance and the backfill jobs recover the data later.
+  def handle_exhausted_external_data_retries!
+    update_external_data!(etablissement: create_degraded_etablissement, value: external_id)
+    external_data_fetched!
+  end
+
   def search_terms
     etablissement.present? ? etablissement.search_terms : [value]
   end
@@ -77,6 +91,10 @@ def save_additional_job_exception(exception, code)
 
   private
 
+  def create_degraded_etablissement
+    APIEntrepriseService.create_etablissement_as_degraded_mode(self, external_id.delete(" "), dossier.user&.id)
+  end
+
   # We want to validate if SIRET really exists
   # It's valid when an etablissement have been created in turbo with SIRET controller
   # When API Entreprise is down, user won't be stuck because

app/models/concerns/champ_external_data_concern.rb

@@ -47,7 +47,9 @@ module ChampExternalDataConcern
       end
 
       event :external_data_fetched do
-        transitions from: [:fetching], to: :fetched
+        # waiting_for_job: a champ can converge to fetched from the retry_on
+        # exhaustion block (see #handle_exhausted_external_data_retries!)
+        transitions from: [:fetching, :waiting_for_job], to: :fetched
       end
 
       event :external_data_error do
@@ -72,6 +74,11 @@ def has_async_external_data? = false
 
   def external_data_needed_for_validation? = has_async_external_data?
 
+  # Called by ChampFetchExternalDataJob when all retry attempts are exhausted.
+  def handle_exhausted_external_data_retries!
+    external_data_error!
+  end
+
   private
 
   def ready_for_external_call? = external_id.present?

spec/jobs/champ_fetch_external_data_job_spec.rb

@@ -66,5 +66,30 @@
         expect(champ.fetch_external_data_exceptions.size).to eq(3)
       end
     end
+
+    context 'when retries are exhausted on a siret champ' do
+      let(:procedure) { create(:procedure, :published, types_de_champ_public: [{ type: :siret }]) }
+      let(:dossier) { create(:dossier, procedure:) }
+      let(:external_id) { '41816609600051' }
+
+      before do
+        champ.update_columns(external_id:, external_state: 'waiting_for_job')
+        allow_any_instance_of(Champs::SiretChamp).to receive(:fetch_external_data).and_return(failure)
+      end
+
+      it 'converges to a degraded etablissement instead of external_error' do
+        described_class.perform_later(champ, external_id)
+
+        3.times do
+          perform_enqueued_jobs(only: ChampFetchExternalDataJob)
+        rescue StandardError
+        end
+
+        champ.reload
+
+        expect(champ).to be_fetched
+        expect(champ.etablissement).to be_as_degraded_mode
+      end
+    end
   end
 end

spec/models/champs/siret_champ_spec.rb

@@ -259,6 +259,21 @@
       end
     end
 
+    context 'when API returns a non-retryable technical failure' do
+      before do
+        allow(APIEntrepriseService).to receive(:create_etablissement_with_fallback)
+          .and_return(Dry::Monads::Failure(type: :forbidden, code: 403, retryable: false))
+        allow(Sentry).to receive(:capture_message)
+      end
+
+      it 'converges to a degraded etablissement instead of external_error' do
+        result = champ.fetch_external_data
+        expect(result).to be_success
+        expect(result.value![:etablissement]).to be_as_degraded_mode
+        expect(Sentry).to have_received(:capture_message)
+      end
+    end
+
     context 'when API returns Success in degraded mode' do
       let(:etablissement) { instance_double(Etablissement, as_degraded_mode?: true) }
       before do
@@ -300,7 +315,7 @@
     end
   end
 
-  describe '#external_data_status_message' do
+  describe '#external_data_status_message (unit)' do
     let(:champ) { Champs::SiretChamp.new }
 
     it 'returns nil when fetched' do
@@ -349,6 +364,29 @@
     end
   end
 
+  describe '#handle_exhausted_external_data_retries!' do
+    let(:procedure) { create(:procedure, types_de_champ_public: [{ type: :siret }]) }
+    let(:dossier) { create(:dossier, procedure:) }
+    let(:champ) { dossier.champs.first }
+
+    before do
+      champ.update_columns(
+        external_id: '41816609600051',
+        external_state: 'waiting_for_job',
+        fetch_external_data_exceptions: [ExternalDataException.new(error: 'boom', code: 503)]
+      )
+    end
+
+    it 'converges to a degraded etablissement instead of external_error' do
+      expect { champ.handle_exhausted_external_data_retries! }
+        .to have_enqueued_job(APIEntreprise::EtablissementJob)
+
+      champ.reload
+      expect(champ).to be_fetched
+      expect(champ.etablissement).to be_as_degraded_mode
+    end
+  end
+
   describe '#external_data_required_for_conditions?' do
     let(:procedure) { create(:procedure, types_de_champ_public: [{ type: :siret }, { type: :text }]) }
     let(:siret_tdc) { procedure.draft_revision.types_de_champ_public.first }