construprogress/docs/MANUAL.md

Manual de ConstruProgress

Aplicación de seguimiento de obra — MAI Group / RTE International

Versión del documento	1.0
Fecha	Junio 2026
Ámbito	Aplicación web + API para la app móvil

Documento de origen en Markdown (docs/MANUAL.md). Para obtener el Word: pandoc docs/MANUAL.md -o docs/Manual.docx, o copiar/pegar en Manual.docx.

---

Índice

1. Introducción y conceptos
2. Requisitos del sistema
3. Instalación y despliegue
4. Acceso y primeros pasos
5. Roles y permisos
6. Manual de uso por secciones
7. Flujos de trabajo típicos
8. API (app móvil)
9. Mantenimiento, copias de seguridad y actualización
10. Resolución de problemas (FAQ)
11. 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.

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 install necesita --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): root del 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

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.

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.

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.

Crear / Editar

El editor de proyecto está organizado en pestañas:

1. Datos: referencia, nombre, dirección, ubicación (lat/lng en mapa), fechas y estado.
2. Fases (ver 6.3).
3. Usuarios (ver 6.11): asignar usuarios al proyecto con su rol.
4. Empresas: asignar empresas al proyecto con su rol.

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.)

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.

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).

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).

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.

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.

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.)

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.

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.

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)

1. Proyectos → Nuevo: rellena datos y ubicación.
2. Pestaña Fases: crea las fases con fechas y colores.
3. Pestaña Usuarios/Empresas: asigna el equipo y las empresas con su rol.
4. Mapa: crea capas e importa/dibuja los elementos.
5. Plantillas: define las plantillas de inspección necesarias.

7.2 Trabajo de seguimiento (en obra/oficina)

1. En el Mapa, selecciona un elemento y registra una inspección.
2. Si detectas un problema, pulsa “Incidencia” para crearla vinculada al elemento.
3. En el detalle de la incidencia, añade el checklist (o aplica una plantilla), asigna responsables y fechas, sube fotos y comenta el avance.
4. Cuando todas las tareas están hechas, envía a revisión y luego valida y resuelve.

7.3 Reporte y cierre

1. Actualiza el progreso de fases/elementos.
2. Consulta el Gantt y el Dashboard del proyecto.
3. 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: bundle completo la primera vez; luego ?since=<fecha> trae solo lo cambiado más los ids borrados (tombstones). El parámetro since debe ir URL-encoded.
• PUSH /sync: lote de operaciones, cada una con uuid (idempotencia) y client_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_id y 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=false en 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 Capturas de pantalla

(Reservado: insertar capturas de cada sección al pasar el manual a Word.)