feat: enrichment Hub API, feature flags UI/gating, NCM refresher, Agent enrichment worker with tests

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

central/app/agent_distribution.py

@@ -175,7 +175,9 @@ def router(session_factory):
                 session.add(agent)
                 session.flush()
                 session.add(Installation(agent_id=agent.id, tenant_id=enr.tenant_id, installation_id=enr.enrollment_uuid,
-                                          display_name=enr.display_name, hostname=hostname or None))
+                                          display_name=enr.display_name, hostname=hostname or None,
+                                          features_configured=bool(enr.features_selected), corrector_enabled=bool(enr.features_selected and enr.feature_corrector),
+                                          enrichment_mode=(enr.feature_enrichment_mode if enr.features_selected else "DISABLED")))
 
                 enr.status = "ENROLLED"
                 enr.enrollment_used_at = datetime.now(timezone.utc)

central/app/api.py

@@ -19,6 +19,7 @@ from .events import record_event
 from .installation_identity import compute_agent_health, compute_version_drift, reference_agent_version, sanitize_registration
 from .control_plane import list_jobs
 from .human_auth import require_human
+from .enrichment.api import router as enrichment_router
 
 logger = logging.getLogger("gti_fiscal_hub")
 
@@ -180,7 +181,8 @@ def router(session_factory, bootstrap_token):
             if installation is not None and installation.installation_id != installation_key:
                 raise HTTPException(409, "installation_id conflicts with registered Agent")
             if installation is None:
-                installation = Installation(agent_id=agent.id, tenant_id=agent.tenant_id, installation_id=installation_key, display_name=supplied.get("display_name") or agent.name)
+                installation = Installation(agent_id=agent.id, tenant_id=agent.tenant_id, installation_id=installation_key, display_name=supplied.get("display_name") or agent.name,
+                                            features_configured=True, corrector_enabled=True)      # legacy/bootstrap self-registration keeps the pre-existing behaviour
                 session.add(installation); session.flush()
             fields = {"display_name": supplied.get("display_name"), "customer_code": supplied.get("customer_code"), "notes": supplied.get("notes"), "hostname": supplied.get("hostname"), "windows_version": supplied.get("windows_version"), "machine_fingerprint": supplied.get("machine_fingerprint"), "company_code": supplied.get("company_code"), "company_name": supplied.get("company_name"), "company_cnpj_masked": supplied.get("company_cnpj_masked"), "company_uf": supplied.get("company_uf"), "company_crt": supplied.get("company_crt"), "firebird_version": supplied.get("firebird_version"), "firebird_ods": supplied.get("firebird_ods"), "database_identifier": supplied.get("database_identifier"), "capabilities": supplied.get("capabilities"), "fiscal_engine_version": supplied.get("fiscal_engine_version"), "dataset_versions": supplied.get("dataset_versions"), "last_status": supplied.get("status") or payload.get("status"), "last_seen_at": now}
             for key, value in fields.items():
@@ -464,4 +466,5 @@ def router(session_factory, bootstrap_token):
             return _job_view(session.get(Job, job_id))
         finally: session.close()
 
+    routes.include_router(enrichment_router(principal))
     return routes

central/app/config.py

@@ -77,6 +77,11 @@ class Settings:
     # Z.ai general endpoint (NOT the /api/coding/paas/v4 coding-plan endpoint).
     ai_api_key: str = os.getenv("AI_API_KEY", "")
     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)
+    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"))
 
 
 settings = Settings()

central/app/datasets/updater.py

