docs: manual del programa (instalación, uso por secciones, roles/permisos, flujos, API, FAQ)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

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