acv-django-core 0.9.0__py3-none-any.whl

acv_core/__init__.py

@@ -0,0 +1,3 @@
+"""Piezas compartidas de los backends Django de ACV (acv-tms, acv-wms, acv-suma)."""
+
+__version__ = "0.9.0"

acv_core/_opcionales.py

@@ -0,0 +1,51 @@
+"""Dependencias que no todos los proyectos instalan (suma no tiene ninguna de las dos).
+
+Sin ``drf-spectacular`` los decoradores del esquema OpenAPI no hacen nada; sin
+``django-countries`` no hay ``CountryField`` que mapear, así que el mixin sobra.
+"""
+
+try:
+    from drf_spectacular.types import OpenApiTypes
+    from drf_spectacular.utils import (
+        OpenApiParameter,
+        extend_schema,
+        extend_schema_field,
+        inline_serializer,
+    )
+except ImportError:  # pragma: no cover -- depende de lo instalado
+
+    class OpenApiTypes:
+        OBJECT = STR = BINARY = None
+
+    class OpenApiParameter:
+        QUERY = "query"
+
+        def __init__(self, *args, **kwargs):
+            pass
+
+    def extend_schema_field(*args, **kwargs):
+        return lambda decorado: decorado
+
+    def extend_schema(*args, **kwargs):
+        return lambda decorado: decorado
+
+    def inline_serializer(*args, **kwargs):
+        return None
+
+
+try:
+    from django_countries.serializers import CountryFieldMixin
+except ImportError:  # pragma: no cover -- depende de lo instalado
+
+    class CountryFieldMixin:
+        pass
+
+
+__all__ = [
+    "CountryFieldMixin",
+    "OpenApiParameter",
+    "OpenApiTypes",
+    "extend_schema",
+    "extend_schema_field",
+    "inline_serializer",
+]

acv_core/actividad.py

@@ -0,0 +1,124 @@
+"""Registro de presencia de usuarios en Redis.
+
+El sistema usa JWT sin sesiones, así que no hay ninguna tabla que diga quién está
+usando el portal en este momento: `last_login` solo se actualiza al iniciar sesión y el
+refresh token dura mucho, por lo que alguien puede estar trabajando durante semanas sin
+un `last_login` nuevo.
+
+Para resolverlo se guarda un latido por request en un sorted set de Redis
+(`member` = id del usuario, `score` = epoch del último request). Consultar "quién estuvo
+activo en los últimos N minutos" es entonces un `ZRANGEBYSCORE`, sin tocar la base de
+datos y sin migraciones. Como es cache, perder la llave no rompe nada: se vuelve a llenar
+con el siguiente request de cada usuario.
+
+Las llaves llevan el prefijo de ``settings.ACV_PREFIJO`` (``"tms"``, ``"wms"``,
+``"suma"``): `cache.client` no aplica el KEY_PREFIX de Django, así que el prefijo es lo único
+que las separa de las de otro proyecto en el mismo Redis.
+"""
+
+import logging
+import time
+
+from django.core.cache import cache
+
+from acv_core.proyecto import prefijo
+
+logger = logging.getLogger(__name__)
+
+# Ventana que se conserva; más allá de esto la respuesta ya no lo reporta como activo.
+RETENCION = 60 * 60 * 24
+
+
+def llave_actividad():
+    return f"{prefijo()}:actividad:usuarios"
+
+
+def llave_rutas():
+    return f"{prefijo()}:actividad:rutas"
+
+
+def _redis():
+    """Cliente crudo de Redis, o `None` si el backend de cache no es Redis.
+
+    Se accede al cliente directo porque la API de Django no expone sorted sets, que es lo
+    que hace barata la consulta por ventana de tiempo.
+    """
+    try:
+        return cache.client.get_client(write=True)
+    except (AttributeError, NotImplementedError):
+        return None
+
+
+def registrar_actividad(usuario_id, ruta=None):
+    """Marca al usuario como activo *ahora*. Nunca lanza excepción.
+
+    Corre en cada request autenticado, así que si Redis está caído se ignora el error: la
+    presencia es telemetría, no puede tumbar el request que la generó.
+    """
+    redis = _redis()
+    if redis is None:
+        return
+
+    try:
+        pipe = redis.pipeline()
+        pipe.zadd(llave_actividad(), {str(usuario_id): time.time()})
+        if ruta:
+            pipe.hset(llave_rutas(), str(usuario_id), ruta)
+        pipe.execute()
+    except Exception:
+        logger.debug("No se pudo registrar la actividad del usuario", exc_info=True)
+
+
+def usuarios_activos_desde(segundos):
+    """Regresa `{usuario_id: epoch de su último request}` dentro de la ventana dada."""
+    redis = _redis()
+    if redis is None:
+        return {}
+
+    try:
+        corte = time.time() - segundos
+        pares = redis.zrangebyscore(llave_actividad(), corte, "+inf", withscores=True)
+        return {int(miembro): score for miembro, score in pares}
+    except Exception:
+        logger.warning("No se pudo consultar la actividad de usuarios", exc_info=True)
+        return {}
+
+
+def rutas_actuales(usuario_ids):
+    """Última ruta vista por cada usuario, para los ids pedidos."""
+    redis = _redis()
+    if redis is None or not usuario_ids:
+        return {}
+
+    try:
+        ids = [str(uid) for uid in usuario_ids]
+        valores = redis.hmget(llave_rutas(), ids)
+        return {
+            int(uid): valor.decode() if isinstance(valor, bytes) else valor
+            for uid, valor in zip(ids, valores, strict=True)
+            if valor
+        }
+    except Exception:
+        logger.debug("No se pudieron consultar las rutas actuales", exc_info=True)
+        return {}
+
+
+def purgar_actividad_vieja():
+    """Descarta latidos más viejos que `RETENCION`.
+
+    Se llama al leer el dashboard en lugar de por request: el sorted set crece cuando
+    mucho hasta el número de usuarios del sistema, así que no urge, pero evita que las
+    rutas guardadas de usuarios que ya no entran se queden para siempre.
+    """
+    redis = _redis()
+    if redis is None:
+        return
+
+    try:
+        corte = time.time() - RETENCION
+        vencidos = redis.zrangebyscore(llave_actividad(), "-inf", corte)
+        if vencidos:
+            redis.zremrangebyscore(llave_actividad(), "-inf", corte)
+            redis.hdel(llave_rutas(), *vencidos)
+    except Exception:
+        logger.debug("No se pudo purgar la actividad vieja", exc_info=True)

