metis-desk/docs/implementacion-uiux-ficha-puesto-v2.2.md

# Implementación UI/UX v2.2: ficha de puesto

Fecha: 24 de octubre de 2026. Ruta: `/companies/:companyId/workstations/:id`.

## Resultado y línea base

M05 distingue la prominencia de las dos entradas al editor completo, conserva el historial general y contextual y mantiene título y gestión de Software en una fila hasta 320 px. M07 concentra la explicación de la dependencia en Equipamiento y reduce los mensajes secundarios, diferenciando ausencia confirmada, bloqueo, carga, error y datos desconocidos.

La línea base es la implementación v2.1 con M01/M02/M03/M04/M06 presentes. Se contrastaron la [auditoría](auditoria-uiux-ficha-puesto-trabajo.md), especialmente M05/M07 y E01/E03/E04/E06/E07/E08/E10/E11, los informes y evidencias de [v1](implementacion-uiux-ficha-puesto-v1.md) y [v2.1](implementacion-uiux-ficha-puesto-v2.1.md), DESIGN.md, patrones de listados compactos y diálogos, estructura web, WD04.3 y procedimiento Playwright. Los criterios se verificaron contra componentes, traducciones y contratos reales.

Antes de modificar producción se comprobaron directorio, estado Git, Node v24.20.0 y PNPM 11.25.0; se guardó el estado inicial local en `/tmp/metis-uiux-v22-initial-status.txt`. Había cambios de las iteraciones anteriores y trabajos de búsqueda, listados y Recursos. Se conservaron, incluidos los cambios concurrentes de navegación; no se atribuyen a esta entrega. Las capturas `antes/` se obtuvieron antes de implementar v2.2. No se sobrescribieron evidencias de v1/v2.1.

No cambian API, DTO, esquemas, migraciones, reglas de negocio, permisos, dependencias ni vendor. M08/M09 quedan pendientes. Se reutilizan Inter, tokens y componentes existentes.

## Skills consultadas y aplicación efectiva

| Skill | Aportación concreta |
| --- | --- |
| **ux-microcopy**, principal | Etiqueta fiel al editor completo, título corto Software y ámbito separado; mensajes específicos es/en y razones visibles de bloqueo. |
| **ux-empty-states**, principal | Orientación central en Equipamiento; vacío confirmado diferente de incertidumbre; texto neutral para puesto inactivo. |
| ux-dashboard | Jerarquía entre acción global, acceso contextual y siguiente paso; menos altura y repetición sin retirar secciones. |
| shadcn | APIs instaladas de Button, Empty y diálogos Base UI a través de rdx-ui; reutilización de `actions` y `finalFocus`. |
| frontend-design | Ritmo, encabezados y densidad locales; comprobación de capturas, sin nuevas recetas globales. |
| ux-navigation | Conservar destinos y ambos historiales; retorno de foco al origen o a una alternativa estable. |
| ux-error-recovery | Errores recuperables y datos retenidos; reintento de la fuente que realmente falta. |
| ux-inputs-and-forms | Reutilizar el formulario completo; explicar altas deshabilitadas y comprobar guardar/cancelar. |
| vercel-composition-patterns | Extraer orientación de Equipamiento y feedback de contexto de perfiles por responsabilidad; sin nuevas capas ni Context. |
| vercel-react-best-practices | Derivar disponibilidad durante render; mantener montado el preview para conservar expansión entre refetches. |
| ux-design-review | Consolidar revisión de textos, usabilidad, accesibilidad de uso y responsive bajo el sistema existente. |
| rdx-solid | Cambios acotados y pruebas observables; reutilizar contratos de consulta y controles existentes. |

Los auditores especializados de heurísticas, microcopy, accesibilidad, estética, arquitectura de información, dark patterns y responsive no están instalados. No se ejecutaron, simularon ni instalaron. Las verificaciones directas con MCP se describen abajo; no equivalen a esos auditores ni a una prueba con lector de pantalla.

## M05: inventario de acciones y decisiones

