Saltar a contenido

ADR 011: PanelProvider y plugins host

Estado

Aceptado — 2026-06

Contexto

ADR 004 introdujo multi-panel con hook register_panels() en plugins de negocio. Eso mezclaba identidad del panel (path, auth, branding) con módulos de dominio y obligaba a un plugin monolítico (shells) para varios panels.

Cortex necesita el mismo orden de boot: host primero, negocio después.

Decisión

  1. Contratos en core (PanelConfiguration, PanelBrand, PanelTheme) y framework/cortex_framework/panel (PanelBuilder, PanelProvider).
  2. Entry point cortex.panels separado de cortex.plugins. Cada plugin host exporta configure_panel(builder).
  3. Orden de carga en load_plugins():
  4. load_panel_hosts() → PanelRegistry + módulo home stub
  5. plugins de negocio (cortex.plugins) → register_dashboards / register_forms
  6. validate_panels()
  7. Cuatro hosts fijan namespace y shell (portal B2C futuro: host aparte, sin colisión con el módulo clients):
Panel Plugin host API namespace
Operación plugins/panel operations
Entrenador plugins/trainer trainer
Contabilidad plugins/accounting accounting
Control plugins/control control

Nota: El módulo de negocio clientes (plugins/clients, API /api/v1/clients/) no es un panel host; registra recursos en operations / admin. Un portal self-service para el cliente final, si se necesita, será un host con id distinto (p. ej. customer-portal).

  1. Negocio contable en plugins/ledger (cortex.plugins), montado sobre panel_id=accounting con API /api/v1/ledger/.
  2. register_panels en negocio queda deprecado (warning); solo hosts y legacy reference/samples.
  3. GET /api/v1/panels/{id} incluye bloque configuration (brand, theme, defaultRoute) para el shell React.

Leyenda: Orden de boot: hosts → plugins → validación. Actores: entry points, registries, loader. Estado: Implementado.

flowchart TB
  EP[cortex.panels + cortex.plugins]
  LH[load_panel_hosts configure_panel]
  LP[load_plugins register_resources]
  VP[validate_panels]
  EP --> LH --> LP --> VP

Conceptos del panel host

Concepto Cortex
Id del panel builder.id()
Ruta base UI builder.path()
Autenticación builder.auth(scopes=...)
Marca builder.brand()
Módulos de negocio plugins vía register_resources / register_dashboards
Ruta por defecto builder.default_route()

Consecuencias

  • plugins/shells eliminado; UI migrada a hosts.
  • CORTEX_ENABLED_PANELS controla hosts; CORTEX_ENABLED_PLUGINS incluye hosts (para workspace) y negocio.
  • Frontend (PanelShell) lee configuration de la API en lugar de valores hardcodeados.

Referencias

  • ADR 004 — multi-panel
  • Plan PanelProvider (2026-06)