# 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

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

### 2. Instalar dependencias

```bash
npm install
```

### 3. Configurar variables de entorno

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

```env
# 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

```bash
# Crear las tablas
npx prisma migrate dev

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

### 5. Generar iconos PWA (opcional)

```bash
# 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

```bash
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

```bash
# 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

```bash
docker-compose up -d
```

### Producción

```bash
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

```prisma
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