| Acción | Ubicación | Ámbito real y condiciones | Decisión |
| --- | --- | --- | --- |
| Editar puesto | Cabecera | Editor completo: nombre, sede, responsable, activos y principal. Se conserva el contrato existente. | Acción principal, sin cambiar etiqueta. |
| Editar puesto | Equipamiento con principal | El mismo editor completo, no un editor limitado a activos. | Conservar acceso cerca de los datos; variante `ghost` reduce competencia con cabecera. |
| Editar puesto | Equipamiento incompleto o vacío | Mismo editor; permite completar la dependencia con las restricciones existentes. | Conservar `outline`, también como acción del vacío. No llamarlo «Cambiar equipamiento». |
| Editar nombre | Junto al título | Renombrado mediante el editor existente. | Conservar; alcance específico y nombre accesible existentes. |
| Ver historial | Cabecera | Historial completo del puesto. | Conservar acción general `outline`. |
| Ver historial completo | Último cambio | Mismo historial completo y mismas revisiones, sin filtro adicional. | Conservar acceso contextual `ghost`; texto explicita que amplía el resumen. |
| Gestionar software | Software | Gestión de instalaciones del ordenador principal, en diálogo existente. Solo aparece con principal resuelto. | Título «Software» y ámbito «Del ordenador principal.» en cuerpo; seguir usando `DetailPanel.actions`. |
| Añadir instalación | Gestión de software | Alta condicionada a puesto activo y principal no retirado, conforme a política existente del servidor. | Reflejar la restricción ya existente y explicar el motivo tanto en panel como en diálogo. Gestión y consulta se conservan. |
| Nuevo perfil | Personas y perfiles | Alta sobre principal resuelto, activo y no retirado. | Conservar control deshabilitado con explicación visible y `aria-describedby`. |
| Gestionar soporte | Soporte registrado | Gestión del soporte del activo; acceso dependiente de carga y autorización existentes. | Conservar M02, sin cambios a su CRUD ni diálogo. |
| Más acciones del puesto | Cabecera | Desactivar o eliminar con las confirmaciones existentes. | Conservar; verificadas apertura y cancelación. |

La duplicación de edición e historial tiene una justificación contextual: la ficha puede ser larga y los datos se gestionan desde sus secciones. No se elimina ningún acceso. No se modifican `DetailPanel`, sus consumidores generales ni el editor de nombre/historial.

Se añadió `editButtonRef` opcional a `WorkstationActions` y `finalFocus` opcional a `WorkstationEditorDialog`. Los demás consumidores mantienen sus callbacks y comportamiento. El detalle captura el botón real de apertura; al cancelar vuelve a él. Si se guarda desde la acción del vacío, vuelve al botón estable de cabecera porque el botón original desaparece al completarse Equipamiento. Esta pérdida de foco se reprodujo y corrigió durante la revisión.

## M07: modelo de estados y tratamiento

Los siguientes son estados de presentación derivados de contratos existentes; no son nuevos estados de dominio.

| Situación real | Tratamiento |
| --- | --- |
| Principal ausente confirmado; puesto activo | Equipamiento explica qué falta, para qué sirve y cómo editar. Perfiles, Software y Soporte conservan títulos y mensajes breves que remiten a Equipamiento. |
| Hay periféricos, falta principal | Se mantienen las filas y el total de activos; orientación compacta y acción de edición en Equipamiento. |
| Consulta de perfiles completada sin filas | Cero conocido y mensaje específico; alta disponible si procede. No mostrar cabeceras de una tabla vacía. |
| Software o soporte sin registros confirmados | Mantener los mensajes específicos y los accesos de gestión existentes; no interpretarlos como ausencia de principal. |
| Puesto desmantelado/inactivo | Explicar inactividad y conservación del historial. No invitar a completar el puesto ni crear perfiles/instalaciones. Edición y consulta conservan sus reglas. |
| Principal retirado | Explicar por qué no pueden crearse perfiles o añadirse instalaciones. Mantener consulta, historial y gestión disponibles según contratos actuales. |
| Fuente cargando | Feedback de carga; no afirmar vacío ni publicar total desconocido como cero. |
| Error inicial o parcial | Mensaje recuperable y reintento de su fuente; los demás paneles siguen disponibles. |
| Refetch con datos previos | Conservar datos y expansión; informar actualización/error y omitir contadores cuya fuente falla. Un cero retenido con error no se presenta como ausencia confirmada. |
| Referencia a principal no resuelta o inventario fallido sin principal | Explicar que no se puede consultar; pendientes desconocidos, sin cero falso. El reintento de Perfiles recupera Inventario. |
| Perfiles pendientes/fallidos en contexto de soporte | Mostrar su carga/error, en lugar de afirmar que no existen perfiles activos. |
| Perfil seleccionado con persona no resuelta | Mensaje específico para revisar el perfil; no convertirlo en ausencia de perfiles. |

