Mexus App - Sistema de Gestión de Obras de Construcción

Sistema integral para la gestión de obras de construcción, desarrollado con Next.js 14+, diseñado para empresas constructoras que necesitan administrar proyectos, finanzas, recursos e inventario.

Características Principales

Módulos del Sistema

Módulo	Descripción
Dashboard	Panel principal con KPIs, gráficos de avance, timeline de actividades y resumen financiero
Obras	Gestión completa de proyectos con fases, tareas, Gantt, fotos y bitácora
Finanzas	Control de gastos, presupuestos, órdenes de compra y flujo de caja
Recursos	Administración de personal, asistencia y subcontratistas
Inventario	Control de materiales con alertas de stock bajo y movimientos
Reportes	Generación de reportes con exportación a PDF y CSV
Portal Cliente	Acceso exclusivo para clientes con seguimiento de sus obras

Funcionalidades Destacadas

Core

• Autenticación segura con NextAuth.js v5
• Control de acceso por roles (Admin, Gerente, Supervisor, Contador, Empleado)
• Multi-empresa - Cada usuario pertenece a una empresa
• Dashboard interactivo con gráficos Recharts
• Responsive design con Tailwind CSS y shadcn/ui

Gestión de Obras

• Fases y Tareas - Cronograma completo de actividades
• Diagrama de Gantt - Visualización temporal de tareas con gantt-task-react
• Galería de Fotos - Subida y organización de fotos por obra
• Bitácora de Obra - Registro diario de actividades, clima y personal
• Registro de Avances - Seguimiento del progreso porcentual

Control Financiero

• Presupuestos - Creación y seguimiento de presupuestos por partidas
• Gastos - Registro, aprobación y categorización de gastos
• Órdenes de Compra - Gestión completa del ciclo de compras
• Exportación PDF - Reportes de gastos, presupuestos y bitácora

Recursos Humanos

• Control de Asistencia - Registro diario de personal por obra
• Tipos de Asistencia - Presente, ausente, retardo, permiso, incapacidad, vacaciones
• Gestión de Personal - Administración de empleados y jornales

Sistema de Notificaciones

• Notificaciones Push - Alertas en tiempo real vía Service Worker
• Campana de Notificaciones - Centro de notificaciones en el header
• Configuración Personalizada - Cada usuario configura qué notificaciones recibir

Log de Actividades

• Timeline de Actividades - Historial completo de acciones por obra
• Filtrado por Tipo - Obras, tareas, gastos, órdenes, avances, etc.
• Auditoría - Registro de quién hizo qué y cuándo

Portal de Cliente

• Acceso Exclusivo - Los clientes pueden ver sus obras
• Permisos Granulares - Configurar qué puede ver cada cliente
• Autenticación por Token - Sistema JWT independiente
• Vista de Avances - Seguimiento del progreso de sus proyectos

Progressive Web App (PWA)

• Instalable - Se puede instalar como app nativa
• Offline Support - Funciona sin conexión con caché
• Push Notifications - Recibe alertas aunque la app esté cerrada
• Responsive - Optimizado para móviles y tablets

Stack Tecnológico

Tecnología	Versión	Uso
Next.js	14.2.x	Framework React con App Router
TypeScript	5.x	Tipado estático
Tailwind CSS	3.4.x	Estilos utilitarios
shadcn/ui	-	Componentes UI
Prisma	5.22.x	ORM para PostgreSQL
PostgreSQL	15+	Base de datos
NextAuth.js	5.x (beta)	Autenticación
Recharts	2.x	Gráficos y visualizaciones
gantt-task-react	0.3.x	Diagrama de Gantt
@react-pdf/renderer	3.x	Generación de PDFs
web-push	3.x	Notificaciones Push
jose	5.x	JWT para portal de clientes
date-fns	3.x	Manejo de fechas
Zod	3.x	Validación de esquemas

Requisitos Previos

• Node.js 20.x o superior
• PostgreSQL 15 o superior
• npm o yarn

Instalación

1. Clonar el repositorio

git clone https://git.consultoria-as.com/consultoria-as/mexus-app.git
cd mexus-app

2. Instalar dependencias

npm install

3. Configurar variables de entorno

Crear archivo .env en la raíz del proyecto:

# Base de Datos
DATABASE_URL="postgresql://usuario:password@localhost:5432/construccion_db?schema=public"

