# Diseño de Dashboards por Rol - Credify Go

## Resumen Ejecutivo

Este documento define la arquitectura y KPIs para los dashboards de Credify Go, separando claramente las responsabilidades por rol y alineando las métricas con estándares de la industria de microcréditos.

---

## 1. Super Admin (Nivel Plataforma SaaS)

### Propósito
Visión global del negocio SaaS. **NO debe ver datos operativos de créditos**.

### KPIs Principales

| KPI | Fórmula/Fuente | Actualización |
|-----|----------------|---------------|
| **Companies Activas** | `companies.where(status: active).count` | Real-time |
| **Companies Inactivas/Suspendidas** | `companies.where(status: [inactive, suspended]).count` | Real-time |
| **MRR (Monthly Recurring Revenue)** | `Σ(subscription.plan.price / billing_cycle_months)` donde status=active | Diario |
| **ARR (Annual Recurring Revenue)** | `MRR × 12` | Diario |
| **Suscripciones por Estado** | Breakdown: active, trial, grace, expired, canceled | Real-time |
| **Suscripciones por Plan** | Group by plan_id con count | Real-time |
| **Tasa de Conversión Trial→Paid** | `(trials_converted / trials_started) × 100` últimos 30 días | Diario |
| **Churn Rate** | `(canceled_subscriptions / active_start_period) × 100` mensual | Mensual |
| **Uso Promedio de Límites** | Avg de `getUsagePercentage()` por plan | Cada 6 horas |
| **Solicitudes Pendientes** | `subscription_requests.where(status: pending).count` | Real-time |

### Widgets Propuestos

```
┌─────────────────────────────────────────────────────────────────┐
│ HEADER: Platform Stats                                          │
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐        │
│ │ Companies │ │    MRR    │ │    ARR    │ │  Churn %  │        │
│ │    125    │ │  $4.5M    │ │  $54M     │ │   2.3%    │        │
│ │  +5 este  │ │  +12%     │ │           │ │  ↓ 0.5%   │        │
│ │    mes    │ │  vs prev  │ │           │ │           │        │
│ └───────────┘ └───────────┘ └───────────┘ └───────────┘        │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────┐ ┌─────────────────────────────────┐
│ Suscripciones por Estado    │ │ Crecimiento MRR (12 meses)      │
│ ┌─────────────────────────┐ │ │ [LINE CHART]                    │
│ │ ● Active      89 (71%)  │ │ │                          ╱──    │
│ │ ● Trial       15 (12%)  │ │ │                      ╱──╱       │
│ │ ● Grace        8  (6%)  │ │ │                  ╱──╱           │
│ │ ● Expired      7  (6%)  │ │ │              ╱──╱               │
│ │ ● Canceled     6  (5%)  │ │ │ ────────╱──╱                    │
│ └─────────────────────────┘ │ │ Ene Feb Mar Abr May Jun Jul...  │
└─────────────────────────────┘ └─────────────────────────────────┘

┌─────────────────────────────┐ ┌─────────────────────────────────┐
│ Distribución por Plan       │ │ Uso de Límites por Plan         │
│ [PIE/DONUT CHART]           │ │ ┌─────────────────────────────┐ │
│      ┌────┐                 │ │ │ Starter    ████████░░  78%  │ │
│    ╱│Basic│╲                │ │ │ Growth     █████░░░░░  52%  │ │
│   ╱ └────┘ ╲                │ │ │ Business   ███░░░░░░░  34%  │ │
│  │ Pro │ Ent│               │ │ │ Enterprise ██░░░░░░░░  21%  │ │
│   ╲       ╱                 │ │ └─────────────────────────────┘ │
└─────────────────────────────┘ └─────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│ Solicitudes de Suscripción Pendientes                           │
│ ┌─────────┬──────────────┬──────────┬──────────┬──────────────┐│
│ │ Company │ Tipo         │ Plan     │ Fecha    │ Acciones     ││
│ ├─────────┼──────────────┼──────────┼──────────┼──────────────┤│
│ │ ABC Ltd │ Upgrade      │ Pro→Ent  │ Hace 2d  │ [Ver] [Apr]  ││
│ │ XYZ Inc │ Limit Change │ +50 cred │ Hace 1d  │ [Ver] [Apr]  ││
│ └─────────┴──────────────┴──────────┴──────────┴──────────────┘│
└─────────────────────────────────────────────────────────────────┘
```