`WorkstationEquipmentGuidance` concentra la explicación principal usando `EmptyState` para cero miembros y texto compacto cuando hay periféricos. Las secciones dependientes mantienen su identidad y acciones. `WorkstationProfiles` utiliza `EntityListStatus` para cero filas y conserva `CollectionPreview`/tabla montados en un contenedor oculto: así no pierde «Mostrar todos» al pasar de seis a cero y volver a cincuenta registros. La tabla responsive con datos mantiene M03/M06.

`workstationProfileAvailability` y `workstationComputerDependencyKey` derivan disponibilidad y texto; no hacen I/O ni duplican datos remotos. `WorkstationProfileContextFeedback` separa carga/error del contexto realmente vacío. Pendientes distingue ahora el principal desconocido del cero confirmado. No se colapsan errores ni acciones útiles.

## Componentes y traducciones

Cambios locales en `workstation-assets`, `workstation-profiles`, `workstation-software`, su diálogo, `workstation-support`, `workstation-pending-configurations`, `workstation-detail-content` y `workstation-detail-page`, bajo `modules/companies/src/web/workstations/detail/`. Dos helpers y dos componentes nuevos con responsabilidades concretas. Se extienden únicamente las dos APIs de foco de componentes propios de Assets descritas arriba.

Se añaden 16 claves por idioma bajo `workstationDashboard` en los locales es/en de Assets: `softwareTitle`, `softwareScope`, `equipmentNeedsComputer`, `equipmentSetup`, `inactiveEquipment`, `inactiveEquipmentTitle`, `profilesNeedEquipment`, `softwareNeedsEquipment`, `supportNeedsEquipment`, `computerUnavailable`, `profilesInactive`, `profilesRetiredComputer`, `softwareInactive`, `softwareRetiredComputer`, `profilePersonUnavailable`, `inactiveWithoutComputer`. Se conservan las claves anteriores para otros consumidores y títulos de diálogos. Pruebas de componentes comprueban ambos idiomas; las capturas y recorridos MCP se hicieron en castellano.

## Evidencias y mediciones

[Comparaciones e índice de capturas](auditorias/ficha-puesto-trabajo/implementacion-v2.2/comparaciones/README.md) · [mediciones originales](auditorias/ficha-puesto-trabajo/implementacion-v2.2/mediciones.json).

Se verificaron 1600×1000, 1440×900, 1280×900, 1024×768, 768×1024, 390×844 y 320×720. Hay 29 capturas de línea base y 38 finales, con SHA-256, geometría, texto y acciones cuando corresponde: completo, sin principal, con periféricos, vacíos confirmados, inactivo, Software, Último cambio, error parcial y carga controlada. Las finales adicionales cubren incertidumbre, paneles dependientes en móvil y regresiones de detalles técnicos y gestión de soporte. Una captura puede acreditar varios vacíos; no se duplican imágenes sin necesidad.

Medidas del mismo puesto sin principal, sumando alturas de Personas y perfiles, Software y Soporte:

