Arquitectura SaaS Empresarial: Decisiones que Definen el Negocio

// Middleware de multi-tenancy con tenant_id en Pool Model
// El tenant_id se propaga en el contexto de cada request

import { AsyncLocalStorage } from 'node:async_hooks';

const tenantStorage = new AsyncLocalStorage<string>();

// Middleware: extraer tenant del JWT y establecer el contexto
export const tenantMiddleware = async (req: Request, res: Response, next: NextFunction) => {
  const tenantId = req.auth?.tenantId;
  if (!tenantId) return res.status(401).json({ error: 'Tenant no identificado' });

  tenantStorage.run(tenantId, () => next());
};

// Prisma extension: añadir tenant_id automáticamente a todas las queries
export const tenantPrismaExtension = Prisma.defineExtension({
  query: {
    $allModels: {
      async findMany({ args, query }) {
        const tenantId = tenantStorage.getStore();
        if (!tenantId) throw new Error('Tenant context no establecido');
        args.where = { ...args.where, tenant_id: tenantId };
        return query(args);
      },
      async create({ args, query }) {
        const tenantId = tenantStorage.getStore();
        if (!tenantId) throw new Error('Tenant context no establecido');
        args.data = { ...args.data, tenant_id: tenantId };
        return query(args);
      },
    },
  },
});

// Registro de uso para billing por consumo con Stripe Metered Billing
async function recordApiUsage(tenantId: string, count: number): Promise<void> {
  const subscription = await db.subscription.findUnique({
    where: { tenantId },
    select: { stripeSubscriptionItemId: true }
  });

  if (!subscription?.stripeSubscriptionItemId) return;

  // Stripe acumula el uso y lo factura al final del período
  await stripe.subscriptionItems.createUsageRecord(
    subscription.stripeSubscriptionItemId,
    {
      quantity: count,
      timestamp: Math.floor(Date.now() / 1000),
      action: 'increment',  // acumular, no sobrescribir
    }
  );
}

// Llamar después de cada operación facturable
await recordApiUsage(tenantId, requestCount);

// Pipeline de onboarding de tenant nuevo — completamente automatizado
async function onboardNewTenant(signupData: SignupDto): Promise<Tenant> {
  return db.transaction(async (trx) => {
    // 1. Crear tenant y usuario admin
    const tenant = await Tenant.create({
      name: signupData.companyName,
      plan: 'trial',
      trialEndsAt: addDays(new Date(), 14),
    }, { transaction: trx });

    const adminUser = await User.create({
      tenantId: tenant.id,
      email: signupData.email,
      role: 'admin',
    }, { transaction: trx });

    // 2. Provisionar datos de ejemplo para reducir tiempo-a-valor
    await seedDemoData(tenant.id, trx);

    // 3. Crear customer en Stripe para futura conversión
    const stripeCustomer = await stripe.customers.create({
      email: signupData.email,
      name: signupData.companyName,
      metadata: { tenantId: tenant.id },
    });
    await tenant.update({ stripeCustomerId: stripeCustomer.id }, { transaction: trx });

    // 4. Enviar email de bienvenida con instrucciones
    await emailQueue.add('welcome', {
      to: signupData.email,
      tenantId: tenant.id,
      adminUserId: adminUser.id,
    });

    return tenant;
  });
}

// Sistema de entitlements para planes SaaS
const PLAN_FEATURES = {
  starter: ['api_access', 'basic_reports', 'email_support'],
  professional: ['api_access', 'advanced_reports', 'webhooks', 'priority_support', 'sso'],
  enterprise: ['api_access', 'advanced_reports', 'webhooks', 'priority_support', 'sso',
               'custom_domain', 'audit_logs', 'dedicated_support', 'sla_guarantee'],
} as const;

async function hasFeature(tenantId: string, feature: string): Promise<boolean> {
  const tenant = await getTenantWithPlan(tenantId);  // cached
  const planFeatures = PLAN_FEATURES[tenant.plan as keyof typeof PLAN_FEATURES] ?? [];
  return (planFeatures as string[]).includes(feature);
}

// En el handler de API:
if (!await hasFeature(tenantId, 'webhooks')) {
  return res.status(402).json({
    error: 'Esta función requiere el plan Professional o superior',
    upgradeUrl: '/settings/billing'
  });
}