### Queries/Services Necesarios

```php
// app/Services/Platform/SaaSMetricsService.php
class SaaSMetricsService
{
    public function getMRR(): Money;
    public function getARR(): Money;
    public function getChurnRate(Carbon $period): float;
    public function getTrialConversionRate(int $days = 30): float;
    public function getSubscriptionsByStatus(): Collection;
    public function getSubscriptionsByPlan(): Collection;
    public function getCompanyStats(): array;
    public function getAverageUsageByPlan(): Collection;
    public function getMRRGrowthTrend(int $months = 12): Collection;
}
```

### NO Mostrar
- ❌ Créditos
- ❌ Pagos
- ❌ Caja
- ❌ Clientes de companies
- ❌ Collectors

---

## 2. Admin de Company (Nivel Negocio)

### Propósito
Visión estratégica y financiera del negocio de microcréditos. Decisiones de alto nivel.

### KPIs Principales

| KPI | Fórmula | Categoría |
|-----|---------|-----------|
| **Capital Colocado (Cartera Activa)** | `Σ credits.remaining_balance WHERE status IN (active, delayed, overdue)` | Cartera |
| **Capital Recuperado (Mes)** | `Σ payments.applied_amount WHERE month = current` | Cartera |
| **Cartera en Riesgo (PAR 30)** | `(Σ remaining_balance WHERE days_overdue > 30) / total_portfolio × 100` | Riesgo |
| **Índice de Morosidad** | `(credits.overdue.count / credits.active.count) × 100` | Riesgo |
| **Caja Actual** | `opening_balance + Σ incomes(affects_cash) - Σ expenses(affects_cash)` | Liquidez |
| **Ganancia Neta (Mes)** | `Σ incomes(affects_profit) - Σ expenses(affects_profit)` | Rentabilidad |
| **Intereses Ganados (Mes)** | `Σ incomes WHERE category = loan_payment_interest` | Rentabilidad |
| **ROI de Cartera** | `(interest_earned / capital_deployed) × 100` anualizado | Rentabilidad |
| **Ticket Promedio** | `Σ credits.amount / credits.count` últimos 30 días | Operación |
| **Volumen Desembolsado (Mes)** | `Σ credits.amount WHERE created_at IN month` | Operación |
| **Tasa de Recuperación** | `capital_recovered / capital_due × 100` del mes | Eficiencia |

### Widgets Propuestos

