86bfbd2039
Sistema de Gestión de Obras de Construcción completo con: - Dashboard con KPIs y gráficos - Módulo de obras con fases y tareas - Control financiero (gastos, presupuestos) - Gestión de recursos (personal, subcontratistas) - Inventario de materiales con alertas de stock - Reportes con exportación CSV - Autenticación con roles (NextAuth.js v5) - API REST completa - Documentación de API y base de datos - Configuración Docker para despliegue Stack: Next.js 14+, TypeScript, Tailwind CSS, Prisma, PostgreSQL Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
242 lines
7.2 KiB
Markdown
242 lines
7.2 KiB
Markdown
# 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 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 |
|
|
|
|
### Funcionalidades Destacadas
|
|
|
|
- **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
|
|
|
|
## 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 |
|
|
| 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/tu-usuario/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"
|
|
|
|
# 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. 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
|
|
├── 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
|
|
│ │ │ │ ├── materiales/ # Inventario
|
|
│ │ │ │ └── personal/ # Empleados
|
|
│ │ │ └── reportes/ # Reportes
|
|
│ │ └── api/ # API Routes
|
|
│ │ ├── auth/ # NextAuth endpoints
|
|
│ │ ├── obras/ # CRUD obras
|
|
│ │ ├── gastos/ # CRUD gastos
|
|
│ │ └── materiales/ # CRUD materiales
|
|
│ ├── components/
|
|
│ │ ├── ui/ # Componentes shadcn/ui
|
|
│ │ └── layout/ # Sidebar, Header
|
|
│ ├── lib/
|
|
│ │ ├── auth.ts # Configuración NextAuth
|
|
│ │ ├── prisma.ts # Cliente Prisma
|
|
│ │ ├── utils.ts # Utilidades
|
|
│ │ └── validations.ts # Esquemas Zod
|
|
│ ├── 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
|
|
```
|
|
|
|
## 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
|
|
|
|
### Obras
|
|
- `GET /api/obras` - Listar obras
|
|
- `POST /api/obras` - Crear obra
|
|
- `GET /api/obras/[id]` - Obtener obra
|
|
- `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` - Aprobar 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
|
|
|
|
## 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 |
|
|
|
|
## 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
|
|
|
|
## 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
|
|
|
|
## 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
|