From 4f6617540688faaadfaf76209319d1d679d7cf66 Mon Sep 17 00:00:00 2001 From: javier Date: Thu, 18 Jun 2026 16:42:06 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20manual=20del=20programa=20(instalaci?= =?UTF-8?q?=C3=B3n,=20uso=20por=20secciones,=20roles/permisos,=20flujos,?= =?UTF-8?q?=20API,=20FAQ)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/MANUAL.md | 483 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 483 insertions(+) create mode 100644 docs/MANUAL.md diff --git a/docs/MANUAL.md b/docs/MANUAL.md new file mode 100644 index 0000000..036d141 --- /dev/null +++ b/docs/MANUAL.md @@ -0,0 +1,483 @@ +# 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: +```bash +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. +```bash +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: +```ini +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 +```bash +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 +```bash +chmod -R ug+rwX storage bootstrap/cache +``` + +## 3.8 Cron del planificador (avisos de tareas vencidas) +Añade un cron **cada minuto**: +```cron +* * * * * 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) +```bash +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 `. + +## 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=` 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.)*