template-saas/docs/05-frontend/FRONTEND-ROUTING.md

# Frontend Routing - Template SaaS

**Versión:** 1.0.0
**Actualizado:** 2026-01-25
**Router:** React Router DOM v7.1.1

---

## Arquitectura de Routing

El sistema de routing está basado en **React Router v6/7** con guards de protección para controlar el acceso a las rutas según el estado de autenticación y rol del usuario.

### Archivo Principal
`apps/frontend/src/router/index.tsx`

---

## Guards de Protección

| Guard | Descripción | Redirección |
|-------|-------------|-------------|
| **GuestRoute** | Solo usuarios no autenticados | → `/dashboard` si está autenticado |
| **ProtectedRoute** | Requiere autenticación | → `/auth/login` si no está autenticado |
| **SuperadminRoute** | Requiere rol `superadmin` | → `/dashboard` si no tiene rol |

---

## Mapa de Rutas Completo

### 1. Rutas Públicas

| Ruta | Componente | Guard | Descripción |
|------|------------|-------|-------------|
| `/` | Navigate | - | Redirect a `/auth/login` |

### 2. Rutas de Autenticación (`/auth`)

**Layout:** `AuthLayout`
**Guard:** `GuestRoute`

| Ruta | Componente | Descripción |
|------|------------|-------------|
| `/auth/login` | `LoginPage` | Formulario de inicio de sesión |
| `/auth/register` | `RegisterPage` | Formulario de registro |
| `/auth/forgot-password` | `ForgotPasswordPage` | Recuperación de contraseña |

### 3. Rutas de Dashboard (`/dashboard`)

**Layout:** `DashboardLayout`
**Guard:** `ProtectedRoute`

#### 3.1 Rutas Core

| Ruta | Componente | Descripción |
|------|------------|-------------|
| `/dashboard` | `DashboardPage` | Dashboard principal con métricas |
| `/dashboard/settings` | `SettingsPage` | Configuración de cuenta |
| `/dashboard/billing` | `BillingPage` | Gestión de suscripción (Stripe) |
| `/dashboard/users` | `UsersPage` | Gestión de usuarios del tenant |
| `/dashboard/ai` | `AIPage` | Panel de control AI/LLM |
| `/dashboard/storage` | `StoragePage` | Gestión de archivos |
| `/dashboard/webhooks` | `WebhooksPage` | Configuración de webhooks |
| `/dashboard/audit` | `AuditLogsPage` | Registro de auditoría |
| `/dashboard/feature-flags` | `FeatureFlagsPage` | Feature toggles |
| `/dashboard/whatsapp` | `WhatsAppSettings` | Config WhatsApp Business |

#### 3.2 Rutas de Sales (`/dashboard/sales`)

| Ruta | Componente | Parámetros | Descripción |
|------|------------|------------|-------------|
| `/dashboard/sales` | `SalesPage` | - | Dashboard de ventas |
| `/dashboard/sales/leads` | `LeadsPage` | - | Listado de leads |
| `/dashboard/sales/leads/:id` | `LeadDetailPage` | `id: string` | Detalle de lead |
| `/dashboard/sales/opportunities` | `OpportunitiesPage` | - | Pipeline de oportunidades |
| `/dashboard/sales/opportunities/:id` | `OpportunityDetailPage` | `id: string` | Detalle de oportunidad |
| `/dashboard/sales/activities` | `ActivitiesPage` | - | Actividades de ventas |

#### 3.3 Rutas de Commissions (`/dashboard/commissions`)

| Ruta | Componente | Parámetros | Descripción |
|------|------------|------------|-------------|
| `/dashboard/commissions` | `CommissionsPage` | - | Dashboard de comisiones |
| `/dashboard/commissions/schemes` | `SchemesPage` | - | Esquemas de comisiones |
| `/dashboard/commissions/entries` | `EntriesPage` | - | Entradas de comisiones |
| `/dashboard/commissions/periods` | `PeriodsPage` | - | Períodos de pago |
| `/dashboard/commissions/my-earnings` | `MyEarningsPage` | - | Mis ganancias |

### 4. Rutas de Superadmin (`/superadmin`)

**Layout:** `DashboardLayout`
**Guard:** `SuperadminRoute`

| Ruta | Componente | Parámetros | Descripción |
|------|------------|------------|-------------|
| `/superadmin` | Navigate | - | Redirect a `/superadmin/tenants` |
| `/superadmin/tenants` | `TenantsPage` | - | Listado de tenants |
| `/superadmin/tenants/:id` | `TenantDetailPage` | `id: string` | Detalle de tenant |
| `/superadmin/metrics` | `MetricsPage` | - | Métricas del sistema |

### 5. Ruta de Onboarding

| Ruta | Componente | Guard | Descripción |
|------|------------|-------|-------------|
| `/onboarding` | `OnboardingPage` | `ProtectedRoute` | Wizard de onboarding (4 pasos) |

### 6. Ruta 404 (Catch-All)