# NextAuth.js
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="tu-secret-key-segura-aqui"

# JWT para Portal de Clientes
PORTAL_JWT_SECRET="otra-secret-key-para-portal"

# Push Notifications (generar con web-push generate-vapid-keys)
NEXT_PUBLIC_VAPID_PUBLIC_KEY="tu-vapid-public-key"
VAPID_PRIVATE_KEY="tu-vapid-private-key"

# Node Environment
NODE_ENV="development"

4. Configurar base de datos

# Crear las tablas
npx prisma migrate dev

# Poblar con datos de ejemplo (opcional)
npx prisma db seed

5. Generar iconos PWA (opcional)

# Usando el script incluido (requiere sharp)
npm install sharp --save-dev
node scripts/generate-icons.js

# O usando el script simple que genera placeholders
node scripts/generate-icons-simple.js

6. Iniciar el servidor de desarrollo

npm run dev

La aplicación estará disponible en http://localhost:3000

Credenciales de Prueba

Si ejecutaste el seed, puedes usar estas credenciales:

Email	Contraseña	Rol
admin@demo.com	admin123	ADMIN

Estructura del Proyecto

construccion-app/
├── prisma/
│   ├── schema.prisma          # Modelos de datos
│   └── seed.ts                # Datos de ejemplo
├── public/
│   ├── icons/                 # Iconos PWA
│   ├── uploads/               # Archivos subidos
│   ├── manifest.json          # Manifest PWA
│   └── sw.js                  # Service Worker
├── scripts/
│   ├── generate-icons.js      # Generador de iconos
│   └── generate-icons-simple.js
├── src/
│   ├── app/
│   │   ├── (auth)/            # Páginas de autenticación
│   │   │   ├── login/
│   │   │   └── registro/
│   │   ├── (dashboard)/       # Área principal protegida
│   │   │   ├── dashboard/     # Panel principal
│   │   │   ├── obras/         # Gestión de obras
│   │   │   ├── finanzas/      # Control financiero
│   │   │   ├── recursos/      # Personal y recursos
│   │   │   └── reportes/      # Reportes
│   │   ├── portal/            # Portal de clientes
│   │   │   ├── obras/         # Vista de obras del cliente
│   │   │   └── page.tsx       # Login del portal
│   │   └── api/               # API Routes
│   │       ├── auth/          # NextAuth endpoints
│   │       ├── obras/         # CRUD obras
│   │       ├── gastos/        # CRUD gastos
│   │       ├── materiales/    # CRUD materiales
│   │       ├── fotos/         # Gestión de fotos
│   │       ├── bitacora/      # Bitácora de obra
│   │       ├── asistencia/    # Control de asistencia
│   │       ├── ordenes-compra/ # Órdenes de compra
│   │       ├── actividades/   # Log de actividades
│   │       ├── notifications/ # Notificaciones push
│   │       ├── clientes-acceso/ # Gestión acceso clientes
│   │       └── portal/        # API del portal
│   ├── components/
│   │   ├── ui/                # Componentes shadcn/ui
│   │   ├── layout/            # Sidebar, Header
│   │   ├── fotos/             # Galería de fotos
│   │   ├── bitacora/          # Bitácora de obra
│   │   ├── asistencia/        # Control de asistencia
│   │   ├── ordenes/           # Órdenes de compra
│   │   ├── gantt/             # Diagrama de Gantt
│   │   ├── pdf/               # Componentes de PDF
│   │   ├── actividades/       # Timeline de actividades
│   │   ├── notifications/     # Campana de notificaciones
│   │   ├── clientes/          # Gestión acceso clientes
│   │   └── pwa/               # Componentes PWA
│   ├── lib/
│   │   ├── auth.ts            # Configuración NextAuth
│   │   ├── prisma.ts          # Cliente Prisma
│   │   ├── utils.ts           # Utilidades
│   │   ├── validations.ts     # Esquemas Zod
│   │   ├── activity-log.ts    # Sistema de logging
│   │   ├── push-notifications.ts # Notificaciones push
│   │   └── portal-auth.ts     # Auth del portal
│   ├── hooks/                 # Custom React hooks
│   └── types/                 # TypeScript types
├── docker-compose.yml         # Configuración Docker
├── Dockerfile                 # Build de producción
└── nginx.conf                 # Configuración Nginx

