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:

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

/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
├── 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: 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.
• 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.

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.