Cuando la lógica de un SaaS empieza con condiciones como if ($tenant->plan === 'pro'), parece una solución directa. El problema aparece al segundo cambio de catálogo: un plan se renombra, una capacidad se vende por separado, un cliente conserva condiciones antiguas o soporte necesita habilitar algo temporalmente. Entonces el nombre comercial deja de describir una regla estable y termina repartido entre controladores, tareas programadas, consultas, API e interfaz.
La gestión de capacidades en SaaS PHP debe traducir la oferta comercial a decisiones de dominio verificables. El código no debería preguntarse si una empresa es “Pro”, sino si puede realizar una acción concreta, con qué límite, bajo qué condiciones y hasta cuándo. Esta separación permite cambiar precios o empaquetados sin reescribir reglas operativas.
Separar plan, capacidad, límite, permiso y configuración
Estos conceptos se relacionan, pero no son intercambiables. Un plan es un empaquetado comercial. Una capacidad habilita una posibilidad de producto, como exportar datos, crear automatizaciones o usar una integración. Un límite define una cantidad o ritmo permitido, por ejemplo proyectos activos, usuarios facturables o solicitudes API por periodo.
Un permiso responde a otra pregunta: qué identidad puede hacer una acción dentro de una empresa. Que una organización tenga la capacidad de exportar datos no significa que cualquier usuario pueda exportarlos. Finalmente, la configuración del cliente son opciones válidas para una empresa concreta, como el proveedor de identidad elegido, una política de retención o una plantilla de notificaciones. No conviene usar configuración libre para ocultar decisiones comerciales o de autorización.
- Plan: composición comercial de derechos y límites.
- Capacidad: regla funcional expresada en términos del producto.
- Límite: umbral cuantificable asociado a una capacidad o recurso.
- Permiso: autorización de un actor para ejecutar una acción.
- Configuración: parámetro de comportamiento disponible dentro de las reglas ya concedidas.
Una decisión puede requerir todas las capas. Para crear una automatización, la empresa necesita la capacidad correspondiente, debe estar por debajo del límite de automatizaciones activas y el usuario debe tener permiso de administración. Después, el flujo puede validar la configuración de destino.
Modelar reglas de dominio, no nombres de planes
Mantenga un catálogo estable de capacidades con identificadores técnicos independientes del marketing: automation.create, data.export o api.webhooks. El catálogo puede incluir el tipo de valor esperado: booleano, entero, conjunto de opciones o política estructurada. El identificador expresa una necesidad de producto; no debe incorporar el nombre de un plan ni una campaña.
La asignación comercial puede resolverse en una capa separada. Un plan vigente aporta un conjunto de concesiones, pero también pueden existir complementos, migraciones heredadas y excepciones explícitas. El resultado para cada empresa es una resolución de derechos efectiva con procedencia.
capacidad: automation.create
valor efectivo: true
procedencia: complemento de automatizaciones
vigencia: hasta cancelación
Esta procedencia es esencial. Si una capacidad está activa, producto, soporte y facturación necesitan saber si viene del plan actual, de una cláusula heredada o de una excepción con fecha de caducidad. Evite guardar sólo un campo plan en la empresa y deducir todo el resto en cada punto de uso.
Un servicio único de decisión
En PHP, exponga un servicio de dominio, por ejemplo EntitlementResolver o CapabilityGate, que reciba la empresa, la capacidad y el contexto necesario. Debe devolver una decisión explicable, no sólo un booleano: permitido o rechazado, valor resuelto, motivo, regla fuente y fecha de evaluación. Esta fecha representa el instante en que el resolvedor determinó la decisión y permite interpretar correctamente vigencias, caducidades y cambios de plan posteriores. Los controladores, comandos, listeners y trabajadores asíncronos consultan ese servicio; no reconstruyen sus propias consultas de suscripción.
Definir límites medibles antes de programarlos
Un límite ambiguo genera conflictos y errores de implementación. “Hasta 100 usuarios” exige responder qué cuenta como usuario: ¿invitado pendiente, suspendido, miembro eliminado durante el ciclo, cuenta de servicio? “Mil exportaciones” requiere definir periodo, zona horaria, reintentos y si una exportación fallida consume cuota.
Para cada límite, documente al menos:
- El recurso, evento o consumo que se contabiliza.
- El alcance: empresa, proyecto, usuario o integración.
- La ventana: total vigente, día natural, mes de facturación o ventana móvil.
- El momento de control: antes de crear, al activar, al enviar o tras consolidar.
- La reacción: bloquear, permitir con aviso, encolar, degradar o exigir aprobación.
- El tratamiento de concurrencia, reintentos, cancelaciones y reversión.
Los límites de objetos activos suelen validarse con una operación transaccional o una reserva que evite superar el umbral bajo concurrencia. Los límites de consumo necesitan un contador con semántica clara e idempotencia mediante una clave de evento. No confíe sólo en un contador mostrado en la interfaz: dos peticiones simultáneas pueden pasar una comprobación previa y superar el máximo.
También diferencie entre advertencia y bloqueo. Una alerta al 80 % mejora la previsibilidad, pero no sustituye una protección real en el punto donde se crea o ejecuta el recurso.
Aplicar las reglas en todos los caminos de ejecución
Ocultar un botón es una mejora de experiencia, no un control de acceso. La validación debe existir en el caso de uso del servidor que ejecuta la acción. Así cubre la interfaz web, API pública, integraciones y llamadas internas.
Los procesos asíncronos requieren una decisión adicional: comprobar al encolar y volver a comprobar al ejecutar cuando el trabajo pueda demorar. Si una empresa pierde una capacidad entre ambos momentos, la política debe definir si el trabajo se cancela, se completa por haber sido aceptado antes o requiere revisión. La elección depende del tipo de operación, pero debe ser consistente y registrada.
Las herramientas de soporte y administración no deberían saltarse las reglas silenciosamente. Pueden operar con una autorización administrativa distinta, pero han de dejar trazabilidad e indicar si generan una concesión formal, una corrección de datos o una acción excepcional.
Gestionar cambios, herencias y excepciones sin bifurcar el producto
Un cambio de plan no es sólo actualizar una etiqueta. Puede reducir un límite por debajo del uso actual o retirar una capacidad que sostiene procesos activos. Defina políticas por tipo de recurso: impedir nuevas creaciones y conservar lo existente, desactivar excedentes de forma explícita, dar un periodo de transición o solicitar una elección al administrador de la empresa.
Las excepciones temporales deben ser concesiones de primera clase con alcance, valor, motivo, emisor y caducidad. Un campo manual como is_vip es difícil de interpretar y suele sobrevivir a la causa original. Para clientes heredados, modele una asignación de migración con reglas precisas y fecha de revisión, en lugar de crear ramas permanentes de código.
Una excepción sostenible es un dato auditable que el mismo resolvedor interpreta; una excepción peligrosa es un condicional especial añadido a un flujo concreto.
Combinar capacidades, roles y aislamiento multiempresa
En una plataforma multiempresa, toda consulta de derechos, consumo y configuración debe estar delimitada por la empresa correcta. No derive el contexto sólo de valores enviados por el cliente. Resuélvalo desde la autenticación, el dominio solicitado o el contexto interno validado, y propáguelo a trabajos en cola y eventos.
La decisión final suele ser una intersección: la empresa dispone de la capacidad, el límite no se ha agotado y el actor tiene el permiso requerido. Centralizar capacidades no reemplaza un modelo de roles; evita que roles y planes se mezclen. Un rol puede conceder quién administra automatizaciones, mientras la capacidad determina si la empresa puede usar automatizaciones.
Datos, auditoría y pruebas que permiten explicar decisiones
Conserve asignaciones de derechos con vigencia y precedencia, junto con eventos de consumo cuando un agregado no baste. Registre decisiones relevantes: empresa, actor o proceso, capacidad, valor evaluado, resultado, fuente y correlación de la petición. No guarde datos personales innecesarios en estos registros y establezca retención conforme a sus obligaciones.
La auditoría debe responder por qué se rechazó una acción sin obligar a leer código histórico. Es especialmente útil ante cambios comerciales, incidencias de facturación y operaciones de soporte.
Las pruebas deben incluir una matriz de capacidades y valores, límites en el borde exacto, concurrencia, cambios de plan, caducidad de excepciones y reintentos de eventos. Ejecute los mismos casos a través de HTTP, API y trabajadores en cola cuando compartan caso de uso. Añada pruebas de aislamiento para confirmar que una empresa no puede consultar ni consumir derechos de otra.
Plan gradual para centralizar una plataforma PHP existente
- Inventarie nombres de planes, condiciones, contadores y excepciones manuales en el código y operaciones.
- Elija una capacidad o límite de alto impacto y defina su semántica completa antes de migrarlo.
- Introduzca el resolvedor como fachada, inicialmente compatible con las fuentes actuales.
- Mueva los puntos de aplicación al caso de uso central, no sólo a la interfaz.
- Registre decisiones y compare el comportamiento nuevo con el anterior antes de retirar ramas antiguas.
- Migre plan por plan a asignaciones explícitas y elimine referencias comerciales del dominio.
Lista de comprobación antes de publicar un cambio
- ¿La capacidad tiene un identificador estable y una definición de negocio inequívoca?
- ¿El límite especifica unidad, alcance, periodo, concurrencia y reacción al exceso?
- ¿La regla se aplica en servidor, API y procesos asíncronos?
- ¿Roles, capacidades y contexto de empresa se validan por separado?
- ¿Los cambios de plan y las excepciones tienen vigencia, procedencia y auditoría?
- ¿Existen pruebas para el borde del límite, la revocación y el aislamiento multiempresa?
Con este modelo, el catálogo comercial puede evolucionar sin convertir cada modificación en una búsqueda de condicionales. La plataforma conserva reglas comprensibles, medibles y defendibles tanto para producto como para ingeniería.
