# Despliegue a producción — mbinv (backend) + mbinv-catalogo (frontend)

Manual para el equipo de soporte. Cubre: desplegar el backend a un cliente,
desplegar el frontend del catálogo, y activar/configurar el módulo
Diccionario usando la plantilla general (para no configurar cada tabla a
mano por cada cliente).

No se necesita saber programar para seguir estos pasos. Si algo falla en un
punto que dice "avisar a programación", detenerse ahí y escalar.

---

## 0. Antes de empezar (una sola vez, ya en curso)

Estos dos features viven en ramas separadas del repo `mbinv` y deben estar
en `main` antes de que cualquier cliente pueda recibirlos:

- **Diccionario** (rama `feature/diccionario-mbinv-catalogo`): el PR ya fue
  aprobado y mergeado a `main`. Actualmente hay una mejora nueva encima
  (la "plantilla general", ver sección 4) que todavía está sin commitear/PR
  — **programación debe commitearla, subirla y mergearla a `main` antes de
  que este manual sea 100% válido**. Si al llegar a la sección 4 los botones
  "Importar/Aportar a plantilla" no aparecen en el panel de Diccionario, es
  porque ese merge todavía no llegó al servidor del cliente.
- **Pedidos a Proveedor** (rama `feature/pedidos-proveedor`): a la fecha de
  este manual **no tiene ningún commit**, todo el trabajo vive sin
  guardar en el checkout de programación. No se puede desplegar a ningún
  cliente hasta que programación lo commitee, suba y lo mergee a `main`.

Si ambos ya están en `main` cuando se lea esto, se puede ignorar este punto
y seguir directo con la sección 1.

---

## 1. Desplegar el backend (`mbinv`) a un cliente

Esto aplica a **cualquier cliente que ya exista** (no a la creación de un
cliente nuevo, que es un proceso aparte que ya maneja el equipo de
sistemas). Se hace por cada servidor de cliente:

1. Conectarse al servidor del cliente (SSH, igual que para cualquier
   mantenimiento).
2. Ubicarse en la carpeta del proyecto `mbinv` de ese cliente y actualizar
   el código:
   ```
   git pull origin main
   ```
3. Entrar al sistema como usuario con rol Administrador (`ROLE_ADMIN`) y
   visitar:
   ```
   /procesos/install
   ```
4. Pulsar el botón **"Actualizar"**. Esto revisa la base de datos del
   cliente contra la estructura de referencia (`mbinvestructura`, en el
   servidor de pruebas) y aplica automáticamente las tablas/columnas nuevas
   que falten — incluyendo las 9 tablas `dic_*` del módulo Diccionario si
   el cliente nunca las tuvo.
5. Esperar a que el proceso reporte "Fin del proceso" (puede tardar varios
   minutos). Si se queda pegado más de 5 minutos sin avanzar, es un proceso
   huérfano — la misma pantalla ofrece la opción de reintentar.
6. Verificar que no haya errores en el mensaje final. Si los hay, **avisar
   a programación antes de continuar** — no repetir el proceso a ciegas.

Este mismo paso cubre backend de Diccionario y de Pedidos a Proveedor a la
vez, porque ambos están en el mismo repo/rama `main`.

---

## 2. Desplegar el frontend del catálogo (`mbinv-catalogo`)

Solo aplica si el cliente usa el catálogo web (Next.js, servido aparte del
backend). Se despliega una sola vez para todos los clientes (no es por
cliente, es una app compartida):

1. Conectarse al servidor donde corre `mbinv-catalogo` (`oci-mbinv`).
2. Ejecutar:
   ```
   ./deploy.sh
   ```
   Esto hace `git pull origin main`, reconstruye la imagen Docker y
   reinicia el contenedor (puerto 3002).
3. Confirmar que el sitio responde después del reinicio.

---

## 3. Activar Diccionario para un cliente existente

Por defecto Diccionario está **apagado** para todos los clientes aunque el
backend ya tenga las tablas `dic_*` instaladas (paso 1). Para activarlo:

1. Como Administrador, ir a **Parámetros de Backoffice** del cliente.
2. Ubicar el parámetro `usa_catalogo_diccionario` y ponerlo en `S`.
3. Guardar.
4. **Habilitar el acceso al menú "Diccionario" para el usuario que lo va a
   configurar** (ej. `mb`): activar `usa_catalogo_diccionario` NO hace que
   el menú aparezca solo — cada usuario tiene su propia lista de accesos
   al sistema. Ir a `/usuario/{id}/accesos` (o desde el listado de
   usuarios → el usuario → "Accesos") y marcar "Diccionario" en el árbol
   de menú, luego guardar. Sin este paso, aunque el parámetro esté en `S`,
   el usuario no va a ver el menú ni va a poder entrar a configurarlo.
   (Nota: solo un usuario que ya tenga el permiso "Módulo Catálogos"
   puede entrar a esa pantalla de accesos para dárselo a otro.)

