construprogress/docs/MANUAL.md

<!--
  Portada / índice: este documento está pensado para convertirse a Word.
  - Para generar el .docx conservando títulos e índice navegable:
      pandoc docs/MANUAL.md -o docs/Manual.docx --toc --toc-depth=3
  - Los bloques "📷 Captura:" son huecos donde insertar la imagen correspondiente.
-->

<div align="center">

# 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`) |

</div>

<div style="page-break-after: always;"></div>

---

## Índice

1. [Introducción y conceptos](#1-introducción-y-conceptos)
2. [Requisitos del sistema](#2-requisitos-del-sistema)
3. [Instalación y despliegue](#3-instalación-y-despliegue)
4. [Acceso y primeros pasos](#4-acceso-y-primeros-pasos)
5. [Roles y permisos](#5-roles-y-permisos)
6. [Manual de uso por secciones](#6-manual-de-uso-por-secciones)
7. [Flujos de trabajo típicos](#7-flujos-de-trabajo-típicos)
8. [API (app móvil)](#8-api-app-móvil)
9. [Mantenimiento, copias de seguridad y actualización](#9-mantenimiento-copias-de-seguridad-y-actualización)
10. [Resolución de problemas (FAQ)](#10-resolución-de-problemas-faq)
11. [Anexos](#11-anexos)

<div style="page-break-after: always;"></div>

---

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

<div style="page-break-after: always;"></div>

---

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

<div style="page-break-after: always;"></div>

---

# 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
```

<div style="page-break-after: always;"></div>

---

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

<div style="page-break-after: always;"></div>

---

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

<div style="page-break-after: always;"></div>

---

# 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**:
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.

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

<div style="page-break-after: always;"></div>

---

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

<div style="page-break-after: always;"></div>

---

# 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`.

<div style="page-break-after: always;"></div>

---

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

<div style="page-break-after: always;"></div>

---

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

<div style="page-break-after: always;"></div>

---

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