Maintenance Robot Architect

Maintenance Robot Architect

Este Skill instruye al agente sobre cómo modificar, extender y mantener el sistema de inicialización de base de datos automatizado, conocido como "Maintenance Robot". Dicho sistema reside en la lista migration_steps dentro de orchestrator_service/​main.py.

Propósito

Asegurar que CADA NUEVO DESPLIEGUE en un entorno limpio (Zero-Config / Self-Hosted) nazca completamente funcional, con:

1. Todas las tablas necesarias creadas.
2. Datos semilla ("seed data") críticos insertados.
3. Columnas nuevas agregadas a tablas existentes.

Esto elimina la necesidad de ejecutar scripts SQL manuales o depender de carpetas db/​init que a veces no se montan correctamente en orquestadores como EasyPanel.

Reglas de Oro (Protocolo Omega)

1. Idempotencia Absoluta:

   • Todo create table debe ser CREATE TABLE IF NOT EXISTS.
   • Toda inserción de datos semilla debe tener ON CONFLICT DO NOTHING (o DO UPDATE si es configuración mutable).
   • Toda alteración de columna debe usar bloques DO $$ ... EXCEPTION ... END $$ para capturar errores si la columna ya existe.

2. Atomicidad por Paso:

   • Cada elemento de la lista migration_steps se ejecuta como una transacción individual implícita.
   • Si un paso falla, se loguea el error pero el sistema intenta continuar (Soft Fail), a menos que sea una tabla crítica que impida el arranque.

3. No Borrar Pasos Antiguos:

   • La historia de migración se mantiene secuencial. Agrega nuevos pasos al final de la lista.
   • Solo modifica pasos existentes si detectas un error grave de sintaxis que rompe el arranque.

Guía de Implementación

1. Ubicación

El código vive en orchestrator_service/​main.py. Busca la variable:

migration_steps = [
    # ... pasos previos ...
]

2. Formato de Nuevo Paso

Para agregar una nueva tabla o semilla, añade un string triple-comilla al final de la lista:

    # N. Nombre Descriptivo (vX.X Update)
    """
    -- Tu SQL Aquí
    CREATE TABLE IF NOT EXISTS nueva_tabla (...);
    
    INSERT INTO nueva_tabla (...) VALUES (...) ON CONFLICT DO NOTHING;
    """

3. Manejo de Seeds Complejos

Si necesitas lógica condicional (ej: "Solo insertar X si existe Y"), usa bloques PL/​pgSQL anónimos:

DO $$
DECLARE
    parent_id INT;
BEGIN
    SELECT id INTO parent_id FROM parent_table WHERE name = 'target';
    
    IF parent_id IS NOT NULL THEN
        INSERT INTO child_table (parent_id, ...) VALUES (parent_id, ...);
    END IF;
END $$;

Casos de Uso Comunes

• Nuevas Credenciales: Si el sistema ahora soporta un nuevo proveedor (ej: TikTok), debes agregar el INSERT en oauth_providers y sus tipos en credential_types aquí.
• Nuevas Columnas: Si el modelo SQLAlchemy agrega un campo, agrega el ALTER TABLE aquí para que las BD existentes se actualicen al reiniciar.
• Configuración Global: Si cambias políticas globales (ej: Prompt del Sistema por defecto), actualiza el paso de UPDATE tenants SET system_prompt_template = ....