@@ -0,0 +1,85 @@
+"""Automatic refresh of the official NCM dataset (Siscomex JSON): staging -> validate -> atomic promotion, keeping the last valid dataset on ANY failure.
+
+Every attempt leaves a SourceRefreshRun (url, time, sha256, version label, record count, status, error) for the panel. Nothing here touches Agents or providers.
+"""
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from datetime import datetime, timedelta, timezone
+
+import httpx
+from sqlalchemy import select
+
+from ..config import settings
+from ..models import Dataset, SourceRefreshRun
+from .ncm import parse_ncm_payload
+from .service import DatasetService
+
+logger = logging.getLogger("gti_fiscal_hub")
+MIN_RATIO = 0.9          # a payload with < 90% of the active record count is treated as a broken download, never promoted
+INTERVAL = timedelta(hours=24)
+RETRY_AFTER_FAILURE = timedelta(hours=6)
+
+
+def _fetch(url: str) -> bytes:
+    response = httpx.get(url, timeout=max(settings.http_timeout_seconds, 60), follow_redirects=True, headers={"User-Agent": "GTIFiscalHub/1.0 (official dataset refresh)"})
+    response.raise_for_status()
+    return response.content
+
+
+def refresh_ncm(session, fetch=_fetch, url: str | None = None) -> SourceRefreshRun:
+    url = url or settings.ncm_dataset_url
+    run = SourceRefreshRun(source="NCM", source_url=url, status="RUNNING")
+    session.add(run)
+    session.commit()
+    try:
+        content = fetch(url)                                                       # staging: bytes in memory, nothing written to the active dataset yet
+        parsed = parse_ncm_payload(content)                                        # schema validation
+        run.sha256, run.version_label, run.record_count = parsed.sha256, (parsed.version or "")[:64], len(parsed.entries)
+        active = session.scalar(select(Dataset).where(Dataset.kind == "NCM", Dataset.status == "ACTIVE"))
+        if active is not None and active.sha256 == parsed.sha256:
+            run.status = "UNCHANGED"
+        else:
+            if active is not None and len(parsed.entries) < MIN_RATIO * (active.record_count or 0):
+                raise ValueError(f"implausible record count {len(parsed.entries)} vs active {active.record_count}")
+            DatasetService(session).import_payload(parsed, url, datetime.now(timezone.utc))      # atomic: one transaction, old ACTIVE superseded only at the end
+            run.status = "UPDATED"
+    except Exception as error:                                                     # keep the last valid dataset
+        session.rollback()
+        run = session.get(SourceRefreshRun, run.id)
+        run.status, run.error = "FAILED", f"{type(error).__name__}: {error}"[:300]
+        logger.warning("NCM refresh failed: %s", run.error)
+    run.finished_at = datetime.now(timezone.utc)
+    session.commit()
+    return run
+
+
+def last_runs(session, source: str = "NCM", limit: int = 5):
+    return session.scalars(select(SourceRefreshRun).where(SourceRefreshRun.source == source).order_by(SourceRefreshRun.id.desc()).limit(limit)).all()
+
+
+def _due(session) -> bool:
+    last = session.scalar(select(SourceRefreshRun).where(SourceRefreshRun.source == "NCM", SourceRefreshRun.status != "RUNNING").order_by(SourceRefreshRun.id.desc()).limit(1))
+    if last is None or last.finished_at is None:
+        return True
+    finished = last.finished_at if last.finished_at.tzinfo else last.finished_at.replace(tzinfo=timezone.utc)
+    return datetime.now(timezone.utc) - finished >= (RETRY_AFTER_FAILURE if last.status == "FAILED" else INTERVAL)
+
+
+def start_scheduler(session_factory, first_delay: float = 90.0):
+    """Daemon thread: checks hourly whether a refresh is due (survives restarts because due-ness is derived from SourceRefreshRun)."""
+    def loop():
+        time.sleep(first_delay)
+        while True:
+            try:
+                with session_factory() as session:
+                    if _due(session):
+                        refresh_ncm(session)
+            except Exception:                                                      # never let the scheduler die
+                logger.exception("official refresh loop error")
+            time.sleep(3600)
+    thread = threading.Thread(target=loop, name="official-refresh", daemon=True)
+    thread.start()
+    return thread

central/app/enrichment/api.py

