Core¶

El Core es la base compartida de todos los módulos del sistema.
Su propósito es centralizar la infraestructura común que todos los submódulos necesitan, evitando duplicación y asegurando consistencia.

Responsabilidades principales¶

DB:
Conexión ORM (SQLAlchemy).
Conexión MySQL cruda (transacciones por request).
Soporte mixto: queries raw + modelos ORM.
Seguridad (RBAC):
Validación de permisos basada en business_id.
Centralización de roles y acciones (view, create, update, archive).
Reutilizable desde cualquier módulo o blueprint.
UI común:
Layout base (Tailwind + Lucide).
Navbar y Sidebar configurables por cada submódulo.
Utilidades para marcar items activos y expandir menús dinámicamente.
Autoregistro de Blueprints:
Descubre automáticamente los bp definidos en cada submódulo bajo interface/web/web_bp.py.
Evita editar manualmente create_app cada vez que se añade un módulo.

Estructura de carpetas¶

core/
 ┣ db/
 ┃ ┣ db_ORM.py      # SQLAlchemy (ORM)
 ┃ ┗ mysql.py       # MySQL crudo (PyMySQL)
 ┣ security/
 ┃ ┗ rbac.py        # Lógica de roles y permisos
 ┣ ui/
 ┃ ┣ templates/core_ui/layout.html  # Layout común (navbar+sidebar)
 ┃ ┗ menu_utils.py  # Normalizador de menús dinámicos
 ┗ auto_blueprints.py # Autoregistro de blueprints

Diagrama de alto nivel¶

flowchart LR
    subgraph Core
        DB1[db/db_ORM.py<br/>SQLAlchemy ORM]
        DB2[db/mysql.py<br/>MySQL Compat]
        SEC[security/rbac.py<br/>RBAC centralizado]
        UI[ui/layout.html + menu_utils.py<br/>UI base]
        AB[auto_blueprints.py<br/>Autoregistro BP]
    end

    App[Flask App] --> DB1
    App --> DB2
    App --> SEC
    App --> UI
    App --> AB

    subgraph Módulos
        BP[modules/.../interface/web/web_bp.py<br/>Blueprint de submódulo]
    end

    AB --> BP --> UI
    SEC -.verifica permisos.-> BP
    DB1 -.modelos ORM.-> BP
    DB2 -.queries raw.-> BP

Flujo de ejecución (simplificado)¶

Inicio de la app:
create_app inicializa db, mysql, seguridad y autoregistro de blueprints.
autoregister_submodule_blueprints(app, "modules") escanea y registra todos los bp.
Ingreso de usuario:
El login resuelve qué business_id está activo y lo guarda en session.
Todas las consultas de módulos se filtran por business_id.
Acceso a vistas:
Antes de ejecutar mutaciones, se llama assert_perm_or_raise(user_id, business_id, action).
En plantillas, se usa build_can_map(...) para habilitar/deshabilitar botones.
UI render:
Cada submódulo define sus NAVBAR y SIDEBAR como listas de dicts.
menu_utils.normalize_menu marca activo y expande el menú según request.path.
Todo renderiza sobre core_ui/layout.html.

Convenciones clave¶

Layout:
Todos los submódulos deben extender core_ui/layout.html.

Sidebar & Navbar:
Definidos en cada submódulo en forma de lista de diccionarios, por ejemplo:

NAVBAR = [
  {"title":"Panel","href":"/panel","icon":"layout-dashboard"},
  {"title":"Clientes","href":"/crm/customers","icon":"users"},
]
SIDEBAR = [
  {"title":"Overview","href":"/crm/base","icon":"info"},
  {"title":"Clientes","href":"/crm/customers","icon":"users","children":[
    {"title":"Nuevo","href":"/crm/customers/new","icon":"user-plus"}
  ]},
]

Roles y permisos:
Cada acción en vistas protegidas usa assert_perm_or_raise.
Los templates consultan can = build_can_map(...).
BluePrints:
Siempre exportar bp en web_bp.py.
autoregister_submodule_blueprints los detecta automáticamente.

Ventajas¶

Escalabilidad: agregar módulos no requiere modificar la app central.
Consistencia: todos comparten DB, RBAC y UI.
Seguridad: permisos controlados en un solo punto.
Experiencia dev: documentación clara, flujo estandarizado.