feat: OSCBR optional provider, re-baseline after inactivity, field audit, provider UI/feature matrix tests, benchmark chain; 1.3.1

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

central/app/config.py

@@ -79,6 +79,8 @@ class Settings:
     ai_base_url: str = os.getenv("AI_BASE_URL", "https://api.z.ai/api/paas/v4")
     # ---- Product enrichment (docs/product_enrichment.md): free providers only, tokens live ONLY in the Hub environment ----
     cosmos_token: str = os.getenv("COSMOS_TOKEN", "")          # optional; without it Cosmos is NOT_CONFIGURED (not an error)
+    oscbr_user: str = os.getenv("OSCBR_USER", "")              # optional free-plan account of gtin.rscsistemas.com.br (never in logs/UI)
+    oscbr_password: str = os.getenv("OSCBR_PASSWORD", "")
     allow_paid_providers: bool = os.getenv("ALLOW_PAID_PROVIDERS", "0") == "1"
     official_refresh_enabled: bool = os.getenv("OFFICIAL_REFRESH_ENABLED", "1") == "1"
     enrichment_time_budget_seconds: float = float(os.getenv("ENRICHMENT_TIME_BUDGET_SECONDS", "4.5"))

central/app/enrichment/providers.py

@@ -225,9 +225,71 @@ class Cosmos(Provider):
         return out
 
 
+class Oscbr(Provider):
+    """OSCBR / RSC Sistemas GTIN API (https://gtin.rscsistemas.com.br). Free plan (no card): 20 req/min; account created BY THE OPERATOR, credentials only in the Hub env
+    (OSCBR_USER / OSCBR_PASSWORD). Bearer token lasts 1 h and is renewed automatically. Optional: NOT_CONFIGURED without credentials (no call is made)."""
+    name = "oscbr"
+    rate_per_minute = 20
+    provides_ncm = True
+    base = "https://gtin.rscsistemas.com.br"
+
+    def __init__(self, client=None, token=None, user=None, password=None):
+        super().__init__(client, token)
+        self._user, self._password = user, password
+        self._bearer, self._bearer_until = None, 0.0
+
+    @property
+    def configured(self) -> bool:
+        return bool(self._user and self._password)
+
+    def _auth(self) -> str:
+        if self._bearer and time.time() < self._bearer_until:
+            return self._bearer
+        try:
+            response = self.client.post(f"{self.base}/oauth/token", auth=(self._user, self._password), headers={"User-Agent": USER_AGENT})
+        except httpx.TimeoutException as error:
+            raise ProviderError("TIMEOUT", type(error).__name__) from error
+        except httpx.HTTPError as error:
+            raise ProviderError("NETWORK", type(error).__name__) from error
+        if response.status_code in (400, 401, 403):
+            raise ProviderError("AUTH_ERROR", f"HTTP {response.status_code}")
+        if response.status_code == 429:
+            raise ProviderError("RATE_LIMITED", "HTTP 429")
+        if response.status_code >= 500 or response.status_code != 200:
+            raise ProviderError("SERVER_ERROR", f"HTTP {response.status_code}")
+        try:
+            token = response.json().get("token") or response.json().get("access_token")
+        except ValueError as error:
+            raise ProviderError("BAD_RESPONSE", "not JSON") from error
+        if not token:
+            raise ProviderError("BAD_RESPONSE", "no token")
+        self._bearer, self._bearer_until = token, time.time() + 55 * 60
+        return token
+
+    def lookup_gtin(self, gtin: str) -> ProviderProduct:
+        if not self.configured:
+            raise ProviderError("AUTH_ERROR", "NOT_CONFIGURED")
+        response = self._get(f"{self.base}/api/gtin/infor/{gtin}", headers={"Authorization": f"Bearer {self._auth()}", "User-Agent": USER_AGENT})
+        headers = {k.lower(): v for k, v in response.headers.items()}
+        if response.status_code == 404:
+            return ProviderProduct(self.name, gtin, False, latency_ms=getattr(response, "latency_ms", 0), headers=headers)
+        if response.status_code != 200:
+            raise ProviderError("BAD_RESPONSE", f"HTTP {response.status_code}")
+        try:
+            body = response.json()
+        except ValueError as error:
+            raise ProviderError("BAD_RESPONSE", "not JSON") from error
+        if isinstance(body, list):
+            body = body[0] if body else {}
+        if not body or not (body.get("nome") or body.get("ncm")):
+            return ProviderProduct(self.name, gtin, False, latency_ms=getattr(response, "latency_ms", 0), headers=headers)
+        return ProviderProduct(self.name, gtin, True, title=body.get("nome"), brand=body.get("marca"), category=body.get("categoria"), ncm=_digits(body.get("ncm")), cest=_digits(body.get("cest")),
+                               raw_hash=hashlib.sha256(json.dumps(body, sort_keys=True, ensure_ascii=False).encode()).hexdigest(), latency_ms=getattr(response, "latency_ms", 0), headers=headers)
+
+
 def build_providers(settings, client: httpx.Client | None = None) -> list[Provider]:
-    """Fixed order chosen from the benchmark (docs/product_enrichment.md): Cosmos (fiscal-capable) first when configured, then UPCitemdb, then the Open *Facts family (food, general products, beauty; identity only). Paid providers do not exist here."""
-    providers: list[Provider] = [Cosmos(client, getattr(settings, "cosmos_token", None)), UpcItemDb(client), OpenFoodFacts(client), OpenProductsFacts(client), OpenBeautyFacts(client)]
+    """Fixed order chosen from the benchmark (docs/product_enrichment.md): Cosmos then OSCBR (fiscal-capable) first when configured, then UPCitemdb, then the Open *Facts family (food, general products, beauty; identity only). Paid providers do not exist here."""
+    providers: list[Provider] = [Cosmos(client, getattr(settings, "cosmos_token", None)), Oscbr(client, None, getattr(settings, "oscbr_user", None), getattr(settings, "oscbr_password", None)), UpcItemDb(client), OpenFoodFacts(client), OpenProductsFacts(client), OpenBeautyFacts(client)]
     if any(p.paid for p in providers) and not getattr(settings, "allow_paid_providers", False):
         raise RuntimeError("paid providers are not allowed (ALLOW_PAID_PROVIDERS=false)")
     return providers

central/app/version.py

@@ -4,5 +4,5 @@ kept identical to this) and what an AgentRelease row's `version` column holds
 once published — never a second, independent version number. Fiscal semantics
 are versioned separately (ENGINE_VERSION/DECISION_VERSION in classification.py,
 DECISION_ENGINE_VERSION etc.) and are NOT changed by a release bump."""
-GTI_FISCAL_VERSION = "1.3.0"
+GTI_FISCAL_VERSION = "1.3.1"
 API_COMPAT_MAJOR_MINOR = "1.0"  # an Agent 1.0.x/1.1.x talks to any Hub 1.0.x

central/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "gti-fiscal-hub"
-version = "1.3.0"
+version = "1.3.1"
 requires-python = ">=3.10"
 dependencies = [
   "fastapi>=0.115,<1",

central/tests/test_health.py

@@ -17,7 +17,7 @@ def test_health_is_unavailable_when_database_is_down():
 
 def test_version_endpoint_reports_release_and_fiscal_versions():
     body = TestClient(create_app(database_probe=lambda: True)).get("/version").json()
-    assert body["version"] == "1.3.0" and body["api_compat"] == "1.0" and body["engine_version"] and body["decision_version"]
+    assert body["version"] == "1.3.1" and body["api_compat"] == "1.0" and body["engine_version"] and body["decision_version"]
 
 
 def test_production_refuses_the_dev_token(monkeypatch):

central/tests/test_product_enrichment_api.py

@@ -158,3 +158,45 @@ def test_corrector_switch_off_stops_jobs_but_not_enrichment(monkeypatch):
         s.commit()
     assert client.get("/v1/jobs/next", headers=H).json() is None
     assert resolve(client)["state"] != "FEATURE_DISABLED"
+
+
+import pytest
+
+
+@pytest.mark.parametrize("corrector,mode,configured,jobs,enrich", [
+    (True, "DISABLED", True, True, False),       # Corrector ON / Enrichment OFF
+    (False, "DRY_RUN", True, False, True),       # Corrector OFF / DRY_RUN
+    (False, "ENABLED", True, False, True),       # Corrector OFF / ENABLED
+    (True, "ENABLED", True, True, True),         # both ON
+    (False, "DISABLED", False, False, False),    # no features -> WAITING_FEATURE_CONFIGURATION
+])
+def test_feature_mode_matrix(monkeypatch, corrector, mode, configured, jobs, enrich):
+    client, engine = setup(monkeypatch, mode)
+    with Session(engine) as s:
+        i = s.scalars(select(Installation)).one()
+        i.corrector_enabled, i.features_configured = corrector, configured
+        from central.app.jobs import create_job
+        from central.app.models import Agent
+        create_job(s, s.scalars(select(Agent)).one(), "SYNC_INCREMENTAL", {})
+        s.commit()
+    assert (client.get("/v1/jobs/next", headers=H).json() is not None) == jobs
+    assert (resolve(client)["state"] != "FEATURE_DISABLED") == enrich
+    feats = client.get("/v1/agents/me/authorizations", headers=H).json()["features"]
+    assert feats["features_configured"] == configured
+
+
+def test_provider_panel_shows_every_state_and_column(monkeypatch):
+    from datetime import datetime, timedelta, timezone
+    from central.app.models import ProviderState, ProviderUsageDaily
+    client, agent_id, _ = _panel_client()
+    now = datetime.now(timezone.utc)
+    with client._session_factory() as s:
+        s.add(ProviderState(provider="upcitemdb", configured=True, status="RATE_LIMITED", quota_kind="REMOTE_QUOTA", daily_limit=100, remaining=0, reset_at=now + timedelta(hours=3), last_success_at=now, last_error="RATE_LIMITED: HTTP 429", last_latency_ms=140))
+        s.add(ProviderState(provider="openfoodfacts", configured=True, status="DEGRADED", last_latency_ms=655))
+        s.add(ProviderState(provider="openproductsfacts", configured=True, status="AUTH_ERROR"))
+        s.add(ProviderState(provider="openbeautyfacts", configured=True, status="OFFLINE"))
+        s.add(ProviderUsageDaily(provider="upcitemdb", day=now.strftime("%Y-%m-%d"), requests=100, cache_hits=30, cache_misses=70))
+        s.commit()
+    page = client.get("/").text
+    for label in ("Limite atingido", "Instável", "Credencial recusada", "Indisponível", "Não configurado", "100 / 100", "restam 0", "renova", "último sucesso", "último erro", "140 ms", "cache 30%"):
+        assert label in page, label

central/tests/test_product_enrichment_resolver.py

@@ -10,7 +10,7 @@ from sqlalchemy.pool import StaticPool
 
 from central.app.enrichment import kb
 from central.app.enrichment.gtin import check_digit_ok
-from central.app.enrichment.providers import Cosmos, OpenFoodFacts, Provider, ProviderError, ProviderProduct, UpcItemDb, build_providers
+from central.app.enrichment.providers import Oscbr, Cosmos, OpenFoodFacts, Provider, ProviderError, ProviderProduct, UpcItemDb, build_providers
 from central.app.enrichment.quota import ProviderGateway
 from central.app.enrichment.resolver import resolve
 from central.app.models import (Base, CestEntry, CestNcmEntry, Dataset, GtinLookupCache, KbKnowledge, NcmEntry, ProviderUsageDaily, TipiEntry)
@@ -223,7 +223,7 @@ def test_cosmos_without_token_is_not_configured_and_costs_nothing(env):
 
 def test_paid_provider_guard():
     class S: allow_paid_providers = False; cosmos_token = None
-    assert [p.name for p in build_providers(S())] == ["cosmos", "upcitemdb", "openfoodfacts", "openproductsfacts", "openbeautyfacts"]
+    assert [p.name for p in build_providers(S())] == ["cosmos", "oscbr", "upcitemdb", "openfoodfacts", "openproductsfacts", "openbeautyfacts"]
 
 
 # ---- provider contract tests against recorded fixtures (httpx.MockTransport, no network) ----------------------------------------------------------
@@ -269,3 +269,26 @@ def test_cosmos_contract_and_errors():
     with pytest.raises(ProviderError) as e:
         Cosmos(_client(boom), "tok").lookup_gtin(G1)
     assert e.value.kind == "TIMEOUT"
+
+
+def test_oscbr_optional_and_contract():
+    calls = []
+    assert not Oscbr(_client(lambda r: pytest.fail("no call expected"))).configured
+    with pytest.raises(ProviderError):
+        Oscbr(_client(lambda r: pytest.fail("no call expected"))).lookup_gtin(G1)
+
+    def handler(request):
+        calls.append(str(request.url))
+        if request.url.path == "/oauth/token":
+            assert request.headers["authorization"].startswith("Basic ")
+            return httpx.Response(200, json={"token": "tkn"})
+        assert request.headers["authorization"] == "Bearer tkn"
+        return httpx.Response(200, json={"ean": G1, "nome": "COLA 350ML", "marca": "X", "ncm": "2202.10.00", "cest": "03.007.00"})
+    p = Oscbr(_client(handler), None, "u", "p")
+    first, second = p.lookup_gtin(G1), p.lookup_gtin(G1)
+    assert first.ncm == "22021000" and first.cest == "0300700" and second.found
+    assert sum(1 for c in calls if "oauth" in c) == 1                     # token reused for ~55 min
+    bad = Oscbr(_client(lambda r: httpx.Response(401)), None, "u", "p")
+    with pytest.raises(ProviderError) as e:
+        bad.lookup_gtin(G1)
+    assert e.value.kind == "AUTH_ERROR"