acv_core/admin.py

@@ -0,0 +1,13 @@
+from simple_history.admin import SimpleHistoryAdmin
+
+
+class CustomModelAdmin(SimpleHistoryAdmin):
+    """Despliega todos los campos del modelo como columnas del panel de admin"""
+
+    show_full_result_count = False
+
+    def __init__(self, model, admin_site):
+        fields = [f for f in model._meta.fields if f.name != "id"]
+        self.list_display = [f.name for f in fields]
+        self.list_select_related = [f.name for f in fields if f.is_relation]
+        super().__init__(model, admin_site)

acv_core/archivos/__init__.py

@@ -0,0 +1,14 @@
+"""El intercambio de archivos con los listados: importar CSV/xlsx, exportar CSV/xlsx y plantillas.
+
+Requiere el extra ``archivos`` (pandas, numpy, openpyxl, PyYAML).
+
+**Los modelos concretos viven en cada proyecto**, en su app ``general`` (o la que nombre
+``ACV_APP_DE_ARCHIVOS``): el paquete trae sus bases abstractas (``acv_core.archivos.modelos``) y el
+proyecto declara ``Document``, ``PreferenciaDeExportacion``, ``ExportacionCSV``, ``ImportacionCSV`` y
+``FilaDeImportacion`` heredándolas. Así cada proyecto conserva sus tablas y su historia de
+migraciones, y el motor encuentra los modelos por nombre (``modelo_de``).
+
+Las tareas de Celery también se quedan en el proyecto, como envolturas de una línea sobre
+``acv_core.archivos.trabajos``: el nombre de una tarea es la ruta de su módulo, y las filas de
+``PeriodicTask`` y las tareas en cola lo guardan.
+"""

acv_core/archivos/comando.py