```
┌─────────────────────────────────────────────────────────────────┐
│ HEADER: KPIs Financieros                                        │
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐        │
│ │  Cartera  │ │   Caja    │ │ Ganancia  │ │ Morosidad │        │
│ │  Activa   │ │  Actual   │ │   Neta    │ │   (PAR)   │        │
│ │ $245.5M   │ │  $32.1M   │ │  $8.2M    │ │   4.7%    │        │
│ │  +12%     │ │   ↑ 5%    │ │  +18%     │ │  ↓ 0.3%   │        │
│ └───────────┘ └───────────┘ └───────────┘ └───────────┘        │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│ SECOND ROW: Métricas de Cartera                                 │
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐        │
│ │ Créditos  │ │  Capital  │ │ Intereses │ │   Tasa    │        │
│ │  Activos  │ │Recuperado │ │  Ganados  │ │Recuperac. │        │
│ │    847    │ │  $18.3M   │ │  $12.1M   │ │   94.2%   │        │
│ │  +23 sem  │ │  este mes │ │  este mes │ │  vs 92%   │        │
│ └───────────┘ └───────────┘ └───────────┘ └───────────┘        │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────┐ ┌─────────────────────────────────┐
│ Flujo de Caja (30 días)     │ │ Composición de Cartera          │
│ [AREA CHART]                │ │ [STACKED BAR]                   │
│     ╱╲    ╱╲                │ │                                 │
│    ╱  ╲  ╱  ╲ ←Ingresos     │ │ ████████████████░░░░ Al día 78% │
│ ──╱────╲╱────╲──            │ │ ████░░░░░░░░░░░░░░░░ Mora<30 12%│
│   ╲    ╱╲    ╱ ←Egresos     │ │ ██░░░░░░░░░░░░░░░░░░ Mora>30 7% │
│    ╲  ╱  ╲  ╱               │ │ █░░░░░░░░░░░░░░░░░░░ Vencido 3% │
└─────────────────────────────┘ └─────────────────────────────────┘

┌─────────────────────────────┐ ┌─────────────────────────────────┐
│ Ingresos vs Egresos (6m)    │ │ Aging de Cartera Vencida        │
│ [BAR CHART COMPARATIVO]     │ │ ┌─────────────────────────────┐ │
│ █ Ingresos  ░ Egresos       │ │ │ 1-7 días    $2.1M   (42%)   │ │
│                             │ │ │ 8-15 días   $1.4M   (28%)   │ │
│ Sep ████████ ░░░░           │ │ │ 16-30 días  $0.8M   (16%)   │ │
│ Oct █████████░░░░░          │ │ │ 31-60 días  $0.5M   (10%)   │ │
│ Nov ██████████░░░░░         │ │ │ >60 días    $0.2M   (4%)    │ │
│ Dic █████████████░░░░░░░    │ │ └─────────────────────────────┘ │
└─────────────────────────────┘ └─────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│ Créditos en Mora (Top 10 por Monto)                             │
│ ┌────────┬──────────┬──────────┬─────────┬──────────┬─────────┐│
│ │Cliente │ Monto    │ Vencido  │ Días    │ Últ Pago │ Acción  ││
│ ├────────┼──────────┼──────────┼─────────┼──────────┼─────────┤│
│ │J. Pérez│ $2,500K  │ $450K    │ 23      │ 15-Dic   │ [Ver]   ││
│ │M. López│ $1,800K  │ $320K    │ 18      │ 20-Dic   │ [Ver]   ││
│ └────────┴──────────┴──────────┴─────────┴──────────┴─────────┘│
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│ Rendimiento por Collector                                       │
│ ┌──────────┬──────────┬──────────┬──────────┬─────────────────┐│
│ │ Collector│ Cartera  │ Cobrado  │ Mora %   │ Cumplimiento    ││
│ ├──────────┼──────────┼──────────┼──────────┼─────────────────┤│
│ │ Carlos G │ $45.2M   │ $3.8M    │ 2.1%     │ ████████░░ 95%  ││
│ │ Ana M    │ $38.7M   │ $3.2M    │ 3.4%     │ ███████░░░ 87%  ││
│ │ Pedro L  │ $41.1M   │ $2.9M    │ 5.8%     │ ██████░░░░ 72%  ││
│ └──────────┴──────────┴──────────┴──────────┴─────────────────┘│
└─────────────────────────────────────────────────────────────────┘
```

### Queries/Services Necesarios

```php
// app/Services/Dashboard/AdminDashboardService.php
class AdminDashboardService
{
    public function getPortfolioSummary(int $companyId): array;
    public function getCashPosition(int $companyId): Money;
    public function getNetProfit(int $companyId, Carbon $from, Carbon $to): Money;
    public function getInterestEarned(int $companyId, Carbon $from, Carbon $to): Money;
    public function getDelinquencyMetrics(int $companyId): array; // PAR1, PAR7, PAR30, PAR60, PAR90
    public function getCashFlowTrend(int $companyId, int $days = 30): Collection;
    public function getPortfolioComposition(int $companyId): array;
    public function getAgingReport(int $companyId): Collection;
    public function getCollectorPerformance(int $companyId): Collection;
    public function getRecoveryRate(int $companyId, Carbon $from, Carbon $to): float;
    public function getROI(int $companyId, Carbon $from, Carbon $to): float;
}
```

---

## 3. Supervisor (Nivel Gestión de Equipo)

### Propósito
Gestión operativa del equipo de collectors. **NO ve información financiera sensible** (ganancias, caja global).

### KPIs Principales

