# Especificación de Páginas Frontend - Template SaaS

**Versión:** 1.0.0
**Actualizado:** 2026-01-25
**Total Páginas:** 38

---

## Índice

1. [Auth Pages](#1-auth-pages)
2. [Dashboard Pages](#2-dashboard-pages)
3. [Sales Pages](#3-sales-pages)
4. [Commissions Pages](#4-commissions-pages)
5. [Settings Pages](#5-settings-pages)
6. [Superadmin Pages](#6-superadmin-pages)
7. [Onboarding Pages](#7-onboarding-pages)

---

## 1. Auth Pages

### 1.1 LoginPage

**Ruta:** `/auth/login`
**Archivo:** `src/pages/auth/LoginPage.tsx`

| Aspecto | Detalle |
|---------|---------|
| **Propósito** | Autenticación de usuarios existentes |
| **Layout** | AuthLayout |
| **Guard** | GuestRoute |
| **Componentes** | LoginForm, OAuthButtons |
| **Hooks** | useAuth, useForm |
| **APIs** | `authApi.login()` |

**Estados:**
- `idle` - Formulario disponible
- `loading` - Enviando credenciales
- `error` - Credenciales inválidas
- `success` - Redirige a `/dashboard`

**Campos:**
- Email (required, email format)
- Password (required, min 8 chars)
- Remember me (checkbox)

---

### 1.2 RegisterPage

**Ruta:** `/auth/register`
**Archivo:** `src/pages/auth/RegisterPage.tsx`

| Aspecto | Detalle |
|---------|---------|
| **Propósito** | Registro de nuevos usuarios |
| **Layout** | AuthLayout |
| **Guard** | GuestRoute |
| **Componentes** | RegisterForm, OAuthButtons |
| **Hooks** | useAuth, useForm |
| **APIs** | `authApi.register()` |

**Estados:**
- `idle` - Formulario disponible
- `loading` - Creando cuenta
- `error` - Email duplicado u otro error
- `success` - Redirige a `/onboarding`

**Campos:**
- First name (optional)
- Last name (optional)
- Email (required, email format)
- Password (required, min 8 chars, complexity)
- Confirm password (must match)
- Terms acceptance (required)

---

### 1.3 ForgotPasswordPage

**Ruta:** `/auth/forgot-password`
**Archivo:** `src/pages/auth/ForgotPasswordPage.tsx`

| Aspecto | Detalle |
|---------|---------|
| **Propósito** | Solicitar reset de contraseña |
| **Layout** | AuthLayout |
| **Guard** | GuestRoute |
| **Componentes** | Form básico |
| **Hooks** | useForm |
| **APIs** | `authApi.requestPasswordReset()` |

**Estados:**
- `idle` - Formulario disponible
- `loading` - Enviando solicitud
- `success` - Muestra mensaje de email enviado
- `error` - Email no encontrado

---

## 2. Dashboard Pages

### 2.1 DashboardPage

**Ruta:** `/dashboard`
**Archivo:** `src/pages/dashboard/DashboardPage.tsx`

| Aspecto | Detalle |
|---------|---------|
| **Propósito** | Vista principal con métricas y acciones rápidas |
| **Layout** | DashboardLayout |
| **Guard** | ProtectedRoute |
| **Componentes** | MetricCard, TrendChart, QuickActions |
| **Hooks** | useAuth, useSubscription, useNotifications |
| **APIs** | `billingApi.getSummary()`, `notificationsApi.getUnreadCount()` |

**Secciones:**
- Welcome banner con nombre de usuario
- Métricas principales (usuarios, storage, API calls)
- Gráfico de actividad reciente
- Acciones rápidas
- Notificaciones recientes

---

### 2.2 BillingPage

**Ruta:** `/dashboard/billing`
**Archivo:** `src/pages/dashboard/BillingPage.tsx`

| Aspecto | Detalle |
|---------|---------|
| **Propósito** | Gestión de suscripción y pagos |
| **Layout** | DashboardLayout |
| **Guard** | ProtectedRoute |
| **Componentes** | SubscriptionCard, InvoiceList, PaymentMethodCard |
| **Hooks** | useSubscription, useInvoices, useBillingPortal |
| **APIs** | `billingApi.*`, `stripeApi.*` |

**Secciones:**
- Plan actual y estado
- Uso del mes (límites)
- Métodos de pago
- Historial de facturas
- Botón "Manage Subscription" (Stripe Portal)

---

### 2.3 UsersPage

**Ruta:** `/dashboard/users`
**Archivo:** `src/pages/dashboard/UsersPage.tsx`

| Aspecto | Detalle |
|---------|---------|
| **Propósito** | Gestión de usuarios del tenant |
| **Layout** | DashboardLayout |
| **Guard** | ProtectedRoute |
| **Componentes** | UserTable, InviteModal, RoleSelect |
| **Hooks** | useUsers, useRoles |
| **APIs** | `usersApi.list()`, `usersApi.invite()`, `usersApi.update()` |

**Acciones:**
- Listar usuarios
- Invitar nuevos usuarios
- Cambiar roles
- Desactivar usuarios

---

### 2.4 AIPage

**Ruta:** `/dashboard/ai`
**Archivo:** `src/pages/dashboard/AIPage.tsx`

| Aspecto | Detalle |
|---------|---------|
| **Propósito** | Chat con LLM y configuración |
| **Layout** | DashboardLayout |
| **Guard** | ProtectedRoute |
| **Componentes** | AIChat, AISettings, ChatMessage |
| **Hooks** | useAI, useAIChat, useAIUsage |
| **APIs** | `aiApi.chat()`, `aiApi.getConfig()`, `aiApi.getCurrentUsage()` |

**Secciones:**
- Chat interface con historial
- Selector de modelo
- Uso actual (tokens, costo)
- Configuración (temperatura, max tokens)

---

### 2.5 StoragePage

**Ruta:** `/dashboard/storage`
**Archivo:** `src/pages/dashboard/StoragePage.tsx`

| Aspecto | Detalle |
|---------|---------|
| **Propósito** | Gestión de archivos |
| **Layout** | DashboardLayout |
| **Guard** | ProtectedRoute |
| **Componentes** | FileList, FileUpload, FileItem, StorageUsageCard |
| **Hooks** | useFiles, useUpload, useStorageUsage |
| **APIs** | `storageApi.listFiles()`, `storageApi.uploadFile()`, `storageApi.deleteFile()` |

**Acciones:**
- Subir archivos (drag & drop)
- Listar archivos con paginación
- Filtrar por carpeta/tipo
- Descargar archivos
- Eliminar archivos
- Ver uso de storage

---

### 2.6 WebhooksPage

**Ruta:** `/dashboard/webhooks`
**Archivo:** `src/pages/dashboard/WebhooksPage.tsx`

| Aspecto | Detalle |
|---------|---------|
| **Propósito** | Configuración de webhooks outbound |
| **Layout** | DashboardLayout |
| **Guard** | ProtectedRoute |
| **Componentes** | WebhookCard, WebhookForm, WebhookDeliveryList |
| **Hooks** | useWebhooks, useWebhookDeliveries |
| **APIs** | `webhooksApi.*` |

**Acciones:**
- Crear webhook
- Editar URL, eventos, headers
- Ver historial de entregas
- Reintentar entregas fallidas
- Test webhook

---

### 2.7 AuditLogsPage

**Ruta:** `/dashboard/audit`
**Archivo:** `src/pages/dashboard/AuditLogsPage.tsx`

| Aspecto | Detalle |
|---------|---------|
| **Propósito** | Registro de auditoría de acciones |
| **Layout** | DashboardLayout |
| **Guard** | ProtectedRoute |
| **Componentes** | AuditLogRow, AuditFilters, AuditStatsCard, ActivityTimeline |
| **Hooks** | useAuditLogs, useActivityLogs |
| **APIs** | `auditApi.queryLogs()`, `auditApi.getStats()` |

**Filtros:**
- Por usuario
- Por acción (create, update, delete, login)
- Por entidad
- Por fecha

---

### 2.8 FeatureFlagsPage

**Ruta:** `/dashboard/feature-flags`
**Archivo:** `src/pages/dashboard/FeatureFlagsPage.tsx`

| Aspecto | Detalle |
|---------|---------|
| **Propósito** | Gestión de feature toggles |
| **Layout** | DashboardLayout |
| **Guard** | ProtectedRoute |
| **Componentes** | FeatureFlagCard, FeatureFlagForm, TenantOverridesPanel |
| **Hooks** | useFeatureFlags, useFeatureFlag |
| **APIs** | `featureFlagsApi.*` |

**Acciones:**
- Listar flags
- Crear/editar flags
- Toggle on/off
- Configurar overrides por tenant/usuario
- Ver targeting rules

---

### 2.9 WhatsAppSettings

**Ruta:** `/dashboard/whatsapp`
**Archivo:** `src/pages/admin/WhatsAppSettings.tsx`

| Aspecto | Detalle |
|---------|---------|
| **Propósito** | Configuración WhatsApp Business API |
| **Layout** | DashboardLayout |
| **Guard** | ProtectedRoute |
| **Componentes** | WhatsAppTestMessage |
| **Hooks** | useWhatsApp |
| **APIs** | `whatsappApi.*` |

**Secciones:**
- Estado de conexión
- Configuración de API
- Envío de mensaje de prueba
- Templates de mensajes

---

## 3. Sales Pages

### 3.1 SalesPage (Dashboard)

**Ruta:** `/dashboard/sales`
**Archivo:** `src/pages/sales/index.tsx`

| Aspecto | Detalle |
|---------|---------|
| **Propósito** | Dashboard de ventas con métricas |
| **Layout** | DashboardLayout |
| **Guard** | ProtectedRoute |
| **Componentes** | SalesDashboard |
| **Hooks** | useSalesSummary, useConversionRates |
| **APIs** | Sales Dashboard API |

**Métricas:**
- Total leads
- Conversion rate
- Pipeline value
- Deals cerrados

---

### 3.2 LeadsPage

**Ruta:** `/dashboard/sales/leads`
**Archivo:** `src/pages/sales/leads/index.tsx`

| Aspecto | Detalle |
|---------|---------|
| **Propósito** | Listado y gestión de leads |
| **Layout** | DashboardLayout |
| **Guard** | ProtectedRoute |
| **Componentes** | LeadsList, LeadForm |
| **Hooks** | useLeads, useLeadStats |
| **APIs** | Leads API |

**Filtros:**
- Search (nombre, email, empresa)
- Status (new, contacted, qualified, unqualified, converted)
- Source (website, referral, cold_call, event, advertisement, social_media)

**Acciones:**
- Crear lead
- Ver detalle
- Filtrar y buscar

---

### 3.3 LeadDetailPage

**Ruta:** `/dashboard/sales/leads/:id`
**Archivo:** `src/pages/sales/leads/[id].tsx`

| Aspecto | Detalle |
|---------|---------|
| **Propósito** | Detalle y edición de un lead |
| **Layout** | DashboardLayout |
| **Guard** | ProtectedRoute |
| **Componentes** | LeadCard, LeadForm, ActivityTimeline, ActivityForm |
| **Hooks** | useLead, useDeleteLead, useConvertLead, useLeadActivities |
| **APIs** | Leads API, Activities API |

**Secciones:**
- Información del lead
- Score
- Información de contacto
- Timeline de actividades
- Notas

**Acciones:**
- Editar lead
- Eliminar lead
- Convertir a oportunidad
- Agregar actividad

---

### 3.4 OpportunitiesPage

**Ruta:** `/dashboard/sales/opportunities`
**Archivo:** `src/pages/sales/opportunities/index.tsx`

| Aspecto | Detalle |
|---------|---------|
| **Propósito** | Pipeline de oportunidades (Kanban) |
| **Layout** | DashboardLayout |
| **Guard** | ProtectedRoute |
| **Componentes** | PipelineBoard, OpportunityForm |
| **Hooks** | usePipeline, useOpportunityStats |
| **APIs** | Pipeline API, Opportunities API |

**Vistas:**
- Pipeline (Kanban)
- List view

**Métricas:**
- Open
- Won
- Win Rate
- Avg Deal Size

---

### 3.5 OpportunityDetailPage

**Ruta:** `/dashboard/sales/opportunities/:id`
**Archivo:** `src/pages/sales/opportunities/[id].tsx`

| Aspecto | Detalle |
|---------|---------|
| **Propósito** | Detalle y gestión de una oportunidad |
| **Layout** | DashboardLayout |
| **Guard** | ProtectedRoute |
| **Componentes** | OpportunityForm, ActivityTimeline, ActivityForm |
| **Hooks** | useOpportunity, useDeleteOpportunity, useMarkAsWon, useMarkAsLost, useOpportunityActivities |
| **APIs** | Opportunities API, Activities API |

**Secciones:**
- Valor y probabilidad
- Descripción
- Timeline de actividades
- Status (Open/Won/Lost)
- Contacto
- Timeline de fechas

**Acciones:**
- Editar oportunidad
- Eliminar
- Marcar como Won
- Marcar como Lost
- Agregar actividad

---

### 3.6 ActivitiesPage

**Ruta:** `/dashboard/sales/activities`
**Archivo:** `src/pages/sales/activities/index.tsx`

| Aspecto | Detalle |
|---------|---------|
| **Propósito** | Gestión de actividades de ventas |
| **Layout** | DashboardLayout |
| **Guard** | ProtectedRoute |
| **Componentes** | ActivityForm |
| **Hooks** | useActivities, useUpcomingActivities, useOverdueActivities, useActivityStats |
| **APIs** | Activities API |

**Tipos de actividad:**
- Call
- Meeting
- Task
- Email
- Note

**Estados:**
- Pending
- Completed
- Cancelled

---

## 4. Commissions Pages

### 4.1 CommissionsPage (Dashboard)

**Ruta:** `/dashboard/commissions`
**Archivo:** `src/pages/commissions/index.tsx`

| Aspecto | Detalle |
|---------|---------|
| **Propósito** | Dashboard de comisiones |
| **Layout** | DashboardLayout |
| **Guard** | ProtectedRoute |
| **Componentes** | CommissionsDashboard |
| **Hooks** | useCommissionsSummary, useTopEarners, useEarningsByPeriod |
| **APIs** | Commissions Dashboard API |

**Métricas:**
- Total comisiones
- Pendientes
- Aprobadas
- Top earners

---

### 4.2 SchemesPage

**Ruta:** `/dashboard/commissions/schemes`
**Archivo:** `src/pages/commissions/schemes/index.tsx`

| Aspecto | Detalle |
|---------|---------|
| **Propósito** | Configuración de esquemas de comisiones |
| **Layout** | DashboardLayout |
| **Guard** | ProtectedRoute |
| **Componentes** | SchemesList, SchemeForm |
| **Hooks** | useSchemes |
| **APIs** | Schemes API |

**Tipos de esquema:**
- Percentage
- Fixed
- Tiered

**Filtros:**
- Type
- Status (active/inactive)
- Search

---

### 4.3 EntriesPage

**Ruta:** `/dashboard/commissions/entries`
**Archivo:** `src/pages/commissions/entries/index.tsx`

| Aspecto | Detalle |
|---------|---------|
| **Propósito** | Gestión de entradas de comisiones |
| **Layout** | DashboardLayout |
| **Guard** | ProtectedRoute |
| **Componentes** | EntriesList |
| **Hooks** | useEntries, useBulkApprove, useBulkReject |
| **APIs** | Entries API |

**Estados:**
- Pending
- Approved
- Rejected
- Paid
- Cancelled

**Acciones bulk:**
- Aprobar seleccionados
- Rechazar seleccionados

---

### 4.4 PeriodsPage

**Ruta:** `/dashboard/commissions/periods`
**Archivo:** `src/pages/commissions/periods/index.tsx`

| Aspecto | Detalle |
|---------|---------|
| **Propósito** | Gestión de períodos de pago |
| **Layout** | DashboardLayout |
| **Guard** | ProtectedRoute |
| **Componentes** | PeriodManager |
| **Hooks** | usePeriods, useCreatePeriod |
| **APIs** | Periods API |

**Estados de período:**
- Open
- Closed
- Processing
- Paid

---

### 4.5 MyEarningsPage

**Ruta:** `/dashboard/commissions/my-earnings`
**Archivo:** `src/pages/commissions/my-earnings/index.tsx`

| Aspecto | Detalle |
|---------|---------|
| **Propósito** | Vista de ganancias del usuario actual |
| **Layout** | DashboardLayout |
| **Guard** | ProtectedRoute |
| **Componentes** | EarningsCard, EntryStatusBadge |
| **Hooks** | useMyEarnings |
| **APIs** | Dashboard API (my earnings) |

**Secciones:**
- Total earnings
- Pending
- Approved
- Current period earnings
- Recent commissions table

---

## 5. Settings Pages

### 5.1 SettingsPage

**Ruta:** `/dashboard/settings`
**Archivo:** `src/pages/settings/index.tsx`

| Aspecto | Detalle |
|---------|---------|
| **Propósito** | Configuración de cuenta (tabs) |
| **Layout** | DashboardLayout |
| **Guard** | ProtectedRoute |
| **Componentes** | GeneralSettings, NotificationSettings, SecuritySettings |
| **Hooks** | useAuth, useCurrentUser |
| **APIs** | `usersApi.update()`, `notificationsApi.*`, `authApi.*` |

**Tabs:**
- General (perfil)
- Notifications (preferencias)
- Security (password, MFA)
- AI (configuración AI)

---

### 5.2 GeneralSettings

**Archivo:** `src/pages/settings/GeneralSettings.tsx`

| Aspecto | Detalle |
|---------|---------|
| **Propósito** | Configuración de perfil |
| **Componentes** | Form básico |
| **Hooks** | useCurrentUser, useForm |

**Campos:**
- First name
- Last name
- Email (read-only)
- Avatar

---

### 5.3 NotificationSettings

**Archivo:** `src/pages/settings/NotificationSettings.tsx`

| Aspecto | Detalle |
|---------|---------|
| **Propósito** | Preferencias de notificaciones |
| **Componentes** | Toggle switches |
| **Hooks** | useNotifications |

**Configuración:**
- Email notifications
- Push notifications
- In-app notifications
- Tipos de eventos

---

### 5.4 SecuritySettings

**Archivo:** `src/pages/settings/SecuritySettings.tsx`

| Aspecto | Detalle |
|---------|---------|
| **Propósito** | Seguridad de la cuenta |
| **Componentes** | Form de password |
| **Hooks** | useAuth |

**Secciones:**
- Cambiar contraseña
- Sesiones activas
- MFA (futuro)

---

## 6. Superadmin Pages

### 6.1 TenantsPage

**Ruta:** `/superadmin/tenants`
**Archivo:** `src/pages/superadmin/TenantsPage.tsx`

| Aspecto | Detalle |
|---------|---------|
| **Propósito** | Listado de todos los tenants |
| **Layout** | DashboardLayout |
| **Guard** | SuperadminRoute |
| **Componentes** | TenantTable |
| **Hooks** | useSuperadmin |
| **APIs** | `superadminApi.listTenants()` |

**Filtros:**
- Search
- Status
- Plan

---

### 6.2 TenantDetailPage

**Ruta:** `/superadmin/tenants/:id`
**Archivo:** `src/pages/superadmin/TenantDetailPage.tsx`

| Aspecto | Detalle |
|---------|---------|
| **Propósito** | Detalle de un tenant específico |
| **Layout** | DashboardLayout |
| **Guard** | SuperadminRoute |
| **Componentes** | TenantForm, UserTable |
| **Hooks** | useSuperadmin |
| **APIs** | `superadminApi.getTenant()`, `superadminApi.getTenantUsers()` |

**Secciones:**
- Información del tenant
- Usuarios del tenant
- Suscripción
- Métricas de uso

---

### 6.3 MetricsPage

**Ruta:** `/superadmin/metrics`
**Archivo:** `src/pages/superadmin/MetricsPage.tsx`

| Aspecto | Detalle |
|---------|---------|
| **Propósito** | Métricas globales del sistema |
| **Layout** | DashboardLayout |
| **Guard** | SuperadminRoute |
| **Componentes** | MetricCard, TrendChart |
| **Hooks** | useSuperadmin |
| **APIs** | `superadminApi.getMetricsSummary()`, `superadminApi.getTenantGrowth()` |

**Métricas:**
- Total tenants
- Total users
- MRR
- Tenant growth chart
- Plan distribution
- Top tenants

---

## 7. Onboarding Pages

### 7.1 OnboardingPage

**Ruta:** `/onboarding`
**Archivo:** `src/pages/onboarding/OnboardingPage.tsx`

| Aspecto | Detalle |
|---------|---------|
| **Propósito** | Wizard de onboarding para nuevos tenants |
| **Layout** | Propio (sin DashboardLayout) |
| **Guard** | ProtectedRoute |
| **Componentes** | WizardProgress, CompanyStep, PlanStep, InviteStep, CompleteStep |
| **Hooks** | useOnboarding, useOnboardingStatus |
| **APIs** | Onboarding API |

**Pasos:**
1. **CompanyStep** - Información de la empresa (nombre, logo)
2. **PlanStep** - Selección de plan
3. **InviteStep** - Invitar miembros del equipo
4. **CompleteStep** - Confirmación y redirección

---

## Resumen de Estados Comunes

### Loading State
```tsx
<div className="flex items-center justify-center h-64">
  <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-blue-600" />
</div>
```

### Empty State
```tsx
<div className="text-center py-12">
  <p className="text-gray-500">No data found</p>
</div>
```

### Error State
```tsx
<div className="bg-red-50 p-4 rounded-lg">
  <p className="text-red-600">{error.message}</p>
</div>
```

---

## Resumen Cuantitativo

| Categoría | Cantidad |
|-----------|----------|
| Auth Pages | 3 |
| Dashboard Core | 9 |
| Sales Pages | 6 |
| Commissions Pages | 5 |
| Settings Pages | 4 |
| Superadmin Pages | 3 |
| Onboarding Pages | 1 (+4 steps) |
| **Total** | **38** |

---

*Documentación generada - Template SaaS v1.0.0 - 2026-01-25*