Handle unavailable seasons with validated fallback

CHECKSUMS.sha256

@@ -10,9 +10,9 @@ a68770f781b7acacfaaf56e5110d9846b7001e87d9936d433990b8393d5b86e5  TUTORIAL.md
 e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855  app/__init__.py
 c4891fc509f38fb94d9006be910c18b7573645c11da3532c38356302d99c7e55  app/config.py
 e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855  app/core/__init__.py
-ac21a5ed1bb8695b6dad694de61c2c85b5ad7c086f5ca9b9c41f484084a88caf  app/core/analyzer.py
+9511f0e32638b1951f5e153d76e827bf67c54b250e6863c32fcadd76f01ab43a  app/core/analyzer.py
 48c155a14807a76713edb7579076fa877587e5cff9e35f8f7d0fef35d821396f  app/core/calibration.py
-545b836f97ca6f9d847055ae2632f3dfefdee0749555e0e4622d7addc6f3b554  app/core/competitions.py
+ecc608094af12bc17a728263a7e963bde91ea26ac2a8715101e7493735f95453  app/core/competitions.py
 0545a029d7488a10cc6d3dd8d2c69c38d5b6b3246ceb34b035ed0f2b77570e49  app/core/history.py
 d2a9298d6d322fecb72184990c6c7bd720be5b3b12fb9245615f3687ee890aba  app/core/market.py
 70922a2b322aeb7512ba9147e391687cb8d50083523d03fa3fd6ae9441a94fc2  app/core/names.py
@@ -21,9 +21,9 @@ abf7d9982399348a65b3f1e1b14ccdbe03e0b37c984eff790ed59248738fa56c  app/core/ticke
 8c76f9b59d601719dee412f494a964ea588ff5e6393af49c203765524fe26bd2  app/logging_config.py
 2c30ffa77b5c69a67ab90a257504af4372909de8e95c4f61e32b752352f112d9  app/main.py
 34193815ff5356263a850c254ab48a2850b12f3b623831ea81b61708fced9519  app/models.py
-c1af8e753cd3c63f2286719b2ae091ec3364d365f287bf7db9cb3747f2203ca0  app/pipeline.py
+87235eccba7b95cc05a9a5239d6c17ceeb8ddc11c1c2efebd6daea2182fbb92f  app/pipeline.py
 e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855  app/providers/__init__.py
-bd060539c6d9bedb43d57aa7ff1e514bcf0a837b25d3db37212052fd23068465  app/providers/football_data.py
+d6f32051d88974c1816db0b83570698cdc35c83d9381ce99d769160905e656f1  app/providers/football_data.py
 1ffb376b0856a863a512d06ae36a736003692a8bbf5e74cfe23704c2c98f29d9  app/providers/http_client.py
 255c1050280cb7c1816c4c0c05aba96c4ac75c547415ada1e91dd8d17078fea2  app/providers/odds_api.py
 adfcb95146b325af7cfddb67e1ab29f714f912736374c6d0d384f9ba93139659  app/static/app.js
@@ -36,5 +36,5 @@ e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855  data/.gitkeep
 8636f9ab1a075be9f3039e2a6471837259c4f36b625bcaf7a3d9a1edd2419c6d  requirements-dev.txt
 27d9fc069a1ce60bdf78cf32226af023d57a63c5ab4076797edb3d05258a5397  requirements.txt
 66b37f1efcf7bc1f3b2c2437dc991f489a0413b3de9268565fd17eca882880b2  tests/test_core.py
-a0af163abacd7022e70f87b92e7da89a1b87aea4c34588287bd2e4c345d8228a  tests/test_pipeline.py
-c1dadd7cd92ba0732867b4f7ba7775c09427358a5a1bc5e43a062956c257d964  tests/test_robustness.py
+75901c556c3e578d6e075d81a9fb686e6129731c997bbe6555611b85bcc67d56  tests/test_pipeline.py
+2698e47665232af00cc3d951b3c673473eb7a889c364a4da57f01fc809801526  tests/test_robustness.py

app/core/analyzer.py

@@ -5,7 +5,7 @@ from statistics import pstdev
 
 from app.config import MODEL_VERSION
 from app.core.calibration import calibrate_probability