| KPI | Fórmula | Frecuencia |
|-----|---------|------------|
| **Collectors a Cargo** | `users.where(role: collector, supervisor_id: current).count` | Real-time |
| **Cobros del Día** | `Σ payments.amount WHERE date = today AND collector IN team` | Real-time |
| **Meta Diaria** | Configurada por admin | Diario |
| **% Cumplimiento Meta** | `(cobros_día / meta_día) × 100` | Real-time |
| **Cobros de la Semana** | `Σ payments WHERE week = current AND collector IN team` | Real-time |
| **Créditos por Collector** | Group by collector_user_id | Real-time |
| **Mora por Collector** | `(overdue_credits / total_credits) × 100` por collector | Diario |
| **Visitas Realizadas** | Si hay tracking de visitas | Real-time |
| **Promedio de Cobro** | `total_cobrado / num_pagos` por collector | Semanal |

### Widgets Propuestos

```
┌─────────────────────────────────────────────────────────────────┐
│ HEADER: Resumen del Equipo Hoy                                  │
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐        │
│ │ Collectors│ │ Cobrado   │ │   Meta    │ │Cumplimien.│        │
│ │  Activos  │ │   Hoy     │ │   Hoy     │ │   Meta    │        │
│ │    8/10   │ │  $4.2M    │ │  $5.0M    │ │   84%     │        │
│ │ 2 inactiv │ │  ↑ vs ayer│ │           │ │ ████████░░│        │
│ └───────────┘ └───────────┘ └───────────┘ └───────────┘        │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│ Rendimiento por Collector (Hoy)                                 │
│ ┌──────────┬──────────┬──────────┬──────────┬─────────────────┐│
│ │ Collector│ Cobrado  │ # Pagos  │ Meta     │ Progreso        ││
│ ├──────────┼──────────┼──────────┼──────────┼─────────────────┤│
│ │ 🟢 Carlos│ $780K    │ 12       │ $700K    │ ██████████ 111% ││
│ │ 🟢 Ana   │ $650K    │ 9        │ $650K    │ █████████░ 100% ││
│ │ 🟡 Pedro │ $420K    │ 6        │ $600K    │ ███████░░░ 70%  ││
│ │ 🔴 María │ $180K    │ 3        │ $500K    │ ████░░░░░░ 36%  ││
│ └──────────┴──────────┴──────────┴──────────┴─────────────────┘│
│ 🟢 Sobre meta  🟡 En rango  🔴 Bajo rendimiento                 │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────┐ ┌─────────────────────────────────┐
│ Cobros por Día (Semana)     │ │ Mora por Collector              │
│ [BAR CHART]                 │ │ ┌─────────────────────────────┐ │
│                             │ │ │ Carlos  ██░░░░░░░░  2.1%    │ │
│ Lun ████████                │ │ │ Ana     ███░░░░░░░  3.4%    │ │
│ Mar █████████               │ │ │ Pedro   █████░░░░░  5.8%    │ │
│ Mie ███████████             │ │ │ María   ████████░░  8.2%    │ │
│ Jue ████████████ ←Hoy       │ │ │ Luis    ██████░░░░  6.1%    │ │
│ Vie [pendiente]             │ │ └─────────────────────────────┘ │
└─────────────────────────────┘ └─────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│ 🚨 Alertas de Rendimiento                                       │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ ⚠️ María López: 3 días consecutivos bajo meta (<50%)        │ │
│ │ ⚠️ Pedro García: Mora aumentó 2.3% esta semana              │ │
│ │ ⚠️ 5 créditos sin gestión hace >7 días (Zona Norte)         │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│ Créditos Vencidos por Collector (Requieren Gestión)             │
│ ┌──────────┬──────────┬──────────┬──────────┬─────────────────┐│
│ │ Collector│ Vencidos │ Monto    │ Más Antig│ Acción          ││
│ ├──────────┼──────────┼──────────┼──────────┼─────────────────┤│
│ │ María    │ 8        │ $1.2M    │ 23 días  │ [Ver Detalle]   ││
│ │ Pedro    │ 5        │ $0.8M    │ 15 días  │ [Ver Detalle]   ││
│ │ Luis     │ 4        │ $0.6M    │ 12 días  │ [Ver Detalle]   ││
│ └──────────┴──────────┴──────────┴──────────┴─────────────────┘│
└─────────────────────────────────────────────────────────────────┘
```

