De la idea al primer cliente de pago: una hoja de ruta de entrega para un SaaS multi-tenant en Laravel: 05 de 08

Un plan trabajando hacia atrás para llevar un SaaS multi-tenant en Laravel de la idea al primer cliente de pago: criterios de éxito, orden de construcción, límites de plan, webhooks de facturación idempotentes, logs por tenant y despliegues seguros.

De la idea al primer cliente de pago: una hoja de ruta de entrega para un SaaS multi-tenant en Laravel: 05 de 08
Photo by Fotis Fotopoulos / Unsplash
Un plan trabajando hacia atrás para llevar un SaaS multi-tenant en Laravel de la idea al primer cliente de pago: criterios de éxito, orden de construcción, límites de plan, webhooks de facturación idempotentes, logs por tenant y despliegues seguros.

Imagina un equipo que empieza un SaaS multi-tenant como lo hacen la mayoría. La primera semana es login y registro. De la segunda a la sexta, pantallas de configuración, un panel de administración y un sistema de diseño. Nadie ha usado aún el producto para el único trabajo para el que existe, y el modelo de datos no sabe que las empresas deben estar separadas entre sí.

El código de los artículos anteriores (aislamiento de tenants, Actions, Data objects, Events) es solo la mitad del proyecto. La otra mitad es el orden en que lo construyes y la evidencia que reúnes antes de cobrarle a alguien. Este artículo es ese plan, escrito hacia atrás desde el día en que un desconocido paga.

Empieza por el día en que un desconocido paga

Antes de un plan, un resultado. Para una primera versión lo escribiría como un solo párrafo: una persona se registra, crea una empresa, invita a un colega, hace el trabajo central, llega al límite del plan gratuito y paga. Toda tarea que no sirva a esa frase espera.

Luego conviértelo en criterios de éxito que puedas comprobar. Un primer conjunto podría ser:

  • Una empresa nueva puede completar el trabajo central sin tu ayuda.
  • Ningún test, script o comprobación manual puede mostrarle a una empresa los datos de otra.
  • Un límite de plan se aplica en un solo lugar y la app lo explica cuando se alcanza.
  • Un pago, una cancelación y un cobro fallido cambian cada uno lo que la empresa puede hacer.
  • Puedes responder "¿qué le pasó a la empresa X ayer?" desde tus logs.

Escribe al lado las restricciones y los supuestos: tamaño del equipo, presupuesto, el único proveedor de pagos que usarás, los roles que crees necesitar. Los supuestos son la parte útil. Cada uno es algo que descubrirás que está mal, y es más barato descubrirlo mientras todavía es una línea en un documento.

Levanta los muros antes que las habitaciones

El orden importa, y el tenancy va primero. Agregar una columna de empresa a treinta tablas después del lanzamiento es una de las migraciones más caras que puede enfrentar un SaaS, y una tabla olvidada es una fuga de datos. Un orden de construcción viable:

  1. Empresas, membresía y roles, con el contexto de tenant y el scope que falla cerrado, y los tests de fuga que los acompañan.
  2. Un slice de punta a punta del trabajo central, construido con las convenciones de Action, Data object y controlador que vas a conservar.
  3. Las piezas en segundo plano que ese slice necesita (events, listeners y jobs), cada una corriendo dentro de un contexto de tenant.
  4. Planes y límites.
  5. Facturación.
  6. Todo lo demás, ordenado según lo que pidan los primeros clientes.

El razonamiento es simple. Los muros son difíciles de añadir después y las habitaciones son fáciles de agregar. La facturación necesita planes, y los planes necesitan algo que valga la pena limitar.

Un slice, hasta el fondo

El segundo paso merece su propia sección, porque es el que más reduce el riesgo. Un slice vertical va de la migración a una pantalla y un test: la tabla con su company_id, el modelo con su trait, el Data object, la Action, el controlador delgado, una vista, un test que intenta filtrar. Y despliégalo antes de empezar la segunda funcionalidad.

Esa última parte parece prematura, y no lo es. Un slice en un entorno real saca a la luz los problemas que no viven en el código: el worker de colas que no está corriendo, el scheduler que no está programado, el mailer sin credenciales, el disco de almacenamiento con los permisos equivocados. Quieres encontrarte con ellos con una funcionalidad en juego, no con doce.

El costo es que el primer slice es lento. Estás construyendo las convenciones y el pipeline a la vez. Los slices siguientes son rápidos porque el primero pagó el patrón.

Planes, límites y facturación

Los límites tienden a filtrarse en el código como comprobaciones dispersas de if ($company->plan === 'free'). Pónlos detrás de una sola clase a la que llamen las Actions:

final class PlanLimits
{
    public function assertCanAddMember(Company $company): void
    {
        $limit = $company->plan->maxMembers();

        if ($company->members()->count() >= $limit) {
            throw PlanLimitReached::for('members', $limit);
        }
    }
}

