# US-MGN004-004: Subscripciones y Limites

## Identificacion

| Campo | Valor |
|-------|-------|
| **ID** | US-MGN004-004 |
| **Modulo** | MGN-004 Tenants |
| **RF Relacionado** | RF-TENANT-004 |
| **Prioridad** | P1 - Alta |
| **Story Points** | 13 |
| **Sprint** | TBD |

---

## Historia de Usuario

**Como** Tenant Admin
**Quiero** gestionar la subscripcion de mi organizacion y ver los limites de uso
**Para** controlar los costos y asegurar que tengo los recursos necesarios

---

## Criterios de Aceptacion

### AC-001: Ver subscripcion actual

```gherkin
Given soy Tenant Admin autenticado
  And tengo plan Professional activo
When accedo a GET /api/v1/tenant/subscription
Then veo:
  | plan | Professional |
  | price | $99 USD/mes |
  | status | active |
  | nextRenewal | 01/01/2026 |
  And veo uso actual vs limites
```

### AC-002: Ver uso de recursos

```gherkin
Given soy Tenant Admin con plan Professional (50 usuarios, 25GB)
  And tengo 35 usuarios activos y 18GB usado
When consulto GET /api/v1/tenant/subscription/usage
Then veo:
  | recurso | actual | limite | porcentaje |
  | usuarios | 35 | 50 | 70% |
  | storage | 18GB | 25GB | 72% |
  | apiCalls | 5000 | 50000 | 10% |
```

### AC-003: Bloqueo por limite de usuarios

```gherkin
Given tenant con plan Starter (10 usuarios)
  And 10 usuarios activos (100%)
When Admin intenta crear usuario #11
Then el sistema responde con status 402
  And el mensaje indica limite alcanzado
  And sugiere planes con mayor limite
```

### AC-004: Bloqueo por modulo no incluido

```gherkin
Given tenant con plan Starter (sin CRM)
When usuario intenta GET /api/v1/crm/contacts
Then el sistema responde con status 402
  And el mensaje indica modulo no disponible
  And sugiere planes que incluyen CRM
```

### AC-005: Ver planes disponibles

```gherkin
Given soy usuario autenticado
When accedo a GET /api/v1/subscription/plans
Then veo lista de planes publicos
  And cada plan muestra: nombre, precio, limites, features
  And puedo comparar con mi plan actual
```

### AC-006: Upgrade de plan

```gherkin
Given tenant en Starter ($29/mes) al dia 15 del mes
When solicito upgrade a Professional ($99/mes)
Then sistema calcula prorrateo: $35 (15 dias de diferencia)
  And proceso pago de $35
  And plan cambia inmediatamente a Professional
  And nuevos limites aplican de inmediato
```

### AC-007: Cancelar subscripcion

```gherkin
Given soy Tenant Admin con subscripcion activa
When solicito cancelar subscripcion
Then sistema muestra encuesta de salida
  And confirmo cancelacion
  And subscripcion se marca cancel_at_period_end = true
  And acceso continua hasta fin de periodo pagado
```

### AC-008: Trial expira

```gherkin
Given tenant en Trial de 14 dias
When pasan los 14 dias sin subscribirse
Then estado cambia a "trial_expired"
  And usuarios no pueden acceder (excepto admin para subscribirse)
  And datos se conservan
```

### AC-009: Verificar limite antes de accion

```gherkin
Given endpoint que crea usuarios
  And tiene decorador @CheckLimit('users')
When se ejecuta la accion
Then LimitGuard verifica limite automaticamente
  And si excede, retorna 402 antes de ejecutar logica
```

### AC-010: Ver historial de facturas

```gherkin
Given soy Tenant Admin autenticado
When accedo a GET /api/v1/tenant/invoices
Then veo lista de facturas:
  | fecha | concepto | monto | estado |
  | 01/12/2025 | Professional - Dic | $99.00 | Pagado |
  And puedo descargar PDF de cada factura
```

---

## Tareas Tecnicas

| ID | Tarea | Estimacion |
|----|-------|------------|
| T-001 | Crear entidades Plan, Subscription, Invoice | 2 SP |
| T-002 | Implementar SubscriptionsService | 3 SP |
| T-003 | Implementar LimitGuard | 2 SP |
| T-004 | Implementar ModuleGuard | 1 SP |
| T-005 | Implementar TenantUsageService | 2 SP |
| T-006 | Crear endpoints de subscripcion | 2 SP |
| T-007 | Tests unitarios | 2 SP |
| **Total** | | **14 SP** |

---

## Notas de Implementacion

### Decorador CheckLimit

```typescript
@Post()
@CheckLimit('users')
create(@Body() dto: CreateUserDto) { }
```

### Decorador CheckModule

```typescript
@Get()
@CheckModule('crm')
findAllContacts() { }
```

### Response 402 Payment Required

```json
{
  "statusCode": 402,
  "error": "Payment Required",
  "message": "Limite de usuarios alcanzado (10/10)",
  "upgradeOptions": [
    { "planId": "...", "name": "Professional", "newLimit": 50 }
  ]
}
```

---

## Mockup de Referencia

Ver RF-TENANT-004.md seccion Mockup.

---

## Dependencias

| Tipo | Descripcion |
|------|-------------|
| Backend | Tenants y Settings (US-MGN004-001, US-MGN004-002) |
| Payment | Integracion con Stripe/PayPal (futuro) |
| Scheduler | Jobs para renovacion y notificaciones |

---

## Definition of Done

- [ ] Planes y subscripciones funcionando
- [ ] LimitGuard bloqueando excesos
- [ ] ModuleGuard verificando acceso a modulos
- [ ] Upgrade/downgrade funcionando
- [ ] Calculo de prorrateo correcto
- [ ] Historial de facturas visible
- [ ] Tests unitarios con >80% coverage