Con esto el cliente puede usar Diccionario, pero **cada tabla que se quiera
publicar como catálogo hay que configurarla** (qué campos se ven, títulos,
descripciones, acciones, restricciones). Ahí es donde entra la plantilla
general — sección 4.

---

## 4. Configurar una tabla usando la plantilla general

Desde hace tiempo existe `crearTablaDesdeEsquema()`, que genera
automáticamente los campos de una tabla nueva a partir de su estructura
física (nombres, tipos, si es llave). Eso resuelve lo mecánico, pero deja
vacíos los títulos de reporte, descripciones, relaciones/validaciones,
botones de acción y restricciones de borrado — antes había que llenar todo
eso a mano, por cada tabla, en cada cliente.

Ahora existe una **plantilla general** compartida entre todos los clientes
(vive en una base de datos de referencia, `mbinvestructura`, en el
servidor de pruebas — no en producción). Cualquier cliente puede "bajar"
de ahí la configuración ya hecha, y cualquier cliente bien configurado
puede "subir" su configuración para que los demás la aprovechen.

**¿Desde qué proyecto lo hace soporte?** No hace falta un proyecto
especial — el botón "Aportar a plantilla" siempre escribe en la misma
`mbinvestructura` compartida sin importar desde qué cliente se dispare,
así que se puede hacer desde el `/dic/admin` de cualquier cliente donde ya
se tenga acceso. Para armar contenido de la plantilla desde cero (sin
acoplarlo a los textos/nombres de un cliente real en particular), usar el
proyecto dedicado **`mbinvdiccionario`** — una base de pruebas clonada de
`mbinvmacrobase` (mismo esquema y datos de ejemplo, sin ser la base real),
en el servidor de pruebas (132.226.40.48:3310, user `manuel`). **No usar
`mbinvmacrobase` directamente** para esto — es la base real de
auto-facturación de MacroBase, no un sandbox.

Hoy `mbinvdiccionario` solo es accesible corriendo el backend local
(worktree `mbinv-diccionario`, ver `dev-servers.sh` en
`/Users/manuelbustamante/proyectosweb/`) — todavía no tiene un proyecto
desplegado con URL pública propia. Si hace falta acceso remoto persistente
(un subdominio como `qa-manuel`), es un paso aparte (vhost + DNS).

**Cómo saber en cuál base se está parado**: las 4 pantallas del panel de
Diccionario (Panel, Campos, Permisos, Bitácora) muestran un aviso justo
debajo del título:
- **Amarillo "BASE DE PLANTILLA"** → esto es `mbinvdiccionario`; lo que se
  "aporte" aquí impacta la plantilla general de todos los clientes.
- **Rojo "CUIDADO"** → esto es `mbinvmacrobase`, la base real — no usarla
  para curar la plantilla.
- **Gris "Cliente: `<nombre_de_base>`"** → es un cliente real; lo que se
  configure aquí es solo de ese cliente (aunque igual se le puede "aportar"
  a la plantilla si aplica).

**Herramientas para trabajar con varias tablas a la vez** (Panel principal,
junto a "Agregar tabla nueva"):
- **"Actualizar desde plantilla"**: compara TODAS las tablas del cliente
  contra la plantilla de una sola vez (nuevas / con cambios / al día) e
  importa las que se seleccionen — reemplaza tener que probar "Importar
  plantilla" tabla por tabla a ciegas.
- **"Aportar pendientes"**: el espejo — muestra qué tablas de este cliente
  tienen contenido que la plantilla todavía no tiene, y las aporta todas
  de una vez (con confirmación, porque sí sobrescribe la plantilla).

### 4.1 Importar una tabla desde la plantilla (caso normal)

1. Entrar al panel de administración de Diccionario del cliente:
   `/dic/admin`.
2. Si la tabla todavía no existe en la lista, crearla primero con
   **"Nueva tabla"** (o simplemente seguir al paso siguiente — importar la
   crea sola si hace falta).
3. Ubicar la tabla en la lista y pulsar **"📥 Importar desde plantilla"**.
4. El sistema muestra un resumen: cuántos campos se completaron, cuántas
   acciones y restricciones se agregaron. Si dice que "la plantilla
   general no tenía nada nuevo para esta tabla todavía", significa que
   nadie ha aportado esa tabla a la plantilla aún — pasar a configurarla a
   mano esta primera vez (ver 4.3).
5. Revisar lo que trajo y ajustar lo que sea específico de este cliente
   (por ejemplo, textos que mencionen su negocio en particular).

