diff --git a/docs/05-frontend/pages/PAGE-ANALYTICS.md b/docs/05-frontend/pages/PAGE-ANALYTICS.md new file mode 100644 index 00000000..2b0dd68c --- /dev/null +++ b/docs/05-frontend/pages/PAGE-ANALYTICS.md @@ -0,0 +1,96 @@ +# Analytics Dashboard Page Specification + +**Modulo:** analytics +**Ultima actualizacion:** 2026-02-03 +**Total Paginas:** 1 + +--- + +## AnalyticsDashboardPage + +**Ruta:** `/dashboard/analytics` +**Archivo:** `src/pages/admin/AnalyticsDashboardPage.tsx` + +### Descripcion +Dashboard de analiticas con metricas clave del negocio, tendencias temporales y uso por feature. Permite seleccionar diferentes periodos de tiempo. + +### Componentes Utilizados +- Period Selector - Botones de seleccion de periodo (7d, 30d, 90d, 1y) +- MetricCard - Tarjetas de KPI con tendencia +- TrendChart - Graficos de linea para tendencias +- Top Features Section - Barras de uso por feature +- Activity by Hour Chart - Grafico de barras por hora +- Icons: Users, DollarSign, Activity, TrendingUp, BarChart3, Clock (lucide-react) +- clsx - Utilidad para clases condicionales + +### Hooks Utilizados +- `useAnalyticsSummary()` - Resumen de metricas principales +- `useAnalyticsTrends(period)` - Tendencias por periodo +- `useUsageMetrics(period)` - Metricas de uso +- `getAvailablePeriods()` - Lista de periodos disponibles +- `getPeriodLabel(period)` - Label legible del periodo +- `formatCurrency(value)` - Formato moneda +- `formatNumber(value)` - Formato numero + +### Funcionalidades +1. Seleccionar periodo de tiempo (7d, 30d, 90d, 1y) +2. Ver KPIs principales: + - Active Users (con cambio % y total) + - MRR (con cambio % y ARR) + - Total Actions (con cambio % y promedio por usuario) + - Engagement Rate (con cambio % y sesiones) +3. Ver graficos de tendencia: + - User Growth + - Revenue Trend + - Daily Actions +4. Ver top 5 features mas usadas con porcentaje +5. Ver actividad por hora del dia (24 barras) + +### Estados +- Loading: Skeletons y spinners por seccion +- Success: Dashboard completo con datos +- Empty Top Features: "No feature data available" +- Empty Hourly: "No hourly data available" + +### Acciones del Usuario +| Accion | Resultado | +|--------|-----------| +| Click periodo | Recarga datos con nuevo periodo | +| Hover barra hora | Muestra tooltip con valor | + +### Permisos Requeridos +- `analytics:read` - Ver dashboard de analiticas + +### Tipos de Datos + +```typescript +type AnalyticsPeriod = '7d' | '30d' | '90d' | '1y'; + +interface AnalyticsSummary { + users: { active: number; total: number; change?: number }; + revenue: { mrr: number; arr: number; change?: number }; + usage: { actions: number; avgPerUser: number; change?: number }; + engagement: { rate: number; sessions: number; change?: number }; +} + +interface TrendData { + users: { date: string; value: number }[]; + revenue: { date: string; value: number }[]; + actions: { date: string; value: number }[]; +} + +interface UsageMetrics { + topFeatures: { feature: string; count: number; percentage: number }[]; + byHour: { hour: number; actions: number }[]; +} +``` + +### Notas +- Los valores de cambio (change) se muestran en verde (positivo) o rojo (negativo) +- Los graficos de tendencia usan colores consistentes por metrica +- El grafico de horas muestra 24 barras, con labels cada 4 horas +- La altura de las barras es proporcional al maximo del periodo + +--- + +*Documentacion generada - Template SaaS - 2026-02-03* diff --git a/docs/05-frontend/pages/PAGE-AUDIT.md b/docs/05-frontend/pages/PAGE-AUDIT.md new file mode 100644 index 00000000..e8e9bcae --- /dev/null +++ b/docs/05-frontend/pages/PAGE-AUDIT.md @@ -0,0 +1,92 @@ +# Audit Logs Page Specification + +**Modulo:** audit +**Ultima actualizacion:** 2026-02-03 +**Total Paginas:** 1 + +--- + +## AuditLogsPage + +**Ruta:** `/dashboard/audit` +**Archivo:** `src/pages/dashboard/AuditLogsPage.tsx` + +### Descripcion +Pagina de logs de auditoria. Muestra registro de todas las acciones realizadas en el sistema con filtros avanzados y timeline. + +### Componentes Utilizados +- AuditFilters - Panel de filtros multiples +- AuditLogRow - Fila de log con detalles expandibles +- AuditStatsCard - Tarjetas de estadisticas +- ActivityTimeline - Timeline visual de actividad + +### Hooks Utilizados +- `useAuditLogs(filters)` - Lista logs con filtros +- `useActivityLogs()` - Timeline de actividad + +### Funcionalidades +1. Filtrar por usuario +2. Filtrar por tipo de accion (create, update, delete, login, logout) +3. Filtrar por entidad afectada +4. Filtrar por rango de fechas +5. Ver detalles de cada accion +6. Ver cambios realizados (before/after) +7. Ver timeline de actividad reciente + +### Filtros Disponibles + +| Filtro | Tipo | Opciones | +|--------|------|----------| +| Usuario | Select | Lista de usuarios | +| Accion | Select | create, update, delete, login, logout | +| Entidad | Select | user, tenant, invoice, etc | +| Fecha desde | Date | Datepicker | +| Fecha hasta | Date | Datepicker | + +### Estados +- Loading: Spinner centrado +- Success: Tabla de logs con paginacion +- Empty: Mensaje "No audit logs found" +- Error: Mensaje de error + +### Acciones del Usuario +| Accion | Resultado | +|--------|-----------| +| Seleccionar filtro | Filtra resultados | +| Click en fila | Expande detalles | +| Limpiar filtros | Reset a todos | +| Previous/Next | Cambia pagina | + +### Permisos Requeridos +- `audit:read` - Ver logs de auditoria + +### Estructura de Log + +```typescript +interface AuditLog { + id: string; + user_id: string; + user_email: string; + action: 'create' | 'update' | 'delete' | 'login' | 'logout'; + entity_type: string; + entity_id: string; + changes?: { + before: Record; + after: Record; + }; + metadata?: Record; + ip_address?: string; + user_agent?: string; + created_at: string; +} +``` + +### Notas +- Los logs son inmutables, no se pueden editar ni eliminar +- La retencion de logs depende del plan de suscripcion +- Los campos sensibles (passwords) nunca se registran +- El IP y user agent se registran para seguridad + +--- + +*Documentacion generada - Template SaaS - 2026-02-03* diff --git a/docs/05-frontend/pages/PAGE-GOALS.md b/docs/05-frontend/pages/PAGE-GOALS.md new file mode 100644 index 00000000..c6ad03ae --- /dev/null +++ b/docs/05-frontend/pages/PAGE-GOALS.md @@ -0,0 +1,230 @@ +# Goals Pages Specification + +**Modulo:** goals +**Ultima actualizacion:** 2026-02-03 +**Total Paginas:** 5 + +--- + +## 1. GoalsPage (Dashboard) + +**Ruta:** `/dashboard/goals` +**Archivo:** `src/pages/dashboard/goals/GoalsPage.tsx` + +### Descripcion +Dashboard principal del modulo de metas. Muestra un resumen de las metas del usuario y de la organizacion, con metricas clave y accesos rapidos. + +### Componentes Utilizados +- Summary Cards (custom) - Tarjetas de resumen con iconos +- Goals List - Listado de metas activas +- Top Performers - Ranking de usuarios +- Quick Actions - Enlaces rapidos a otras paginas + +### Hooks Utilizados +- `useGoalDefinitions()` - Obtiene definiciones de metas activas +- `useMyGoalsSummary()` - Obtiene resumen de metas del usuario +- `useGoalCompletionReport()` - Obtiene reporte de completitud general +- `useGoalUserReport()` - Obtiene ranking de usuarios + +### Funcionalidades +1. Mostrar metricas personales (activas, logradas, en riesgo, progreso promedio) +2. Mostrar overview de la organizacion +3. Listar metas activas con estado y asignados +4. Mostrar top 5 performers +5. Accesos rapidos a otras secciones + +### Estados +- Loading: Spinner centrado +- Success: Muestra dashboard completo +- Empty: Mensajes individuales por seccion + +### Acciones del Usuario +| Accion | Resultado | +|--------|-----------| +| Click en meta | Navega a detalle | +| Click en Quick Action | Navega a seccion | + +### Permisos Requeridos +- Usuario autenticado + +--- + +## 2. DefinitionsPage + +**Ruta:** `/dashboard/goals/definitions` +**Archivo:** `src/pages/dashboard/goals/DefinitionsPage.tsx` + +### Descripcion +Listado y gestion de definiciones de metas. Permite crear, editar, duplicar y eliminar definiciones de metas. + +### Componentes Utilizados +- Filters Panel - Filtros por status, periodo, categoria +- Definitions Table - Tabla con paginacion +- Status Badge - Badges de estado con color + +### Hooks Utilizados +- `useGoalDefinitions(filters)` - Lista definiciones con filtros +- `useDeleteGoalDefinition()` - Elimina definicion +- `useUpdateGoalStatus()` - Cambia estado de definicion +- `useDuplicateGoalDefinition()` - Duplica definicion + +### Funcionalidades +1. Filtrar por status (draft, active, paused, completed, cancelled) +2. Filtrar por periodo (daily, weekly, monthly, quarterly, yearly) +3. Filtrar por categoria +4. Buscar por nombre +5. Cambiar estado inline via select +6. Ver, editar, duplicar, eliminar desde tabla + +### Estados +- Loading: Spinner centrado +- Error: Mensaje de error +- Empty: Icono + mensaje + CTA para crear +- Success: Tabla con definiciones + +### Acciones del Usuario +| Accion | Resultado | +|--------|-----------| +| Click "+ New Definition" | Navega a formulario | +| Cambiar status select | Actualiza estado | +| Click "View" | Navega a detalle | +| Click "Edit" | Navega a edicion | +| Click "Duplicate" | Crea copia | +| Click "Delete" | Confirm + elimina | + +### Permisos Requeridos +- `goals:read` - Ver listado +- `goals:write` - Crear/editar/duplicar +- `goals:delete` - Eliminar + +--- + +## 3. MyGoalsPage + +**Ruta:** `/dashboard/goals/my-goals` +**Archivo:** `src/pages/dashboard/goals/MyGoalsPage.tsx` + +### Descripcion +Vista personal de metas asignadas al usuario actual. Permite ver progreso y actualizar avance manualmente. + +### Componentes Utilizados +- Summary Cards - Resumen de estadisticas personales +- Goal Cards - Tarjetas de meta con barra de progreso +- Progress Form - Formulario inline para actualizar progreso + +### Hooks Utilizados +- `useMyGoals()` - Lista metas asignadas al usuario +- `useMyGoalsSummary()` - Resumen de estadisticas +- `useUpdateMyGoalProgress()` - Actualiza progreso de meta + +### Funcionalidades +1. Ver resumen personal (total, activas, logradas, en riesgo, progreso promedio) +2. Ver tarjetas de cada meta con progreso visual +3. Ver dias restantes por meta +4. Actualizar progreso manualmente con notas +5. Navegar a detalle de asignacion + +### Estados +- Loading: Spinner centrado +- Error: Mensaje de error +- Empty: Mensaje "No goals assigned" + link +- Success: Lista de tarjetas de metas + +### Acciones del Usuario +| Accion | Resultado | +|--------|-----------| +| Click "Update Progress" | Abre formulario inline | +| Submit progreso | Guarda nuevo valor | +| Click "Cancel" | Cierra formulario | +| Click "View Details" | Navega a detalle | + +### Permisos Requeridos +- Usuario autenticado + +--- + +## 4. ReportsPage + +**Ruta:** `/dashboard/goals/reports` +**Archivo:** `src/pages/dashboard/goals/ReportsPage.tsx` + +### Descripcion +Reportes detallados de metas con estadisticas de completitud, rendimiento por usuario y exportacion CSV. + +### Componentes Utilizados +- Date Range Filter - Filtro de fechas +- Summary Cards - KPIs principales +- Status Distribution Bars - Barras de progreso por estado +- User Performance Table - Tabla de rendimiento +- Active Goals List - Lista de metas activas + +### Hooks Utilizados +- `useGoalCompletionReport(startDate, endDate)` - Reporte de completitud +- `useGoalUserReport()` - Reporte por usuario +- `useGoalDefinitions({status: 'active'})` - Metas activas + +### Funcionalidades +1. Filtrar por rango de fechas +2. Ver KPIs: total, logradas, tasa completitud, progreso promedio +3. Ver distribucion por estado (achieved, active, failed) +4. Ver usuarios con logros y top performer +5. Ver tabla de rendimiento por usuario con ranking +6. Exportar a CSV (summary y user report) + +### Estados +- Loading: Spinner centrado +- Success: Dashboard de reportes +- Empty: Mensajes por seccion + +### Acciones del Usuario +| Accion | Resultado | +|--------|-----------| +| Seleccionar fecha inicio | Filtra datos | +| Seleccionar fecha fin | Filtra datos | +| Click "Clear Filters" | Limpia filtros | +| Click "Export Summary" | Descarga CSV summary | +| Click "Export User Report" | Descarga CSV usuarios | +| Click "View" en meta | Navega a detalle | + +### Permisos Requeridos +- `goals:read` - Ver reportes +- `reports:export` - Exportar CSV + +--- + +## 5. AssignmentsPage + +**Ruta:** `/dashboard/goals/assignments` +**Archivo:** `src/pages/dashboard/goals/AssignmentsPage.tsx` + +### Descripcion +Gestion de asignaciones de metas a usuarios. Permite ver, filtrar y gestionar asignaciones. + +### Componentes Utilizados +- Filters Panel - Filtros multiples +- Assignments Table - Tabla con paginacion +- Status Badge - Badges de estado + +### Hooks Utilizados +- `useGoalAssignments(filters)` - Lista asignaciones +- `useDeleteAssignment()` - Elimina asignacion + +### Funcionalidades +1. Filtrar por definicion, usuario, estado +2. Ver tabla con progreso visual +3. Navegar a detalle de asignacion + +### Estados +- Loading: Spinner centrado +- Error: Mensaje de error +- Empty: Mensaje + CTA +- Success: Tabla de asignaciones + +### Permisos Requeridos +- `goals:read` - Ver listado +- `goals:assign` - Crear asignaciones +- `goals:delete` - Eliminar asignaciones + +--- + +*Documentacion generada - Template SaaS - 2026-02-03* diff --git a/docs/05-frontend/pages/PAGE-MLM.md b/docs/05-frontend/pages/PAGE-MLM.md new file mode 100644 index 00000000..12d91781 --- /dev/null +++ b/docs/05-frontend/pages/PAGE-MLM.md @@ -0,0 +1,233 @@ +# MLM Pages Specification + +**Modulo:** mlm +**Ultima actualizacion:** 2026-02-03 +**Total Paginas:** 5 + +--- + +## 1. MLMPage (Dashboard) + +**Ruta:** `/dashboard/mlm` +**Archivo:** `src/pages/dashboard/mlm/MLMPage.tsx` + +### Descripcion +Dashboard principal del modulo MLM (Marketing Multinivel). Muestra resumen de red, rango actual, progreso hacia siguiente rango y estructuras activas. + +### Componentes Utilizados +- Summary Cards - Tarjetas con metricas clave +- Rank Display - Muestra rango actual con badge visual +- Next Rank Progress - Barras de progreso hacia siguiente rango +- Volume Summary - Resumen de volumenes +- Active Structures Grid - Grid de estructuras activas +- Quick Actions - Enlaces rapidos + +### Hooks Utilizados +- `useMyDashboard()` - Obtiene dashboard personal MLM +- `useStructures({isActive: true})` - Lista estructuras activas + +### Funcionalidades +1. Ver metricas principales (downline total, referidos directos, volumen grupo, ganancias) +2. Ver rango actual con nivel y badge +3. Ver progreso hacia siguiente rango (PV, GV, referidos requeridos) +4. Ver resumen de volumenes (personal, grupo, downline activos) +5. Ver estructuras MLM activas +6. Accesos rapidos a otras secciones + +### Estados +- Loading: Spinner centrado +- Success: Dashboard completo +- No Rank: Mensaje "No rank assigned yet" +- Top Rank: Mensaje "You've reached the highest rank!" + +### Acciones del Usuario +| Accion | Resultado | +|--------|-----------| +| Click en estructura | Navega a detalle | +| Click Quick Action | Navega a seccion | + +### Permisos Requeridos +- Usuario autenticado + +--- + +## 2. StructuresPage + +**Ruta:** `/dashboard/mlm/structures` +**Archivo:** `src/pages/dashboard/mlm/StructuresPage.tsx` + +### Descripcion +Listado y gestion de estructuras MLM. Permite crear, ver y eliminar estructuras con diferentes tipos (unilevel, binary, matrix, hybrid). + +### Componentes Utilizados +- Filters Panel - Filtros por tipo y estado +- Structure Cards Grid - Grid de tarjetas de estructura +- Type Badge - Badge con color segun tipo + +### Hooks Utilizados +- `useStructures(filters)` - Lista estructuras con filtros +- `useDeleteStructure()` - Elimina estructura + +### Funcionalidades +1. Filtrar por tipo (unilevel, binary, matrix, hybrid) +2. Filtrar por estado (activo/inactivo) +3. Buscar por nombre +4. Ver tarjetas con configuracion (max depth, max width, commission levels) +5. Ver estado activo/inactivo +6. Eliminar estructura con confirmacion + +### Estados +- Loading: Spinner centrado +- Error: Mensaje de error +- Empty: Icono + mensaje + CTA +- Success: Grid de tarjetas + +### Acciones del Usuario +| Accion | Resultado | +|--------|-----------| +| Click "+ Add Structure" | Navega a formulario | +| Cambiar filtro tipo | Filtra estructuras | +| Cambiar filtro estado | Filtra estructuras | +| Buscar | Filtra por nombre | +| Click "View Details" | Navega a detalle | +| Click "Delete" | Confirm + elimina | + +### Permisos Requeridos +- `mlm:read` - Ver listado +- `mlm:write` - Crear/editar +- `mlm:delete` - Eliminar + +--- + +## 3. MyNetworkPage + +**Ruta:** `/dashboard/mlm/my-network` +**Archivo:** `src/pages/dashboard/mlm/MyNetworkPage.tsx` + +### Descripcion +Vista de la red personal del usuario. Muestra arbol jerarquico de downline, estadisticas y permite generar enlaces de invitacion. + +### Componentes Utilizados +- Invite Link Banner - Banner con link de invitacion +- Summary Cards - Metricas de red +- My Rank Card - Tarjeta de rango actual +- Volume Summary Card - Resumen de volumenes +- Network Tree - Arbol de red con nodos expandibles +- Quick Actions - Enlaces rapidos + +### Hooks Utilizados +- `useMyDashboard()` - Datos del dashboard +- `useMyNetwork(maxDepth)` - Arbol de red con profundidad configurable +- `useMyRank()` - Informacion de rango +- `useGenerateInviteLink()` - Genera link de invitacion + +### Funcionalidades +1. Generar link de invitacion unico +2. Copiar link al clipboard +3. Ver metricas (downline total, referidos directos, activos, volumen grupo) +4. Ver rango actual con color y nivel +5. Ver volumenes (personal, grupo, ganancias) +6. Ver arbol de red con profundidad configurable (1-10 niveles) +7. Ver status de cada nodo (pending, active, inactive, suspended) + +### Estados +- Loading: Spinner centrado +- Success: Dashboard con arbol +- Empty Network: Mensaje "You're not part of any MLM structure" +- Invite Generated: Muestra banner con link + +### Acciones del Usuario +| Accion | Resultado | +|--------|-----------| +| Click "Generate Invite Link" | Genera y muestra link | +| Click "Copy" | Copia link al clipboard | +| Cambiar selector depth | Recarga arbol con nueva profundidad | +| Click Quick Action | Navega a seccion | + +### Permisos Requeridos +- Usuario autenticado + +--- + +## 4. RanksPage + +**Ruta:** `/dashboard/mlm/ranks` +**Archivo:** `src/pages/dashboard/mlm/RanksPage.tsx` + +### Descripcion +Gestion de rangos MLM. Permite ver, crear, editar y eliminar rangos con sus requisitos y bonificaciones. + +### Componentes Utilizados +- Filters Panel - Filtro por estructura y estado +- Ranks Table - Tabla con nivel, badge, requisitos +- Level Badge - Badge circular con color y nivel +- Requirements Display - Muestra PV, GV, referidos + +### Hooks Utilizados +- `useRanks(filters)` - Lista rangos con filtros +- `useStructures({isActive: true})` - Estructuras para filtro +- `useDeleteRank()` - Elimina rango +- `useEvaluateRanks(structureId)` - Evalua rangos de toda la estructura + +### Funcionalidades +1. Filtrar por estructura +2. Filtrar por estado (activo/inactivo) +3. Ver tabla con nivel, nombre, requisitos, bonus rate, estado +4. Evaluar rangos de todos los miembros de una estructura +5. Editar y eliminar rangos + +### Estados +- Loading: Spinner centrado +- Error: Mensaje de error +- Empty: Icono + mensaje + CTA +- Success: Tabla de rangos + +### Acciones del Usuario +| Accion | Resultado | +|--------|-----------| +| Click "+ Add Rank" | Navega a formulario | +| Seleccionar estructura | Filtra rangos | +| Click "Evaluate All Ranks" | Evalua y actualiza rangos | +| Click "Edit" | Navega a edicion | +| Click "Delete" | Confirm + elimina | + +### Permisos Requeridos +- `mlm:read` - Ver listado +- `mlm:write` - Crear/editar/evaluar +- `mlm:delete` - Eliminar + +--- + +## 5. MyEarningsPage (MLM) + +**Ruta:** `/dashboard/mlm/my-earnings` +**Archivo:** `src/pages/dashboard/mlm/MyEarningsPage.tsx` + +### Descripcion +Vista de ganancias MLM del usuario. Muestra comisiones por nivel, bonos y historial. + +### Componentes Utilizados +- Earnings Summary Cards - Tarjetas de resumen +- Earnings by Level Chart - Grafico por nivel +- Recent Commissions Table - Tabla de comisiones recientes + +### Hooks Utilizados +- `useMyMLMEarnings()` - Ganancias MLM del usuario + +### Funcionalidades +1. Ver total de ganancias +2. Ver ganancias por nivel de la red +3. Ver bonificaciones +4. Ver historial de comisiones + +### Estados +- Loading: Spinner centrado +- Empty: Mensaje sin datos +- Success: Dashboard de ganancias + +### Permisos Requeridos +- Usuario autenticado + +--- + +*Documentacion generada - Template SaaS - 2026-02-03* diff --git a/docs/05-frontend/pages/PAGE-NOTIFICATIONS-ADMIN.md b/docs/05-frontend/pages/PAGE-NOTIFICATIONS-ADMIN.md new file mode 100644 index 00000000..35c67c21 --- /dev/null +++ b/docs/05-frontend/pages/PAGE-NOTIFICATIONS-ADMIN.md @@ -0,0 +1,149 @@ +# Notifications Admin Pages Specification + +**Modulo:** notifications +**Ultima actualizacion:** 2026-02-03 +**Total Paginas:** 2 + +--- + +## 1. NotificationsPage + +**Ruta:** `/dashboard/notifications` +**Archivo:** `src/pages/dashboard/notifications/NotificationsPage.tsx` + +### Descripcion +Centro de notificaciones del usuario. Muestra notificaciones recibidas con tabs para filtrar y configurar preferencias. + +### Componentes Utilizados +- Tab Navigation - Tabs All/Unread/Settings +- Notification Item - Card de notificacion con acciones +- Preferences Section - Toggles de preferencias +- Pagination - Navegacion de paginas +- Icons: Bell, CheckCheck, ExternalLink, Settings, Mail, Smartphone, MessageSquare, FileText (lucide-react) + +### Hooks Utilizados +- `useNotifications({page, limit, unreadOnly})` - Lista notificaciones +- `useUnreadCount()` - Contador de no leidas +- `useMarkAsRead()` - Marca como leida +- `useMarkAllAsRead()` - Marca todas como leidas +- `useNotificationPreferences()` - Obtiene preferencias +- `useUpdatePreferences()` - Actualiza preferencias +- `getNotificationTypeColor()` - Color segun tipo +- `formatNotificationTime()` - Formato de tiempo + +### Funcionalidades +1. Ver notificaciones con titulo, cuerpo, tiempo +2. Filtrar por todas o solo no leidas +3. Marcar individual como leida +4. Marcar todas como leidas +5. Ver action link si existe +6. Configurar preferencias por canal (email, push, in-app, SMS) +7. Navegar a gestion de templates + +### Estados +- Loading: Spinner centrado +- Success: Lista de notificaciones +- Empty All: "No notifications yet" +- Empty Unread: "No unread notifications" + +### Acciones del Usuario +| Accion | Resultado | +|--------|-----------| +| Click tab "All" | Muestra todas | +| Click tab "Unread" | Filtra no leidas | +| Click tab "Settings" | Muestra preferencias | +| Click "Mark as read" | Marca como leida | +| Click "Mark all as read" | Confirm + marca todas | +| Click action link | Navega a URL | +| Toggle preferencia | Actualiza setting | +| Click "Manage Templates" | Navega a templates | +| Click Previous/Next | Cambia pagina | + +### Permisos Requeridos +- Usuario autenticado + +--- + +## 2. TemplatesPage + +**Ruta:** `/dashboard/notifications/templates` +**Archivo:** `src/pages/dashboard/notifications/TemplatesPage.tsx` + +### Descripcion +Gestion de templates de notificacion. Permite crear, editar, previsualizar y gestionar templates para diferentes canales. + +### Componentes Utilizados +- Search Input - Busqueda de templates +- Channel Filter - Filtro por canal (email, push, in_app, sms) +- Category Filter - Filtro por categoria +- Templates Grid - Grid de cards de template +- TemplateCard - Card con preview y acciones +- TemplateForm - Formulario de creacion/edicion +- TemplatePreview - Modal de preview +- Delete Confirmation Modal - Modal de confirmacion +- Icons: Plus, ArrowLeft, FileText, AlertTriangle, Search, Filter (lucide-react) + +### Hooks Utilizados +- `useNotificationTemplates()` - Lista templates +- `useCreateTemplate()` - Crea template +- `useUpdateTemplate()` - Actualiza template +- `useDeleteTemplate()` - Elimina template +- `useToggleTemplateActive()` - Activa/desactiva template + +### Funcionalidades +1. Buscar templates por nombre, codigo o descripcion +2. Filtrar por canal (email, push, in_app, sms) +3. Filtrar por categoria +4. Ver grid de templates con preview rapido +5. Toggle active/inactive desde card +6. Crear nuevo template con formulario completo +7. Editar template existente +8. Previsualizar template +9. Eliminar template con confirmacion + +### Estados +- View Modes: list, create, edit +- Loading: Spinner en grid +- Success: Grid de templates +- Empty: "No templates yet" + CTA +- Filtered Empty: "No matching templates" + +### Acciones del Usuario +| Accion | Resultado | +|--------|-----------| +| Click "Create Template" | Cambia a vista create | +| Buscar | Filtra templates | +| Seleccionar canal | Filtra por canal | +| Seleccionar categoria | Filtra por categoria | +| Click edit en card | Cambia a vista edit | +| Click preview en card | Abre modal preview | +| Click delete en card | Abre modal confirm | +| Toggle active | Activa/desactiva | +| Submit form | Crea o actualiza | +| Click "Cancel" | Vuelve a lista | +| Confirm delete | Elimina template | + +### Permisos Requeridos +- `notifications:read` - Ver templates +- `notifications:write` - Crear/editar/toggle +- `notifications:delete` - Eliminar templates + +### Notas +- Los templates usan variables con formato `{{variable}}` +- Cada canal tiene campos especificos (email tiene subject, html_body) +- La preview muestra como se veria la notificacion + +--- + +## Canales de Notificacion + +| Canal | Campos | Descripcion | +|-------|--------|-------------| +| email | subject, html_body, text_body | Correo electronico | +| push | title, body | Notificacion push del navegador | +| in_app | title, body, action_url | Notificacion dentro de la app | +| sms | body | Mensaje SMS | + +--- + +*Documentacion generada - Template SaaS - 2026-02-03* diff --git a/docs/05-frontend/pages/PAGE-PORTFOLIO.md b/docs/05-frontend/pages/PAGE-PORTFOLIO.md new file mode 100644 index 00000000..d330718e --- /dev/null +++ b/docs/05-frontend/pages/PAGE-PORTFOLIO.md @@ -0,0 +1,163 @@ +# Portfolio Pages Specification + +**Modulo:** portfolio +**Ultima actualizacion:** 2026-02-03 +**Total Paginas:** 3 + +--- + +## 1. PortfolioPage (Dashboard) + +**Ruta:** `/dashboard/portfolio` +**Archivo:** `src/pages/dashboard/portfolio/PortfolioPage.tsx` + +### Descripcion +Dashboard principal del catalogo de productos. Muestra estadisticas, categorias y productos recientes con busqueda global. + +### Componentes Utilizados +- Search Input - Busqueda global con icono +- Filter Button - Boton de filtros (placeholder) +- Stats Cards - 4 tarjetas con metricas +- Categories Panel - Panel con lista de categorias +- Recent Products Panel - Panel con productos recientes +- Icons: Package, FolderTree, Plus, Search, Filter (lucide-react) + +### Hooks Utilizados +- `useCategories()` - Lista categorias +- `useProducts({limit: 10})` - Lista productos recientes + +### Funcionalidades +1. Buscar productos o categorias (UI, sin filtrado implementado) +2. Ver estadisticas (total productos, categorias, activos, borradores) +3. Ver lista de categorias (max 5) con link a todas +4. Ver productos recientes (max 5) con status badge +5. Crear nueva categoria o producto via botones header + +### Estados +- Loading: Spinner en cada panel +- Success: Dashboard completo +- Empty Categories: Mensaje "No categories yet" +- Empty Products: Mensaje "No products yet" + +### Acciones del Usuario +| Accion | Resultado | +|--------|-----------| +| Click "New Category" | Navega a /portfolio/categories/new | +| Click "New Product" | Navega a /portfolio/products/new | +| Click categoria | Navega a detalle | +| Click producto | Navega a detalle | +| Click "View all" | Navega a listado completo | + +### Permisos Requeridos +- `portfolio:read` - Ver catalogo + +--- + +## 2. ProductsPage + +**Ruta:** `/dashboard/portfolio/products` +**Archivo:** `src/pages/dashboard/portfolio/ProductsPage.tsx` + +### Descripcion +Listado de productos con filtros, busqueda y acciones CRUD. Tabla paginada con acciones inline. + +### Componentes Utilizados +- Search Input - Busqueda por nombre +- Status Filter Select - Filtro por estado +- Products Table - Tabla con columnas y paginacion +- Status Badge - Badge con color segun estado +- Action Icons: Eye, Edit, Copy, Trash2 (lucide-react) + +### Hooks Utilizados +- `useProducts({page, limit, search, status})` - Lista productos con filtros +- `useDeleteProduct()` - Elimina producto +- `useDuplicateProduct()` - Duplica producto + +### Funcionalidades +1. Buscar por nombre de producto +2. Filtrar por estado (draft, active, inactive, discontinued, out_of_stock) +3. Ver tabla con nombre, tipo, SKU, categoria, precio, estado +4. Paginacion con 20 items por pagina +5. Ver detalle, editar, duplicar, eliminar desde acciones + +### Estados +- Loading: Spinner en tabla +- Success: Tabla con productos +- Empty: Mensaje "No products found" + CTA + +### Acciones del Usuario +| Accion | Resultado | +|--------|-----------| +| Click "New Product" | Navega a formulario | +| Buscar | Filtra tabla | +| Cambiar filtro estado | Filtra tabla | +| Click View icon | Navega a detalle | +| Click Edit icon | Navega a edicion | +| Click Copy icon | Duplica producto | +| Click Delete icon | Confirm + elimina | +| Click Previous/Next | Cambia pagina | + +### Permisos Requeridos +- `portfolio:read` - Ver listado +- `portfolio:write` - Crear/editar/duplicar +- `portfolio:delete` - Eliminar + +--- + +## 3. CategoriesPage + +**Ruta:** `/dashboard/portfolio/categories` +**Archivo:** `src/pages/dashboard/portfolio/CategoriesPage.tsx` + +### Descripcion +Gestion de categorias en estructura de arbol jerarquico. Permite expandir/colapsar y buscar categorias. + +### Componentes Utilizados +- Search Input - Busqueda de categorias +- Category Tree - Arbol jerarquico recursivo +- CategoryTreeNode - Nodo individual con expand/collapse +- Expand/Collapse All Button - Toggle global +- Icons: FolderTree, Plus, Search, Edit, Trash2, ChevronRight, ChevronDown (lucide-react) + +### Hooks Utilizados +- `useCategoryTree()` - Arbol de categorias +- `useDeleteCategory()` - Elimina categoria + +### Funcionalidades +1. Buscar categorias (filtra arbol recursivamente) +2. Expandir/colapsar nodos individuales +3. Expandir/colapsar todos +4. Ver count de productos por categoria +5. Ver estado activo/inactivo +6. Editar y eliminar desde cada nodo + +### Estados +- Loading: Spinner centrado +- Success: Arbol de categorias +- Empty: Icono + mensaje +- Filtered Empty: Mensaje "No categories match your search" + +### Acciones del Usuario +| Accion | Resultado | +|--------|-----------| +| Click "New Category" | Navega a formulario | +| Click chevron | Expande/colapsa nodo | +| Click "Expand/Collapse all" | Toggle global | +| Buscar | Filtra arbol | +| Click nombre categoria | Navega a detalle | +| Click Edit icon | Navega a edicion | +| Click Delete icon | Confirm + elimina (productos quedan sin categoria) | + +### Permisos Requeridos +- `portfolio:read` - Ver listado +- `portfolio:write` - Crear/editar +- `portfolio:delete` - Eliminar + +### Notas +- La eliminacion de categoria NO elimina productos, los deja sin categoria +- El arbol soporta multiples niveles de anidacion +- La busqueda muestra padres de resultados para mantener contexto + +--- + +*Documentacion generada - Template SaaS - 2026-02-03* diff --git a/docs/05-frontend/pages/PAGE-RBAC.md b/docs/05-frontend/pages/PAGE-RBAC.md new file mode 100644 index 00000000..ca294954 --- /dev/null +++ b/docs/05-frontend/pages/PAGE-RBAC.md @@ -0,0 +1,138 @@ +# RBAC Pages Specification + +**Modulo:** rbac +**Ultima actualizacion:** 2026-02-03 +**Total Paginas:** 2 + +--- + +## 1. RolesPage + +**Ruta:** `/dashboard/rbac/roles` +**Archivo:** `src/pages/dashboard/rbac/RolesPage.tsx` + +### Descripcion +Gestion de roles de usuario. Vista master-detail con lista de roles a la izquierda y detalle de permisos a la derecha. + +### Componentes Utilizados +- Search Input - Busqueda de roles +- Roles List - Lista seleccionable de roles +- Role Card - Tarjeta de rol con icono y contador +- Role Detail Panel - Panel derecho con info y permisos +- Permission Tags - Tags agrupados por categoria +- Lock Icon - Indica roles de sistema +- Icons: Shield, Plus, Search, Edit, Trash2, Lock (lucide-react) + +### Hooks Utilizados +- `useRoles()` - Lista todos los roles +- `usePermissions()` - Lista todos los permisos (para agrupar) +- `useDeleteRole()` - Elimina rol +- `getPermissionCategoryLabel()` - Labels de categorias + +### Funcionalidades +1. Buscar roles por nombre +2. Ver lista de roles con contador de permisos +3. Identificar roles de sistema (bloqueados) +4. Seleccionar rol para ver detalle +5. Ver info del rol (tipo, default, slug) +6. Ver permisos agrupados por categoria +7. Editar y eliminar roles custom (no system) + +### Estados +- Loading: Spinner en lista +- Success: Layout master-detail +- No Selection: Panel derecho con mensaje "Select a role" +- Empty Search: Mensaje "No roles found" + +### Acciones del Usuario +| Accion | Resultado | +|--------|-----------| +| Click "New Role" | Navega a /rbac/roles/new | +| Buscar | Filtra lista de roles | +| Click en rol | Selecciona y muestra detalle | +| Click "Edit" | Navega a edicion (solo custom) | +| Click "Delete" | Confirm + elimina (solo custom) | +| Click en rol system | Alerta "System roles cannot be deleted" | + +### Permisos Requeridos +- `rbac:read` - Ver roles y permisos +- `rbac:write` - Crear/editar roles +- `rbac:delete` - Eliminar roles + +### Notas +- Roles de sistema (is_system: true) no pueden editarse ni eliminarse +- El rol default se asigna automaticamente a nuevos usuarios + +--- + +## 2. PermissionsPage + +**Ruta:** `/dashboard/rbac/permissions` +**Archivo:** `src/pages/dashboard/rbac/PermissionsPage.tsx` + +### Descripcion +Vista de todos los permisos del sistema. Solo lectura, agrupados por categoria con filtros. + +### Componentes Utilizados +- Stats Cards - Metricas de permisos +- Search Input - Busqueda de permisos +- Category Filter Select - Filtro por categoria +- Permissions List - Lista agrupada por categoria +- Permission Item - Item con nombre, action badge, descripcion, slug +- Action Badge - Badge con color segun accion (read, write, delete, assign) +- Icons: Key, Shield, Filter, Search (lucide-react) + +### Hooks Utilizados +- `usePermissions()` - Lista todos los permisos +- `getPermissionCategoryLabel(category)` - Label de categoria +- `getPermissionActionLabel(action)` - Label de accion + +### Funcionalidades +1. Ver estadisticas (total permisos, categorias, filtrados) +2. Buscar por nombre, slug o descripcion +3. Filtrar por categoria +4. Ver permisos agrupados por categoria +5. Ver accion con color (read=gray, write=yellow, delete=red, assign=purple) +6. Ver slug tecnico de cada permiso + +### Estados +- Loading: Spinner centrado +- Error: Mensaje de error +- Success: Lista agrupada +- Empty Filter: Icono + mensaje "No permissions found matching your criteria" + +### Acciones del Usuario +| Accion | Resultado | +|--------|-----------| +| Buscar | Filtra permisos | +| Seleccionar categoria | Filtra por categoria | +| (Solo lectura) | - | + +### Permisos Requeridos +- `rbac:read` - Ver permisos + +### Notas +- Esta pagina es SOLO lectura +- Los permisos son definidos por el sistema, no se pueden crear/editar/eliminar +- Sirve como referencia para administradores al asignar roles + +--- + +## Diagrama de Flujo RBAC + +``` +Usuario → tiene → Roles +Roles → tienen → Permisos +Permisos → definen → Acciones permitidas + +Ejemplo: +- Usuario "John" + → Rol "Admin" + → Permiso "users:read" (puede ver usuarios) + → Permiso "users:write" (puede editar usuarios) + → Permiso "users:delete" (puede eliminar usuarios) +``` + +--- + +*Documentacion generada - Template SaaS - 2026-02-03* diff --git a/docs/05-frontend/pages/PAGE-SETTINGS.md b/docs/05-frontend/pages/PAGE-SETTINGS.md new file mode 100644 index 00000000..f1afeb63 --- /dev/null +++ b/docs/05-frontend/pages/PAGE-SETTINGS.md @@ -0,0 +1,179 @@ +# Settings Pages Specification + +**Modulo:** settings +**Ultima actualizacion:** 2026-02-03 +**Total Paginas:** 4 + +--- + +## 1. SettingsPage (Container) + +**Ruta:** `/dashboard/settings` +**Archivo:** `src/pages/settings/SettingsPage.tsx` + +### Descripcion +Pagina contenedora de configuracion con navegacion por tabs. Agrupa las diferentes secciones de configuracion del usuario. + +### Componentes Utilizados +- Tabs Navigation - Navegacion entre secciones +- Tab Content - Contenido dinamico segun tab + +### Hooks Utilizados +- `useAuth()` - Estado de autenticacion +- `useCurrentUser()` - Datos del usuario actual + +### Tabs Disponibles + +| Tab | Componente | Descripcion | +|-----|------------|-------------| +| General | GeneralSettings | Perfil del usuario | +| Notifications | NotificationSettings | Preferencias de notificaciones | +| Security | SecuritySettings | Password y sesiones | +| AI | AISettings | Configuracion de IA | + +### Acciones del Usuario +| Accion | Resultado | +|--------|-----------| +| Click en tab | Cambia seccion | + +### Permisos Requeridos +- Usuario autenticado + +--- + +## 2. GeneralSettings + +**Archivo:** `src/pages/settings/GeneralSettings.tsx` + +### Descripcion +Configuracion del perfil del usuario. Permite editar nombre y avatar. + +### Componentes Utilizados +- Profile Form - Formulario de perfil +- Avatar Upload - Subir/cambiar avatar + +### Hooks Utilizados +- `useCurrentUser()` - Datos actuales +- `useUpdateProfile()` - Actualiza perfil +- `useForm()` - Manejo de formulario + +### Campos del Formulario + +| Campo | Tipo | Validacion | Editable | +|-------|------|------------|----------| +| First name | text | Opcional | Si | +| Last name | text | Opcional | Si | +| Email | email | Requerido | No (read-only) | +| Avatar | file | Image only | Si | + +### Estados +- Loading: Skeleton del formulario +- Success: Formulario con datos +- Saving: Boton disabled + spinner + +### Acciones del Usuario +| Accion | Resultado | +|--------|-----------| +| Editar campos | Habilita boton guardar | +| Click avatar | Abre file picker | +| Submit | Guarda cambios | + +--- + +## 3. NotificationSettings + +**Archivo:** `src/pages/settings/NotificationSettings.tsx` + +### Descripcion +Preferencias de notificaciones del usuario. Configura canales y tipos de eventos. + +### Componentes Utilizados +- Toggle Switches - Switches para on/off +- Event Checkboxes - Seleccion de eventos + +### Hooks Utilizados +- `useNotificationPreferences()` - Preferencias actuales +- `useUpdatePreferences()` - Actualiza preferencias + +### Configuraciones Disponibles + +| Categoria | Opciones | +|-----------|----------| +| Canales | Email, Push, In-app | +| Eventos | Billing, Security, Updates, Marketing | + +### Estados +- Loading: Skeletons de toggles +- Success: Toggles con estado actual +- Saving: Toggle disabled momentaneamente + +### Acciones del Usuario +| Accion | Resultado | +|--------|-----------| +| Toggle canal | Activa/desactiva canal | +| Toggle evento | Activa/desactiva evento | + +--- + +## 4. SecuritySettings + +**Archivo:** `src/pages/settings/SecuritySettings.tsx` + +### Descripcion +Configuracion de seguridad de la cuenta. Permite cambiar password y ver sesiones activas. + +### Componentes Utilizados +- Password Form - Formulario de cambio de password +- Sessions List - Lista de sesiones activas + +### Hooks Utilizados +- `useAuth()` - Operaciones de auth +- `useChangePassword()` - Cambia password +- `useSessions()` - Lista sesiones +- `useRevokeSession()` - Cierra sesion + +### Secciones + +#### Cambiar Password + +| Campo | Tipo | Validacion | +|-------|------|------------| +| Current password | password | Requerido | +| New password | password | Min 8 chars, complexity | +| Confirm password | password | Debe coincidir | + +#### Sesiones Activas + +| Info | Descripcion | +|------|-------------| +| Device | Tipo de dispositivo | +| Browser | Navegador | +| IP | Direccion IP | +| Location | Ubicacion aproximada | +| Last active | Ultima actividad | +| Current | Si es la sesion actual | + +### Estados +- Loading: Spinner en secciones +- Success: Formulario y lista +- Password Changed: Toast de exito +- Session Revoked: Toast de exito + +### Acciones del Usuario +| Accion | Resultado | +|--------|-----------| +| Submit password form | Cambia password | +| Click "Revoke" en sesion | Cierra sesion remota | +| Click "Revoke all" | Cierra todas menos actual | + +### Permisos Requeridos +- Usuario autenticado + +### Notas +- La sesion actual no puede revocarse desde aqui +- El cambio de password cierra otras sesiones +- MFA esta planificado pero no implementado + +--- + +*Documentacion generada - Template SaaS - 2026-02-03* diff --git a/docs/05-frontend/pages/PAGE-STORAGE.md b/docs/05-frontend/pages/PAGE-STORAGE.md new file mode 100644 index 00000000..bb1522b2 --- /dev/null +++ b/docs/05-frontend/pages/PAGE-STORAGE.md @@ -0,0 +1,88 @@ +# Storage Page Specification + +**Modulo:** storage +**Ultima actualizacion:** 2026-02-03 +**Total Paginas:** 1 + +--- + +## StoragePage + +**Ruta:** `/dashboard/storage` +**Archivo:** `src/pages/dashboard/StoragePage.tsx` + +### Descripcion +Gestion de archivos del tenant. Permite subir, listar, filtrar, descargar y eliminar archivos con visualizacion del uso de almacenamiento. + +### Componentes Utilizados +- FileList - Tabla/grid de archivos +- FileUpload - Zona de drag & drop +- FileItem - Item individual de archivo +- StorageUsageCard - Tarjeta de uso de storage + +### Hooks Utilizados +- `useFiles(filters)` - Lista archivos con filtros +- `useUpload()` - Sube archivos +- `useStorageUsage()` - Obtiene uso de storage +- `useDeleteFile()` - Elimina archivo + +### Funcionalidades +1. Subir archivos via drag & drop o click +2. Listar archivos con paginacion +3. Filtrar por carpeta/tipo de archivo +4. Buscar por nombre +5. Descargar archivos +6. Eliminar archivos con confirmacion +7. Ver uso de storage vs limite del plan +8. Preview de imagenes +9. Ver metadata (tamano, tipo, fecha) + +### Estados +- Loading: Spinner en lista +- Uploading: Progress bar durante upload +- Success: Lista de archivos +- Empty: Mensaje "No files uploaded" +- Storage Full: Warning cuando esta lleno + +### Acciones del Usuario +| Accion | Resultado | +|--------|-----------| +| Drag & drop archivo | Inicia upload | +| Click zona upload | Abre file picker | +| Click descargar | Descarga archivo | +| Click eliminar | Confirm + elimina | +| Filtrar por tipo | Filtra lista | +| Buscar | Filtra por nombre | +| Previous/Next | Cambia pagina | + +### Permisos Requeridos +- `storage:read` - Ver archivos +- `storage:write` - Subir archivos +- `storage:delete` - Eliminar archivos + +### Tipos de Archivo Soportados + +| Categoria | Extensiones | MIME Types | +|-----------|-------------|------------| +| Images | jpg, jpeg, png, gif, webp | image/* | +| Documents | pdf, doc, docx, xls, xlsx | application/* | +| Text | txt, csv, json | text/* | +| Archives | zip, rar, tar, gz | application/* | + +### Limites por Plan + +| Plan | Storage | Max File Size | +|------|---------|---------------| +| Free | 1 GB | 10 MB | +| Pro | 10 GB | 100 MB | +| Enterprise | 100 GB | 1 GB | + +### Notas +- Los archivos son privados por tenant (RLS) +- Los uploads usan presigned URLs para eficiencia +- Se genera thumbnail automatico para imagenes +- Los archivos eliminados van a "trash" por 30 dias + +--- + +*Documentacion generada - Template SaaS - 2026-02-03* diff --git a/docs/05-frontend/pages/PAGE-WEBHOOKS.md b/docs/05-frontend/pages/PAGE-WEBHOOKS.md new file mode 100644 index 00000000..3b1125d4 --- /dev/null +++ b/docs/05-frontend/pages/PAGE-WEBHOOKS.md @@ -0,0 +1,109 @@ +# Webhooks Page Specification + +**Modulo:** webhooks +**Ultima actualizacion:** 2026-02-03 +**Total Paginas:** 1 + +--- + +## WebhooksPage + +**Ruta:** `/dashboard/webhooks` +**Archivo:** `src/pages/dashboard/WebhooksPage.tsx` + +### Descripcion +Configuracion de webhooks outbound. Permite crear endpoints que reciben notificaciones de eventos del sistema. + +### Componentes Utilizados +- WebhookCard - Tarjeta de webhook con estado +- WebhookForm - Formulario de creacion/edicion +- WebhookDeliveryList - Lista de entregas recientes +- EventSelector - Selector de eventos a escuchar + +### Hooks Utilizados +- `useWebhooks()` - Lista webhooks +- `useCreateWebhook()` - Crea webhook +- `useUpdateWebhook()` - Actualiza webhook +- `useDeleteWebhook()` - Elimina webhook +- `useWebhookDeliveries(webhookId)` - Lista entregas +- `useRetryDelivery()` - Reintenta entrega fallida +- `useTestWebhook()` - Envia test + +### Funcionalidades +1. Crear nuevo webhook con URL y eventos +2. Configurar headers custom (ej: Authorization) +3. Ver estado (active/paused) +4. Ver historial de entregas con status +5. Reintentar entregas fallidas +6. Enviar evento de test +7. Ver secreto para validar firma +8. Editar y eliminar webhooks + +### Eventos Disponibles + +| Evento | Descripcion | +|--------|-------------| +| user.created | Usuario creado | +| user.updated | Usuario actualizado | +| user.deleted | Usuario eliminado | +| subscription.created | Suscripcion creada | +| subscription.updated | Suscripcion actualizada | +| subscription.cancelled | Suscripcion cancelada | +| invoice.paid | Factura pagada | +| invoice.failed | Pago fallido | + +### Estados +- Loading: Spinner en lista +- Success: Lista de webhooks +- Empty: Mensaje "No webhooks configured" +- Delivery Success: Badge verde +- Delivery Failed: Badge rojo con retry + +### Acciones del Usuario +| Accion | Resultado | +|--------|-----------| +| Click "Create Webhook" | Abre formulario | +| Submit formulario | Crea webhook | +| Click "Edit" | Abre edicion | +| Click "Delete" | Confirm + elimina | +| Click "Test" | Envia evento test | +| Click "Retry" en delivery | Reintenta envio | +| Toggle active | Activa/pausa webhook | + +### Permisos Requeridos +- `webhooks:read` - Ver webhooks y entregas +- `webhooks:write` - Crear/editar webhooks +- `webhooks:delete` - Eliminar webhooks + +### Estructura de Entrega + +```typescript +interface WebhookDelivery { + id: string; + webhook_id: string; + event: string; + payload: Record; + response_status?: number; + response_body?: string; + error?: string; + attempts: number; + delivered_at?: string; + created_at: string; +} +``` + +### Seguridad + +- Cada webhook tiene un `secret` unico +- Las entregas incluyen header `X-Webhook-Signature` con HMAC-SHA256 +- Los endpoints deben responder con 2xx en 30 segundos +- Reintentos automaticos: 3 intentos con backoff exponencial + +### Notas +- Los webhooks pausados no reciben eventos +- Las entregas fallidas se retienen por 7 dias +- El payload incluye `event`, `data`, `timestamp` y `webhook_id` + +--- + +*Documentacion generada - Template SaaS - 2026-02-03* diff --git a/docs/05-frontend/pages/_INDEX.md b/docs/05-frontend/pages/_INDEX.md new file mode 100644 index 00000000..4a677962 --- /dev/null +++ b/docs/05-frontend/pages/_INDEX.md @@ -0,0 +1,57 @@ +# Frontend Pages Documentation Index + +**Proyecto:** template-saas +**Actualizado:** 2026-02-03 +**Total de Especificaciones:** 10 + +--- + +## Documentacion Detallada de Paginas + +Esta carpeta contiene especificaciones detalladas de paginas que no estan cubiertas en el archivo principal `FRONTEND-PAGES-SPEC.md`. + +--- + +## Indice de Especificaciones + +| Archivo | Modulo | Paginas | Descripcion | +|---------|--------|---------|-------------| +| [PAGE-GOALS.md](./PAGE-GOALS.md) | goals | 5 | Sistema de metas y objetivos | +| [PAGE-MLM.md](./PAGE-MLM.md) | mlm | 5 | Marketing multinivel | +| [PAGE-PORTFOLIO.md](./PAGE-PORTFOLIO.md) | portfolio | 3 | Catalogo de productos | +| [PAGE-RBAC.md](./PAGE-RBAC.md) | rbac | 2 | Roles y permisos | +| [PAGE-NOTIFICATIONS-ADMIN.md](./PAGE-NOTIFICATIONS-ADMIN.md) | notifications | 2 | Gestion de notificaciones | +| [PAGE-ANALYTICS.md](./PAGE-ANALYTICS.md) | analytics | 1 | Dashboard de analiticas | +| [PAGE-AUDIT.md](./PAGE-AUDIT.md) | audit | 1 | Logs de auditoria | +| [PAGE-STORAGE.md](./PAGE-STORAGE.md) | storage | 1 | Gestion de archivos | +| [PAGE-WEBHOOKS.md](./PAGE-WEBHOOKS.md) | webhooks | 1 | Configuracion de webhooks | +| [PAGE-SETTINGS.md](./PAGE-SETTINGS.md) | settings | 4 | Configuracion de cuenta | + +--- + +## Resumen por Modulo + +| Modulo | Total Paginas | Estado | +|--------|---------------|--------| +| Goals | 5 | Documentado | +| MLM | 5 | Documentado | +| Portfolio | 3 | Documentado | +| RBAC | 2 | Documentado | +| Notifications | 2 | Documentado | +| Analytics | 1 | Documentado | +| Audit | 1 | Documentado | +| Storage | 1 | Documentado | +| Webhooks | 1 | Documentado | +| Settings | 4 | Documentado | + +--- + +## Relacion con Otros Documentos + +- **FRONTEND-PAGES-SPEC.md**: Especificacion principal que cubre Auth, Dashboard Core, Sales, Commissions, Superadmin y Onboarding +- **FRONTEND-ROUTING.md**: Definicion de rutas y guards +- Esta carpeta complementa esos documentos con paginas de modulos Sprint 2 + +--- + +*Documentacion generada - Template SaaS - 2026-02-03* diff --git a/frontend b/frontend index 891689a4..9bd1aba3 160000 --- a/frontend +++ b/frontend @@ -1 +1 @@ -Subproject commit 891689a4f448b91e244059942533431e22a2fa86 +Subproject commit 9bd1aba33d9f81cc07837c9d28dcba2117c871ae diff --git a/orchestration/tareas/TASK-2026-02-03-AUDITORIA-FRONTEND-UX-UI/DEAD-CODE-REPORT.md b/orchestration/tareas/TASK-2026-02-03-AUDITORIA-FRONTEND-UX-UI/DEAD-CODE-REPORT.md new file mode 100644 index 00000000..4c0db9e8 --- /dev/null +++ b/orchestration/tareas/TASK-2026-02-03-AUDITORIA-FRONTEND-UX-UI/DEAD-CODE-REPORT.md @@ -0,0 +1,179 @@ +# Reporte de Dead Code - Frontend + +**Fecha:** 2026-02-03 +**Autor:** Claude Opus 4.5 (ST-3.4-DEAD-CODE) +**Proyecto:** template-saas/frontend + +--- + +## Resumen Ejecutivo + +| Categoria | Total | Usados | No Usados | % Uso | +|-----------|-------|--------|-----------|-------| +| Hooks usePortfolio | 21 | 18 | 3 | 86% | +| Componentes Portfolio | 6 | 0 | 6 | 0% | + +--- + +## usePortfolio Hook + +### Total funciones exportadas: 21 + +### Funciones USADAS (18) + +| Funcion | Usada En | +|---------|----------| +| `useCategories` | PortfolioPage.tsx, ProductFormPage.tsx | +| `useCategory` | CategoryDetailPage.tsx | +| `useCategoryTree` | CategoriesPage.tsx | +| `useCreateCategory` | CategoryDetailPage.tsx | +| `useUpdateCategory` | CategoryDetailPage.tsx | +| `useDeleteCategory` | CategoriesPage.tsx, CategoryDetailPage.tsx | +| `useProducts` | PortfolioPage.tsx, ProductsPage.tsx, CategoryDetailPage.tsx | +| `useProduct` | ProductDetailPage.tsx, ProductFormPage.tsx | +| `useCreateProduct` | ProductFormPage.tsx | +| `useUpdateProduct` | ProductFormPage.tsx | +| `useUpdateProductStatus` | ProductDetailPage.tsx | +| `useDuplicateProduct` | ProductDetailPage.tsx, ProductsPage.tsx | +| `useDeleteProduct` | ProductDetailPage.tsx, ProductsPage.tsx | +| `useProductVariants` | ProductDetailPage.tsx | +| `useCreateVariant` | ProductDetailPage.tsx | +| `useDeleteVariant` | ProductDetailPage.tsx | +| `useProductPrices` | ProductDetailPage.tsx | +| `useCreatePrice` | ProductDetailPage.tsx | +| `useDeletePrice` | ProductDetailPage.tsx | + +### Funciones NO USADAS (3) + +| Funcion | Descripcion | Recomendacion | +|---------|-------------|---------------| +| `useUpdateVariant` | Actualiza una variante existente | MANTENER - Se usara para edicion de variantes | +| `useUpdatePrice` | Actualiza un precio existente | MANTENER - Se usara para edicion de precios | +| (ninguna otra) | - | - | + +**Nota:** Las funciones `useUpdateVariant` y `useUpdatePrice` tienen DTOs correspondientes (`UpdateVariantDto`, `UpdatePriceDto`) y siguen el patron CRUD completo. Aunque actualmente los modales solo permiten crear y eliminar, la funcionalidad de edicion es esperada en futuras iteraciones. + +### Decision: MANTENER todas las funciones + +**Razon:** El hook `usePortfolio` implementa un CRUD completo y bien estructurado. Las 3 funciones no usadas (`useUpdateVariant`, `useUpdatePrice`) son parte del patron completo y seran necesarias cuando se agregue funcionalidad de edicion en los modales de variantes y precios. + +--- + +## Componentes Portfolio NO USADOS + +Los siguientes componentes estan exportados en `src/components/portfolio/index.ts` pero NO se importan en ninguna pagina: + +| Componente | Archivo | Lineas | Recomendacion | +|------------|---------|--------|---------------| +| `CategoryTree` | CategoryTree.tsx | 182 | MANTENER - Version reutilizable | +| `CategoryForm` | CategoryForm.tsx | 200 | MANTENER - Modal reutilizable | +| `ProductCard` | ProductCard.tsx | ~100 | MANTENER - Para vista grid futura | +| `ProductFilters` | ProductFilters.tsx | ~150 | MANTENER - Filtros avanzados | +| `VariantList` | VariantList.tsx | ~100 | MANTENER - Lista reutilizable | +| `PriceTable` | PriceTable.tsx | ~100 | MANTENER - Tabla reutilizable | + +### Analisis Detallado + +1. **CategoryTree.tsx** (182 lineas) + - Version mas robusta y reutilizable del arbol de categorias + - Soporta: `selectedId`, `showActions`, callbacks externos + - Las paginas usan una version inline simplificada + - **Decision:** MANTENER para refactorizacion futura + +2. **CategoryForm.tsx** (200 lineas) + - Modal completo para crear/editar categorias + - Soporta: `parentCategories`, `isLoading` + - CategoryDetailPage.tsx tiene formulario inline + - **Decision:** MANTENER para uso futuro en modal + +3. **ProductCard.tsx** + - Componente de tarjeta para vista grid + - ProductsPage.tsx actualmente usa tabla + - **Decision:** MANTENER para toggle grid/list futuro + +4. **ProductFilters.tsx** + - Filtros avanzados por tipo, status, categoria + - ProductsPage.tsx tiene filtros basicos inline + - **Decision:** MANTENER para filtros avanzados + +5. **VariantList.tsx / PriceTable.tsx** + - Versiones reutilizables con edicion inline + - ProductDetailPage.tsx tiene versiones simplificadas + - **Decision:** MANTENER para refactorizacion + +### Decision: NO ELIMINAR componentes + +**Razon:** Estos componentes fueron creados como parte del diseno del modulo Portfolio y representan versiones mas completas y reutilizables. Las paginas actualmente usan implementaciones inline simplificadas. Eliminarlos seria perder trabajo que sera util en futuras mejoras de UX. + +--- + +## Imports No Usados Encontrados + +Tras revision de todos los archivos de Portfolio, NO se encontraron imports no usados significativos. + +Los archivos revisados tienen imports limpios: +- CategoriesPage.tsx: OK +- CategoryDetailPage.tsx: OK +- ProductsPage.tsx: OK +- ProductDetailPage.tsx: OK +- ProductFormPage.tsx: OK +- PortfolioPage.tsx: OK + +--- + +## Codigo Limpiado + +**Ninguno.** No se realizo limpieza de codigo porque: + +1. Las funciones de hooks no usadas son parte del patron CRUD completo +2. Los componentes no usados son versiones reutilizables que seran utiles +3. No se encontraron imports no usados para limpiar + +--- + +## Validaciones + +```bash +cd projects/template-saas/frontend +npm run build +``` + +**Estado:** BUILD FALLA debido a errores de sintaxis en archivos de tests creados por otra subtarea (ST-3.8-UNIT-TESTS). + +**Archivos con errores:** +- `src/__tests__/hooks/useAuth.test.ts` (linea 55): JSX en archivo .ts (deberia ser .tsx) + +**Nota:** Estos errores NO fueron introducidos por esta subtarea (ST-3.4-DEAD-CODE). Son archivos de tests nuevos creados en paralelo. La subtarea ST-3.4 no modifico ningun archivo de codigo fuente. + +**Codigo del Portfolio:** +- Todos los archivos de Portfolio compilan correctamente +- NO se elimino ningun codigo +- NO se introdujeron cambios + +--- + +## Recomendaciones Futuras + +1. **Refactorizar CategoriesPage.tsx** + - Extraer `CategoryTreeNode` a usar el componente `CategoryTree` + - Reducir duplicacion de codigo + +2. **Agregar edicion de variantes/precios** + - Usar `useUpdateVariant` y `useUpdatePrice` existentes + - Completar la experiencia CRUD en ProductDetailPage + +3. **Agregar toggle grid/list en ProductsPage** + - Usar `ProductCard` para vista grid + - Mejorar la experiencia de navegacion + +4. **Usar ProductFilters en ProductsPage** + - Reemplazar filtros inline con componente reutilizable + - Agregar filtros por categoria y tipo + +--- + +## Conclusion + +El frontend de Portfolio tiene una arquitectura bien disenada con hooks CRUD completos y componentes reutilizables preparados. El codigo "no usado" actual representa preparacion para futuras funcionalidades, no dead code real. + +**Recomendacion Final:** NO eliminar codigo. Documentar para implementacion futura.