La clase asume que plan es un cast a enum con un método maxMembers(). Lo importante es la puerta única. Cuando cambian los precios, cambia un archivo, y la excepción da a todos los llamadores una forma coherente de explicar el límite.

La facturación es donde los errores cuestan dinero. Algunas reglas ayudan, elijas el proveedor que elijas:

  • Trata al proveedor como fuente de verdad del estado de la suscripción, y guarda una copia local que lea la app. Nunca llames al proveedor en cada petición para decidir qué puede hacer una empresa.
  • Verifica la firma de cada webhook antes de leer el cuerpo. Cómo depende del proveedor.
  • Guarda cada evento con el id de evento del proveedor antes de hacer cualquier otra cosa, y responde rápido. Haz el trabajo real en una cola.
  • Asume que los eventos llegan dos veces y fuera de orden.
public function __invoke(Request $request): Response
{
    abort_unless($this->signature->isValid($request), 401);

    $payload = $request->json()->all();

    $event = BillingEvent::firstOrCreate(
        ['provider_event_id' => $payload['id']],
        ['type' => $payload['type'], 'payload' => $payload, 'received_at' => now()],
    );

    if ($event->wasRecentlyCreated) {
        ProcessBillingEvent::dispatch($event->id);
    }

    return response()->noContent();
}

signature es un verificador específico del proveedor que escribes una sola vez. Respalda la columna provider_event_id con un índice único, porque firstOrCreate por sí solo no es atómico. Si dos entregas compiten, una falla en el índice y el reintento del proveedor encuentra la fila ya guardada. Para los eventos fuera de orden, haz que el job de procesamiento compare la marca de tiempo del evento con la última aplicada a esa suscripción y descarte lo que sea más antiguo.

Probar las partes que cuestan dinero

No puedes probarlo todo, así que apunta a lo que sale caro cuando se rompe:

  • Aislamiento. Los tests de fuga del primer artículo, más una guarda que verifique que toda tabla con company_id use el trait.
  • Límites. Por debajo del límite, justo en él y por encima.
  • Webhooks. El mismo evento entregado dos veces produce un solo efecto, y un evento antiguo no sobrescribe un estado más nuevo.
  • El camino feliz. Un smoke test a nivel de navegador desde el registro hasta el trabajo central.

Lo demás puede vivir casi todo como tests de Action, que son rápidos, con una capa fina de tests HTTP para autorización y validación. Esa es la forma que los artículos anteriores establecieron a propósito.

Desplegar sin despertar a nadie

Durante un deploy, el código viejo y el nuevo corren un momento lado a lado. Las migraciones tienen que sobrevivir a eso. La disciplina habitual es expandir primero (añadir una columna nullable, desplegar código que escribe en ambas), luego rellenar, luego cambiar las lecturas y, en un release posterior, endurecer la restricción. Los backfills sobre datos de tenants se hacen mejor como un job por empresa en bloques, por las mismas razones que el job nocturno del primer artículo.

Dos hábitos evitan la mayoría de las sorpresas. Reinicia los workers de colas en cada deploy, porque mantienen la aplicación arrancada en memoria y no notan el código nuevo por su cuenta (php artisan queue:restart lo hace). Y mantén disponible el release anterior, para que el rollback sea un interruptor y no una reconstrucción. Eso solo funciona si las migraciones son retrocompatibles, y por eso el paso de expandir va primero.

Ver por tenant

El último criterio de la lista era responder "¿qué le pasó a la empresa X ayer?". Context de Laravel lo vuelve una sola línea. Añádela donde se resuelve el tenant:

Context::add('company_id', $company->id);

Según la documentación, el contexto se agrega a las entradas de log escritas durante la petición y también se captura cuando se despacha un job y se restaura mientras el job corre. Cada línea de log, desde la web y desde la cola, lleva ahora la empresa. Esto no reemplaza el contexto de tenant explícito para las consultas. Solo hace que los logs se puedan buscar. Envía el mismo id a tu rastreador de errores, y una pregunta de soporte se vuelve un filtro en lugar de una investigación.

Conclusión

El equipo del principio pasó seis semanas en habitaciones sin muros y sin cliente. El plan de aquí lo invierte: define el día en que alguien paga, levanta los muros, entrega un slice de punta a punta y luego añade límites y facturación en el orden del que depende el dinero.

Lo que se deja fuera es tan parte del plan como lo que entra. El single sign-on, los precios por uso y las bases de datos por empresa tienen cada uno un punto en que vale la pena construirlos. Ese punto es un cliente que lo pide, no una corazonada. Hasta entonces, puedes escribir el primer párrafo de este artículo para tu propio producto y comprobar cuáles de sus frases ya puedes demostrar.