### Queries/Services Necesarios

```php
// app/Services/Dashboard/SupervisorDashboardService.php
class SupervisorDashboardService
{
    public function getTeamSummary(int $supervisorId): array;
    public function getCollectorPerformanceToday(int $supervisorId): Collection;
    public function getCollectorPerformanceWeek(int $supervisorId): Collection;
    public function getDelinquencyByCollector(int $supervisorId): Collection;
    public function getDailyCollectionTrend(int $supervisorId, int $days = 7): Collection;
    public function getPerformanceAlerts(int $supervisorId): Collection;
    public function getOverdueCreditsbyCollector(int $supervisorId): Collection;
    public function getGoalCompletion(int $supervisorId): array;
}
```

### NO Mostrar
- ❌ Ganancias netas
- ❌ Caja total
- ❌ Intereses ganados
- ❌ ROI
- ❌ Datos de otros equipos

---

## 4. Collector (PWA - Mobile First)

### Propósito
Operación diaria de cobranza. Información inmediata y accionable.

### KPIs Principales

| KPI | Fórmula | Prioridad Visual |
|-----|---------|------------------|
| **Cuotas Pendientes Hoy** | `installments.where(due_date: today, status: pending)` | ALTA |
| **Monto por Cobrar Hoy** | `Σ installments.balance_due WHERE due_date = today` | ALTA |
| **Cobrado Hoy** | `Σ payments WHERE collector = me AND date = today` | ALTA |
| **Créditos Asignados** | `credits.where(collector_user_id: me, status: active)` | MEDIA |
| **Cuotas Vencidas** | `installments.where(status: overdue, collector: me)` | ALTA |
| **Cobrado Esta Semana** | `Σ payments WHERE week = current` | MEDIA |
| **Cobrado Este Mes** | `Σ payments WHERE month = current` | BAJA |
| **Mi Meta (si aplica)** | Configurada por supervisor | MEDIA |

### Diseño PWA (Mobile-First)

```
┌─────────────────────────────────┐
│ ☰  Credify Go          🔔 (3)  │
│─────────────────────────────────│
│                                 │
│  Buenos días, Carlos 👋        │
│  Martes, 5 de Febrero          │
│                                 │
│ ┌─────────────────────────────┐ │
│ │     💰 COBRADO HOY          │ │
│ │        $780,000             │ │
│ │     ████████████░░ 78%      │ │
│ │     Meta: $1,000,000        │ │
│ └─────────────────────────────┘ │
│                                 │
│ ┌────────────┐ ┌──────────────┐ │
│ │ 📋 Por     │ │ ⚠️ Cuotas   │ │
│ │   Cobrar   │ │   Vencidas  │ │
│ │            │ │              │ │
│ │    12      │ │     5       │ │
│ │  $2.4M     │ │   $890K     │ │
│ └────────────┘ └──────────────┘ │
│                                 │
│ ┌────────────┐ ┌──────────────┐ │
│ │ 📊 Semana  │ │ 📈 Mes      │ │
│ │            │ │              │ │
│ │  $3.2M     │ │  $12.8M     │ │
│ │  +15%      │ │  +8%        │ │
│ └────────────┘ └──────────────┘ │
│                                 │
│─────────────────────────────────│
│ 📋 COBROS DE HOY               │
│─────────────────────────────────│
│ ┌─────────────────────────────┐ │
│ │ 🔴 Juan Pérez               │ │
│ │ Cuota #5 · Vencida 3 días   │ │
│ │ $185,000         [Cobrar →] │ │
│ └─────────────────────────────┘ │
│ ┌─────────────────────────────┐ │
│ │ 🟡 María García             │ │
│ │ Cuota #8 · Vence hoy        │ │
│ │ $220,000         [Cobrar →] │ │
│ └─────────────────────────────┘ │
│ ┌─────────────────────────────┐ │
│ │ 🟢 Pedro López              │ │
│ │ Cuota #3 · Próxima          │ │
│ │ $150,000         [Cobrar →] │ │
│ └─────────────────────────────┘ │
│                                 │
│         [Ver Todos →]          │
│                                 │
│─────────────────────────────────│
│  🏠    📋    ➕    👤    ⚙️   │
│ Home  Lista  Pago  Perfil  Más │
└─────────────────────────────────┘
```