**Importante**: importar nunca borra ni sobrescribe algo que ya esté
configurado en el cliente — solo completa lo que está vacío. Se puede
correr las veces que haga falta sin miedo a perder ediciones.

### 4.2 Aportar una tabla ya bien configurada a la plantilla

Cuando una tabla queda configurada de forma genérica y reutilizable (no
específica de un cliente particular), conviene subirla para que los demás
clientes la hereden automáticamente la próxima vez que la importen:

1. En el mismo panel `/dic/admin`, pulsar **"📤 Aportar a la plantilla"**
   en la tabla ya configurada.
2. Confirmar el aviso (esto **sí sobrescribe** la plantilla general con la
   configuración actual de esa tabla en este cliente — usarlo solo cuando
   la configuración ya esté revisada y sea genérica, no a medio hacer).

### 4.3 Si la plantilla todavía no tiene nada para esa tabla

Es normal para tablas que nadie ha configurado todavía en ningún cliente.
Configurarla a mano una vez (títulos, descripciones, acciones,
restricciones) y luego usar **"Aportar a la plantilla"** (4.2) para que el
trabajo no se repita en el siguiente cliente.

---

## 5. Llevar la plantilla a la base de clientes nuevos (tarea de programación, NO de soporte)

Cuando se crea un cliente nuevo, su base de datos se clona automáticamente
de una base plantilla (`mbinvinstalar`) que vive en producción. Por
motivos de seguridad, **el equipo de soporte y de programación no tiene
acceso de escritura a esa base** — solo el proyecto especial
`macrobase.sistemasmb.com/mbinv` (que está siempre conectado a producción)
puede tocarla, y solo alguien autorizado debe hacerlo.

Esto significa que lo que se "aporta a la plantilla" en el paso 4.2 queda
disponible de inmediato para cualquier cliente existente (vía "Importar
desde plantilla"), pero **no** se propaga solo a clientes nuevos. Para que
un cliente nuevo nazca ya con Diccionario preconfigurado, periódicamente
alguien autorizado debe:

1. Confirmar que las 9 tablas `dic_*` y el parámetro
   `usa_catalogo_diccionario` estén al día en la `mbinvinstalar` real de
   producción (mismo DDL que ya está aplicado en `mbinvestructura`, base
   de pruebas).
2. Volcar el contenido de `dic_tabla`, `dic_campo`, `dic_accion` y
   `dic_restriccion` desde `mbinvestructura` (pruebas) hacia la
   `mbinvinstalar` real, por ejemplo:
   ```
   mysqldump --no-create-info --tables dic_tabla dic_campo dic_accion dic_restriccion mbinvestructura > plantilla_dic.sql
   ```
   y aplicar ese archivo a mano contra la `mbinvinstalar` de producción,
   desde el proyecto autorizado.

Este paso **no está automatizado a propósito** — es responsabilidad de la
persona autorizada a tocar producción, no de soporte ni de un endpoint del
sistema. Soporte solo necesita saber que existe y pedirlo cuando haga
falta que los clientes nuevos ya nazcan con catálogos configurados.

---

## 6. Activar Pedidos a Proveedor para un cliente

Mismo mecanismo que Diccionario, sin el paso de plantilla:

1. Backend ya actualizado (sección 1, cubre ambos features).
2. Verificar con programación si el feature requiere activar algún
   parámetro de backoffice adicional específico de Pedidos a Proveedor
   (pendiente de confirmar una vez esté commiteado y en `main` — ver
   sección 0).

---

## 7. Regla permanente para programación

Cualquier tabla o columna nueva de `dic_*` que se agregue a través de
`Instalacion.php` debe reflejarse también en la base de referencia
`mbinvestructura` (servidor de pruebas) — si no, la próxima vez que un
cliente corra `/procesos/install` (sección 1) no la recibirá. Llevar esos
mismos cambios de estructura a la `mbinvinstalar` real de producción es,
igual que el contenido (sección 5), tarea manual de la persona autorizada
— nunca se hace directo desde el código de Diccionario.

---

## 8. Checklist final de verificación

Después de desplegar a un cliente:

- [ ] `/procesos/install` terminó sin errores.
- [ ] El menú "Diccionario" aparece (si se activó `usa_catalogo_diccionario`).
- [ ] Al menos una tabla de catálogo se ve correctamente en
      `mbinv-catalogo` (frontend) con sus campos, títulos y descripciones.
- [ ] Los botones "Importar desde plantilla" / "Aportar a plantilla"
      aparecen en `/dic/admin` (si no aparecen, el merge de la sección 0
      todavía no llegó a este cliente).
- [ ] Si se activó Pedidos a Proveedor, el módulo carga sin error 500 y
      permite generar una cotización de prueba.