workspace-v1/shared/modules/billing/README.md

# Billing - Core Module

**Modulo:** shared/modules/billing/
**Version:** 0.1.0
**Fecha:** 2026-01-03
**Owner:** Backend-Agent
**Estado:** desarrollo

---

## Descripcion

Modulo de facturacion compartido que provee logica de negocio para planes, pricing, invoices y metricas de uso. Trabaja en conjunto con el modulo de payments para la parte transaccional.

---

## Instalacion

### Prerequisitos

```bash
# El modulo de billing depende de payments
npm install stripe
```

### Configuracion de Paths

```json
{
  "compilerOptions": {
    "paths": {
      "@shared/modules/*": ["../../shared/modules/*"]
    }
  }
}
```

---

## API Publica (Planificada)

### Servicios

| Servicio | Descripcion |
|----------|-------------|
| `PlanService` | Gestion de planes y pricing |
| `InvoiceService` | Generacion y gestion de facturas |
| `UsageService` | Tracking de metricas de uso |
| `QuotaService` | Verificacion de limites y cuotas |

### Tipos

```typescript
interface Plan {
  id: string;
  name: string;
  description: string;
  price: number;
  currency: string;
  interval: 'monthly' | 'yearly';
  features: PlanFeature[];
  limits: PlanLimits;
  isActive: boolean;
}

interface PlanLimits {
  users: number;
  storage: number;  // GB
  apiCalls: number; // per month
  projects: number;
}

interface Invoice {
  id: string;
  customerId: string;
  subscriptionId: string;
  amount: number;
  currency: string;
  status: 'draft' | 'open' | 'paid' | 'void';
  dueDate: Date;
  paidAt?: Date;
  lineItems: InvoiceLineItem[];
}

interface UsageRecord {
  subscriptionId: string;
  metric: string;
  quantity: number;
  timestamp: Date;
}
```

---

## Ejemplos de Uso

### Ejemplo 1: Verificar Cuota

```typescript
import { QuotaService } from '@shared/modules/billing';

@Injectable()
export class ProjectService {
  constructor(private quota: QuotaService) {}

  async createProject(orgId: string, data: CreateProjectDto) {
    // Verificar si la organizacion puede crear mas proyectos
    const canCreate = await this.quota.check(orgId, 'projects', 1);

    if (!canCreate) {
      throw new QuotaExceededException('Project limit reached');
    }

    // Crear proyecto...
    const project = await this.projectRepo.save(data);

    // Incrementar uso
    await this.quota.increment(orgId, 'projects', 1);

    return project;
  }
}
```

### Ejemplo 2: Obtener Plan Actual

```typescript
import { PlanService, UsageService } from '@shared/modules/billing';

@Controller('billing')
export class BillingController {
  constructor(
    private plans: PlanService,
    private usage: UsageService,
  ) {}

  @Get('current-plan')
  async getCurrentPlan(@CurrentOrg() orgId: string) {
    const subscription = await this.plans.getActiveSubscription(orgId);
    const plan = await this.plans.getPlan(subscription.planId);
    const usage = await this.usage.getCurrentPeriodUsage(subscription.id);

    return {
      plan,
      subscription,
      usage,
      limits: plan.limits,
    };
  }
}
```

---

## Dependencias

### Internas

| Modulo | Uso |
|--------|-----|
| `@shared/modules/payments` | Transacciones |
| `@shared/modules/utils` | Formateo |

### Externas (npm)

| Paquete | Version | Uso |
|---------|---------|-----|
| `stripe` | `^14.0` | Billing API |

---

## Estado Actual

```markdown
- [ ] PlanService
- [ ] InvoiceService
- [ ] UsageService
- [ ] QuotaService
- [ ] Integracion con payments
- [ ] Metricas de uso
- [ ] Tests unitarios
```

---

## Changelog

### v0.1.0 (2026-01-03)
- Estructura inicial
- README con planificacion

---

**Modulo:** shared/modules/billing/ | **Owner:** Backend-Agent