@@ -0,0 +1,140 @@
+"""Agent-facing product enrichment routes (authenticated as the Agent; the Agent never talks to external providers)."""
+from __future__ import annotations
+
+import time
+from datetime import datetime, timezone
+
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy import select
+
+from ..blocked_products import upsert_blocker
+from ..config import settings
+from ..models import Installation, ProductEnrichment, ProductFieldAudit
+from .providers import build_providers
+from .quota import ProviderGateway
+from .resolver import FIELDS, resolve
+
+PROVIDERS_OVERRIDE = None      # tests inject fake providers here (never the network)
+PENDING_STATES = {"PENDING_PROVIDER_QUOTA", "PENDING_PROVIDERS_OFFLINE", "PENDING_TIME_BUDGET"}
+REASONS = {   # human PT-BR reasons shown through the existing blockers (category ENRICHMENT); never internal jargon
+    "INVALID_GTIN": "Código de barras (GTIN) inválido: o produto não foi consultado em fontes externas.",
+    "AMBIGUOUS": "Descrição genérica demais para identificar o produto com segurança; informe o código de barras.",
+    "NOT_FOUND": "Produto não encontrado nas fontes consultadas; preencha os campos fiscais manualmente.",
+    "CONFLICT": "As fontes divergem sobre a classificação deste produto; nenhuma alteração foi feita.",
+    "SINGLE_WEAK_SOURCE": "Apenas uma fonte identificou o produto; a classificação foi apenas sugerida.",
+    "PENDING_PROVIDER_QUOTA": "Limite diário das fontes de produtos atingido; a consulta será repetida automaticamente.",
+    "PENDING_PROVIDERS_OFFLINE": "Fontes de produtos indisponíveis no momento; a consulta será repetida automaticamente.",
+}
+
+
+def _aware(dt):
+    return dt.replace(tzinfo=timezone.utc) if dt is not None and dt.tzinfo is None else dt
+
+
+def features_of(installation) -> dict:
+    return {"corrector_enabled": bool(installation.corrector_enabled), "enrichment_mode": installation.enrichment_mode, "features_configured": bool(installation.features_configured)}
+
+
+def router(principal, providers_factory=None):
+    routes = APIRouter(prefix="/products")
+    holder = {}
+
+    def providers():
+        if PROVIDERS_OVERRIDE is not None:
+            return PROVIDERS_OVERRIDE
+        if providers_factory is not None:
+            return providers_factory()
+        if "p" not in holder:
+            holder["p"] = build_providers(settings)
+        return holder["p"]
+
+    @routes.post("/resolve")
+    def resolve_product(payload: dict, identity=Depends(principal)):
+        session, agent = identity
+        try:
+            installation = session.scalar(select(Installation).where(Installation.agent_id == agent.id))
+            if installation is None:
+                raise HTTPException(409, "installation not registered")
+            features = features_of(installation)
+            if not features["features_configured"] or installation.enrichment_mode == "DISABLED":
+                return {"state": "FEATURE_DISABLED", "features": features, "fields": {}}
+            code = str(payload.get("product_code") or "")[:64]
+            if not code:
+                raise HTTPException(422, "product_code required")
+            description, current = str(payload.get("description") or "")[:255], payload.get("current") if isinstance(payload.get("current"), dict) else {}
+            started = time.monotonic()
+            result = resolve(session, ProviderGateway(session, providers()), gtin_raw=payload.get("gtin"), description=description, current={k: current.get(k) for k in FIELDS},
+                             client_label=f"installation:{installation.id}", budget_s=settings.enrichment_time_budget_seconds)
+            latency = int((time.monotonic() - started) * 1000)
+            row = session.scalar(select(ProductEnrichment).where(ProductEnrichment.installation_id == installation.id, ProductEnrichment.product_code == code))
+            if row is None:
+                row = ProductEnrichment(tenant_id=agent.tenant_id, installation_id=installation.id, product_code=code)
+                session.add(row)
+            for field in (row.human_overridden or {}):                       # a human decision (even deleting the value) is final for this product
+                if field in result["fields"]:
+                    result["fields"][field] = {"status": "HUMAN_OVERRIDDEN", "value": None, "rule": None, "kb_status": None, "evidence": [], "reason": "valor alterado por uma pessoa; nunca mais preenchido automaticamente"}
+            pending = result["state"] in PENDING_STATES
+            row.gtin, row.description, row.latency_ms = result.get("gtin"), description, latency
+            row.attempts = (row.attempts or 0) + 1
+            row.status = "PENDING" if pending else "RESOLVED"
+            row.decisions = {"state": result["state"], "fields": {k: {kk: vv for kk, vv in v.items() if kk != "evidence"} for k, v in result["fields"].items()}}
+            row.next_attempt_at = _aware(result["retry_at"]) if pending else None
+            if pending and row.next_attempt_at is None:
+                row.next_attempt_at = datetime.now(timezone.utc).replace(microsecond=0)
+            session.commit()
+            reason = REASONS.get(result["state"])
+            if reason:
+                upsert_blocker(session, agent.tenant_id, {"company": installation.hostname or "", "product_code": code, "gtin": result.get("gtin"), "description": description, "blocker_type": "ENRICHMENT_" + result["state"],
+                                                          "field": "ENRICHMENT", "reason_code": result["state"], "evidence_summary": {"message": reason}, "input_fingerprint": f"{result.get('gtin')}|{description}"}, installation_id=installation.id)
+            result.update({"features": features, "latency_ms": latency, "mode": installation.enrichment_mode})
+            result["retry_at"] = result["retry_at"].isoformat() if result["retry_at"] else None
+            return result
+        finally:
+            session.close()
+
+    @routes.post("/enrichment/applied")
+    def applied(payload: dict, identity=Depends(principal)):
+        """The Agent reports what it wrote / refused. The Hub re-checks that the feature is still ENABLED and audits every field."""
+        session, agent = identity
+        try:
+            installation = session.scalar(select(Installation).where(Installation.agent_id == agent.id))
+            if installation is None:
+                raise HTTPException(409, "installation not registered")
+            code = str(payload.get("product_code") or "")[:64]
+            row = session.scalar(select(ProductEnrichment).where(ProductEnrichment.installation_id == installation.id, ProductEnrichment.product_code == code))
+            if row is None:
+                raise HTTPException(404, "unknown product enrichment")
+            versions = payload.get("dataset_versions") if isinstance(payload.get("dataset_versions"), dict) else {}
+            applied_fields, overridden = dict(row.fields_applied or {}), dict(row.human_overridden or {})
+            for item in (payload.get("fields") or [])[:32]:
+                if not isinstance(item, dict) or item.get("field") not in FIELDS:
+                    continue
+                outcome = str(item.get("outcome") or "APPLIED")[:24]
+                session.add(ProductFieldAudit(tenant_id=agent.tenant_id, installation_id=installation.id, agent_id=agent.id, product_code=code, gtin=row.gtin, description_snapshot=row.description, field=item["field"],
+                                              old_value=(str(item["old"])[:64] if item.get("old") is not None else None), new_value=(str(item["new"])[:64] if item.get("new") is not None else None), rule=str(item.get("rule") or "")[:64] or None,
+                                              kb_status=str(item.get("kb_status") or "")[:16] or None, evidence=item.get("evidence") if isinstance(item.get("evidence"), list) else [], dataset_versions=versions,
+                                              authorization_origin=f"enrichment_mode:{installation.enrichment_mode}", job_id=payload.get("job_id") if isinstance(payload.get("job_id"), int) else None, outcome=outcome,
+                                              reason=str(item.get("reason") or "")[:96] or None))
+                if outcome == "APPLIED":
+                    applied_fields[item["field"]] = item.get("new")
+                elif outcome == "HUMAN_OVERRIDDEN":
+                    overridden[item["field"]] = True
+            row.fields_applied, row.human_overridden = applied_fields, overridden
+            row.status = "APPLIED" if applied_fields and not overridden else ("PARTIAL" if applied_fields else row.status if row.status != "PENDING" else "RESOLVED")
+            row.updated_at = datetime.now(timezone.utc)
+            session.commit()
+            return {"ok": True, "status": row.status, "mode": installation.enrichment_mode}
+        finally:
+            session.close()
+
+    @routes.get("/enrichment/authorization")
+    def authorization(identity=Depends(principal)):
+        """Fresh central authorization read by the Agent right before EVERY field write."""
+        session, agent = identity
+        try:
+            installation = session.scalar(select(Installation).where(Installation.agent_id == agent.id))
+            return features_of(installation) if installation is not None else {"corrector_enabled": False, "enrichment_mode": "DISABLED", "features_configured": False}
+        finally:
+            session.close()
+
+    return routes