Comandos Disponibles

# Desarrollo
npm run dev              # Inicia servidor de desarrollo
npm run build            # Compila para producción
npm run start            # Inicia servidor de producción
npm run lint             # Ejecuta ESLint

# Base de datos
npx prisma migrate dev   # Ejecuta migraciones en desarrollo
npx prisma migrate deploy # Ejecuta migraciones en producción
npx prisma db seed       # Ejecuta el seed
npx prisma studio        # Abre el explorador de BD
npx prisma generate      # Regenera el cliente Prisma

# PWA
node scripts/generate-icons.js  # Genera iconos desde SVG

Despliegue con Docker

Desarrollo

docker-compose up -d

Producción

docker-compose -f docker-compose.prod.yml up -d

API Endpoints

Autenticación

• POST /api/auth/callback/credentials - Login
• GET /api/auth/session - Obtener sesión actual
• POST /api/auth/signout - Cerrar sesión
• POST /api/auth/register - Registro de usuario

Obras

• GET /api/obras - Listar obras
• POST /api/obras - Crear obra
• GET /api/obras/[id] - Obtener obra con detalles
• PUT /api/obras/[id] - Actualizar obra
• DELETE /api/obras/[id] - Eliminar obra

Gastos

• GET /api/gastos - Listar gastos
• POST /api/gastos - Crear gasto
• PUT /api/gastos/[id] - Actualizar gasto
• DELETE /api/gastos/[id] - Eliminar gasto
• PATCH /api/gastos/[id] - Aprobar/Rechazar gasto

Materiales

• GET /api/materiales - Listar materiales
• POST /api/materiales - Crear material
• PUT /api/materiales/[id] - Actualizar material
• DELETE /api/materiales/[id] - Eliminar material
• POST /api/materiales/movimiento - Registrar movimiento

Fotos

• GET /api/fotos?obraId=xxx - Listar fotos de una obra
• POST /api/fotos - Subir foto (multipart/form-data)
• DELETE /api/fotos/[id] - Eliminar foto

Bitácora

• GET /api/bitacora?obraId=xxx - Listar entradas de bitácora
• POST /api/bitacora - Crear entrada de bitácora
• PUT /api/bitacora/[id] - Actualizar entrada
• DELETE /api/bitacora/[id] - Eliminar entrada

Asistencia

• GET /api/asistencia?obraId=xxx&fecha=xxx - Listar asistencia
• POST /api/asistencia - Registrar asistencia
• PUT /api/asistencia/[id] - Actualizar asistencia
• GET /api/asistencia/empleados?obraId=xxx - Empleados de una obra

Órdenes de Compra

• GET /api/ordenes-compra?obraId=xxx - Listar órdenes
• POST /api/ordenes-compra - Crear orden
• PUT /api/ordenes-compra/[id] - Actualizar orden
• DELETE /api/ordenes-compra/[id] - Eliminar orden

Actividades

• GET /api/actividades?obraId=xxx&tipo=xxx - Obtener log de actividades

Notificaciones

• GET /api/notifications - Listar notificaciones del usuario
• PUT /api/notifications - Marcar como leídas
• POST /api/notifications/subscribe - Suscribirse a push
• DELETE /api/notifications/subscribe - Cancelar suscripción

Portal de Clientes

• POST /api/portal/auth - Login del cliente
• GET /api/portal/obras - Listar obras del cliente
• GET /api/portal/obras/[id] - Detalle de obra

Gestión de Acceso de Clientes

• GET /api/clientes-acceso?clienteId=xxx - Obtener accesos
• POST /api/clientes-acceso - Crear acceso
• PUT /api/clientes-acceso/[id] - Actualizar permisos
• DELETE /api/clientes-acceso/[id] - Revocar acceso

Modelos de Datos Principales

Enums

