Namespaces y paneles generativos¶

Un panel (panel_id) es un namespace de composición UI+API: ruta base, tema, navegación y dashboards ensamblados a partir de contribuciones de plugins.

Parte del handbook: Integración con el framework.

Panel de plataforma¶

`panel_id`	Ruta	Origen
`control`	`/control/`	Framework (`bootstrap_control_panel`) — gestión de plugins, template, referencia

control no aparece en /control/plugins como plugin toggleable; siempre está activo. No es un plugin de dominio ni una entrada del catálogo docs/plugins/.

Namespaces generativos¶

Namespaces como operations y admin existen en la API/UI solo cuando plugins habilitados inyectan contenido (register_resources, register_widgets, register_settings, …) con ese panel_id.

El framework materializa el panel con ensure_panel() al primer aporte y fusiona dashboards con merge_panel_infrastructure.

Namespace	Convención	Ejemplos (handbook)
`operations`	Operación diaria	`booking`, `clients`, módulos de dominio
`admin`	Parametrización y back-office	widgets y `configuration`

Para el caso de uso Reservas (booking, clients, …) ver convención de paneles.

El panel_id lo declara cada plugin de dominio en contributes_panels y en register_resources(registry, panel_id, ...). No confundir panel_id con plugin_id.

Sandbox de plataforma (`samples`)¶

El plugin helloworld (cortex-plugin-helloworld) es referencia interna del framework, no dominio de negocio. Exporta panel dedicado samples vía entry point cortex.panels:

[project.entry-points."cortex.panels"]
samples = "cortex_plugin_helloworld:configure_panel"

plugin_id: helloworld (toggle en /control/plugins)
panel_id: samples (UI /samples/, API /api/v1/samples/)
Documentación: API interna del framework

Paquetes pip opcionales de metadata shell¶

Los wheels cortex-plugin-panel y cortex-plugin-admin (repos externos) exportan entry points cortex.panels con ids operations y admin. Aportan metadata de shell (marca, tema, dashboard home, layouts) cuando el namespace está activo; no activan el namespace ni son plugins de dominio en el catálogo.

Entry point opcional `cortex.panels`¶

Para namespaces con identidad propia (accounting, trainer, samples), el plugin exporta configure_panel(builder) en el mismo paquete:

from cortex_framework.panel.builder import PanelBuilder

def configure_panel(builder: PanelBuilder) -> None:
    (
        builder.id("accounting")
        .path("/accounting")
        .title("Contabilidad")
        .namespace("accounting")
        .auth(scopes=("accounting",))
    )

load_panel_hosts() registra paneles dedicados vía configure_panel cuando el panel_id está en el conjunto habilitado (contributes_panels de plugins activos). Los namespaces generativos se materializan con ensure_panel(); el entry point cortex.panels para operations/admin es opcional y solo enriquece metadata.

PanelBuilder — API¶

Método	Descripción
`.id(str)`	`panel_id`
`.path(str)`	Prefijo URL del shell
`.title(str)`	Título en UI
`.namespace(str)`	Namespace API (`GET /{namespace}/info`)
`.auth(scopes=...)`	Scopes OIDC
`.theme(skin=, sidebar_width=)`	Skin y layout
`.brand(title=, version=)`	Marca en sidebar
`.default_route(str)`	Ruta al entrar al panel
`.home_module(manifest, dashboards)`	Módulo home embebido
`.nav_group(id, label, sort)`	Grupos de navegación

Widgets y settings por panel¶

Los plugins registran widgets y settings filtrando por panel_id:

registry.register(
    "admin",
    WidgetDefinition(widget_id="sales-kpi", panel_id="admin", ...),
)

merge_panel_infrastructure fusiona widgets en el dashboard home del panel sin reemplazarlo.

Módulo configuration¶

El módulo configuration en la barra lateral aparece solo si hay segmentos de settings contribuidos para ese panel_id (ADR 029).

Siguiente paso¶

Primeros pasos — registrar módulos de dominio en un namespace.

Ver ADR 011 y ADR 019.