| Ruta | Componente | Descripción |
|------|------------|-------------|
| `*` | Navigate | Redirect a `/` |

---

## Diagrama de Navegación

```
                    ┌─────────────────┐
                    │       /         │
                    │  (redirect)     │
                    └────────┬────────┘
                             │
                             ▼
          ┌──────────────────┴──────────────────┐
          │                                     │
          ▼                                     ▼
┌─────────────────┐                   ┌─────────────────┐
│   /auth/*       │                   │  /dashboard/*   │
│  (GuestRoute)   │                   │ (ProtectedRoute)│
├─────────────────┤                   ├─────────────────┤
│ login           │◄─────────────────►│ (index)         │
│ register        │   login/logout    │ settings        │
│ forgot-password │                   │ billing         │
└─────────────────┘                   │ users           │
                                      │ ai              │
                                      │ storage         │
                                      │ webhooks        │
                                      │ audit           │
                                      │ feature-flags   │
                                      │ whatsapp        │
                                      │                 │
                                      │ sales/*         │
                                      │ ├─ (index)      │
                                      │ ├─ leads        │
                                      │ ├─ leads/:id    │
                                      │ ├─ opportunities│
                                      │ ├─ opportunities/:id │
                                      │ └─ activities   │
                                      │                 │
                                      │ commissions/*   │
                                      │ ├─ (index)      │
                                      │ ├─ schemes      │
                                      │ ├─ entries      │
                                      │ ├─ periods      │
                                      │ └─ my-earnings  │
                                      └────────┬────────┘
                                               │
                                               │ (superadmin only)
                                               ▼
                                      ┌─────────────────┐
                                      │ /superadmin/*   │
                                      │(SuperadminRoute)│
                                      ├─────────────────┤
                                      │ tenants         │
                                      │ tenants/:id     │
                                      │ metrics         │
                                      └─────────────────┘
```

---

## Layouts

### AuthLayout
- **Ubicación:** `src/layouts/AuthLayout.tsx`
- **Uso:** Rutas de autenticación (`/auth/*`)
- **Características:**
  - Diseño de 2 columnas (branding + formulario)
  - Responsive para móvil
  - Sin sidebar ni navegación

### DashboardLayout
- **Ubicación:** `src/layouts/DashboardLayout.tsx`
- **Uso:** Dashboard y Superadmin
- **Características:**
  - Sidebar fijo con navegación
  - Top bar con usuario y notificaciones
  - Contenido principal con scroll
  - Menú dinámico según rol
  - Outlet para rutas hijas

---

## Flujos de Navegación

### Flujo de Autenticación
```
Usuario no autenticado
    │
    ├─► /dashboard → redirect → /auth/login
    │
    └─► /auth/login → login exitoso → /dashboard
```

### Flujo de Onboarding
```
Nuevo usuario (post-registro)
    │
    └─► /onboarding
        │
        ├─ Step 1: CompanyStep (info empresa)
        ├─ Step 2: PlanStep (selección plan)
        ├─ Step 3: InviteStep (invitar usuarios)
        └─ Step 4: CompleteStep → /dashboard
```

### Flujo de Superadmin
```
Usuario con role=superadmin
    │
    ├─► /dashboard/* → acceso normal
    │
    └─► /superadmin/* → acceso permitido
            │
            └─ /superadmin/tenants/:id → detalle tenant
```

---

## Parámetros Dinámicos

| Ruta | Parámetro | Tipo | Descripción |
|------|-----------|------|-------------|
| `/dashboard/sales/leads/:id` | `id` | `string` (UUID) | ID del lead |
| `/dashboard/sales/opportunities/:id` | `id` | `string` (UUID) | ID de la oportunidad |
| `/superadmin/tenants/:id` | `id` | `string` (UUID) | ID del tenant |

### Uso en Componentes
```tsx
import { useParams } from 'react-router-dom';

function LeadDetailPage() {
  const { id } = useParams<{ id: string }>();
  // id contiene el UUID del lead
}
```

---

## Estado de Autenticación

### Store: `auth.store.ts`
```typescript
interface User {
  id: string;
  email: string;
  first_name: string;
  last_name: string;
  role: string;        // 'user' | 'admin' | 'superadmin'
  tenant_id: string;
}

interface AuthState {
  user: User | null;
  accessToken: string | null;
  refreshToken: string | null;
  isAuthenticated: boolean;
  isLoading: boolean;
}
```

---

## Resumen de Rutas

| Portal | Cantidad | Guard |
|--------|----------|-------|
| Auth | 3 rutas | GuestRoute |
| Dashboard Core | 10 rutas | ProtectedRoute |
| Dashboard Sales | 6 rutas | ProtectedRoute |
| Dashboard Commissions | 5 rutas | ProtectedRoute |
| Superadmin | 3 rutas | SuperadminRoute |
| Onboarding | 1 ruta | ProtectedRoute |
| **Total** | **28 rutas** | - |

---

*Documentación generada - Template SaaS v1.0.0*