### API Endpoints PWA

```php
// Existentes a optimizar
GET /pwa/dashboard          // Resumen completo
GET /pwa/collections        // Lista de cobros del día
GET /pwa/credits           // Créditos asignados

// Nuevos sugeridos
GET /pwa/dashboard/summary  // Solo KPIs (lightweight)
GET /pwa/dashboard/today    // Cobros de hoy con priorización
GET /pwa/stats/weekly       // Stats semanales
GET /pwa/stats/monthly      // Stats mensuales
```

---

## 5. Arquitectura Técnica Recomendada

### Estructura de Services

```
app/Services/
├── Dashboard/
│   ├── AdminDashboardService.php      # KPIs para Admin
│   ├── SupervisorDashboardService.php # KPIs para Supervisor
│   └── CollectorDashboardService.php  # KPIs para Collector/PWA
├── Platform/
│   └── SaaSMetricsService.php         # KPIs para Super Admin
├── Metrics/
│   ├── PortfolioMetricsService.php    # Cálculos de cartera
│   ├── DelinquencyMetricsService.php  # Cálculos de mora (PAR)
│   ├── CashFlowMetricsService.php     # Flujo de caja
│   └── CollectionMetricsService.php   # Métricas de cobranza
└── Cache/
    └── DashboardCacheService.php      # Gestión de cache
```

### Estrategia de Caching

| Métrica | TTL | Invalidación |
|---------|-----|--------------|
| MRR/ARR | 1 hora | Al cambiar suscripción |
| Cartera Activa | 5 min | Al crear/pagar crédito |
| Caja | 5 min | Al registrar income/expense |
| Cobros del Día | 1 min | Al registrar pago |
| Mora por Collector | 15 min | Al cambiar status crédito |
| Stats Semanales | 30 min | Scheduled |

```php
// Ejemplo de implementación
class DashboardCacheService
{
    public function getOrCompute(string $key, Closure $compute, int $ttl = 300): mixed
    {
        return Cache::tags(['dashboard', "company:{$companyId}"])
            ->remember($key, $ttl, $compute);
    }

    public function invalidateCompany(int $companyId): void
    {
        Cache::tags(["company:{$companyId}"])->flush();
    }
}
```

### Widgets Filament Propuestos

```
app/Filament/Widgets/
├── SuperAdmin/
│   ├── PlatformStatsWidget.php
│   ├── SubscriptionsByStatusChart.php
│   ├── MRRGrowthChart.php
│   ├── PlanUsageWidget.php
│   └── PendingRequestsTable.php
├── Admin/
│   ├── FinancialKPIsWidget.php
│   ├── PortfolioKPIsWidget.php
│   ├── CashFlowChart.php
│   ├── PortfolioCompositionChart.php
│   ├── AgingReportWidget.php
│   ├── TopOverdueCreditsTable.php
│   └── CollectorPerformanceTable.php
├── Supervisor/
│   ├── TeamSummaryWidget.php
│   ├── CollectorPerformanceTodayTable.php
│   ├── WeeklyCollectionChart.php
│   ├── DelinquencyByCollectorWidget.php
│   ├── PerformanceAlertsWidget.php
│   └── OverdueByCollectorTable.php
└── Shared/
    └── (componentes reutilizables)
```

---

## 6. Orden de Implementación Sugerido

### Fase 1: Fundamentos (1-2 semanas)
1. ✅ Crear estructura de Services (`Dashboard/`, `Platform/`, `Metrics/`)
2. ✅ Implementar `PortfolioMetricsService` (base para varios dashboards)
3. ✅ Implementar `DelinquencyMetricsService` (PAR calculations)
4. ✅ Implementar `DashboardCacheService`
5. ✅ Crear tests unitarios para services

### Fase 2: Super Admin Dashboard (1 semana)
1. Implementar `SaaSMetricsService`
2. Crear widgets de Super Admin
3. Remover widgets operativos del dashboard Super Admin
4. Tests de integración

