rckrdmrd/template-saas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
9d54f832b4
template-saas/docs/05-frontend/FRONTEND-PAGES-SPEC.md
Adrian Flores Cortes f853c49568
Some checks are pending
CI / Backend CI (push) Waiting to run
Details
CI / Frontend CI (push) Waiting to run
Details
CI / Security Scan (push) Waiting to run
Details
CI / CI Summary (push) Blocked by required conditions
Details
feat(frontend): Align documentation with development - complete frontend audit 
- Add Sales/Commissions routes to router (11 new routes)
- Complete authStore (refreshTokens, updateProfile methods)
- Add JSDoc documentation to 40+ components across all categories
- Create FRONTEND-ROUTING.md with complete route mapping
- Create FRONTEND-PAGES-SPEC.md with 38 page specifications
- Update FRONTEND_INVENTORY.yml to v4.1.0 with resolved gaps

Components documented: ai/, audit/, commissions/, feature-flags/,
notifications/, sales/, storage/, webhooks/, whatsapp/

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-25 01:23:50 -06:00

805 lines
18 KiB
Markdown
Raw Blame History

# 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*
Reference in New Issue View Git Blame Copy Permalink