21 KiB
ConstruProgress
Manual de la aplicación
Sistema de seguimiento de obra
MAI Group · RTE International
📷 Captura: portada / logotipo de la aplicación (public/images/logo-rte.png).
| Versión del documento | 1.0 |
| Fecha | Junio 2026 |
| Ámbito | Aplicación web + API para la app móvil |
| Idioma | Español (versión en inglés: MANUAL.en.md) |
Índice
- Introducción y conceptos
- Requisitos del sistema
- Instalación y despliegue
- Acceso y primeros pasos
- Roles y permisos
- Manual de uso por secciones
- Flujos de trabajo típicos
- API (app móvil)
- Mantenimiento, copias de seguridad y actualización
- Resolución de problemas (FAQ)
- Anexos
1. Introducción y conceptos
1.1 ¿Qué es ConstruProgress?
ConstruProgress es una aplicación web para el seguimiento y control de obra. Permite organizar cada proyecto en fases, cartografiar sus elementos sobre un mapa, registrar inspecciones con plantillas, gestionar incidencias (con tareas, comentarios y fotos) y generar informes. Está preparada además para alimentar una app móvil que trabaja sin conexión en campo y sincroniza al recuperar red.
📷 Captura: panel principal (dashboard) con el resumen general.
1.2 Conceptos clave (glosario)
| Término | Significado |
|---|---|
| Proyecto | Unidad principal de trabajo (una obra). Contiene fases, capas, elementos, inspecciones e incidencias. |
| Fase | Etapa del proyecto (p. ej. Cimentación, Estructura). Tiene orden, color, progreso y fechas previstas/reales. |
| Capa (layer) | Agrupación de elementos en el mapa dentro de una fase. |
| Elemento (feature) | Objeto geográfico (punto/línea/polígono) sobre el mapa, con estado y % de progreso. |
| Inspección | Registro de control sobre un elemento, normalmente mediante una plantilla. |
| Plantilla de inspección | Formulario reutilizable con campos configurables (texto, número, %, booleano, selección…). |
| Incidencia | Problema o defecto detectado: tiene prioridad, estado, tipo, tareas, comentarios y fotos. |
| Checklist de incidencia | Lista de tareas para resolver una incidencia; puede generarse desde una plantilla de checklist. |
| Rol | Conjunto de permisos del usuario en el sistema (Admin, Supervisor…). |
| Rol en proyecto | Papel de un usuario/empresa dentro de un proyecto concreto (supervisor, cliente, constructor…). |
1.3 Arquitectura (resumen técnico)
- Backend: Laravel 12 (PHP 8.2+), Livewire 3 (Volt).
- UI: TailwindCSS + DaisyUI, tablas Rappasoft, mapas Leaflet, iconos Heroicons.
- BD: MySQL/MariaDB.
- Permisos: spatie/laravel-permission.
- API móvil: Laravel Sanctum (tokens), sincronización offline-first.
2. Requisitos del sistema
Servidor
- PHP 8.3 recomendado (mínimo 8.2). Extensiones:
mbstring, pdo_mysql, openssl, tokenizer, xml, ctype, json, bcmath, fileinfo, curl, gd, zip. - MySQL/MariaDB.
- Composer. (Node solo para compilar los assets, preferiblemente en local.)
- HTTPS (SSL).
Nota de versión: una dependencia (
zipstream-php) requiere PHP 8.3. Con PHP 8.2,composer installnecesita--ignore-platform-reqs. Recomendado: usar PHP 8.3.
Cliente (navegador)
- Navegador moderno (Chrome, Edge, Firefox, Safari) con JavaScript activado.
3. Instalación y despliegue
Guía para un servidor web tipo OVH (VPS recomendado; también válido en hosting compartido con las salvedades indicadas).
3.1 Base de datos
Crea una base de datos MySQL y un usuario con permisos. Anota host, nombre, usuario y contraseña.
3.2 Compilar los assets (en tu PC)
El hosting normalmente no tiene Node. Compila localmente y sube el resultado:
npm install
npm run build # genera public/build
3.3 Subir el código
Sube todo el proyecto excepto node_modules/, .git/ y .env. vendor/ puedes
instalarlo en el servidor (si tienes SSH) o subirlo.
composer install --no-dev --optimize-autoloader
3.4 Document root → carpeta public/
El dominio debe apuntar a …/construprogress/public (nunca a la raíz).
- VPS (nginx/apache):
rootdel virtualhost →/ruta/construprogress/public. - OVH compartido: en Multisite, carpeta raíz del dominio →
construprogress/public.
3.5 Configurar .env
Copia .env.example a .env y ajusta:
APP_NAME=ConstruProgress
APP_ENV=production
APP_DEBUG=false
APP_URL=https://tudominio.com
APP_LOCALE=es
DB_CONNECTION=mysql
DB_HOST=...
DB_DATABASE=...
DB_USERNAME=...
DB_PASSWORD=...
FILESYSTEM_DISK=public # las fotos/archivos usan el disco public
SESSION_DRIVER=database
3.6 Preparar la aplicación
php artisan key:generate
php artisan migrate --force
php artisan db:seed --force # roles, permisos (PermissionCatalogSeeder…)
php artisan storage:link # public/storage → storage/app/public
php artisan config:cache
php artisan route:cache
php artisan view:cache
3.7 Permisos de escritura
chmod -R ug+rwX storage bootstrap/cache
3.8 Cron del planificador (avisos de tareas vencidas)
Añade un cron cada minuto:
* * * * * cd /ruta/construprogress && php artisan schedule:run >> /dev/null 2>&1
Esto ejecuta issues:notify-overdue a diario. No se necesita worker de colas
(las notificaciones son síncronas).
3.9 HTTPS
Activa el SSL gratuito (Let's Encrypt) de OVH y fuerza HTTPS.
3.10 Comprobaciones tras desplegar
- La home redirige al login (correcto).
- Se ven el logo (
/images/logo-rte.png) y las banderas (/images/flags/*.svg). - Subir una foto en una incidencia funciona (valida
storage:link+FILESYSTEM_DISK=public). - La API responde:
GET https://tudominio.com/api/v1/...con token.
3.11 Actualizar cambios (deploys posteriores)
git pull
composer install --no-dev --optimize-autoloader
# (en tu PC) npm run build y subir public/build
php artisan migrate --force
php artisan config:cache && php artisan route:cache && php artisan view:cache
4. Acceso y primeros pasos
📷 Captura: pantalla de inicio de sesión (login) con el conmutador de idioma.
4.1 Inicio de sesión
Accede a https://tudominio.com/login con tu email y contraseña. Tras la instalación,
el seeder crea un administrador inicial (admin@email.com) — cambia su contraseña
en cuanto entres.
4.2 Recuperar contraseña
Desde el login, “¿Olvidaste tu contraseña?” envía un correo de restablecimiento
(requiere el correo saliente configurado en .env).
4.3 Perfil
En el menú de usuario → Perfil puedes actualizar tus datos, cambiar la contraseña y (opcionalmente) eliminar la cuenta.
4.4 Idioma
La aplicación está disponible en Español e Inglés. Cambia el idioma con el conmutador de banderas (🇪🇸/🇬🇧) de la cabecera. Cada usuario tiene además un idioma por defecto configurable al crear/editar el usuario.
5. Roles y permisos
5.1 Roles del sistema (base)
| Rol | Permisos base (editables) |
|---|---|
| Admin | Acceso total (manage all). |
| Supervisor | Ver proyectos, subir capas, actualizar progreso. |
| Consultor | Ver proyectos, ver informes. |
| Cliente | Ver proyectos. |
Los permisos de cada rol son totalmente configurables desde Administración → Roles (matriz de permisos). La tabla anterior es la configuración inicial del seeder. Para que un rol no-Admin use módulos nuevos (fases, incidencias, asignaciones…), asígnale los permisos correspondientes.
📷 Captura: matriz de permisos en la edición de un rol.
5.2 Catálogo de permisos (por sección)
- Proyectos: ver, crear, editar, eliminar, exportar.
- Fases y progreso: ver fases, gestionar fases, actualizar progreso.
- Capas y elementos: ver, subir/importar, editar, eliminar.
- Inspecciones: ver, registrar, eliminar, gestionar plantillas.
- Incidencias: ver, crear, editar (resolver/cerrar), eliminar.
- Empresas: ver, crear, editar, eliminar, asignar a proyectos.
- Usuarios: ver, crear, editar, eliminar, asignar usuarios/roles a proyectos.
- Roles: gestionar roles y permisos.
- Informes: ver panel, exportar.
- Archivos: ver, subir, eliminar.
- General:
manage all(súper-administrador).
5.3 Rol en proyecto (distinto del rol del sistema)
Al asignar usuarios a un proyecto se elige su papel: Supervisor, Consultor, Cliente, Observador. Al asignar empresas: Promotor, Constructor, Subcontratista, Consultor, Proveedor, Otro.
6. Manual de uso por secciones
6.1 Panel principal (Dashboard)
Vista de inicio con el resumen: proyectos accesibles, progreso, incidencias abiertas/ críticas e incidencias recientes. Incluye accesos directos a las secciones.
📷 Captura: dashboard principal.
6.2 Proyectos
Listado
Proyectos muestra una tabla (con búsqueda y orden) de los proyectos a los que tienes acceso, con referencia, nombre, dirección, estado, progreso y fechas. Acciones por fila: Dashboard, Mapa y Editar.
📷 Captura: listado de proyectos.
Crear / Editar
El editor de proyecto está organizado en pestañas:
- Datos: referencia, nombre, dirección, ubicación (lat/lng en mapa), fechas y estado.
- Fases (ver 6.3).
- Usuarios (ver 6.11): asignar usuarios al proyecto con su rol.
- Empresas: asignar empresas al proyecto con su rol.
📷 Captura: editor de proyecto (pestaña Datos).
6.3 Fases
Dentro del editor de proyecto, la pestaña Fases lista las fases en una tabla (orden, nombre, progreso, fechas, color) y permite:
- Agregar fase: abre un formulario modal con todos los parámetros (nombre, descripción, orden, color, % progreso, fechas previstas y reales).
- Editar: mismo modal con los datos cargados.
- Actualizar progreso: pantalla dedicada para registrar avance.
- Eliminar. (Requiere el permiso gestionar fases.)
📷 Captura: pestaña Fases con la tabla y el modal de crear/editar fase.
6.4 Mapa del proyecto
Proyectos → Mapa abre el mapa interactivo (Leaflet) con pestañas/panel lateral:
- Capas y elementos: visualización por capas; selección de un elemento muestra su panel con responsable, progreso, archivos e inspecciones.
- Inspección: desde un elemento, elige una plantilla y registra la inspección.
- Archivos: gestor de ficheros del elemento.
- Incidencias: pestaña con las incidencias del proyecto; desde un elemento puedes pulsar “Incidencia” para reportar una nueva ya vinculada a ese elemento.
📷 Captura: mapa del proyecto con el panel de un elemento seleccionado.
6.5 Capas y elementos
Gestión de capas por fase (importar/subir, editar, eliminar) y de los elementos que contienen, con su geometría, estado y progreso.
6.6 Inspecciones y plantillas
- Plantillas (Proyectos → Plantillas): formularios configurables (campos de tipo texto, número, porcentaje, booleano, selección, área de texto…). Cada plantilla se versiona para la sincronización móvil.
- Registrar inspección: desde el mapa, sobre un elemento, seleccionando la plantilla y rellenando sus campos (estado, resultado, notas).
📷 Captura: formulario de inspección desde el mapa.
6.7 Incidencias
Acceso desde Proyectos → Incidencias o la pestaña Incidencias del mapa.
Listado
Tabla (Rappasoft) con filtros por estado, prioridad y tipo, búsqueda, barra de progreso de tareas, contadores de comentarios/fotos y badge de tareas vencidas. Cabecera con botones Nueva incidencia y Plantillas (de checklist).
📷 Captura: listado de incidencias con filtros.
Crear / Editar
Páginas propias (no modal). Campos: título, descripción, prioridad (baja/media/ alta/crítica), estado (abierto/en revisión/resuelto/cerrado), tipo (defecto/ seguridad/calidad/documentación/otro), asignado y notas de resolución. Al guardar se abre el detalle.
Detalle de incidencia
- Tareas (checklist): añadir/marcar/eliminar tareas con asignado y fecha límite; barra de % de avance; aplicar una plantilla de checklist para alta masiva.
- Seguimiento y comentarios: hilo de comentarios, cada uno con foto opcional.
- Fotos de la incidencia: galería con subida/eliminación.
- Verificación / workflow: enviar a revisión (cuando las tareas están completas), validar y resolver, cerrar, reabrir; con notas de resolución.
📷 Captura: detalle de incidencia (checklist + comentarios + fotos).
Plantillas de checklist
Incidencias → Plantillas: crea listas de tareas reutilizables (para defectos recurrentes) que luego se aplican a cualquier incidencia.
Notificaciones
Se notifica (campana) al asignar una incidencia/tarea, al comentar y al cambiar de estado. El comando programado avisa de tareas vencidas.
6.8 Cronograma (Gantt)
Proyectos → Gantt: vista de planificación temporal de las fases del proyecto.
📷 Captura: cronograma Gantt.
6.9 Informes y exportaciones
Informes muestra un panel con métricas y permite exportar a Excel: proyectos, fases e inspecciones. (Requiere permisos ver/exportar informes.)
📷 Captura: panel de informes.
6.10 Empresas
Empresas: tabla (Rappasoft) con búsqueda y filtros (tipo, estado). Permite crear, ver y editar empresas (logo, NIF, contacto, dirección…). Las empresas se asignan a proyectos con un rol desde la pestaña Empresas del proyecto.
📷 Captura: listado de empresas.
6.11 Usuarios
Administración → Usuarios: tabla (Rappasoft) de usuarios. Crear/editar usuario incluye datos personales, empresa, estado y validez, rol del sistema, idioma por defecto (con banderas) y notas. La asignación a proyectos (con rol) se hace desde la pestaña Usuarios del proyecto.
📷 Captura: formulario de crear/editar usuario (con el selector de idioma).
6.12 Roles y permisos (administración)
Administración → Roles: tabla de roles; al crear/editar un rol se asignan permisos mediante una matriz agrupada por sección. Administración → Permisos muestra el catálogo completo.
6.13 Portal del cliente
Los usuarios con rol de cliente disponen de un panel simplificado (/client)
centrado en consultar el avance de sus proyectos.
6.14 Archivos / galería
Cada proyecto y elemento dispone de un gestor de archivos (imágenes y documentos) con subida, visor y eliminación, según permisos de Archivos.
7. Flujos de trabajo típicos
7.1 Poner en marcha un proyecto (Admin/Supervisor)
- Proyectos → Nuevo: rellena datos y ubicación.
- Pestaña Fases: crea las fases con fechas y colores.
- Pestaña Usuarios/Empresas: asigna el equipo y las empresas con su rol.
- Mapa: crea capas e importa/dibuja los elementos.
- Plantillas: define las plantillas de inspección necesarias.
7.2 Trabajo de seguimiento (en obra/oficina)
- En el Mapa, selecciona un elemento y registra una inspección.
- Si detectas un problema, pulsa “Incidencia” para crearla vinculada al elemento.
- En el detalle de la incidencia, añade el checklist (o aplica una plantilla), asigna responsables y fechas, sube fotos y comenta el avance.
- Cuando todas las tareas están hechas, envía a revisión y luego valida y resuelve.
7.3 Reporte y cierre
- Actualiza el progreso de fases/elementos.
- Consulta el Gantt y el Dashboard del proyecto.
- En Informes, exporta a Excel proyectos/fases/inspecciones para la entrega.
8. API (app móvil)
La aplicación expone una API REST (prefijo /api/v1) pensada para una app móvil
offline-first. El contrato completo está en:
docs/openapi.yaml— especificación OpenAPI 3.docs/MOBILE_SYNC_PROTOCOL.md— protocolo de sincronización.docs/MOBILE_APP_BRIEF.md— guía de traspaso con ejemplos y modelo de datos.
8.1 Autenticación
Tokens Sanctum por dispositivo (ability mobile-sync). POST /login devuelve el
token; el resto de llamadas usan Authorization: Bearer <token>.
8.2 Endpoints
| Método | Ruta | Uso |
|---|---|---|
| POST | /api/v1/login |
Token de dispositivo |
| GET | /api/v1/me |
Usuario + permisos |
| POST | /api/v1/logout |
Revocar token |
| GET | /api/v1/projects |
Proyectos accesibles |
| GET | /api/v1/projects/{id}/bundle?since= |
Descarga (snapshot o delta + borrados) |
| GET | /api/v1/templates?since= |
Plantillas (versión/hash) |
| POST | /api/v1/sync |
Subida de cambios (idempotente por uuid) |
| POST | /api/v1/media |
Subida de ficheros (multipart) |
8.3 Modelo de sincronización (resumen)
- PULL:
bundlecompleto la primera vez; luego?since=<fecha>trae solo lo cambiado más los ids borrados (tombstones). El parámetrosincedebe ir URL-encoded. - PUSH
/sync: lote de operaciones, cada una conuuid(idempotencia) yclient_updated_at. Respuesta por operación:applied | duplicate | conflict | error(conflictos por last-write-wins). - Media: multipart, idempotente por
uuid, asociada a la entidad padre. - Seguridad: el servidor fija
user_id/project_idy valida permisos por operación.
Detalle de operaciones, payloads y campos: ver
docs/MOBILE_APP_BRIEF.md.
9. Mantenimiento, copias de seguridad y actualización
9.1 Copias de seguridad
- Base de datos: copia diaria (
mysqldump) — contiene todos los datos. - Archivos subidos: copia de
storage/app/public(fotos, logos, documentos). - Guarda también una copia del
.env(contiene claves y credenciales) en lugar seguro.
9.2 Actualización de versión
Sigue 3.11: git pull, composer install --no-dev, recompilar assets, migrate --force y regenerar cachés. Haz copia de seguridad antes de migrar.
9.3 Tareas programadas
El cron del planificador (3.8) debe estar activo para los avisos de tareas vencidas.
9.4 Buenas prácticas
APP_DEBUG=falseen producción.- HTTPS forzado.
- Cambiar credenciales por defecto y revisar permisos de roles.
10. Resolución de problemas (FAQ)
No se ven los estilos / la página sale “rota”.
No se subieron los assets compilados. Ejecuta npm run build y sube public/build;
revisa que APP_URL sea correcta y regenera cachés.
Las imágenes/fotos no se ven (icono roto).
Falta el enlace de almacenamiento: php artisan storage:link y FILESYSTEM_DISK=public.
Error 500 tras desplegar.
Revisa .env (BD, APP_KEY con key:generate), permisos de storage/ y
bootstrap/cache, y php artisan config:clear.
Las banderas se ven como “ES/GB” en vez de la bandera.
Es comportamiento de algunos sistemas con emoji; la app usa banderas SVG locales
(/images/flags). Verifica que esa carpeta se subió.
Un usuario no ve un módulo / no puede crear. Es cuestión de permisos: asígnaselos a su rol en Administración → Roles.
composer install falla por versión de PHP.
Usa PHP 8.3, o composer install --no-dev --ignore-platform-reqs.
Los avisos de vencimiento no llegan. Falta el cron del planificador (3.8) o el correo/notificaciones no están configurados.
11. Anexos
11.1 Mapa de rutas principales
| Sección | Ruta |
|---|---|
| Login | /login |
| Dashboard | /dashboard |
| Proyectos | /projects |
| Editar proyecto | /projects/{id}/edit |
| Mapa | /projects/{id}/map |
| Gantt | /projects/{id}/gantt |
| Informe del proyecto | /projects/{id}/report |
| Incidencias | /projects/{id}/issues |
| Plantillas de checklist | /projects/{id}/issues/checklists |
| Plantillas de inspección | /projects/{id}/templates |
| Empresas | /companies |
| Usuarios | /admin/users |
| Roles | /admin/roles |
| Permisos | /admin/permissions |
| Informes | /reports/dashboard |
| Portal cliente | /client |
11.2 Documentos relacionados
docs/openapi.yaml,docs/MOBILE_SYNC_PROTOCOL.md,docs/MOBILE_APP_BRIEF.md.
11.3 Índice de capturas
Lista de huecos de captura marcados con “📷 Captura:” a lo largo del manual, para insertarlos al pasar el documento a Word.