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
parent a08e7057e8
commit e1847597d6
1 changed files with 262 additions and 30 deletions
--- 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