| Ancho | Antes (px) | Después (px) | Reducción (px) |
| --- | ---: | ---: | ---: |
| 1600 | 366,25 | 289,75 | 76,50 |
| 1440 | 366,25 | 289,75 | 76,50 |
| 1280 | 366,25 | 289,75 | 76,50 |
| 1024 | 366,25 | 289,75 | 76,50 |
| 768 | 366,25 | 289,75 | 76,50 |
| 390 | 402,25 | 289,75 | 112,50 |
| 320 | 486,75 | 373,75 | 113,00 |

Las menciones literales visibles de «ordenador principal» en los seis paneles pasan de cinco a una en ese escenario. Es una medida de repetición textual, no una prueba de comprensión con usuarios. La cabecera de Software pasa de 65 a 32 px en 1440/390/320, con título y gestión en una fila. El ámbito sigue escrito en el cuerpo. No se detectó desbordamiento horizontal global ni recorte nuevo en los controles examinados. No se confunde la suma de paneles con altura total de la página: en escritorio el grid y la altura mínima pueden absorber la diferencia.

## Pruebas funcionales y accesibilidad de uso

El preparador documentado `visual-audit.py` creó una instalación y base `metis_desk_test` desechables, accedió por el formulario real con usuario ordinario y mantuvo la sesión privada. Playwright MCP se lanzó mediante la configuración de proyecto y su imagen Docker fijada; no se instaló Chromium ni se cambió configuración global. Se utilizó la URL anunciada por Vite y una única sesión de navegador por ejecución.

Volumen real: 15 compañías; la principal con 59 personas, 137 activos, 73 recursos, 57 puestos y 64 perfiles. Puesto denso con 80 activos y 50 perfiles activos más 10 archivados; cuentas/rutas extensas y relaciones coherentes. Las modificaciones de formularios afectaron exclusivamente a esos datos. Se restauraron nombre y composición tras las comprobaciones; las revisiones nuevas son historial sintético esperado.

Recorridos de v2.2:

- Edición completa desde cabecera y Equipamiento a 1440/390/320; mismos campos/ámbito, Enter, cancelación y foco de vuelta.
- Historial desde ambos accesos; mismas revisiones y contenido completo, Escape y retorno de foco.
- Gestión de software accesible y contenida en móvil; Escape y foco al disparador.
- Guardado real del nombre desde Equipamiento: composición conservada y revisión añadida; restauración posterior.
- Completar Equipamiento vacío con selector real, elección de principal mediante Espacio y guardado: principal visible, alta de perfil habilitada y foco estable.
- Vacíos confirmados de perfiles/software/soporte, ausencia de principal con y sin periféricos, puesto inactivo, principal retirado y referencia no resuelta.
- Carga controlada, error parcial de Software y Perfiles, error de Inventario con cero retenido, reintento y restauración de cero conocido sin perder foco.

Regresiones v2.1: seis recorridos pasan: umbrales reales de tabla, puesto denso y expansión con teclado, detalles técnicos y Solo pendientes, totales durante refetch, selección con Espacio y valores completos, navegación/aislamiento entre compañías. Se conserva la expansión al cambiar el conjunto de datos.

Regresiones v1: gestión de soporte por teclado/cancelación; CRUD, historial, retirada y confirmación; fallos 401/403/503 con recuperación y datos parciales; carga, datos retenidos y vacío; cabecera móvil, navegación, cancelación de ciclo de vida y geometría del diálogo a 1440/390/320. Los recorridos se reutilizan en memoria, con el selector de Equipamiento adaptado a su contador; escriben sus evidencias exclusivamente en v2.2. Un intento del caso de carga agotó su espera; su repetición aislada con navegador nuevo pasó. Los resultados finales se conservan en mediciones.

Se comprobaron nombres y regiones accesibles, estados semánticos, Tab/foco en recorridos, Enter/Espacio según control, Escape, acciones visibles sin hover y explicaciones que no dependen solo del color. Los controles deshabilitados se acompañan de texto visible. Se verificó acceso real con usuario ordinario y aislamiento/sesión no autenticada; 401/403 de soporte se simularon en la frontera HTTP. El sistema actual no proporciona un rol granular de solo lectura para contrastarlo: no se inventaron permisos ni se afirma haber probado ese rol.