-from app.core.competitions import competition_for_sport_key
+from app.core.competitions import MIN_COMPETITION_HISTORY, competition_for_sport_key
 from app.core.market import market_consensus
 from app.core.names import build_team_catalog, resolve_event_pair
 from app.core.stats import build_elo, predictive_models, tune_ensemble_weights
@@ -121,7 +121,7 @@ def analyze_events(
 
         comp_code = spec.football_data_code
         comp_matches = matches_by_comp.get(comp_code, [])
-        if len(comp_matches) < 40:
+        if len(comp_matches) < MIN_COMPETITION_HISTORY:
             rejected.append({
                 "event": event_name,
                 "reason": f"histórico insuficiente em {comp_code} ({len(comp_matches)} jogos)",

app/core/competitions.py

@@ -4,6 +4,9 @@ from dataclasses import dataclass
 from datetime import date
 
 
+MIN_COMPETITION_HISTORY = 40
+
+
 @dataclass(frozen=True)
 class CompetitionSpec:
     sport_key: str

app/pipeline.py

@@ -165,6 +165,11 @@ class DailyPipeline:
                         f"{len(football_meta['errors'])} consulta(s) de histórico falharam; "
                         "o cache foi preservado quando disponível."
                     )
+                if football_meta.get("fallbacks"):
+                    warnings.append(
+                        f"{len(football_meta['fallbacks'])} temporada(s) atual(is) ainda "
+                        "não publicada(s); o histórico anterior foi carregado."
+                    )
 
                 remaining = odds.quota.get("remaining")
                 if isinstance(remaining, int) and remaining < 50:

app/providers/football_data.py

@@ -6,7 +6,11 @@ from datetime import datetime, timedelta, timezone
 import logging
 import time
 
-from app.core.competitions import requested_competitions, season_start_year
+from app.core.competitions import (
+    MIN_COMPETITION_HISTORY,
+    requested_competitions,
+    season_start_year,
+)
 from app.models import FinishedMatch
 from app.providers.http_client import ResilientHTTP, ProviderError
 
@@ -110,7 +114,11 @@ class FootballDataProvider:
             away_aliases=cls._team_aliases(away),
         )
 
-    async def _fetch_season(self, competition_code: str, season: int) -> tuple[list[FinishedMatch], str | None]:
+    async def _fetch_season(
+        self,
+        competition_code: str,
+        season: int,
+    ) -> tuple[list[FinishedMatch], str | None, int | None]:
         try:
             payload = await self._get(
                 f"{self.BASE}/competitions/{competition_code}/matches",
@@ -123,15 +131,15 @@ class FootballDataProvider:
                 and "token" in message
                 and any(word in message for word in ("invalid", "missing", "invalido"))
             )
-            if exc.status_code == 401 or invalid_token:
+            if exc.status_code in {401, 429} or invalid_token:
                 raise
-            return [], f"{competition_code}/{season}: {exc}"
+            return [], f"{competition_code}/{season}: {exc}", exc.status_code
         except Exception as exc:
-            return [], f"{competition_code}/{season}: {type(exc).__name__}: {exc}"
+            return [], f"{competition_code}/{season}: {type(exc).__name__}: {exc}", None
 
         items = payload.get("matches")
         if not isinstance(items, list):
-            return [], f"{competition_code}/{season}: resposta sem lista de partidas"
+            return [], f"{competition_code}/{season}: resposta sem lista de partidas", 200
 
         out: list[FinishedMatch] = []
         for item in items:
@@ -139,8 +147,8 @@ class FootballDataProvider:
             if match:
                 out.append(match)
         if items and not out:
-            return [], f"{competition_code}/{season}: nenhuma partida válida na resposta"
-        return out, None
+            return [], f"{competition_code}/{season}: nenhuma partida válida na resposta", 200
+        return out, None, None
 
     @staticmethod
     def _merge(matches: list[FinishedMatch]) -> list[FinishedMatch]:
@@ -168,18 +176,24 @@ class FootballDataProvider:
             m for m in cached_matches
             if m.utc_date >= cutoff and any(m.competition == s.football_data_code for s in specs)
         ]
