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. |
| `/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
├── 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 y procesos
utilizan `/<section>/:entityId`. 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
└── 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`.
- Activos: `q` y `template` (UUID de plantilla), tanto en el listado como en la ficha seleccionada.
- Recursos: `q` y `template` (UUID de plantilla), tanto en el listado como en la ficha seleccionada.
- Personas: `q` y `contactsOnly`, también al abrir su detalle.
- Los pilotos Activos, Recursos y Personas añaden `sort`, `direction` y `page`, según
  [L03.1](contexto-listados-l03-1.md). Son parámetros de las rutas existentes, no destinos nuevos.
- Puestos, Perfiles y directorio de Compañías adoptan también `sort`, `direction` y `page` en [L04.1](adopcion-listados-l04-1.md). Puestos añade `q`; Perfiles conserva `q`/`archived`; Compañías conserva `q`/`activeOnly`/`companyId`.
- Procesos: `q` y `closed`.
- 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 conservan su contrato de ruta; Solo contactos se representa con `true` o ausencia.
Identidades de ruta, pestañas y parámetros ajenos desconocidos se rechazan antes de seleccionar
una pantalla. Los pilotos validan sort/direction/page y plantilla contra sus metadatos y
normalizan valores inválidos o repetidos sin perder parámetros de otras operaciones. 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, sort o página en los pilotos 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 y ordenación mantienen su estado existente fuera de los pilotos y los tres consumidores de L04.1. Tamaño y
columnas conservan sus claves de preferencias. Los consumidores controlados guardan exclusivamente scroll y
origen de foco en `history.state.metisListReturn`, aislados por compañía/listado y filtros.
No se guarda una segunda copia de datos remotos ni se persiste ese contexto en localStorage.

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

## Funcionalidades archivadas

Tickets, intervenciones y plantillas de intervención no tienen rutas activas. Sus antiguas direcciones muestran página no encontrada. Consultar [el archivo](funcionalidades-archivadas.md).

### Ficha completa de un activo

`/companies/:companyId/assets/:assetId` muestra una página de detalle con las pestañas
Información e Historial. El listado conserva la selección local para su panel lateral;
los enlaces de nombre y las acciones de ver abren la página. Los parámetros `q` y
`template`, `sort`, `direction` y `page` se conservan en los enlaces y el retorno.
`BrowserLink navigation="return"` vuelve a la entrada anterior si coincide con el listado;
sin historial apropiado reemplaza la entrada por ese destino. Clic modificado y nueva pestaña
siguen utilizando un enlace real. La ausencia del activo conserva el acceso a Volver.

## Presentaciones responsive de la navegación

[V01.2](navegacion-responsive-v01-2.md) cambia la presentación de los enlaces existentes según capacidad del shell: global expandida, raíl o Sheet; compañía fija o Sheet. No añade destinos ni utiliza Select para navegar. Compañía/sección/ficha siguen en la URL; apertura y ocultación contextual son temporales. Enlaces modificados mantienen nueva pestaña e historial; navegar ordinariamente desde Sheet lo cierra y enfoca contenido. El resize conserva la URL y el estado local del contenido.

### Presentación del detalle de recursos por capacidad

[V01.4](recursos-responsive-v01-4.md) conserva `/companies/:companyId/resources/:resourceId` como selección del inventario. El nombre sigue siendo un BrowserLink a esa ruta; no existe una nueva página independiente equivalente a la ficha de activos. Por capacidad se presenta panel o diálogo contextual. El cierre inline conserva URL/selección; el cierre compacto voluntario mantiene closeRoute. «Ficha e historial» conserva su diálogo explícito sin cambiar URL ni la selección previa. Un resize nunca cambia rutas ni abre automáticamente un modal.

### Retorno en Puestos, Perfiles y Compañías — L04.1

Puestos conserva la consulta del listado en sus enlaces a la ficha y en el enlace de retorno.
Perfiles la conserva en el entorno; las configuraciones tienen su propia colección y búsqueda,
por lo que no heredan `q`/`sort`/`page` del listado. Atrás recupera el entorno y su consulta;
el retorno explícito del entorno usa el listado con fallback seguro si se abrió directamente.
Compañías vuelve al directorio mediante History, también desde una sección interna al
recorrer sus entradas. El acceso global Compañías sigue abriendo el directorio por defecto.
No cambia la validación del workspace ni se crean rutas. Alcance y pruebas en [L04.1](adopcion-listados-l04-1.md).

### Consulta en catálogos y Procesos — L04.2

Las rutas existentes de catálogo de activos/recursos conservan q/tab y ahora sort,
direction/page. Accesos conserva además kind y los ámbitos explícitos environmentId y
resourceId. Cambiar colección limpia criterios incompatibles en un único replace;
limpiar búsqueda no elimina el ámbito. Las preferencias de columnas se separan por scope
y colección. No se crean rutas para sus editores modales.

`/companies/:companyId/processes` y su ficha existente conservan q/closed/sort/direction/page
en enlaces de ida y vuelta; History restaura scroll/foco con fallback para entradas directas.
Las configuraciones de perfil/persona mantienen sus restricciones de ruta y su consulta
local: no absorben los parámetros del listado de perfiles. Software conserva assetId local;
seguir un enlace al recurso usa su presentación contextual V01.4. Atrás vuelve a la ficha
de origen sin convertir el modal efímero de Software en otra ruta. Detalle en [L04.2](adopcion-listados-l04-2.md).


## Catálogo global de aplicaciones (R2.3)

- `/catalogs/global-applications`: listado de productos globales, fuera de compañía.
- `/catalogs/global-applications/:resourceId`: ficha global por UUID; una identidad local no
  se convierte en global mediante esta ruta.

Los criterios propios son `q`, `active=true|false`, `sort=name|id`, `direction=asc|desc`,
`pageSize` (10/25/50/100), `cursor` y `page`. Los filtros se conservan en los enlaces de ficha
/retorno. La API valida el cursor contra los criterios; la URL no acredita autorización.
Las acciones administrativas son modales y no cambian el contrato de las rutas de compañía.

### Verificación del contexto de listados

El [cierre L04.4](cierre-programa-listados-l04-4.md) registra las rutas y consumidores
comprobados. No se añade navegación en esta entrega: los detalles auxiliares del dashboard
siguen siendo modales; los sublistados de una ficha no heredan sus criterios del listado
que abrió esa ficha. Las variantes remotas conservan los cursores del proveedor únicamente
cuando su consumidor integra el contrato de retorno; no se promete reconstruir una pila
de cursores al compartir una URL.