El atajo de zoom nativo no cambió ni `innerWidth` (1440) ni DPR (1) en Chromium headless. No se pudieron comprobar zoom nativo 200/400 % ni lector de pantalla. El reflow de 320 px se documenta como responsive, sin presentarlo como zoom nativo o auditoría con lector de pantalla.

## Validación técnica

| Comprobación ejecutada | Resultado |
| --- | --- |
| `pnpm --filter @metis/assets --filter @metis/companies --filter @metis/web typecheck` | Correcto; incluye consumidores de las APIs compartidas. |
| Biome dirigido a 17 ficheros de código/locales de esta entrega | Correcto tras formateo local, sin supresiones. |
| ESLint dirigido a los 15 ficheros TypeScript de esta entrega | Correcto. |
| `TSX_TSCONFIG_PATH=../../tsconfig.json node --import tsx src/web/workstations/detail/ui/workstation-detail.test.tsx`, desde Companies | 24/24; cuatro casos nuevos y aserciones ajustadas al estado preciso. |
| `pnpm build` | Correcto, 2 tareas; persiste aviso de tamaño de chunk. |
| `pnpm typecheck` global | Falla en vendor `calendar.tsx:165`, TS2375 de `locale` opcional; mismo diagnóstico que v2.1. No se modifica vendor. |
| `pnpm lint` global | Falla: 15 errores, 2 warnings y 4 infos, fuera de los ficheros de v2.2. |
| `pnpm check` global | Falla: 169 errores, 2 warnings y 4 infos de lint/formato global. |
| `pnpm test` global | 7 tareas correctas y Companies fallida: 238/240; fallan `companies-page.test.tsx:180` y `:210`, ajenas a la ficha y ya registradas en v2.1. Assets 145/145. |
| Revisión de diff y comprobación de espacios | Completada sobre el alcance de la entrega; se preservan cambios ajenos. |

Los fallos globales se observaron de nuevo, no se asumieron por el informe previo. Las comprobaciones dirigidas aíslan el código modificado. Los ficheros compartidos consultados fueron `WorkstationActions`, `WorkstationEditorDialog`, `WorkstationNameEditor`, `DetailPanel`, `EmptyState`, `FormDialog` y sus consumidores reales. No se alteraron primitivas vendor.

Para reproducir, mantener abierto el preparador privado con fixtures de puestos y volumen, ejecutar `METIS_UIUX_PHASE=antes` y los casos `test_00_prepare`, `test_01_comparable_captures`, `test_02_comparable_errors_and_loading` antes de cambiar producción; después ejecutar el script `scripts/workstation-uiux-v22.test.py` con `METIS_UIUX_PHASE=despues` y `METIS_PLAYWRIGHT_STORAGE_STATE` apuntando a la sesión privada del preparador. No reutilizar una base real ni copiar la sesión a evidencias. Las regresiones requieren también los scripts v1/v2.1 del repositorio.

## Revisión final, límites y próximos pasos

Durante la revisión se corrigieron tres problemas observados: mensaje de puesta en marcha en un puesto inactivo; pérdida de expansión al alternar colección vacía durante refetch; pérdida de foco al guardar desde la acción que desaparece. El error de Inventario con cero retenido ahora conserva incertidumbre y un reintento funcional.

Riesgos residuales: las pruebas con usuario ordinario no sustituyen investigación con usuarios ni la verificación pendiente con lector de pantalla/zoom nativo. Persisten las incidencias globales indicadas. Las capturas reflejan datos sintéticos y fechas/revisiones de la auditoría, no producción. El color y el resumen de pendientes se conservan conforme al alcance actual; no se implementan M08/M09.

Próximos pasos: abordar M08/M09 con su propia línea base y criterios; completar zoom nativo y lector de pantalla en un entorno con esas capacidades. El preparador propio (PID 581726) se cerró mediante SIGTERM y confirmó la retirada de sus servicios temporales. Se verificaron su salida y la eliminación de `session.json` y `database.env`; se conservaron únicamente evidencias sin sesión. El cierre está registrado en `mediciones.json`.