From e1847597d6aad472c98f7334d12229c72b75c37e Mon Sep 17 00:00:00 2001 From: Mexus Date: Mon, 19 Jan 2026 03:12:40 +0000 Subject: [PATCH] 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 --- README.md | 292 ++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 262 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 97c879a..82269b9 100644 --- a/README.md +++ b/README.md @@ -8,23 +8,63 @@ Sistema integral para la gestión de obras de construcción, desarrollado con Ne | Módulo | Descripción | |--------|-------------| -| **Dashboard** | Panel principal con KPIs, gráficos de avance y resumen financiero | -| **Obras** | Gestión completa de proyectos de construcción con fases y tareas | -| **Finanzas** | Control de gastos, presupuestos y flujo de caja | -| **Recursos** | Administración de personal y subcontratistas | -| **Inventario** | Control de materiales con alertas de stock bajo | -| **Reportes** | Generación de reportes con exportación a CSV | +| **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 -- **Alertas automáticas** de stock bajo en inventario -- **Registro de movimientos** de inventario (entradas/salidas) - **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 | @@ -37,6 +77,11 @@ Sistema integral para la gestión de obras de construcción, desarrollado con Ne | 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 @@ -50,7 +95,7 @@ Sistema integral para la gestión de obras de construcción, desarrollado con Ne ### 1. Clonar el repositorio ```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 ``` @@ -72,6 +117,13 @@ DATABASE_URL="postgresql://usuario:password@localhost:5432/construccion_db?schem 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" ``` @@ -86,7 +138,18 @@ npx prisma migrate dev 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 npm run dev @@ -109,6 +172,14 @@ 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 @@ -119,22 +190,44 @@ construccion-app/ │ │ │ ├── obras/ # Gestión de obras │ │ │ ├── finanzas/ # Control financiero │ │ │ ├── recursos/ # Personal y recursos -│ │ │ │ ├── materiales/ # Inventario -│ │ │ │ └── personal/ # Empleados │ │ │ └── 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 +│ │ ├── 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 +│ │ ├── 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 +│ │ ├── 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 @@ -157,6 +250,9 @@ 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 @@ -179,11 +275,12 @@ docker-compose -f docker-compose.prod.yml up -d - `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 +- `GET /api/obras/[id]` - Obtener obra con detalles - `PUT /api/obras/[id]` - Actualizar 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 - `PUT /api/gastos/[id]` - Actualizar gasto - `DELETE /api/gastos/[id]` - Eliminar gasto -- `PATCH /api/gastos/[id]/aprobar` - Aprobar 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 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 | Rol | Descripción | Permisos | |-----|-------------|----------| -| ADMIN | Administrador | Acceso completo | -| GERENTE | Gerente de proyectos | Gestión de obras y finanzas | -| SUPERVISOR | Supervisor de obra | Registro de avances y gastos | -| CONTADOR | Contador | Gestión financiera | -| EMPLEADO | Empleado general | Solo lectura | +| 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 -- Middleware de protección de rutas -- Validación de datos con Zod en cliente y servidor -- Filtrado de datos por empresa (multi-tenant) -- Contraseñas hasheadas con bcrypt -- Headers de seguridad configurados +- **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 @@ -228,6 +438,28 @@ docker-compose -f docker-compose.prod.yml up -d 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. @@ -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