@@ -0,0 +1,265 @@
+"""
+``manage.py importar_csv`` — corre un plan de importación de CSV contra los recursos de la API.
+
+Cada proyecto lo publica en su app de archivos con una subclase de una línea, para que aparezca
+en su ``manage.py`` sin volver a ``acv_core`` una app instalada::
+
+    # general/management/commands/importar_csv.py
+    from acv_core.archivos.comando import ImportarCSV
+
+    class Command(ImportarCSV):
+        pass
+
+**Es un manejador delgado sobre la API, no un segundo importador.** Resuelve la ruta del recurso,
+rearma su viewset y llama exactamente el mismo motor que ``subir_archivo``: mismas columnas, mismo
+serializador, misma resolución de FK por código o nombre, mismas dos políticas. Una carga masiva
+—sembrar los catálogos de configuración en un ambiente nuevo, por ejemplo— es así la prueba de
+carga del importador que la gente usa todos los días, en vez de un camino aparte que se descubre
+roto el día que se corre.
+
+**El orden del plan ES el orden de construcción.** Un ``SlugRelatedField`` exige que la fila
+referida exista —una ruta pide sus locaciones, un operador su transportista—, así que el orden
+tiene que vivir en un archivo versionado y no en el orden en que alguien abra las pestañas.
+
+El plan es un YAML::
+
+    version: 1
+    modo: CREAR_O_ACTUALIZAR        # por omisión CREAR
+    tolerancia: ESTRICTA            # por omisión ESTRICTA
+    pasos:
+      - id: "01"
+        recurso: /configuracion/destinos/
+        archivo: destinos.csv       # relativo al plan
+      - id: "02"
+        recurso: /configuracion/rutas/
+        archivo: rutas.csv
+        tolerancia: PARCIAL         # cada paso puede pisar las dos políticas
+
+Uso:
+
+    manage.py importar_csv --plan carga/plan.yml --usuario mario --dry-run
+    manage.py importar_csv --plan carga/plan.yml --usuario mario
+    manage.py importar_csv --plan carga/plan.yml --usuario mario --desde 02
+    manage.py importar_csv --plan carga/plan.yml --usuario mario --solo /configuracion/rutas/
+"""
+
+from pathlib import Path
+
+import yaml
+from django.contrib.auth import get_user_model
+from django.core.files.uploadedfile import SimpleUploadedFile
+from django.core.management.base import BaseCommand, CommandError
+from django.db import transaction
+from django.urls import Resolver404, resolve
+
+from acv_core.archivos.importacion import (
+    csv_de_rechazadas,
+    hileras_del_dataframe,
+    leer_tabla,
+    preparar_importacion,
+    procesar_importacion,
+)
+from acv_core.archivos.modelos import ImportacionCSVBase, modelo_de
+from acv_core.vistas import armar_vista, ruta_de
+
+
+class _Ensayo(Exception):
+    """Señal para revertir el trabajo de un ``--dry-run`` después de haberlo medido."""
+
+
+class ImportarCSV(BaseCommand):
+    help = "Corre un plan de importación de CSV contra los recursos de la API."
+
+    def add_arguments(self, parser):
+        parser.add_argument("--plan", required=True, help="Archivo YAML con el plan.")
+        parser.add_argument(
+            "--usuario",
+            required=True,
+            help=(
+                "Username o correo de quien queda como autor de la carga. Es obligatorio y no "
+                "tiene default: una carga atribuida a quien haya quedado primero en la tabla "
+                "es peor que una que se niega a correr, porque el historial ya no se puede "
+                "corregir después."
+            ),
+        )
+        parser.add_argument("--desde", help="Empieza en el paso con este id (para reanudar).")
+        parser.add_argument("--solo", help="Corre únicamente el paso de este recurso.")
+        parser.add_argument(
+            "--dry-run",
+            action="store_true",
+            help=(
+                "Corre todo y lo revierte. Valida contra la base de verdad —restricciones "
+                "incluidas— y deja el CSV de rechazadas junto al archivo de entrada."
+            ),
+        )
+
+    # ==============================|| ENTRADA ||============================== #
+
+    def handle(self, *args, **opciones):
+        plan_ruta = Path(opciones["plan"]).resolve()
+        if not plan_ruta.exists():
+            raise CommandError(f"No existe el plan: {plan_ruta}")
+
+        plan = yaml.safe_load(plan_ruta.read_text(encoding="utf-8")) or {}
+        usuario = self._resolver_usuario(opciones["usuario"])
+        pasos = self._pasos_a_correr(plan, opciones)
+
+        modo_global = plan.get("modo", ImportacionCSVBase.Modos.CREAR)
+        tolerancia_global = plan.get("tolerancia", ImportacionCSVBase.Tolerancias.ESTRICTA)
+
+        if opciones["dry_run"]:
+            self.stdout.write(self.style.WARNING("ENSAYO: todo se revierte al terminar.\n"))
+
+        for paso in pasos:
+            self._correr_paso(
+                paso,
+                base=plan_ruta.parent,
+                usuario=usuario,
+                modo=paso.get("modo", modo_global),
+                tolerancia=paso.get("tolerancia", tolerancia_global),
+                ensayo=opciones["dry_run"],
+            )
+
+    # ==============================|| PLAN ||============================== #
+
+    def _resolver_usuario(self, identificador: str):
+        User = get_user_model()
+        usuario = (
+            User.objects.filter(username=identificador).first()
+            or User.objects.filter(email__iexact=identificador).first()
+        )
+        if usuario is None:
+            raise CommandError(f"No hay usuario '{identificador}'.")
+
+        return usuario
+
+    def _pasos_a_correr(self, plan: dict, opciones: dict) -> list[dict]:
+        pasos = plan.get("pasos") or []
+        if not pasos:
+            raise CommandError("El plan no tiene pasos.")
+
+        if opciones["solo"]:
+            pasos = [p for p in pasos if p["recurso"] == opciones["solo"]]
+            if not pasos:
+                raise CommandError(f"El plan no tiene un paso para '{opciones['solo']}'.")
+
+        if opciones["desde"]:
+            ids = [str(p.get("id", "")) for p in pasos]
+            if opciones["desde"] not in ids:
+                raise CommandError(f"El plan no tiene un paso con id '{opciones['desde']}'.")
+            pasos = pasos[ids.index(opciones["desde"]) :]
+
+        return pasos
+
+    def _vista_de(self, ruta_api: str, usuario):
+        """Resuelve la ruta de la API a su viewset, ya armado con el usuario de la carga.
+
+        Se llavea por **ruta y no por ``app_label.model``** porque un mismo modelo puede tener
+        dos imports con columnas distintas, y el modelo no los distingue. La ruta sí, es estable, y
+        de paso vuelve el plan la documentación de qué entró por dónde.
+        """
+
+        try:
+            coincidencia = resolve(ruta_api)
+        except Resolver404 as error:
+            raise CommandError(f"La ruta '{ruta_api}' no resuelve a ningún recurso.") from error
+
+        clase = getattr(coincidencia.func, "cls", None)
+        if clase is None:
+            raise CommandError(f"La ruta '{ruta_api}' no es un viewset.")
+
+        vista = armar_vista(ruta_de(clase), usuario, accion="subir_archivo")
+
+        if "rename_columns" not in (getattr(vista, "csv", None) or {}):
+            raise CommandError(f"El recurso '{ruta_api}' no importa archivos.")
+
+        return vista
+
+    # ==============================|| UN PASO ||============================== #
+
+    def _correr_paso(self, paso, *, base: Path, usuario, modo, tolerancia, ensayo: bool) -> None:
+        etiqueta = f"{paso.get('id', '?')} {paso['recurso']}"
+        archivo_ruta = (base / paso["archivo"]).resolve()
+
+        if not archivo_ruta.exists():
+            raise CommandError(f"[{etiqueta}] No existe el archivo: {archivo_ruta}")
+
+        vista = self._vista_de(paso["recurso"], usuario)
+
+        if modo not in vista.get_csv_modos():
+            raise CommandError(
+                f"[{etiqueta}] El recurso no se importa en modo {modo}; admite "
+                f"{', '.join(vista.get_csv_modos())}. Corrige el modo en el plan."
+            )
+
+        self.stdout.write(f"[{etiqueta}] {archivo_ruta.name} · {modo} · {tolerancia}")
+
+        importacion = None
+        try:
+            with transaction.atomic():
+                importacion = self._aplicar(vista, usuario, archivo_ruta, modo, tolerancia)
+                self._reportar(etiqueta, importacion)
+                self._escribir_rechazadas(vista, importacion, archivo_ruta)
+
+                if ensayo:
+                    raise _Ensayo
+        except _Ensayo:
+            self.stdout.write(self.style.WARNING(f"[{etiqueta}] revertido (ensayo).\n"))
+            return
+
+        if importacion.estado == ImportacionCSVBase.Estados.RECHAZADA:
+            raise CommandError(
+                f"[{etiqueta}] Archivo rechazado y la tolerancia es estricta. "
+                "Corrige el CSV de rechazadas y vuelve a correr desde este paso."
+            )
+
+    def _aplicar(self, vista, usuario, archivo_ruta: Path, modo, tolerancia):
+        """Mismo camino que ``subir_archivo``, sin la mitad HTTP.
+
+        Siempre síncrono: aquí no hay un ``timeout`` de gunicorn del que huir, y encolarlo sólo
+        haría que el comando terminara antes que el trabajo.
+        """
+
+        contenido = archivo_ruta.read_bytes()
+        subido = SimpleUploadedFile(archivo_ruta.name, contenido, content_type="text/csv")
+
+        hileras = hileras_del_dataframe(leer_tabla(subido, vista))
+        if not hileras:
+            raise CommandError(f"{archivo_ruta.name} no trae hileras de datos.")
+
+        subido.seek(0)
+        documento = modelo_de("Document")(file=subido, user=usuario)
+        documento.set_serialized_rows(hileras)
+        documento.save()
+
+        importacion = preparar_importacion(vista, usuario, documento, modo, tolerancia)
+
+        return procesar_importacion(importacion, vista=vista)
+
+    # ==============================|| SALIDA ||============================== #
+
+    def _reportar(self, etiqueta: str, importacion) -> None:
+        resumen = importacion.resumen()
+        linea = (
+            f"[{etiqueta}] {importacion.get_estado_display()} · "
+            f"{resumen['creadas']} creadas, {resumen['actualizadas']} actualizadas, "
+            f"{resumen['con_error']} con error, {resumen['omitidas']} omitidas "
+            f"de {resumen['total']}"
+        )
+
+        if importacion.estado == ImportacionCSVBase.Estados.COMPLETADA:
+            self.stdout.write(self.style.SUCCESS(linea))
+        elif importacion.estado == ImportacionCSVBase.Estados.ERROR:
+            self.stdout.write(self.style.ERROR(linea))
+        else:
+            self.stdout.write(self.style.WARNING(linea))
+
+    def _escribir_rechazadas(self, vista, importacion, archivo_ruta: Path) -> None:
+        """Deja el CSV de rechazadas junto al de entrada, listo para corregir y volver a correr."""
+
+        if not importacion.resumen()["con_error"]:
+            return
+
+        destino = archivo_ruta.with_name(f"{archivo_ruta.stem}.rechazadas.csv")
+        destino.write_text("".join(csv_de_rechazadas(importacion, vista=vista)), encoding="utf-8")
+        self.stdout.write(f"    rechazadas -> {destino}")

