Saltar a contenido

Módulos clave del backend

Guía de los paquetes que dan soporte a las rutas FastAPI: núcleo (core), autenticación, utilitarios y tareas. Usa esta página junto con arquitectura.md para tener contexto completo.

app/core

Módulo Responsabilidad Puntos clave
settings.py Configuración central (Pydantic BaseSettings). Variables .env, propiedades derivadas (domain_url, database_uri, mail_config), credenciales de superusuario, get_settings() con lru_cache.
database.py Conexión a PostgreSQL vía SQLModel/SQLAlchemy. engine = create_engine(...), dependencia SessionDep, helper test_db_connection.
executor.py Ejecutar tareas largas devolviendo StreamingResponse. stream_executor(work, finalize, ping_interval, padding) para API de backups/restauraciones.
redis.py Cliente global de Redis. Instancia redis_client basada en settings.
mongo.py Cliente y dependencias para MongoDB. get_mongo_client, get_mongo_db, cierre controlado.
lifespan.py Lógica de startup/shutdown. Ejecuta init_db(session) en el arranque y libera recursos al cerrar.

app/auth

  • auth.py: crea la sesión (authenticate), cookies set_session_cookie/delete_session_cookie y controla bloqueo por intentos fallidos.
  • auth_dependencies.py: dependencias get_token, get_current_user, cache de usuario en Redis (USER_SESSION_KEY, TTL=45 minutos), expone CurrentUser.
  • security.py: hashing Argon2 (pwd_context), creación/decodificación de JWT (create_access_token, decode_jwt), expiración configurable (settings.access_token_expire).
  • register.py, forgotpassword.py, locked.py: procesos de registro, recuperación de contraseña y gestión de cuentas bloqueadas.
  • __init__.py: reexporta funciones clave para su uso en rutas (app/auth/__init__.py).

app/access

  • access_control.py: clase AccessControl con .requiere (Annotated[bool, Depends(...)]), .check() para validar permisos y .href para construir menús.
  • access_domain.py: enum base DomainAccessEnum (gestión de dominios, navegación, helper domain_requiere).
  • access_admin.py, access_ingenieria.py, access_construccion.py, access_lda.py: enumeraciones de permisos por contexto. Cada valor usa AccessControl y opcionalmente NavigationMenu.
  • modules_access.py: mapa { módulo: DomainAccessEnum } usado en paneles de configuración o dashboards.

app/preferences

  • preference_cookie.py: clase base para cookies de preferencias (prefix=cfg:, métodos set, get, delete, clear_all).
  • centro_costos_preference.py: extiende lo anterior para la cookie cfg:centros_costos. Valida que los centros solicitados sigan activos y asignados al usuario. Expone dependencia centroCostosDep.

app/utils

Archivo Uso principal
listing.py Paginación ( paginate, resolve_order ), construcción de ColumnSpec (auto_specs_from_model ), integración con search_dsl.
search_dsl.py Analizador DSL para filtros avanzados (~=, rangos, ltree, listas, negaciones). Protecciones contra entradas enormes (MAX_SEARCH_LENGTH, MAX_SEARCH_TOKENS).
spec_builders.py Factories como any_ilike_spec, has_ilike_spec para relaciones M:N o FK.
database_dump.py Backups/restore cifrados (create_encrypted_dump_for_download, restore_from_uploaded_file, AES-GCM). Gestión de claves (generate_key, decode_key).
email.py Helpers para envío con FastAPI-Mail.
material_search.py DSL especializado para catálogos de materiales.
process_img.py Normalización de imágenes (resize, sanitización).
utc_time.py Conversión consistente de datetime a UTC.

app/logging

  • logging_setup.py: Configura structlog + logging estándar, handler rotativo diario (TimedRotatingFileHandler), JSON logs.
  • access_log.py: Middleware AccessLogMiddleware inyectado en FastAPI. Enriquecimiento de contexto: request_id, subdominio ↔ tenant, usuario desde cookie JWT, preferencia cfg:centros_costos, cuerpos pequeños de request/response. Usa structlog.contextvars.

app/tasks

  • tasks_registry.py: Decorador @register_task para registrar metadatos (TaskMeta). Lista utilizable en UI/admin.
  • tasks.py: Tareas concretas (importaciones CFDI, AMANO, ingeniería). Llaman a scripts auxiliares con sesiones SQL y Mongo.
  • runner_task.py: Tarea Huey run_registered_task que aplica locks (jobs:lock:* en Redis), captura stdout/stderr y persiste resultados (jobs:last:*).
  • scheduler_tick.py: Tarea periódica (@huey.periodic_task) que revisa calendario en Redis (sched:index) y encola ejecuciones pendientes.
  • huey_consumer.py: Configura RedisHuey con ConnectionPool.
  • huey_task.py: Entrada principal para worker (importa tareas, scheduler y valida registro).

Otros módulos relevantes

  • app/models/: Modelos SQLAlchemy (usuarios, roles, proyectos, ingeniería, construcción, LDA). base.py define Base = declarative_base() para Alembic.
  • app/routes/: Rutas organizadas por dominio (admin, ingenieria, construccion, lda, auth, agents_ai). La mayoría aprovecha utilitarios listing + search_dsl y dependencias de permisos/centros.
  • app/scripts/: Scripts de bootstrap y sincronización (init_db, importaciones). Llamados desde tareas o lifespan.

Conocer estos paquetes acelera la depuración y la extensión de endpoints. Usa los enlaces dentro de cada archivo para profundizar en implementaciones específicas.