central/app/enrichment/resolver.py

@@ -7,7 +7,8 @@ Field decisions: AUTO_FILL_SAFE | SUGGESTION_ONLY | CONFLICT | INSUFFICIENT_EVID
 """
 from __future__ import annotations
 
-from datetime import date, datetime
+import time
+from datetime import date
 
 from sqlalchemy import select
 
@@ -79,7 +80,7 @@ def _fiscal_decisions(session, ncm_eval: dict, gtin_kb_verified: bool, current:
     if not _empty(current, "CEST"):
         out["CEST"] = _field(ALREADY, reason="campo já preenchido")
     elif decision["cest_status"] == "CEST_CONFIRMED" and len(cest) == 1 and ncm["status"] == AUTO:
-        out["CEST"] = _field(AUTO, cest[0], "CEST_OFFICIAL_UNIQUE_MAPPING", ncm["kb_status"], [f"NCM {ncm_for_engine}"])
+        out["CEST"] = _field(AUTO, normalize_code(cest[0]), "CEST_OFFICIAL_UNIQUE_MAPPING", ncm["kb_status"], [f"NCM {ncm_for_engine}"])
     elif decision["cest_status"] == "NO_CEST_MAPPING_FOUND":
         out["CEST"] = _field(NA, reason="NCM sem mapeamento de CEST no dataset oficial")
     else:
@@ -96,7 +97,8 @@ def _fiscal_decisions(session, ncm_eval: dict, gtin_kb_verified: bool, current:
     return out
 
 
-def resolve(session, gateway: ProviderGateway, *, gtin_raw, description, current: dict | None = None, client_label: str | None = None, allow_external: bool = True) -> dict:
+def resolve(session, gateway: ProviderGateway, *, gtin_raw, description, current: dict | None = None, client_label: str | None = None, allow_external: bool = True, budget_s: float | None = None) -> dict:
+    started = time.monotonic()
     """Returns {state, gtin_status, gtin, fields:{...}, providers:[...], retry_at, dataset_versions}. Never raises for provider trouble."""
     current = {k: v for k, v in (current or {}).items()}
     g = normalize_gtin(gtin_raw)
@@ -117,6 +119,10 @@ def resolve(session, gateway: ProviderGateway, *, gtin_raw, description, current
         found, pending = [], []
         if allow_external:
             for provider in gateway.providers:
+                if budget_s is not None and time.monotonic() - started > budget_s:
+                    result["providers"].append({"provider": provider.name, "state": "SKIPPED", "reason": "TIME_BUDGET", "from_cache": False})
+                    pending.append(type("P", (), {"reason": "TIME_BUDGET", "retry_at": None})())
+                    continue
                 out = gateway.lookup(provider, query)
                 result["providers"].append({"provider": out.provider, "state": out.state, "reason": out.reason, "from_cache": out.from_cache})
                 if out.state in ("FOUND", "CACHE_HIT") and out.product:

central/app/jobs.py

@@ -61,8 +61,8 @@ def claim_next_job(session, agent):
     processing is enabled centrally and no other job of this Agent is RUNNING
     (one fiscal job at a time per Firebird)."""
     installation = session.scalar(select(Installation).where(Installation.agent_id == agent.id))
