metis-desk/docs/rutas-del-cliente.md

# Rutas del cliente

La URL del navegador identifica el espacio, la sección y, cuando existe una ficha,
el registro seleccionado. No cambia los endpoints HTTP de `/api`, los permisos ni
la persistencia. Los identificadores de compañía y de registros son UUID.

## Destinos generales

| Ruta | Pantalla |
| --- | --- |
| `/dashboard` | Inicio y resumen global; admite `companyId` para limitar el ámbito. |
| `/companies` | Directorio de compañías. |
| `/companies/:companyId` | Estado y resumen operativo de la compañía. |
| `/tickets` | Tickets de todas las compañías, con filtros. |
| `/interventions` | Intervenciones de todas las compañías, con filtros. |
| `/catalogs` | Índice explicativo de catálogos globales. |
| `/settings/users` | Gestión de usuarios, reservada al administrador inicial. |
| `/settings/password` | Cambio de contraseña del usuario conectado. |
| `/login` | Acceso cuando no hay sesión. |
| `/setup` | Alta del administrador inicial únicamente cuando el servidor la requiere. |

`/` se normaliza a `/dashboard`. Las barras finales se eliminan conservando la
consulta. El acceso sin sesión conserva el destino interno en `returnTo`; tras
autenticar se recupera ese destino. No se aceptan redirecciones a otros orígenes.

## Espacio de compañía

Todas las secciones siguientes cuelgan de `/companies/:companyId`:

```text
/companies/:companyId                 → resumen, no inventario
├── assets
├── resources
├── workstations
├── work-profiles
├── telework-authorizations
├── remote-connections
├── processes
├── intervention-templates
├── interventions
├── tickets
├── people
├── departments
├── sites
├── access
├── folder-mappings
├── certificate-configurations
├── application-configurations
├── printer-configurations
├── mail-configurations
└── catalogs                          → índice de catálogos de la compañía
    ├── assets
    └── resources
```

`assets` contiene equipos concretos. `workstations` contiene puestos que agrupan
activos exclusivos o compartidos; no es un alias de activos. `work-profiles`
representa el entorno de una persona en un dispositivo. Sus rutas independientes
respetan las responsabilidades existentes, sin introducir entidades nuevas.

Las fichas existentes de activos, recursos, personas, perfiles, procesos, tickets
e intervenciones utilizan `/<section>/:entityId`. Las de tickets e intervenciones
se abren en su compañía incluso cuando proceden del listado global. El inventario
conserva el panel lateral en escritorio y el diálogo de ficha en anchuras menores
de 1100 px, ambos asociados al UUID de la URL.

Las configuraciones de un perfil tienen rutas contextuales:

```text
/companies/:companyId/work-profiles/:profileId
├── folder-mappings
├── mail-configurations
├── certificate-configurations
├── application-configurations
└── printer-configurations
```

Los accesos remotos y el teletrabajo de una persona se consultan en sus secciones
propias con `personId`. Las vistas generales de configuraciones admiten `profileId`.
No se crean fichas URL para entidades que actualmente solo tienen editor o historial.

## Catálogos globales

```text
/catalogs
├── access
├── assets
├── resources
├── brands
├── intervention-templates
└── process-templates
```

El índice ofrece enlaces y explica el ámbito; no inventa estadísticas. Los catálogos
de compañía representan las variantes de activos y recursos disponibles en ese
ámbito, no duplicados de las rutas de inventario.

## Filtros y estado temporal

La consulta conserva los filtros que ya están conectados a la URL:

- Dashboard y directorio: `companyId`; directorio también `activeOnly` y `q`.
- Tickets: `companyId`, `pendingOnly`, `q`, `state`, `priority` y `assignee`.
- Intervenciones: `companyId`, `pendingOnly`, `q`, `state`, `assignee`, `dateFrom` y `dateTo`.
- Activos y recursos: `q`.
- Perfiles y procesos: `q`, con `archived` o `closed`, respectivamente.
- Catálogos de activos y recursos: `q` y `tab`; `relations` solo en activos.
- Cuentas y accesos: `q` y `kind`, respetando los tipos disponibles en cada ámbito.

Los booleanos se serializan como `true` o `false`; las fechas como ISO `YYYY-MM-DD`.
`assignee` admite UUID o `unassigned`. Los estados y prioridades se validan con los
schemas compartidos del dominio; los UUID, las pestañas y los parámetros repetidos
o desconocidos se rechazan antes de seleccionar una pantalla. La búsqueda admite
hasta 200 caracteres. Un `companyId` de consulta no puede contradecir la compañía
del pathname. Esta validación del navegador no sustituye la autorización del servidor.

Cambiar filtros reemplaza la entrada actual del historial; abrir otra sección o
ficha añade una entrada. Atrás y Adelante recuperan los destinos y filtros. Cerrar
una ficha vuelve al destino interno anterior; si se abrió directamente, sustituye
la entrada por su listado o por el contexto del perfil correspondiente.

Altas, ediciones, confirmaciones, historiales y detalles auxiliares del dashboard
siguen siendo diálogos locales. No se añaden rutas `/new`, `/edit` ni parámetros
`view` sin una necesidad concreta. El alta rápida que cambia de sección lleva una
señal temporal en `history.state`, consumida cuando monta la pantalla que abre el
formulario, sin introducirla en la URL compartida. Los restantes filtros locales,
la paginación, ordenación y preferencias de columnas mantienen su estado existente.

## Implementación y futuros destinos

- `@metis/core/client` centraliza la History API, suscripciones con cleanup,
  enlaces internos, búsqueda y selección de fichas. No se añade una dependencia
  de routing externa.
- `workspace/shared/helpers/workspace-routes.ts` es la fuente de rutas de compañía,
  construcción de destinos y validación del espacio. No repartir condiciones de
  pathname entre componentes de presentación.
- `apps/web/src/navigation` coordina los destinos según la sesión. El servidor
  mantiene su autenticación, autorización y validación HTTP existentes.
- `BrowserLink` produce enlaces reales y conserva abrir en otra pestaña, clic
  modificado y navegación por teclado. Las secciones activas indican `aria-current`.
- Un UUID válido ausente en el ámbito muestra ausencia explícita: no selecciona
  otro registro silenciosamente. Rutas mal formadas y destinos desconocidos tienen
  estados diferenciados y acceso de regreso a Inicio.

Para añadir una sección, actualizar los contratos y el mapa del espacio, revisar sus
consumidores y probar construcción, acceso directo, recarga, historial y casos
inválidos. No cambiar el modelo de dominio únicamente para reproducir una jerarquía URL.
La organización de ficheros sigue el [estándar web](estructura-web-por-entidades-y-operaciones.md).

## Servicio de la SPA

Vite en desarrollo y en preview entrega la SPA para estas rutas. Un servidor de
producción debe servir `index.html` para los destinos del cliente y mantener el
tratamiento propio de `/api` y de los archivos estáticos. Sin ese fallback, abrir
o recargar una ficha dará un 404 del alojamiento aunque la navegación interna funcione.
La API compilada todavía no sirve el frontend estático: no se ha cambiado su
despliegue ni añadido un fallback a Express en esta adaptación.