enum Role { ADMIN, GERENTE, SUPERVISOR, CONTADOR, EMPLEADO }
enum EstadoObra { PLANIFICACION, EN_PROGRESO, PAUSADA, COMPLETADA, CANCELADA }
enum EstadoTarea { PENDIENTE, EN_PROGRESO, COMPLETADA, BLOQUEADA }
enum EstadoGasto { PENDIENTE, APROBADO, RECHAZADO, PAGADO }
enum CategoriaGasto { MATERIALES, MANO_DE_OBRA, EQUIPOS, SUBCONTRATISTAS, PERMISOS, TRANSPORTE, SERVICIOS, OTROS }
enum EstadoOrdenCompra { BORRADOR, PENDIENTE, APROBADA, ENVIADA, RECIBIDA_PARCIAL, RECIBIDA, CANCELADA }
enum TipoAsistencia { PRESENTE, AUSENTE, RETARDO, PERMISO, INCAPACIDAD, VACACIONES }
enum CondicionClima { SOLEADO, NUBLADO, PARCIALMENTE_NUBLADO, LLUVIA_LIGERA, LLUVIA_FUERTE, TORMENTA, VIENTO_FUERTE, FRIO_EXTREMO, CALOR_EXTREMO }

Modelos Principales

Modelo	Descripción
User	Usuarios del sistema con roles
Empresa	Empresas (multi-tenant)
Obra	Proyectos de construcción
FaseObra	Fases del proyecto
TareaObra	Tareas específicas
Presupuesto	Presupuestos de obra
Gasto	Registro de gastos
Material	Catálogo de materiales
OrdenCompra	Órdenes de compra
FotoObra	Galería de fotos
BitacoraObra	Registro diario
RegistroAsistencia	Control de asistencia
ActividadLog	Log de actividades
Notificacion	Notificaciones del usuario
PushSubscription	Suscripciones push
ClienteAcceso	Acceso de clientes al portal

Roles y Permisos

Rol	Descripción	Permisos
ADMIN	Administrador	Acceso completo al sistema
GERENTE	Gerente de proyectos	Gestión de obras, finanzas y personal
SUPERVISOR	Supervisor de obra	Registro de avances, gastos y asistencia
CONTADOR	Contador	Gestión financiera y reportes
EMPLEADO	Empleado general	Solo lectura de información básica

Permisos del Portal de Cliente

Permiso	Descripción
verFotos	Ver galería de fotos de la obra
verAvances	Ver porcentaje de avance
verGastos	Ver detalle de gastos (desactivado por defecto)
verDocumentos	Ver documentos adjuntos
descargarPDF	Descargar reportes en PDF

Seguridad

• Autenticación mediante JWT con NextAuth.js
• Portal de clientes con JWT independiente (jose)
• Middleware de protección de rutas
• Validación de datos con Zod en cliente y servidor
• Multi-tenant - Filtrado de datos por empresa
• Contraseñas hasheadas con bcrypt
• Headers de seguridad configurados
• CORS configurado para API

PWA - Progressive Web App

La aplicación puede instalarse como una app nativa:

Características

• Instalable en Android, iOS y Desktop
• Offline - Funciona sin conexión con Service Worker
• Push Notifications - Alertas en tiempo real
• Responsive - Adaptado a todos los tamaños de pantalla

Instalación en dispositivos

Android/Desktop:

1. Abre la app en Chrome
2. Aparecerá un banner "Instalar Mexus"
3. Click en "Instalar"

iOS:

1. Abre la app en Safari
2. Toca el botón de compartir
3. Selecciona "Agregar a inicio"

Contribuir

1. Fork el repositorio
2. Crea una rama para tu feature (git checkout -b feature/nueva-funcionalidad)
3. Commit tus cambios (git commit -m 'Agrega nueva funcionalidad')
4. Push a la rama (git push origin feature/nueva-funcionalidad)
5. Abre un Pull Request

Changelog

v1.1.0 (2025-01)

• Galería de fotos por obra
• Bitácora de obra con registro diario
• Exportación a PDF (reportes, gastos, presupuestos, bitácora)
• Control de asistencia de personal
• Órdenes de compra con flujo de aprobación
• Portal de clientes con acceso exclusivo
• Diagrama de Gantt para visualización de tareas
• Sistema de notificaciones push
• Log de actividades con timeline
• Soporte PWA completo con offline

v1.0.0 (2024-12)

• Versión inicial
• Dashboard con KPIs
• Gestión de obras
• Control de gastos
• Inventario de materiales
• Sistema de roles

Licencia

Este proyecto es privado y de uso interno.

Soporte

Para soporte técnico, contactar al equipo de desarrollo.

---

Desarrollado con Next.js y TypeScript | Mexus App v1.1.0