consultoria-as/mexus-app
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Update README with all features and improvements

Browse Source 
- 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>
This commit is contained in:
Mexus
2026-01-19 03:12:40 +00:00
parent a08e7057e8
commit e1847597d6
1 changed files with 262 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

292
README.md
View File

@@ -8,23 +8,63 @@ Sistema integral para la gestión de obras de construcción, desarrollado con Ne
| Módulo | Descripción | | Módulo | Descripción |
|--------|-------------| |--------|-------------|
| **Dashboard** | Panel principal con KPIs, gráficos de avance y resumen financiero | | **Dashboard** | Panel principal con KPIs, gráficos de avance, timeline de actividades y resumen financiero |
| **Obras** | Gestión completa de proyectos de construcción con fases y tareas | | **Obras** | Gestión completa de proyectos con fases, tareas, Gantt, fotos y bitácora |
| **Finanzas** | Control de gastos, presupuestos y flujo de caja | | **Finanzas** | Control de gastos, presupuestos, órdenes de compra y flujo de caja |
| **Recursos** | Administración de personal y subcontratistas | | **Recursos** | Administración de personal, asistencia y subcontratistas |
| **Inventario** | Control de materiales con alertas de stock bajo | | **Inventario** | Control de materiales con alertas de stock bajo y movimientos |
| **Reportes** | Generación de reportes con exportación a CSV | | **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 ### Funcionalidades Destacadas
#### Core
- **Autenticación segura** con NextAuth.js v5 - **Autenticación segura** con NextAuth.js v5
- **Control de acceso por roles** (Admin, Gerente, Supervisor, Contador, Empleado) - **Control de acceso por roles** (Admin, Gerente, Supervisor, Contador, Empleado)
- **Multi-empresa** - Cada usuario pertenece a una empresa - **Multi-empresa** - Cada usuario pertenece a una empresa
- **Dashboard interactivo** con gráficos Recharts - **Dashboard interactivo** con gráficos Recharts
- **Alertas automáticas** de stock bajo en inventario
- **Registro de movimientos** de inventario (entradas/salidas)
- **Responsive design** con Tailwind CSS y shadcn/ui - **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 ## Stack Tecnológico
| Tecnología | Versión | Uso | | Tecnología | Versión | Uso |
@@ -37,6 +77,11 @@ Sistema integral para la gestión de obras de construcción, desarrollado con Ne
| PostgreSQL | 15+ | Base de datos | | PostgreSQL | 15+ | Base de datos |
| NextAuth.js | 5.x (beta) | Autenticación | | NextAuth.js | 5.x (beta) | Autenticación |
| Recharts | 2.x | Gráficos y visualizaciones | | 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 | | Zod | 3.x | Validación de esquemas |
## Requisitos Previos ## Requisitos Previos
@@ -50,7 +95,7 @@ Sistema integral para la gestión de obras de construcción, desarrollado con Ne
### 1. Clonar el repositorio ### 1. Clonar el repositorio
```bash ```bash
git clone https://git.consultoria-as.com/tu-usuario/mexus-app.git git clone https://git.consultoria-as.com/consultoria-as/mexus-app.git
cd mexus-app cd mexus-app
``` ```
@@ -72,6 +117,13 @@ DATABASE_URL="postgresql://usuario:password@localhost:5432/construccion_db?schem
NEXTAUTH_URL="http://localhost:3000" NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="tu-secret-key-segura-aqui" 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 Environment
NODE_ENV="development" NODE_ENV="development"
``` ```
@@ -86,7 +138,18 @@ npx prisma migrate dev
npx prisma db seed npx prisma db seed
``` ```
### 5. Iniciar el servidor de desarrollo ### 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 ```bash
npm run dev npm run dev
@@ -109,6 +172,14 @@ construccion-app/
├── prisma/ ├── prisma/
│ ├── schema.prisma # Modelos de datos │ ├── schema.prisma # Modelos de datos
│ └── seed.ts # Datos de ejemplo │ └── 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/ ├── src/
│ ├── app/ │ ├── app/
│ │ ├── (auth)/ # Páginas de autenticación │ │ ├── (auth)/ # Páginas de autenticación
@@ -119,22 +190,44 @@ construccion-app/
│ │ │ ├── obras/ # Gestión de obras │ │ │ ├── obras/ # Gestión de obras
│ │ │ ├── finanzas/ # Control financiero │ │ │ ├── finanzas/ # Control financiero
│ │ │ ├── recursos/ # Personal y recursos │ │ │ ├── recursos/ # Personal y recursos
│ │ │ │ ├── materiales/ # Inventario
│ │ │ │ └── personal/ # Empleados
│ │ │ └── reportes/ # Reportes │ │ │ └── reportes/ # Reportes
│ │ ├── portal/ # Portal de clientes
│ │ │ ├── obras/ # Vista de obras del cliente
│ │ │ └── page.tsx # Login del portal
│ │ └── api/ # API Routes │ │ └── api/ # API Routes
│ │ ├── auth/ # NextAuth endpoints │ │ ├── auth/ # NextAuth endpoints
│ │ ├── obras/ # CRUD obras │ │ ├── obras/ # CRUD obras
│ │ ├── gastos/ # CRUD gastos │ │ ├── gastos/ # CRUD gastos
│ │ └── materiales/ # CRUD materiales │ │ ├── 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/ │ ├── components/
│ │ ├── ui/ # Componentes shadcn/ui │ │ ├── ui/ # Componentes shadcn/ui
│ │ └── layout/ # Sidebar, Header │ │ ├── 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/ │ ├── lib/
│ │ ├── auth.ts # Configuración NextAuth │ │ ├── auth.ts # Configuración NextAuth
│ │ ├── prisma.ts # Cliente Prisma │ │ ├── prisma.ts # Cliente Prisma
│ │ ├── utils.ts # Utilidades │ │ ├── utils.ts # Utilidades
│ │ └── validations.ts # Esquemas Zod │ │ ├── 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 │ ├── hooks/ # Custom React hooks
│ └── types/ # TypeScript types │ └── types/ # TypeScript types
├── docker-compose.yml # Configuración Docker ├── docker-compose.yml # Configuración Docker
@@ -157,6 +250,9 @@ npx prisma migrate deploy # Ejecuta migraciones en producción
npx prisma db seed # Ejecuta el seed npx prisma db seed # Ejecuta el seed
npx prisma studio # Abre el explorador de BD npx prisma studio # Abre el explorador de BD
npx prisma generate # Regenera el cliente Prisma npx prisma generate # Regenera el cliente Prisma
# PWA
node scripts/generate-icons.js # Genera iconos desde SVG
``` ```
## Despliegue con Docker ## Despliegue con Docker
@@ -179,11 +275,12 @@ docker-compose -f docker-compose.prod.yml up -d
- `POST /api/auth/callback/credentials` - Login - `POST /api/auth/callback/credentials` - Login
- `GET /api/auth/session` - Obtener sesión actual - `GET /api/auth/session` - Obtener sesión actual
- `POST /api/auth/signout` - Cerrar sesión - `POST /api/auth/signout` - Cerrar sesión
- `POST /api/auth/register` - Registro de usuario
### Obras ### Obras
- `GET /api/obras` - Listar obras - `GET /api/obras` - Listar obras
- `POST /api/obras` - Crear obra - `POST /api/obras` - Crear obra
- `GET /api/obras/[id]` - Obtener obra - `GET /api/obras/[id]` - Obtener obra con detalles
- `PUT /api/obras/[id]` - Actualizar obra - `PUT /api/obras/[id]` - Actualizar obra
- `DELETE /api/obras/[id]` - Eliminar obra - `DELETE /api/obras/[id]` - Eliminar obra
@@ -192,33 +289,146 @@ docker-compose -f docker-compose.prod.yml up -d
- `POST /api/gastos` - Crear gasto - `POST /api/gastos` - Crear gasto
- `PUT /api/gastos/[id]` - Actualizar gasto - `PUT /api/gastos/[id]` - Actualizar gasto
- `DELETE /api/gastos/[id]` - Eliminar gasto - `DELETE /api/gastos/[id]` - Eliminar gasto
- `PATCH /api/gastos/[id]/aprobar` - Aprobar gasto - `PATCH /api/gastos/[id]` - Aprobar/Rechazar gasto
### Materiales ### Materiales
- `GET /api/materiales` - Listar materiales - `GET /api/materiales` - Listar materiales
- `POST /api/materiales` - Crear material - `POST /api/materiales` - Crear material
- `PUT /api/materiales/[id]` - Actualizar material - `PUT /api/materiales/[id]` - Actualizar material
- `DELETE /api/materiales/[id]` - Eliminar material - `DELETE /api/materiales/[id]` - Eliminar material
- `POST /api/materiales/movimiento` - Registrar movimiento de inventario - `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 ## Roles y Permisos
| Rol | Descripción | Permisos | | Rol | Descripción | Permisos |
|-----|-------------|----------| |-----|-------------|----------|
| ADMIN | Administrador | Acceso completo | | ADMIN | Administrador | Acceso completo al sistema |
| GERENTE | Gerente de proyectos | Gestión de obras y finanzas | | GERENTE | Gerente de proyectos | Gestión de obras, finanzas y personal |
| SUPERVISOR | Supervisor de obra | Registro de avances y gastos | | SUPERVISOR | Supervisor de obra | Registro de avances, gastos y asistencia |
| CONTADOR | Contador | Gestión financiera | | CONTADOR | Contador | Gestión financiera y reportes |
| EMPLEADO | Empleado general | Solo lectura | | 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 ## Seguridad
- Autenticación mediante JWT con NextAuth.js - **Autenticación** mediante JWT con NextAuth.js
- Middleware de protección de rutas - **Portal de clientes** con JWT independiente (jose)
- Validación de datos con Zod en cliente y servidor - **Middleware** de protección de rutas
- Filtrado de datos por empresa (multi-tenant) - **Validación** de datos con Zod en cliente y servidor
- Contraseñas hasheadas con bcrypt - **Multi-tenant** - Filtrado de datos por empresa
- Headers de seguridad configurados - **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 ## Contribuir
@@ -228,6 +438,28 @@ docker-compose -f docker-compose.prod.yml up -d
4. Push a la rama (`git push origin feature/nueva-funcionalidad`) 4. Push a la rama (`git push origin feature/nueva-funcionalidad`)
5. Abre un Pull Request 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 ## Licencia
Este proyecto es privado y de uso interno. Este proyecto es privado y de uso interno.
@@ -238,4 +470,4 @@ Para soporte técnico, contactar al equipo de desarrollo.
--- ---
Desarrollado con Next.js y TypeScript Desarrollado con Next.js y TypeScript | Mexus App v1.1.0