template-saas/docs/05-frontend/FRONTEND-PAGES-SPEC.md

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
2. Dashboard Pages
3. Sales Pages
4. Commissions Pages
5. Settings Pages
6. Superadmin 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

<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

<div className="text-center py-12">
  <p className="text-gray-500">No data found</p>
</div>

Error State

<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