acv_core/archivos/entrega.py

@@ -0,0 +1,86 @@
+"""Cómo se entrega un archivo guardado, sin que quien lo pide tenga que saber dónde vive.
+
+En local el media lo sirve el propio proceso y el archivo sale por un ``FileResponse``; en
+producción vive en Google Cloud Storage, ``url()`` devuelve una URL firmada y se redirige a ella
+en vez de proxear megas por un worker de gunicorn. Las dos ramas ya estaban escritas dos veces
+—en la descarga de un adjunto y en la de una exportación— y copiadas les faltaba lo mismo:
+
+**Un redirect no lleva cabeceras propias.** Todo lo que se dijera en el ``FileResponse`` —cómo se
+llama el archivo, si se baja o se abre— se perdía justo en el entorno donde importa: el navegador
+seguía el redirect a GCS y guardaba el blob con el nombre generado del storage
+(``adjunto/13_20260907232827``, sin extensión). Es decir que el arreglo de "lo que se baja siempre
+lleva extensión" funcionaba sólo en local, que es donde no hacía falta.
+
+La firma sí puede decirlo: ``generate_signed_url`` acepta ``response_disposition`` y
+``response_type``, y GCS contesta con esas cabeceras. Van **dentro de la firma** a propósito —no
+son un parámetro que el cliente pueda cambiar—, así que el nombre con el que se baja lo sigue
+decidiendo el servidor.
+"""
+
+from __future__ import annotations
+
+import unicodedata
+from urllib.parse import quote
+
+from django.http import FileResponse, HttpResponseRedirect
+
+
+def _disposicion(nombre: str, as_attachment: bool) -> str:
+    """La cabecera ``Content-Disposition``, con el nombre escrito de las dos maneras (RFC 6266).
+
+    ``filename`` en ASCII para el cliente que no entienda más, y ``filename*`` en UTF-8 para el
+    resto. Hace falta porque los nombres reales de un expediente llevan acentos y eñes, y un
+    ``filename="Licencia Federal.pdf"`` con acentos se recibe como bytes que nadie sabe decodificar.
+    """
+
+    tipo = "attachment" if as_attachment else "inline"
+
+    # Sin comillas dobles: cerrarían el valor de la cabecera antes de tiempo.
+    plano = (
+        unicodedata.normalize("NFKD", nombre).encode("ascii", "ignore").decode().replace('"', "")
+    )
+
+    return f"{tipo}; filename=\"{plano or 'archivo'}\"; filename*=UTF-8''{quote(nombre)}"
+
+
+def _url_del_storage(archivo, disposicion: str, content_type: str | None) -> str | None:
+    """La URL absoluta con la que el storage sirve el archivo, o ``None`` si no la hay.
+
+    Lo que decide es la URL y no el backend: en local ``FileSystemStorage`` contesta una ruta
+    relativa que nada sirve, y entonces el archivo tiene que salir por el proceso.
+    """
+
+    parametros = {"response_disposition": disposicion}
+    if content_type:
+        parametros["response_type"] = content_type
+
+    try:
+        url = archivo.storage.url(archivo.name, parameters=parametros)
+    except TypeError:
+        # El storage de disco no acepta parámetros. Se pregunta igual, porque lo que decide es
+        # si la URL es absoluta.
+        url = archivo.url
+
+    return url if url.startswith("http") else None
+
+
+def entregar_archivo(archivo, *, nombre: str, as_attachment: bool = True, content_type=None):
+    """La respuesta con la que se entrega ``archivo``, sirva quien lo sirva.
+
+    ``nombre`` y ``as_attachment`` valen igual por las dos ramas, que es el punto: quien llama
+    dice con qué nombre se baja y si se baja o se abre, y no tiene que saber si eso va a acabar
+    en una cabecera o dentro de una firma.
+    """
+
+    disposicion = _disposicion(nombre, as_attachment)
+
+    url = _url_del_storage(archivo, disposicion, content_type)
+    if url is not None:
+        return HttpResponseRedirect(url)
+
+    return FileResponse(
+        archivo.open("rb"),
+        as_attachment=as_attachment,
+        filename=nombre,
+        content_type=content_type,
+    )

