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:

/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:

/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

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

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.

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

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.

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