### Fase 3: Admin Dashboard (1-2 semanas)
1. Implementar `AdminDashboardService`
2. Refactorizar widgets existentes
3. Crear nuevos widgets (Aging, CashFlow, ROI)
4. Tests de integración

### Fase 4: Supervisor Dashboard (1 semana)
1. Implementar `SupervisorDashboardService`
2. Crear widgets de equipo
3. Sistema de alertas de rendimiento
4. Tests de integración

### Fase 5: Collector PWA (1-2 semanas)
1. Implementar `CollectorDashboardService`
2. Optimizar endpoints PWA existentes
3. Crear nuevos endpoints de stats
4. Rediseñar HomeView.vue con nuevos KPIs
5. Tests E2E

### Fase 6: Polish & Performance (1 semana)
1. Optimización de queries (indexes, eager loading)
2. Ajuste de estrategia de cache
3. Dashboard de monitoring
4. Documentación

---

## 7. Riesgos y Errores Comunes a Evitar

### ❌ Errores Críticos

| Error | Consecuencia | Prevención |
|-------|--------------|------------|
| **No excluir parent credits** | KPIs inflados (doble conteo) | Siempre usar `->leafCredits()` o `->whereDoesntHave('children')` |
| **No filtrar por company_id** | Data leak entre tenants | Usar `MultiTenantScope` en todos los queries |
| **Calcular mora incorrectamente** | Decisiones erróneas | Usar estándar PAR (Portfolio at Risk) |
| **Cache sin invalidación** | Datos desactualizados | Implementar eventos de invalidación |
| **N+1 en widgets** | Performance degradada | Eager loading y queries optimizados |

### ⚠️ Errores Comunes

| Error | Solución |
|-------|----------|
| Mezclar montos de diferentes monedas | Siempre trabajar en la moneda base de la company |
| No considerar timezone | Usar `company.timezone` para cálculos de "hoy" |
| Mostrar decimales inconsistentes | Formatear siempre con `Number::currency()` |
| Queries pesados en tiempo real | Precalcular y cachear métricas pesadas |
| No manejar division by zero | Validar denominadores antes de dividir |

### 🔒 Consideraciones de Seguridad

```php
// SIEMPRE validar acceso antes de mostrar datos
public function getPortfolioSummary(int $companyId): array
{
    $user = auth()->user();

    // Super Admin puede ver cualquier company
    if (!$user->isSuperAdmin() && $user->company_id !== $companyId) {
        throw new AuthorizationException('No autorizado');
    }

    // ... resto del código
}
```

### 📊 Métricas de Industria (Referencias)

Para alinear con estándares de microfinanzas:

| Métrica | Fórmula Estándar | Benchmark Saludable |
|---------|------------------|---------------------|
| **PAR 30** | Cartera >30 días mora / Cartera Total | < 5% |
| **PAR 90** | Cartera >90 días mora / Cartera Total | < 2% |
| **Write-off Ratio** | Castigos / Cartera Promedio | < 1% anual |
| **Collection Rate** | Cobrado / Programado del período | > 95% |
| **Operating Expense Ratio** | Gastos Op / Cartera Promedio | < 15% |

---

## 8. Checklist de Implementación

### Por cada Dashboard:

- [ ] Service implementado con todos los métodos
- [ ] Tests unitarios para cada método del service
- [ ] Widgets Filament creados
- [ ] Cache implementado con invalidación
- [ ] Filtrado por company_id verificado
- [ ] Parent credits excluidos
- [ ] Permisos de rol verificados
- [ ] Responsive en todas las resoluciones
- [ ] Datos formateados consistentemente
- [ ] Tooltips/ayudas para métricas complejas
- [ ] Loading states implementados
- [ ] Error handling implementado

---

## Conclusión

Este diseño separa claramente las responsabilidades:

- **Super Admin**: Gestiona el SaaS, no los créditos
- **Admin**: Visión financiera estratégica del negocio
- **Supervisor**: Gestión operativa del equipo
- **Collector**: Ejecución diaria de cobranza

La arquitectura de services permite reutilizar lógica entre Filament y PWA sin duplicación, mientras que la estrategia de cache garantiza performance sin sacrificar precisión.