ADR 004: Multi-panel¶

Estado¶

Aceptado — 2026-06 · Actualizado 2026-07 (paneles generativos)

Contexto¶

HIVE evoluciona hacia una plataforma modular con varios panels independientes. El prototipo histórico UnoSport Club validó este modelo de panels ortogonales; cada panel tiene su propio path de UI, namespace de API y módulos CUS.

El framework no debe hardcodear plugins de dominio ni decidir qué panels de negocio existen. Los panel_id activos emergen de plugins habilitados (contributes_panels, entry point opcional cortex.panels). El framework sí provee mecanismos de plataforma: bootstrap de control, namespaces generativos (operations, admin) y ensure_panel() al registrar módulos.

Decisión¶

Panel como unidad de composición UI/API, independiente de la autenticación.
Los namespaces operations y admin son generativos: el framework los materializa con ensure_panel() cuando plugins habilitados inyectan módulos.
Namespaces dedicados (accounting, trainer) pueden usar entry point opcional cortex.panels + PanelBuilder (ver ADR 011). El hook legacy register_panels() queda deprecado.
El framework expone GET /api/v1/panels y ensambla manifests por panel/módulo.
El shell React (framework/web-shadcn) depende de @cortex/web y monta rutas dinámicas desde la API; la skin @cortex/panel-shadcn renderiza CUS por panel.

Leyenda: Panels registrados por plugins. Actores: shells y plugins de dominio contribuyen módulos. Estado: Implementado.

flowchart TB
  subgraph panels [Panels independientes]
    Trainer[trainer /trainer/]
    Operations[operations /operations]
    Admin[admin /admin]
    Accounting[accounting /accounting/]
    Samples[samples /samples/]
    Control[control /control/]
  end
  FW[Framework ensure_panel] --> Operations
  FW --> Admin
  Domain[Plugins de dominio] --> Operations
  Domain --> Admin
  Optional[cortex.panels opcional] --> Trainer
  Optional --> Accounting
  Hw[cortex_plugin_helloworld] --> Samples
  FW --> Control

Leyenda: Mapa de panels Independiente. Estado: Implementado.

sequenceDiagram
  participant P as cortex_plugin_*
  participant R as PanelRegistry ResourceRegistry
  participant API as GET /api/v1/panels
  participant UI as framework/web-shadcn

  P->>R: register_resources panel_id module_id
  R->>R: ensure_panel panel_id
  UI->>API: panels + routes
  API->>R: manifests ensamblados

Leyenda: Registro dinámico de panels sin rutas hardcodeadas en React. Estado: Implementado.

Ejemplo ilustrativo (sandbox Reservas — no catálogo HIVE)¶

Los panels siguientes aparecen cuando el superadmin habilita los plugins del caso de uso Reservas. Otro vertical elegiría otros panel_id.

Panel ID	UI path	API namespace	Origen típico en sandbox
`trainer`	`/trainer/`	`/api/v1/trainer/`	Plugin dedicado + `configure_panel` vía `cortex.panels`
`operations`	`/operations/`	`/api/v1/operations/`	Generativo — plugins con `contributes_panels`
`admin`	`/admin/`	`/api/v1/admin/`	Generativo — plugins de parametrización
`accounting`	`/accounting/`	`/api/v1/accounting/`	Plugin `accounting` + `configure_panel` opcional
`samples`	`/samples/`	`/api/v1/samples/`	Sandbox `helloworld` (referencia interna)
`control`	`/control/`	`/api/v1/control/`	Framework embebido (siempre activo)

El módulo booking vive como sub-módulo del namespace operations (no panel propio). Ver plugin booking y ADR 008.

Metadata de shell para operations/admin puede enriquecerse con wheels opcionales cortex-plugin-panel / cortex-plugin-admin (entry points cortex.panels); no son requisito para activar el namespace. Ver Namespaces y paneles.

Activación de plugins¶

En producción y desarrollo: superadmin activa plugins en /control/plugins; el estado persiste en PostgreSQL. Los namespaces emergen según panel_id de los plugins habilitados.

La asignación de módulos a operations vs admin para un vertical concreto es decisión de producto (ADR 025), no del framework.

En tests: create_test_app(..., enabled_plugins="booking,clients,...").

Ver ADR 011 y Activación de plugins.

El plugin monolítico reserva fue retirado del monorepo; reservas de negocio → plugin booking (ADR 008, pip futuro cortex-plugin-booking — ADR 002).

Consecuencias¶

Positivas: panels aislados, extensibles por pip, shell único sin panelConfig.ts estático.
Negativas: más superficie en registry/API; documentación y CI deben listar plugins activos explícitamente.
Migración: To-Do del sandbox vive en panel samples en /samples/todo; API en /api/v1/samples/todo. Ver API interna del framework.