consultoria-as/mexus-app
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e964e8f0b50e4efecc6da947200d7ebbbb4e6c09
mexus-app/README.md
Mexus e1847597d6 docs: Update README with all features and improvements 
- Document all modules and functionalities
- Add new API endpoints documentation
- Include PWA installation instructions
- Add changelog with v1.1.0 features
- Update project structure
- Add environment variables for new features
- Document portal client permissions
- Include data models reference

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-19 03:12:40 +00:00

474 lines
16 KiB
Markdown
Raw Blame History

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