-        meta = {"competitions": {}, "errors": [], "cache_loaded": len(all_matches)}
-        successful_current_requests = 0
+        meta = {
+            "competitions": {},
+            "errors": [],
+            "fallbacks": [],
+            "cache_loaded": len(all_matches),
+        }
+        successful_sources = 0
 
         for spec in specs:
             current_season = season_start_year(spec, now.date())
             comp_cache = [m for m in all_matches if m.competition == spec.football_data_code]
 
-            current, error = await self._fetch_season(spec.football_data_code, current_season)
-            if error:
-                meta["errors"].append(error)
-            else:
-                successful_current_requests += 1
+            current, error, error_status = await self._fetch_season(
+                spec.football_data_code,
+                current_season,
+            )
+            if not error:
+                successful_sources += 1
             all_matches.extend(current)
 
             recent_comp = [
@@ -188,19 +202,50 @@ class FootballDataProvider:
             ]
 
             previous_loaded = False
+            previous_usable: list[FinishedMatch] = []
             # Early in a season the current-season sample is too shallow.
             # Fetch the previous season only when the cache/current data does not
             # already provide a reasonable modelling base.
             if len(recent_comp) < 140:
-                previous, prev_error = await self._fetch_season(
+                previous, prev_error, _ = await self._fetch_season(
                     spec.football_data_code,
                     current_season - 1,
                 )
                 if prev_error:
                     meta["errors"].append(prev_error)
                 else:
-                    previous_loaded = True
                     all_matches.extend(previous)
+                    previous_usable = [
+                        match for match in self._merge(previous)
+                        if (
+                            match.competition == spec.football_data_code
+                            and cutoff <= match.utc_date < now
+                        )
+                    ]
+                    previous_loaded = bool(previous_usable)
+
+            # football-data.org may not publish the newly-started season for
+            # every competition at the same time. A 404 is an expected
+            # availability gap only when the previous season alone supplies
+            # the minimum sample consumed by the analyzer.
+            if error:
+                fallback_accepted = (
+                    error_status == 404
+                    and len(previous_usable) >= MIN_COMPETITION_HISTORY
+                )
+                if fallback_accepted:
+                    successful_sources += 1
+                    meta["fallbacks"].append(
+                        {
+                            "competition": spec.football_data_code,
+                            "requested_season": current_season,
+                            "fallback_season": current_season - 1,
+                            "matches": len(previous_usable),
+                            "reason": "temporada atual ainda indisponível (HTTP 404)",
+                        }
+                    )
+                else:
+                    meta["errors"].append(error)
 
             comp_final = [
                 m for m in self._merge(all_matches)
@@ -213,9 +258,9 @@ class FootballDataProvider:
                 "previous_loaded": previous_loaded,
             }
 
-        if specs and successful_current_requests == 0 and meta["errors"]:
+        if specs and successful_sources == 0 and meta["errors"]:
             raise ProviderError(
-                "Todas as consultas atuais ao football-data.org falharam; "
+                "Todas as consultas utilizáveis ao football-data.org falharam; "
                 "o estado anterior foi preservado"
             )
 

tests/test_pipeline.py

@@ -79,6 +79,12 @@ def test_pipeline_happy_path_persists_complete_state_and_closes_http(monkeypatch
             assert cached == []
             return _matches(), {
                 "errors": [],
+                "fallbacks": [{
+                    "competition": "PL",
+                    "requested_season": 2026,
+                    "fallback_season": 2025,
+                    "matches": 45,
+                }],
                 "competitions": {"PL": {"matches": 45}},
             }
 
@@ -116,6 +122,7 @@ def test_pipeline_happy_path_persists_complete_state_and_closes_http(monkeypatch
     assert state["providers"]["football_data"]["ok"] is True
     assert state["providers"]["odds_api"]["ok"] is True
     assert state["providers"]["odds_api"]["estimated_cost_per_league"] == 1
+    assert any("histórico anterior" in warning for warning in state["warnings"])
     assert store.load_state()["generated_at"] == state["generated_at"]
     assert len(store.load_matches()) == 45
     assert store.load_history() == []

tests/test_robustness.py

@@ -13,6 +13,7 @@ from app.core.history import performance_metrics, settle_history
 from app.core.market import market_consensus
 from app.models import FinishedMatch
 from app.pipeline import DailyPipeline
+from app.providers.football_data import FootballDataProvider
 from app.providers.http_client import ProviderError, ResilientHTTP
 from app.providers.odds_api import OddsAPIProvider, _odds_api_timestamp
 from app.storage import StateStore
@@ -140,6 +141,101 @@ def test_odds_timestamp_normalizes_timezone_and_rollover():
     assert _odds_api_timestamp(local + timedelta(hours=6)) == "2027-01-01T02:59:59Z"
 
 
+def test_football_provider_treats_404_with_usable_previous_season_as_fallback(monkeypatch):
+    provider = FootballDataProvider("test-token", http=None)
+    calls = []
+    previous_matches = [
+        FinishedMatch(
+            match_id=f"previous-{index}",
+            competition="PL",
+            utc_date=datetime.now(timezone.utc) - timedelta(days=index + 1),
+            home="Alpha FC",
+            away="Beta FC",
+            home_goals=2,
+            away_goals=0,
+        )
+        for index in range(40)
+    ]
+
+    async def fake_fetch(competition_code, season):
+        calls.append((competition_code, season))
+        if len(calls) == 1:
+            return [], f"{competition_code}/{season}: HTTP 404", 404
+        return previous_matches, None, None
+
+    monkeypatch.setattr(provider, "_fetch_season", fake_fetch)
+    matches, meta = asyncio.run(
+        provider.fetch_finished(240, ("soccer_epl",), cached_matches=[])
+    )
+
+    assert matches == list(reversed(previous_matches))
+    assert meta["errors"] == []
+    assert len(meta["fallbacks"]) == 1
+    assert meta["fallbacks"][0]["requested_season"] == calls[0][1]
+    assert meta["fallbacks"][0]["fallback_season"] == calls[1][1]
+    assert meta["fallbacks"][0]["matches"] == 40
+    assert meta["competitions"]["PL"]["previous_loaded"] is True
+
+
+@pytest.mark.parametrize(
+    ("current_status", "previous_count"),
+    [(404, 39), (500, 40)],
+)
+def test_football_provider_does_not_mask_failed_or_insufficient_fallback(
+    monkeypatch,
+    current_status,
+    previous_count,
+):
+    provider = FootballDataProvider("test-token", http=None)
+    calls = 0
+
+    async def fake_fetch(competition_code, season):
+        nonlocal calls
+        calls += 1
+        if calls == 1:
+            return [], f"{competition_code}/{season}: HTTP {current_status}", current_status
+        matches = [
+            FinishedMatch(
+                match_id=f"fallback-{index}",
+                competition="PL",
+                utc_date=datetime.now(timezone.utc) - timedelta(days=index + 1),
+                home="Alpha FC",
+                away="Beta FC",
+                home_goals=1,
+                away_goals=0,
+            )
+            for index in range(previous_count)
+        ]
+        return matches, None, None
+
+    monkeypatch.setattr(provider, "_fetch_season", fake_fetch)
+    with pytest.raises(ProviderError, match="Todas as consultas utilizáveis"):
+        asyncio.run(provider.fetch_finished(240, ("soccer_epl",), cached_matches=[]))
+
+
+@pytest.mark.parametrize(
+    ("status_code", "message"),
+    [
+        (401, "unauthorized"),
+        (429, "rate limit exceeded"),
+        (400, "Your API token is invalid"),
+    ],
+)
+def test_football_provider_fails_fast_for_auth_or_rate_limit(
+    monkeypatch,
+    status_code,
+    message,
+):
+    provider = FootballDataProvider("test-token", http=None)
+
+    async def failing_get(_url, _params):
+        raise ProviderError(message, status_code)
+
+    monkeypatch.setattr(provider, "_get", failing_get)
+    with pytest.raises(ProviderError, match=message):
+        asyncio.run(provider._fetch_season("PL", 2026))
+
+
 def test_pipeline_running_includes_direct_lock_holder():
     pipeline = DailyPipeline(settings=None, store=None)