template-saas/docs/01-modulos/SAAS-005-plans.md

id	title	type	status	priority	module	version	created_date	updated_date
SAAS-005	Planes y Limites	Module	Published	P0	plans	1.0.0	2026-01-07	2026-01-10

SAAS-005: Planes y Limites

Metadata

• Codigo: SAAS-005
• Modulo: Plans
• Prioridad: P0
• Estado: Completado
• Fase: 2 - Billing

Descripcion

Sistema de planes y limites: definicion de planes con features y limites, verificacion de limites en runtime, y feature gating basado en plan.

Objetivos

1. Definir planes (Free, Starter, Pro, Enterprise)
2. Features por plan
3. Limites configurables
4. Verificacion en runtime
5. Feature gating

Alcance

Incluido

• 4 planes predefinidos
• Features booleanas por plan
• Limites numericos por plan
• Funciones de verificacion
• Middleware de plan

Excluido

• Planes custom por tenant
• Addons/complementos
• Overage charges

Planes Definidos

Free

price: $0/mes
features:
  - basic_dashboard: true
  - api_access: false
  - ai_assistant: false
  - webhooks: false
  - custom_branding: false
limits:
  users: 1
  storage_mb: 100
  api_calls_month: 1000

Starter ($29/mes)

price: $29/mes | $290/ano
features:
  - basic_dashboard: true
  - api_access: true
  - ai_assistant: false
  - webhooks: false
  - custom_branding: false
limits:
  users: 5
  storage_mb: 1000
  api_calls_month: 10000

Pro ($79/mes)

price: $79/mes | $790/ano
features:
  - basic_dashboard: true
  - api_access: true
  - ai_assistant: true
  - webhooks: true
  - custom_branding: false
limits:
  users: 20
  storage_mb: 10000
  api_calls_month: 100000
  ai_tokens_month: 50000

Enterprise ($199/mes)

price: $199/mes | $1990/ano
features:
  - basic_dashboard: true
  - api_access: true
  - ai_assistant: true
  - webhooks: true
  - custom_branding: true
  - sso: true
  - audit_logs: true
limits:
  users: unlimited
  storage_mb: unlimited
  api_calls_month: unlimited
  ai_tokens_month: 200000

Modelo de Datos

Tablas (schema: plans)

plans

• id, name, code, description
• price_monthly, price_yearly, currency
• features (JSONB), limits (JSONB)
• stripe_monthly_price_id, stripe_yearly_price_id
• is_active, sort_order

plan_features (opcional, para tracking)

• id, plan_id, feature_key
• enabled, config

Funciones de Verificacion

SQL Functions

-- Obtener limites del tenant
CREATE FUNCTION get_tenant_limits(p_tenant_id UUID)
RETURNS JSONB AS $$
  SELECT p.limits
  FROM subscriptions s
  JOIN plans p ON s.plan_id = p.id
  WHERE s.tenant_id = p_tenant_id
    AND s.status = 'active';
$$ LANGUAGE SQL;

-- Verificar limite
CREATE FUNCTION check_limit(
  p_tenant_id UUID,
  p_limit_key TEXT,
  p_current_value INT
) RETURNS BOOLEAN AS $$
  SELECT CASE
    WHEN (get_tenant_limits(p_tenant_id)->>p_limit_key)::INT = -1 THEN true
    ELSE p_current_value < (get_tenant_limits(p_tenant_id)->>p_limit_key)::INT
  END;
$$ LANGUAGE SQL;

Backend Service

class PlansService {
  async hasFeature(tenantId: string, feature: string): Promise<boolean> {
    const plan = await this.getTenantPlan(tenantId);
    return plan.features[feature] === true;
  }

  async checkLimit(tenantId: string, limit: string, current: number): Promise<boolean> {
    const plan = await this.getTenantPlan(tenantId);
    const max = plan.limits[limit];
    return max === -1 || current < max; // -1 = unlimited
  }
}

Endpoints API

Metodo	Endpoint	Descripcion
GET	/plans	Listar planes
GET	/plans/:code	Obtener plan
GET	/plans/current	Plan actual del tenant
GET	/plans/current/limits	Limites actuales
GET	/plans/current/usage	Uso actual

Guards y Decorators

// Guard de feature
@RequiresFeature('ai_assistant')
async askAI(question: string) {
  // Solo ejecuta si tiene feature
}

// Guard de plan minimo
@RequiresPlan('pro')
async advancedReport() {
  // Solo Pro o superior
}

// Verificacion de limite
@CheckLimit('users')
async createUser(dto: CreateUserDto) {
  // Verifica antes de crear
}

Entregables

Entregable	Estado	Archivo
plans.service.ts	Completado	modules/plans/
plan.guard.ts	Completado	guards/
Seeds de planes	Completado	seeds/prod/plans.sql
DDL plans schema	Completado	ddl/schemas/plans/

Dependencias

Depende de

• SAAS-002 (Tenants)
• SAAS-004 (Billing - para suscripcion)

Bloquea a

• SAAS-003 (Users - limite usuarios)
• SAAS-006 (AI - feature flag)
• SAAS-010 (Webhooks - feature flag)

Criterios de Aceptacion

• 4 planes creados en BD
• Features se verifican correctamente
• Limites se respetan
• Upgrade desbloquea features
• UI muestra plan actual

---

Ultima actualizacion: 2026-01-10