acv_core/archivos/exportables.py

@@ -0,0 +1,47 @@
+"""
+Las columnas que se pueden exportar de un recurso (``app_label.modelname``) y una variante.
+
+Una preferencia de exportación se llavea por recurso y no por la ruta del listado (ver
+``PreferenciaDeExportacion``), así que para editar sus columnas fuera del diálogo de exportar —que
+sí conoce su listado— hay que encontrar la vista que exporta ese recurso. Se descubre recorriendo
+el URLconf: no hay lista central que mantener.
+
+Si dos vistas exportan el mismo recurso con la misma variante, gana la primera del URLconf.
+"""
+
+from functools import cache
+
+from acv_core.vistas import instanciar_sin_request, vistas_del_urlconf
+
+
+def _variantes_de(vista) -> set[str]:
+    declaradas = (getattr(vista, "csv", None) or {}).get("export") or {}
+    return set(declaradas) or {"main"}
+
+
+@cache
+def _vistas_por_recurso() -> dict[str, list[type]]:
+    """``{recurso: [vistas]}`` de las vistas que exportan CSV, en el orden del URLconf."""
+
+    from acv_core.archivos.viewsets import ExportarCSV
+
+    encontradas: dict[str, list[type]] = {}
+    for vista_cls, _ruta, _nombre in vistas_del_urlconf():
+        if not issubclass(vista_cls, ExportarCSV) or getattr(vista_cls, "queryset", None) is None:
+            continue
+        recurso = instanciar_sin_request(vista_cls).get_csv_export_resource()
+        vistas = encontradas.setdefault(recurso, [])
+        if vista_cls not in vistas:
+            vistas.append(vista_cls)
+    return encontradas
+
+
+def columnas_de(recurso: str, variante: str = "main") -> dict[str, str] | None:
+    """``{campo: etiqueta}`` exportable de ``recurso`` en ``variante``, en el orden declarado; o
+    ``None`` si ninguna vista lo exporta así."""
+
+    for vista_cls in _vistas_por_recurso().get(recurso, []):
+        vista = instanciar_sin_request(vista_cls)
+        if variante in _variantes_de(vista):
+            return vista.get_csv_export_allowlist(variant=variante)
+    return None