-    if installation is not None and not installation.processing_enabled:
-        return None
+    if installation is not None and (not installation.processing_enabled or not installation.features_configured or not installation.corrector_enabled):
+        return None                    # WAITING_FEATURE_CONFIGURATION / corrector switched off centrally: nothing is handed to the Agent
     recover_stale_running(session, agent)
     if session.scalar(select(Job.id).where(Job.agent_id == agent.id, Job.status == "RUNNING").limit(1)) is not None:
         return None
@@ -127,7 +127,7 @@ def schedule_automatic_sync(session, agent, installation, snapshot, now=None):
     - otherwise, if processing is enabled and the last sync attempt is older than
       the installation's interval, and nothing is queued/running -> ONE SYNC_INCREMENTAL.
     Returns the created job or None."""
-    if installation is None or not installation.processing_enabled:
+    if installation is None or not installation.processing_enabled or not installation.features_configured or not installation.corrector_enabled:
         return None
     now = now or datetime.now(timezone.utc)
     sync_jobs = session.scalars(select(Job).where(Job.agent_id == agent.id, Job.kind.in_(SYNC_KINDS)).order_by(Job.id.desc())).all()

central/app/main.py

@@ -1,6 +1,7 @@
 """FastAPI application factory."""
 
 import logging
+import sys
 from collections.abc import Callable
 
 from fastapi import FastAPI, HTTPException
@@ -40,6 +41,12 @@ def create_app(database_probe: Callable[[], bool] = database_is_available, sessi
     app.include_router(control_api_router(session_factory))
     app.include_router(agent_distribution_router(session_factory))
     app.include_router(web_router(session_factory))
+    if settings.official_refresh_enabled and session_factory is SessionLocal and "pytest" not in sys.modules:
+        @app.on_event("startup")
+        def _start_official_refresh():
+            from .datasets.updater import start_scheduler
+            start_scheduler(session_factory)
+
     app.mount("/static", StaticFiles(directory="central/static"), name="static")
     return app
 

central/app/panel_presentation.py

@@ -206,6 +206,8 @@ def _rtc_products_view(resolution, enabled, cclasstrib_applicability=None):
             "catalog": (resolution.get("catalog_compatibility") or {}).get("compatibility")}
 
 
+ENRICHMENT_MODES = ("DISABLED", "DRY_RUN", "ENABLED")
+ENRICHMENT_MODE_LABELS = {"DISABLED": "Desativado", "DRY_RUN": "Simulação (não grava)", "ENABLED": "Automático"}
 RTC_MODE_LABELS = {"DISABLED": "Desativada", "DRY_RUN": "Dry-run", "APPROVAL_REQUIRED": "Aprovação manual", "ENABLED": "Automática"}
 RTC_MODE_EXPLANATION = "Somente cClassTrib com regra fiscal determinística e catálogo validado pode ser preenchido automaticamente."
 

central/app/rtc_audit.py

@@ -20,7 +20,8 @@ def _clip(value, size):
 def job_authorizations(session, installation) -> dict:
     """What the authenticated job carries to the Agent. Decided centrally per installation; the Agent has no local switch."""
     mode = installation.rtc_write_mode if installation.rtc_write_mode in WRITE_MODES else "DISABLED"
-    out = {"rtc_write_mode": mode, "rtc_approved_codes": [], "rtc_rollbacks": []}
+    out = {"rtc_write_mode": mode, "rtc_approved_codes": [], "rtc_rollbacks": [],
+           "features": {"corrector_enabled": bool(installation.corrector_enabled), "enrichment_mode": installation.enrichment_mode, "features_configured": bool(installation.features_configured)}}
     if mode == "APPROVAL_REQUIRED":
         out["rtc_approved_codes"] = list(session.scalars(select(RtcCandidate.product_code).where(RtcCandidate.installation_id == installation.id, RtcCandidate.status == "APPROVED").limit(MAX_APPROVED_PER_JOB)))
     for audit in session.scalars(select(RtcWriteAudit).where(RtcWriteAudit.installation_id == installation.id, RtcWriteAudit.action == "APPLY", RtcWriteAudit.outcome == "APPLIED",

central/app/web.py

@@ -15,11 +15,11 @@ from .config import settings
 from .blocker_resolution import BlockerResolutionUnavailable, _company_key, resolve_blocker_with_context
 from .context_keys import ALLOWED_KEYS, ENUMS
 from .installation_identity import reference_agent_version
-from .panel_presentation import RTC_MODE_EXPLANATION, RTC_MODE_LABELS, abort_reason_label, audit_outcome_label, candidate_status_label, catalog_state_label, job_kind_label, job_status_label, rtc_rule_label, rtc_status_view
+from .panel_presentation import ENRICHMENT_MODES, ENRICHMENT_MODE_LABELS, RTC_MODE_EXPLANATION, RTC_MODE_LABELS, abort_reason_label, audit_outcome_label, candidate_status_label, catalog_state_label, job_kind_label, job_status_label, rtc_rule_label, rtc_status_view
 from .control_plane import blocker_detail, blocker_filter_summary, dashboard_summary, installation_view, jobs_status_summary, list_blockers, list_installations, list_jobs, list_panel_events, rtc_blocker_summary
 from .human_auth import create_session, current_session, require_csrf, verify_password
 from .panel_presentation import format_ui_datetime
-from .models import AdminUser, Agent, AgentEnrollment, AgentRelease, AgentSnapshot, BlockedProduct, FiscalContextEntry, Installation, Job, RtcCandidate, RtcWriteAudit, Tenant
+from .models import AdminUser, Agent, AgentEnrollment, AgentRelease, AgentSnapshot, BlockedProduct, FiscalContextEntry, Installation, Job, ProductEnrichment, ProductFieldAudit, RtcCandidate, RtcWriteAudit, Tenant
 from .jobs import create_job
 from .audit import record_audit
 
@@ -256,14 +256,18 @@ def router(session_factory):
                 return render(request, "agent_new_installation.html", {"tenants": tenants, "clients_json": _clients_json(tenants), "releases": releases, "auth": auth_data, "error": " ".join(errors), "search": ""}, 400)
             enrollment_uuid = str(uuid.uuid4())
             enr = AgentEnrollment(enrollment_uuid=enrollment_uuid, tenant_id=tenant.id, display_name=display_name, expected_hostname=expected_hostname, release_id=release.id, status="PENDING", created_by=admin.id)
+            if values.get("features_selected") == "1":       # chosen explicitly at creation; otherwise the installation waits for an admin (WAITING_FEATURE_CONFIGURATION)
+                mode = (values.get("feature_enrichment_mode") or "DISABLED").strip().upper()
+                enr.features_selected, enr.feature_corrector = True, values.get("feature_corrector") == "1"
+                enr.feature_enrichment_mode = mode if mode in ENRICHMENT_MODES else "DISABLED"
             session.add(enr)
-            record_audit(session, admin_user_id=admin.id, tenant_id=tenant.id, action="INSTALLATION_CREATED", target_type="agent_enrollment", target_id=enrollment_uuid, context={"display_name": display_name, "release_version": release.version})
+            record_audit(session, admin_user_id=admin.id, tenant_id=tenant.id, action="INSTALLATION_CREATED", target_type="agent_enrollment", target_id=enrollment_uuid, context={"display_name": display_name, "release_version": release.version, "features_selected": bool(enr.features_selected), "corrector": bool(enr.feature_corrector), "enrichment_mode": enr.feature_enrichment_mode})
             session.commit()
             return RedirectResponse(f"/agents/pending/{enrollment_uuid}", status_code=303)
         finally: session.close()
 
     @routes.get("/agents/{agent_id}", response_class=HTMLResponse)
-    def agent_detail(request: Request, agent_id: str, tab: str = "overview", event_page: int = 1, severity: str | None = None, event_type: str | None = None, job_id: int | None = None, product_code: str | None = None, since: str | None = None, until: str | None = None):
+    def agent_detail(request: Request, agent_id: str, tab: str = "overview", event_page: int = 1, severity: str | None = None, event_type: str | None = None, job_id: int | None = None, product_code: str | None = None, since: str | None = None, until: str | None = None, enrich_code: str | None = None):
         # agent_id is parsed here (not typed int in the path) so a non-numeric
         # slug like /agents/abc gets a controlled HTML 404 instead of a raw
         # 422 — and can never shadow the static routes above.
@@ -285,7 +289,49 @@ def router(session_factory):
             for event in events:
                 event["occurred_display"] = format_ui_datetime(datetime.fromisoformat(event["occurred_at"]) if event["occurred_at"] else None)
             agent_blockers = list_blockers(session, tenant_id=installation.tenant_id, agent_id=agent_id, page=1, page_size=25, scope="all")
-            return render(request, "agent_detail.html", {"detail": detail, "tab": tab, "blockers": agent_blockers, "blocker_breakdown": blocker_filter_summary(session, tenant_id=installation.tenant_id, agent_id=agent_id, status="OPEN", scope="all")["blocker_breakdown"], "jobs": list_jobs(session, agent_id=agent_id, page=1, page_size=25, scope="all"), "events": events, "event_page": max(1, event_page), "has_more": has_more, "severity": severity or "", "event_type": event_type or "", "job_id": job_id or "", "product_code": product_code or "", "since": since or "", "until": until or "", "event_query_base": query_base(tab=tab, severity=severity, event_type=event_type, job_id=job_id, product_code=product_code, since=since, until=until), "auth": auth_data, "csrf_token": request.cookies.get("gti_csrf", ""), "ops": _ops_view(session, installation, agent)})
+            return render(request, "agent_detail.html", {"detail": detail, "tab": tab, "blockers": agent_blockers, "blocker_breakdown": blocker_filter_summary(session, tenant_id=installation.tenant_id, agent_id=agent_id, status="OPEN", scope="all")["blocker_breakdown"], "jobs": list_jobs(session, agent_id=agent_id, page=1, page_size=25, scope="all"), "events": events, "event_page": max(1, event_page), "has_more": has_more, "severity": severity or "", "event_type": event_type or "", "job_id": job_id or "", "product_code": product_code or "", "since": since or "", "until": until or "", "event_query_base": query_base(tab=tab, severity=severity, event_type=event_type, job_id=job_id, product_code=product_code, since=since, until=until), "auth": auth_data, "csrf_token": request.cookies.get("gti_csrf", ""), "ops": _ops_view(session, installation, agent), "features": _features_view(session, installation, enrich_code), "enrich_code": enrich_code or "", "is_admin": _is_privileged(auth_data[1])})
+        finally: session.close()
+
+    def _features_view(session, installation, enrich_code=None):
+        """FUNCIONALIDADES + small ENRIQUECIMENTO summary of the Agent detail (no separate dashboard)."""
+        counts = dict(session.execute(select(ProductEnrichment.status, func.count()).where(ProductEnrichment.installation_id == installation.id).group_by(ProductEnrichment.status)).all())
+        applied = session.scalar(select(func.count()).select_from(ProductFieldAudit).where(ProductFieldAudit.installation_id == installation.id, ProductFieldAudit.outcome == "APPLIED")) or 0
+        lookup = None
+        if enrich_code:
+            row = session.scalar(select(ProductEnrichment).where(ProductEnrichment.installation_id == installation.id, ProductEnrichment.product_code == enrich_code.strip()[:64]))
+            audits = session.scalars(select(ProductFieldAudit).where(ProductFieldAudit.installation_id == installation.id, ProductFieldAudit.product_code == enrich_code.strip()[:64]).order_by(ProductFieldAudit.id.desc()).limit(20)).all() if row else []
+            lookup = {"found": row is not None, "row": row, "audits": audits}
+        mode = installation.enrichment_mode
+        waiting = not installation.features_configured
+        return {"configured": bool(installation.features_configured), "waiting": waiting, "corrector_enabled": bool(installation.corrector_enabled), "enrichment_mode": mode,
+                "mode_label": ENRICHMENT_MODE_LABELS.get(mode, mode), "counts": counts, "total": sum(counts.values()), "applied": applied, "lookup": lookup,
+                "state_label": "Aguardando configuração de funcionalidades" if waiting else ENRICHMENT_MODE_LABELS.get(mode, mode)}
+
+    @routes.post("/agents/{agent_id}/features")
+    async def set_features(request: Request, agent_id: int):
+        """Per-installation functions (ADMIN only, CSRF, audited). Central decision: the Agent has no local switch."""
+        session, auth_data, redirect = page_auth(request)
+        if redirect: return redirect
+        try:
+            values = await form_values(request); web_session, admin = auth_data
+            require_csrf(web_session, values.get("csrf_token"))
+            agent, installation = _rtc_target(session, agent_id)
+            if not agent or not installation: return HTMLResponse("Agent not found", status_code=404)
+            if not _is_privileged(admin):
+                return _deny(session, admin, installation.tenant_id, "features:set", installation.installation_id)
+            mode = (values.get("enrichment_mode") or "").strip().upper()
+            if mode not in ENRICHMENT_MODES:
+                return HTMLResponse("modo inválido", status_code=422)
+            if mode == "ENABLED" and (values.get("confirm") or "").strip().upper() != "PREENCHER":
+                return HTMLResponse("Digite PREENCHER para confirmar o enriquecimento automático", status_code=422)
+            before = {"corrector": bool(installation.corrector_enabled), "enrichment_mode": installation.enrichment_mode, "configured": bool(installation.features_configured)}
+            installation.corrector_enabled = values.get("corrector_enabled") == "1"
+            installation.enrichment_mode = mode
+            installation.features_configured = True
+            record_audit(session, admin_user_id=admin.id, tenant_id=installation.tenant_id, action="INSTALLATION_FEATURES", target_type="installation", target_id=installation.installation_id,
+                         context={"from": before, "to": {"corrector": installation.corrector_enabled, "enrichment_mode": mode}, "operator": admin.display_name or admin.username, "role": admin.external_role or admin.auth_source}, severity="WARNING")
+            session.commit()
+            return RedirectResponse(f"/agents/{agent_id}", status_code=303)
         finally: session.close()
 
     def _ops_view(session, installation, agent):