# Plugin Builder y ciclo de vida de plugins

Fecha de referencia: 1 de abril de 2026.

Esta guia explica el flujo actual para convertir apps en plugins, generar instaladores y desplegarlos en otros entornos.

## Componentes implicados

- [`../base/plugin_builder/index.php`](../base/plugin_builder/index.php)
- [`../base/plugins/index.php`](../base/plugins/index.php)
- [`../base/plugin_builder/_templates/plugin_installer.tpl.php`](../base/plugin_builder/_templates/plugin_installer.tpl.php)
- [`../base/plugin_builder/_templates/plugin_uninstaller.tpl.php`](../base/plugin_builder/_templates/plugin_uninstaller.tpl.php)

## Que hace hoy el Plugin Builder

El builder toma una app existente y genera un plugin distribuible. En la practica:

- lee metadatos de la app
- genera `plugin.json`
- genera `install/install.php` o `install/installer.php`
- genera desinstalador
- empaqueta la app en ZIP
- conserva la configuracion SQL del plugin

## SQL detectado por el builder

El builder recorre la carpeta de la app y detecta ficheros `.sql`. Luego permite configurar para cada script:

- `file`
- `enabled`
- `order`
- `stage`
- `mode`

Ejemplo:

```json
{
  "file": "_schema_v2.sql",
  "enabled": 1,
  "order": 10,
  "stage": "install",
  "mode": "auto"
}
```

## Fases SQL

- `install`: instalacion nueva
- `migrate`: migracion desde legacy
- `update`: cambios incrementales
- `cleanup`: limpieza final

## Modos SQL

- `auto`: el instalador intenta ejecutar el SQL
- `manual`: el instalador lo muestra, pero no lo ejecuta

`cleanup` suele ser mejor dejarlo manual salvo que este muy probado.

## Que guarda el builder

La configuracion queda reflejada en:

- `app.json` de la app origen
- `plugin.json` del plugin
- metadatos embebidos en el instalador generado

## Que hace el instalador generado

El instalador del plugin:

1. lee el manifiesto embebido
2. ordena los SQL activos
3. resuelve las rutas reales dentro del plugin
4. ejecuta o muestra SQL segun estrategia
5. registra la app en `intranet_apps`
6. registra el plugin en `intranet_plugins`
7. intenta enlazar `/apps/<app_folder>` con `/plugins/<plugin_id>/apps/<app_folder>`

## Estrategias SQL disponibles hoy

El flujo actual ya soporta tres estrategias:

- `auto`: ejecuta con el usuario de aplicacion y muestra lo marcado como manual
- `admin`: ejecuta con credenciales de administrador MySQL
- `show`: muestra todos los SQL para revision o ejecucion manual

Esto existe tanto en:

- el instalador standalone generado por el builder
- el gestor central de plugins

## Credenciales administrativas de BD

Cuando se elige estrategia `admin`, el instalador pide:

- host
- puerto
- usuario admin
- password admin

Con eso puede ejecutar SQL del plugin fuera de los permisos del usuario de aplicacion.

## Compatibilidad con `install/install.sql`

Ademas del manifiesto moderno, el gestor central sigue teniendo en cuenta el flujo heredado:

- `install/install.sql`
- `install/install.php`
- `install/installer.php`

El resultado del SQL legacy y el del instalador moderno se combinan en una sola salida para el operador.

## Resultado visible de la instalacion

El gestor de plugins ya no instala a ciegas. Ahora muestra:

- SQL ejecutados
- modo de conexion usado
- SQL pendientes de revision manual
- errores SQL
- mensaje final de instalacion incompleta si hace falta intervencion

Si eliges `show`, el plugin no se registra todavia en la intranet hasta que vuelvas a instalarlo en modo `auto` o `admin`.

## Analisis automatico del plugin

El gestor central incorpora una primera capa de documentacion automatica. A partir de:

- `plugin.json`
- descripcion
- README
- nombre del plugin
- carpeta de app
- scripts SQL

genera:

- un resumen funcional corto
- capacidades detectadas
- una descripcion visible en la tabla de plugins

Es una heuristica del propio codigo, no un LLM externo, pero ya sirve como base documental minima.

## Flujo recomendado

### Desarrollo

1. terminar la app
2. preparar sus SQL
3. revisar orden, fase y modo en el builder
4. generar ZIP del plugin
5. documentar objetivo y validaciones

### Preproduccion

1. instalar nucleo ya validado
2. instalar o actualizar plugin
3. elegir estrategia SQL adecuada
4. validar navegacion, permisos y datos

### Produccion

1. repetir solo cuando el plugin ya este validado
2. documentar si el SQL sera `auto`, `admin` o `manual`
3. conservar evidencia del resultado

## Plugins con legacy

Orden sugerido:

1. esquema nuevo
2. migracion de datos legacy
3. updates incrementales
4. limpieza legacy

Ejemplo:

1. `_schema_v2.sql`
2. `_migrate_legacy_to_v2.sql`
3. `_schema_update_add_columna.sql`
4. `_schema_drop_legacy_tables.sql`

## Revision minima

Antes de generar el ZIP:

- la app funciona
- los SQL estan presentes y ordenados
- `app.json` es coherente
- `plugin.json` refleja el estado real
- la version del plugin es correcta

Al instalar:

- si el SQL detectado corresponde al estado real del destino
- si conviene `auto`, `admin` o `show`
- si la app aparece en `intranet_apps`
- si el plugin aparece en `intranet_plugins`
- si el enlace en `/apps` funciona

## Relacion con otras guias

- [instalacion-intranet-en-ubuntu.md](./instalacion-intranet-en-ubuntu.md)
- [core-update-y-paso-a-preproduccion.md](./core-update-y-paso-a-preproduccion.md)
- [ldap-ldaps-y-certificados.md](./ldap-ldaps-y-certificados.md)
