docs(manual): portada + índice navegable + huecos de captura; copia en inglés (MANUAL.en.md)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-18 16:50:39 +02:00
parent 4f66175406
commit 9c164bb7ef
2 changed files with 634 additions and 17 deletions
@@ -0,0 +1,547 @@
+<!--
+  Cover / TOC: this document is meant to be converted to Word.
+  - To generate the .docx with headings and a navigable TOC:
+      pandoc docs/MANUAL.en.md -o docs/Manual_EN.docx --toc --toc-depth=3
+  - The "📷 Screenshot:" blocks are placeholders where the matching image goes.
+-->
+
+<div align="center">
+
+# ConstruProgress
+
+## Application Manual
+
+**Construction site tracking system**
+
+MAI Group · RTE International
+
+📷 *Screenshot: cover / application logo (`public/images/logo-rte.png`).*
+
+| | |
+|---|---|
+| Document version | 1.0 |
+| Date | June 2026 |
+| Scope | Web application + mobile app API |
+| Language | English (Spanish version: `MANUAL.md`) |
+
+</div>
+
+<div style="page-break-after: always;"></div>
+
+---
+
+## Table of contents
+
+1. [Introduction and concepts](#1-introduction-and-concepts)
+2. [System requirements](#2-system-requirements)
+3. [Installation and deployment](#3-installation-and-deployment)
+4. [Access and getting started](#4-access-and-getting-started)
+5. [Roles and permissions](#5-roles-and-permissions)
+6. [Section-by-section user guide](#6-section-by-section-user-guide)
+7. [Typical workflows](#7-typical-workflows)
+8. [API (mobile app)](#8-api-mobile-app)
+9. [Maintenance, backups and updates](#9-maintenance-backups-and-updates)
+10. [Troubleshooting (FAQ)](#10-troubleshooting-faq)
+11. [Appendices](#11-appendices)
+
+<div style="page-break-after: always;"></div>
+
+---
+
+# 1. Introduction and concepts
+
+## 1.1 What is ConstruProgress?
+
+ConstruProgress is a web application for **construction site tracking and control**.
+It organizes each project into phases, maps its elements on an interactive map, records
+inspections via templates, manages issues (with tasks, comments and photos) and produces
+reports. It also powers a **mobile app that works offline** in the field and syncs once
+back online.
+
+📷 *Screenshot: main dashboard with the overview.*
+
+## 1.2 Key concepts (glossary)
+
+| Term | Meaning |
+|---|---|
+| **Project** | Main unit of work (a construction site). Contains phases, layers, elements, inspections and issues. |
+| **Phase** | A project stage (e.g. Foundations, Structure). Has order, color, progress and planned/actual dates. |
+| **Layer** | A grouping of elements on the map within a phase. |
+| **Element (feature)** | A geographic object (point/line/polygon) on the map, with status and % progress. |
+| **Inspection** | A control record on an element, usually via a **template**. |
+| **Inspection template** | A reusable form with configurable fields (text, number, %, boolean, select…). |
+| **Issue** | A detected problem or defect: has priority, status, type, tasks, comments and photos. |
+| **Issue checklist** | A task list to resolve an issue; can be generated from a **checklist template**. |
+| **Role** | A user's set of permissions in the system (Admin, Supervisor…). |
+| **Project role** | A user/company's role within a specific project (supervisor, client, constructor…). |
+
+## 1.3 Architecture (technical summary)
+
+- **Backend:** Laravel 12 (PHP 8.2+), Livewire 3 (Volt).
+- **UI:** TailwindCSS + DaisyUI, Rappasoft tables, Leaflet maps, Heroicons.
+- **DB:** MySQL/MariaDB.
+- **Permissions:** spatie/laravel-permission.
+- **Mobile API:** Laravel Sanctum (tokens), offline-first sync.
+
+<div style="page-break-after: always;"></div>
+
+---
+
+# 2. System requirements
+
+**Server**
+- PHP **8.3** recommended (minimum 8.2). Extensions: `mbstring, pdo_mysql, openssl, tokenizer, xml, ctype, json, bcmath, fileinfo, curl, gd, zip`.
+- MySQL/MariaDB.
+- Composer. (Node only to build the assets, preferably locally.)
+- HTTPS (SSL).
+
+> **Version note:** a dependency (`zipstream-php`) requires PHP 8.3. With PHP 8.2,
+> `composer install` needs `--ignore-platform-reqs`. Recommended: use PHP 8.3.
+
+**Client (browser)**
+- A modern browser (Chrome, Edge, Firefox, Safari) with JavaScript enabled.
+
+<div style="page-break-after: always;"></div>
+
+---
+
+# 3. Installation and deployment
+
+Guide for a web server such as OVH (VPS recommended; also valid on shared hosting with
+the noted caveats).
+
+## 3.1 Database
+Create a MySQL database and a user with privileges. Note the **host, name, user and
+password**.
+
+## 3.2 Build the assets (on your PC)
+The host usually has no Node. Build locally and upload the result:
+```bash
+npm install
+npm run build        # generates public/build
+```
+
+## 3.3 Upload the code
+Upload the whole project **except** `node_modules/`, `.git/` and `.env`. You can install
+`vendor/` on the server (if you have SSH) or upload it.
+```bash
+composer install --no-dev --optimize-autoloader
+```
+
+## 3.4 Document root → `public/` folder
+The domain must point to `…/construprogress/public` (never the root).
+- **VPS (nginx/apache):** virtualhost `root` → `/path/construprogress/public`.
+- **OVH shared:** in *Multisite*, set the domain root folder → `construprogress/public`.
+
+## 3.5 Configure `.env`
+Copy `.env.example` to `.env` and adjust:
+```ini
+APP_NAME=ConstruProgress
+APP_ENV=production
+APP_DEBUG=false
+APP_URL=https://yourdomain.com
+APP_LOCALE=es
+
+DB_CONNECTION=mysql
+DB_HOST=...
+DB_DATABASE=...
+DB_USERNAME=...
+DB_PASSWORD=...
+
+FILESYSTEM_DISK=public      # photos/files use the public disk
+SESSION_DRIVER=database
+```
+
+## 3.6 Prepare the application
+```bash
+php artisan key:generate
+php artisan migrate --force
+php artisan db:seed --force        # roles, permissions (PermissionCatalogSeeder…)
+php artisan storage:link           # public/storage → storage/app/public
+php artisan config:cache
+php artisan route:cache
+php artisan view:cache
+```
+
+## 3.7 Write permissions
+```bash
+chmod -R ug+rwX storage bootstrap/cache
+```
+
+## 3.8 Scheduler cron (overdue task alerts)
+Add a cron **every minute**:
+```cron
+* * * * * cd /path/construprogress && php artisan schedule:run >> /dev/null 2>&1
+```
+This runs `issues:notify-overdue` daily. No queue worker is needed (notifications are
+synchronous).
+
+## 3.9 HTTPS
+Enable OVH's free SSL (Let's Encrypt) and force HTTPS.
+
+## 3.10 Post-deploy checks
+- The home redirects to **login** (correct).
+- The **logo** (`/images/logo-rte.png`) and **flags** (`/images/flags/*.svg`) display.
+- Uploading a **photo** in an issue works (validates `storage:link` + `FILESYSTEM_DISK=public`).
+- The **API** responds: `GET https://yourdomain.com/api/v1/...` with a token.
+
+## 3.11 Deploying later changes
+```bash
+git pull
+composer install --no-dev --optimize-autoloader
+# (on your PC) npm run build  and upload 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. Access and getting started
+
+📷 *Screenshot: login screen with the language switcher.*
+
+## 4.1 Sign in
+Go to `https://yourdomain.com/login` with your email and password. After installation,
+the seeder creates an initial administrator (**admin@email.com**) — **change its
+password** as soon as you log in.
+
+## 4.2 Password recovery
+From the login, “Forgot your password?” sends a reset email (requires outgoing mail
+configured in `.env`).
+
+## 4.3 Profile
+In the user menu → **Profile** you can update your details, change your password and
+(optionally) delete your account.
+
+## 4.4 Language
+The application is available in **Spanish** and **English**. Switch the language with the
+flag toggle (🇪🇸/🇬🇧) in the header. Each user also has a **default language** configurable
+when creating/editing the user.
+
+<div style="page-break-after: always;"></div>
+
+---
+
+# 5. Roles and permissions
+
+## 5.1 System roles (baseline)
+
+| Role | Baseline permissions (editable) |
+|---|---|
+| **Admin** | Full access (`manage all`). |
+| **Supervisor** | View projects, upload layers, update progress. |
+| **Consultant (Consultor)** | View projects, view reports. |
+| **Client (Cliente)** | View projects. |
+
+> Each role's permissions are **fully configurable** from *Administration → Roles*
+> (permission matrix). The table above is the seeder's initial setup. For a non-Admin
+> role to use newer modules (phases, issues, assignments…), grant the matching
+> permissions.
+
+📷 *Screenshot: permission matrix when editing a role.*
+
+## 5.2 Permission catalogue (by section)
+
+- **Projects:** view, create, edit, delete, export.
+- **Phases & progress:** view phases, manage phases, update progress.
+- **Layers & elements:** view, upload/import, edit, delete.
+- **Inspections:** view, record, delete, manage templates.
+- **Issues:** view, create, edit (resolve/close), delete.
+- **Companies:** view, create, edit, delete, **assign to projects**.
+- **Users:** view, create, edit, delete, **assign users/roles to projects**.
+- **Roles:** manage roles and permissions.
+- **Reports:** view panel, export.
+- **Files:** view, upload, delete.
+- **General:** `manage all` (super-administrator).
+
+## 5.3 Project role (different from the system role)
+When assigning **users** to a project you pick their role: *Supervisor, Consultant,
+Client, Viewer*. For **companies**: *Owner, Constructor, Subcontractor, Consultant,
+Supplier, Other*.
+
+<div style="page-break-after: always;"></div>
+
+---
+
+# 6. Section-by-section user guide
+
+## 6.1 Main dashboard
+Home view with the overview: accessible projects, progress, open/critical issues and
+recent issues. Includes shortcuts to the sections.
+
+📷 *Screenshot: main dashboard.*
+
+## 6.2 Projects
+
+### Listing
+*Projects* shows a table (with search and sorting) of the projects you can access, with
+reference, name, address, status, progress and dates. Row actions: **Dashboard**, **Map**
+and **Edit**.
+
+📷 *Screenshot: project listing.*
+
+### Create / Edit
+The project editor is organized into **tabs**:
+1. **Data**: reference, name, address, location (lat/lng on a map), dates and status.
+2. **Phases** (see 6.3).
+3. **Users** (see 6.11): assign users to the project with their role.
+4. **Companies**: assign companies to the project with their role.
+
+📷 *Screenshot: project editor (Data tab).*
+
+## 6.3 Phases
+Inside the project editor, the **Phases** tab lists phases in a table (order, name,
+progress, dates, color) and lets you:
+- **Add phase**: opens a **modal form** with all parameters (name, description, order,
+  color, % progress, planned and actual dates).
+- **Edit**: same modal with the data loaded.
+- **Update progress**: a dedicated screen to record progress.
+- **Delete**.
+(Requires the *manage phases* permission.)
+
+📷 *Screenshot: Phases tab with the table and the create/edit modal.*
+
+## 6.4 Project map
+*Projects → Map* opens the interactive map (Leaflet) with side tabs/panel:
+- **Layers & elements**: visualization by layers; selecting an element shows its panel
+  with responsible, progress, files and inspections.
+- **Inspection**: from an element, pick a template and record the inspection.
+- **Files**: the element's file manager.
+- **Issues**: tab with the project's issues; from an element you can click **“Issue”** to
+  report a new one already linked to that element.
+
+📷 *Screenshot: project map with a selected element panel.*
+
+## 6.5 Layers and elements
+Manage layers per phase (import/upload, edit, delete) and the elements they contain,
+with their geometry, status and progress.
+
+## 6.6 Inspections and templates
+- **Templates** (*Projects → Templates*): configurable forms (text, number, percentage,
+  boolean, select, textarea fields…). Each template is versioned for mobile sync.
+- **Record inspection**: from the map, on an element, by selecting the template and
+  filling its fields (status, result, notes).
+
+📷 *Screenshot: inspection form from the map.*
+
+## 6.7 Issues
+Accessible from *Projects → Issues* or the Issues tab on the map.
+
+### Listing
+A table (Rappasoft) with **filters by status, priority and type**, search, a task
+progress bar, comment/photo counters and an **overdue** tasks badge. The header has
+**New issue** and **Templates** (checklist) buttons.
+
+📷 *Screenshot: issue listing with filters.*
+
+### Create / Edit
+Dedicated pages (not a modal). Fields: title, description, **priority** (low/medium/
+high/critical), **status** (open/in review/resolved/closed), **type** (defect/safety/
+quality/documentation/other), assignee and resolution notes. Saving opens the **detail**.
+
+### Issue detail
+- **Tasks (checklist)**: add/check/delete tasks with assignee and due date; a % progress
+  bar; **apply a checklist template** for bulk creation.
+- **Follow-up & comments**: comment thread, each with an optional photo.
+- **Issue photos**: a gallery with upload/delete.
+- **Verification / workflow**: send to review (when tasks are complete), **validate and
+  resolve**, close, reopen; with resolution notes.
+
+📷 *Screenshot: issue detail (checklist + comments + photos).*
+
+### Checklist templates
+*Issues → Templates*: create reusable task lists (for recurring defects) to later apply
+to any issue.
+
+### Notifications
+A bell notification is sent when an issue/task is assigned, when someone comments and on
+status changes. The scheduled command alerts about **overdue tasks**.
+
+## 6.8 Gantt chart
+*Projects → Gantt*: a timeline view of the project's phases.
+
+📷 *Screenshot: Gantt chart.*
+
+## 6.9 Reports and exports
+*Reports* shows a metrics panel and lets you **export to Excel**: projects, phases and
+inspections. (Requires *view/export reports* permissions.)
+
+📷 *Screenshot: reports panel.*
+
+## 6.10 Companies
+*Companies*: a table (Rappasoft) with search and filters (type, status). Lets you create,
+view and edit companies (logo, tax ID, contact, address…). Companies are assigned to
+projects with a role from the project's Companies tab.
+
+📷 *Screenshot: company listing.*
+
+## 6.11 Users
+*Administration → Users*: a table (Rappasoft) of users. Creating/editing a user includes
+personal data, company, status and validity, **system role**, **default language** (with
+flags) and notes. Project assignment (with a role) is done from the project's Users tab.
+
+📷 *Screenshot: create/edit user form (with the language selector).*
+
+## 6.12 Roles and permissions (administration)
+*Administration → Roles*: a roles table; creating/editing a role assigns permissions via
+a **matrix** grouped by section. *Administration → Permissions* shows the full catalogue.
+
+## 6.13 Client portal
+Client-role users get a **simplified panel** (`/client`) focused on checking the progress
+of their projects.
+
+## 6.14 Files / gallery
+Each project and element has a file manager (images and documents) with upload, viewer
+and delete, according to *Files* permissions.
+
+<div style="page-break-after: always;"></div>
+
+---
+
+# 7. Typical workflows
+
+## 7.1 Set up a project (Admin/Supervisor)
+1. **Projects → New**: fill in data and location.
+2. **Phases** tab: create phases with dates and colors.
+3. **Users/Companies** tabs: assign the team and companies with their role.
+4. **Map**: create layers and import/draw the elements.
+5. **Templates**: define the inspection templates you need.
+
+## 7.2 Field/office tracking
+1. On the **Map**, select an element and **record an inspection**.
+2. If you spot a problem, click **“Issue”** to create it linked to the element.
+3. In the **issue detail**, add the **checklist** (or apply a template), assign owners
+   and dates, upload **photos** and comment on progress.
+4. When all tasks are done, **send to review** and then **validate and resolve**.
+
+## 7.3 Reporting and closing
+1. Update the **progress** of phases/elements.
+2. Check the **Gantt** and the project **Dashboard**.
+3. In **Reports**, export projects/phases/inspections to Excel for delivery.
+
+<div style="page-break-after: always;"></div>
+
+---
+
+# 8. API (mobile app)
+
+The application exposes a REST API (prefix `/api/v1`) designed for an **offline-first**
+mobile app. The full contract lives in:
+- `docs/openapi.yaml` — OpenAPI 3 specification.
+- `docs/MOBILE_SYNC_PROTOCOL.md` — sync protocol.
+- `docs/MOBILE_APP_BRIEF.md` — handoff guide with examples and the data model.
+
+## 8.1 Authentication
+Per-device **Sanctum** tokens (ability `mobile-sync`). `POST /login` returns the token;
+all other calls use `Authorization: Bearer <token>`.
+
+## 8.2 Endpoints
+| Method | Route | Use |
+|---|---|---|
+| POST | `/api/v1/login` | Device token |
+| GET | `/api/v1/me` | User + permissions |
+| POST | `/api/v1/logout` | Revoke token |
+| GET | `/api/v1/projects` | Accessible projects |
+| GET | `/api/v1/projects/{id}/bundle?since=` | Download (snapshot or delta + deletions) |
+| GET | `/api/v1/templates?since=` | Templates (version/hash) |
+| POST | `/api/v1/sync` | Push changes (idempotent by `uuid`) |
+| POST | `/api/v1/media` | Upload files (multipart) |
+
+## 8.3 Sync model (summary)
+- **PULL**: full `bundle` the first time; then `?since=<date>` returns only what changed
+  plus the **deleted ids** (tombstones). The `since` parameter must be **URL-encoded**.
+- **PUSH** `/sync`: a batch of operations, each with `uuid` (idempotency) and
+  `client_updated_at`. Per-operation response: `applied | duplicate | conflict | error`
+  (conflicts via *last-write-wins*).
+- **Media**: multipart, idempotent by `uuid`, attached to the parent entity.
+- **Security**: the server sets `user_id`/`project_id` and validates permissions per op.
+
+> Operation, payload and field detail: see `docs/MOBILE_APP_BRIEF.md`.
+
+<div style="page-break-after: always;"></div>
+
+---
+
+# 9. Maintenance, backups and updates
+
+## 9.1 Backups
+- **Database**: daily backup (`mysqldump`) — contains all data.
+- **Uploaded files**: back up `storage/app/public` (photos, logos, documents).
+- Also keep a copy of `.env` (contains keys and credentials) in a safe place.
+
+## 9.2 Version updates
+Follow 3.11: `git pull`, `composer install --no-dev`, rebuild assets, `migrate --force`
+and regenerate caches. Back up **before** migrating.
+
+## 9.3 Scheduled tasks
+The scheduler cron (3.8) must be active for overdue task alerts.
+
+## 9.4 Best practices
+- `APP_DEBUG=false` in production.
+- Force HTTPS.
+- Change default credentials and review role permissions.
+
+<div style="page-break-after: always;"></div>
+
+---
+
+# 10. Troubleshooting (FAQ)
+
+**No styles / the page looks “broken”.**
+Compiled assets were not uploaded. Run `npm run build` and upload `public/build`; check
+`APP_URL` is correct and regenerate caches.
+
+**Images/photos don't show (broken icon).**
+Missing storage link: `php artisan storage:link` and `FILESYSTEM_DISK=public`.
+
+**500 error after deploying.**
+Check `.env` (DB, `APP_KEY` via `key:generate`), permissions on `storage/` and
+`bootstrap/cache`, and `php artisan config:clear`.
+
+**Flags show as “ES/GB” instead of the flag.**
+That's some systems' emoji behavior; the app uses local SVG flags (`/images/flags`).
+Verify that folder was uploaded.
+
+**A user can't see a module / can't create.**
+It's a permissions matter: grant them to their role in *Administration → Roles*.
+
+**`composer install` fails due to PHP version.**
+Use PHP 8.3, or `composer install --no-dev --ignore-platform-reqs`.
+
+**Overdue alerts don't arrive.**
+The scheduler cron (3.8) is missing, or mail/notifications aren't configured.
+
+<div style="page-break-after: always;"></div>
+
+---
+
+# 11. Appendices
+
+## 11.1 Main route map
+| Section | Route |
+|---|---|
+| Login | `/login` |
+| Dashboard | `/dashboard` |
+| Projects | `/projects` |
+| Edit project | `/projects/{id}/edit` |
+| Map | `/projects/{id}/map` |
+| Gantt | `/projects/{id}/gantt` |
+| Project report | `/projects/{id}/report` |
+| Issues | `/projects/{id}/issues` |
+| Checklist templates | `/projects/{id}/issues/checklists` |
+| Inspection templates | `/projects/{id}/templates` |
+| Companies | `/companies` |
+| Users | `/admin/users` |
+| Roles | `/admin/roles` |
+| Permissions | `/admin/permissions` |
+| Reports | `/reports/dashboard` |
+| Client portal | `/client` |
+
+## 11.2 Related documents
+- `docs/openapi.yaml`, `docs/MOBILE_SYNC_PROTOCOL.md`, `docs/MOBILE_APP_BRIEF.md`.
+
+## 11.3 Screenshot index
+> List of the “📷 Screenshot:” placeholders throughout the manual, to insert when
+> converting the document to Word.
@@ -1,31 +1,50 @@
-# Manual de ConstruProgress
+<!--
+  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.
+-->

-**Aplicación de seguimiento de obra — MAI Group / RTE International**
+<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`) |

-> 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`.
+</div>
+
+<div style="page-break-after: always;"></div>

 ---

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

 ---

@@ -39,6 +58,8 @@ registrar inspecciones con plantillas, gestionar incidencias (con tareas, coment
 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 |
@@ -62,6 +83,8 @@ trabaja sin conexión** en campo y sincroniza al recuperar red.
 - **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
@@ -78,6 +101,8 @@ trabaja sin conexión** en campo y sincroniza al recuperar red.
 **Cliente (navegador)**
 - Navegador moderno (Chrome, Edge, Firefox, Safari) con JavaScript activado.

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

 # 3. Instalación y despliegue
@@ -169,10 +194,14 @@ 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**
@@ -191,6 +220,8 @@ La aplicación está disponible en **Español** e **Inglés**. Cambia el idioma
 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
@@ -209,6 +240,8 @@ defecto** configurable al crear/editar el usuario.
 > 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.
@@ -228,6 +261,8 @@ 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
@@ -236,6 +271,8 @@ Consultor, Proveedor, Otro*.
 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
@@ -243,6 +280,8 @@ críticas e incidencias recientes. Incluye accesos directos a las secciones.
 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.
@@ -250,6 +289,8 @@ El editor de proyecto está organizado en **pestañas**:
 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:
@@ -260,6 +301,8 @@ Dentro del editor de proyecto, la pestaña **Fases** lista las fases en una tabl
 - **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
@@ -269,6 +312,8 @@ Dentro del editor de proyecto, la pestaña **Fases** lista las fases en una tabl
 - **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.
@@ -280,6 +325,8 @@ contienen, con su geometría, estado y progreso.
 - **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.

@@ -288,6 +335,8 @@ Tabla (Rappasoft) con **filtros por estado, prioridad y tipo**, búsqueda, barra
 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/
@@ -302,6 +351,8 @@ abre el **detalle**.
 - **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.
@@ -313,21 +364,29 @@ 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
@@ -341,6 +400,8 @@ centrado en consultar el avance de sus proyectos.
 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
@@ -365,6 +426,8 @@ subida, visor y eliminación, según permisos de *Archivos*.
 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)
@@ -403,6 +466,8 @@ token; el resto de llamadas usan `Authorization: Bearer <token>`.

 > 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
@@ -424,6 +489,8 @@ El cron del planificador (3.8) debe estar activo para los avisos de tareas venci
 - HTTPS forzado.
 - Cambiar credenciales por defecto y revisar permisos de roles.

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

 # 10. Resolución de problemas (FAQ)
@@ -452,6 +519,8 @@ 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
@@ -479,5 +548,6 @@ Falta el cron del planificador (3.8) o el correo/notificaciones no están config
 ## 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.)*
+## 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.