Este proyecto es un dashboard administrativo avanzado construido con Next.js 15, TypeScript y Tailwind CSS, siguiendo la metodología Atomic Design. Presenta una arquitectura escalable para gestión de usuarios, pedidos, promociones y análisis de satisfacción, con una experiencia de usuario moderna, accesibilidad mejorada y despliegue automático.
- Arquitectura y Funcionamiento
- Características
- Estructura del Proyecto
- Instalación
- Uso y Flujos Principales
- Despliegue Automático
- Contribución
- Licencia
graph TB
subgraph "Frontend (Next.js)"
A[Dashboard Usuario] --> B[Componentes Atomic Design]
C[Dashboard Admin] --> B
B --> D[Atoms]
B --> E[Molecules]
B --> F[Organisms]
D --> G[Buttons, Inputs, Icons]
E --> H[Cards, Dropdowns, Selects]
F --> I[Sidebar, Header, Sheets]
end
subgraph "Estado y Datos"
J[Hooks Personalizados] --> K[Mock Data]
J --> L[Auth Session]
J --> M[User Profile]
end
subgraph "Despliegue"
N[GitHub Actions] --> O[Vercel]
P[SonarCloud] --> Q[Code Quality]
end
A --> J
C --> J
N --> A
N --> C
flowchart TD
A[Inicio de Sesión] --> B{¿Tipo de Usuario?}
B -->|Usuario Regular| C[Dashboard Cliente]
B -->|Administrador| D[Dashboard Admin]
C --> E[Mis Compras]
C --> F[Perfil Personal]
C --> G[Promociones]
D --> H[Búsqueda de Personas]
D --> I[Búsqueda de Pedidos]
D --> J[Panel de Control]
H --> K[Detalle de Persona]
K --> L[Historial de Compras]
K --> M[Editar Información]
K --> N[Agregar Comentarios]
I --> O[Detalle de Pedido]
O --> P[Cambiar Estado]
O --> Q[Agregar Comentarios]
style A fill:#e1f5fe
style C fill:#e8f5e8
style D fill:#fff3e0
graph LR
subgraph "Atoms"
A1[Button] --> A2[Input]
A2 --> A3[Label]
A3 --> A4[Avatar]
A4 --> A5[Skeleton]
end
subgraph "Molecules"
M1[Card] --> M2[Dropdown Menu]
M2 --> M3[User Menu]
M3 --> M4[Color Theme Select]
M4 --> M5[Profile Avatar]
end
subgraph "Organisms"
O1[Sidebar] --> O2[Header]
O2 --> O3[App Sidebar]
O3 --> O4[Sheets]
O4 --> O5[Tables]
end
A1 --> M1
A2 --> M1
A3 --> M3
A4 --> M5
A5 --> O1
M1 --> O1
M2 --> O2
M3 --> O3
M4 --> O2
M5 --> O3
stateDiagram-v2
[*] --> Inicial
Inicial --> Autenticando: Usuario ingresa credenciales
Autenticando --> Autenticado: Credenciales válidas
Autenticando --> Error: Credenciales inválidas
Autenticado --> DashboardCliente: Rol = Cliente
Autenticado --> DashboardAdmin: Rol = Admin
DashboardCliente --> VerPerfil: Navegar a perfil
DashboardCliente --> VerPromociones: Ver promociones
DashboardCliente --> VerHistorial: Ver historial compras
DashboardAdmin --> BuscarPersonas: Buscar usuarios
DashboardAdmin --> BuscarPedidos: Buscar pedidos
DashboardAdmin --> VerDashboard: Ver métricas
BuscarPersonas --> DetallePersona: Seleccionar persona
DetallePersona --> EditarPersona: Editar información
DetallePersona --> VerHistorialPersona: Ver historial
DetallePersona --> AgregarComentario: Agregar comentario
BuscarPedidos --> DetallePedido: Seleccionar pedido
DetallePedido --> CambiarEstado: Cambiar estado
DetallePedido --> AgregarComentarioPedido: Agregar comentario
Error --> Inicial: Reintentar
VerPerfil --> DashboardCliente: Volver
EditarPersona --> DetallePersona: Guardar cambios
CambiarEstado --> DetallePedido: Actualizar estado
sequenceDiagram
participant U as Usuario
participant C as Componente
participant H as Hook
participant M as Mock Data
participant S as Estado Local
U->>C: Interacción (click, input)
C->>H: Llamada a hook personalizado
H->>M: Solicitud de datos mock
M-->>H: Datos simulados
H->>S: Actualización de estado
S-->>H: Estado actualizado
H-->>C: Datos procesados
C-->>U: UI actualizada
Note over H,M: useAuth, useUserProfile, usePromociones
Note over S: Loading, Error, Success states
- Atomic Design: Componentes atómicos, moleculares y organismos reutilizables.
- Gestión de usuarios y pedidos: Búsqueda, edición, historial, comentarios y cambio de estado.
- Sheets atómicos: Para comentarios, edición de estado, perfil, contraseña y registro.
- Feedback visual: Skeletons, toasts personalizados, animaciones en íconos (Tailwind + Radix).
- Manejo de errores diferenciado: 404 vs. error de carga, con reintento solo cuando aplica.
- Breadcrumbs dinámicos y navegación clara.
- Despliegue automático en Vercel vía GitHub Actions.
- Documentación clara y estructura profesional lista para conectar a backend real.
src/components/atoms/: Elementos básicos (botones, inputs, íconos, skeletons, etc.)src/components/molecules/: Combinaciones de átomos (select, sidebar, cards, etc.)src/components/organisms/: Sheets, tablas, sidebar, header, etc.src/app/: Rutas y layouts principales (admin, dashboard, etc.).github/workflows/: Workflows de CI/CD para despliegue automático.
- Node.js (v14 o superior)
- npm o pnpm
- Clona el repositorio:
git clone <repository-url> - Entra al directorio del proyecto:
cd CourierSync - Instala las dependencias:
npm install # o pnpm install
- Inicia el servidor de desarrollo:
Accede a
npnm run devhttp://localhost:3000. - Explora el dashboard administrativo, busca usuarios/pedidos, edita estados, agrega comentarios y navega entre perfiles.
- Sheets reutilizables para edición y comentarios.
- Feedback visual inmediato y manejo de errores robusto.
- El proyecto se despliega automáticamente en Vercel usando GitHub Actions (
.github/workflows/deploy-vercel.yml). - Secrets requeridos:
VERCEL_TOKEN: Token de acceso de Vercel.VERCEL_ORG_IDyVERCEL_PROJECT_ID: IDs de organización y proyecto en Vercel.
- Configura estos secrets en tu repositorio para habilitar el despliegue automático.
- Forkea el repositorio y envía un Pull Request.
- Sigue la estructura atómica y las buenas prácticas del proyecto.
- (Opcional) Agrega tests automáticos o integra con un backend real.
MIT. Ver archivo LICENSE.
- El sheet de información general (
AppInfoSheet) en la pantalla de inicio explica el estado de desarrollo y credenciales de prueba. - Los íconos y animaciones están personalizados para una mejor experiencia visual.
- El proyecto está listo para escalar y conectar a servicios reales.