Saltar a contenido

ADR 029: Ensamblado del módulo de configuración por panel

Estado

Aceptado — 2026-07

Contexto

ADR 020 define el manifest JSON de configuración por plugin (groups, segments, widgets). La UI y las rutas seguían acopladas al panel admin (admin/home.py definía manualmente /admin/configuration). Otros paneles (accounting, control) no tenían un módulo de configuración ensamblado por el framework.

Además, un mismo plugin (p. ej. ai-agents) debe poder inyectar fragmentos en varios paneles a la vez — credenciales en control, agentes en admin — sin duplicar plugins ni manifests.

Decisión

  1. ConfigurationRegistry (evolución de SettingsRegistry): métodos contribute_group(panel_id, …) y contribute_segment(panel_id, …) con unicidad (panel_id, segment_id) por panel.
  2. Manifest con contributions[] obligatorio (un elemento por panel_id destino).
  3. Hook register_configuration en boot del plugin, análogo a register_widgets / register_layouts.
  4. assemble_configuration_module(panel_id) en merge_panel_infrastructure: registra módulo configuration con pantallas y widget settings cuando el panel tiene ≥1 segmento.
  5. API GET /settings/panels/{panelId} incluye uiPrefsSegmentId opcional (segmento *-ui con parámetros).
  6. Aislamiento: cada panel expone solo sus segmentos; no hay propagación automática entre paneles.

Consecuencias

  • El framework ensambla rutas de configuración automáticamente; no hace falta declararlas en home.py de un plugin.
  • Plugins con alcance multi-panel usan contributions[] (piloto: ai-agents → control + admin).
  • SettingsWidget lee uiPrefsSegmentId del árbol API en lugar de asumir admin-ui.
  • Cada plugin declara panelId del namespace de su dominio (operations para booking/clients, admin para sales/billing/payments).

Alternativas consideradas

  • Un solo panel global de configuración — rechazado: mezcla perfiles operativo/admin/contabilidad.
  • Manifest duplicado por panel — rechazado: contributions[] mantiene un archivo por plugin.