metis-desk/docs/iconos-de-recursos.md

# Iconos PNG de recursos

El campo global de serie `field:icon`, «Icono», es de tipo `image`. Aplicación,
Sistema operativo y Licencia de software lo incluyen como característica opcional.
Se añade una sola vez a las plantillas existentes, conservando sus UUID, campos,
orden, secciones y personalizaciones. Los reinicios no reponen un binding retirado.
El icono de producto es independiente del icono vectorial de la plantilla.

## Selección y validación

El selector compartido admite PNG estáticos de hasta 512 × 512 píxeles y 2 MiB.
Mantiene las proporciones y permite previsualizar, sustituir y quitar la imagen.
Una selección inválida conserva el valor anterior y bloquea el envío hasta
corregirla o retirarla. La lectura pendiente también bloquea el envío. La ayuda,
el estado y los errores están disponibles en español e inglés.

El contrato compartido valida firma PNG, dimensiones, integridad CRC de los chunks,
datos de imagen, final del contenedor y ausencia de animación. El servidor decodifica
además los píxeles con Sharp, con límite de dimensiones. No basta la extensión del
archivo ni el MIME declarado. Las rutas JSON de recursos admiten hasta 3 MiB;
las demás conservan su límite de 64 KiB.

Las fichas, revisiones y columnas de características muestran la imagen, sin
imprimir base64. Los listados de aplicaciones y SO muestran el icono junto al nombre.
La ausencia se representa con «—». El soporte blanco del icono mantiene visibles
los logotipos oscuros también con el tema oscuro.

## Persistencia e historial

La imagen viaja como una URI `data:image/png;base64,...`, validada, dentro de la
característica. Se conserva como valor escalar `valueType=image` en las tablas
relacionales `resource_characteristics` y `resource_revision_characteristics`.
No se almacena JSON ni se crean URLs remotas dependientes de terceros.

`migrateResourceImages` amplía explícitamente sus columnas `textValue` a MEDIUMTEXT
de forma idempotente. Las especificaciones y revisiones admiten el nuevo tipo.
Las escrituras normales conservan UUID e historial; repetir un guardado idéntico
no añade revisiones.

## Carga inicial de los catálogos locales

Las imágenes y su procedencia se conservan en
[`apps/server/data/resource-icons/manifest.json`](../apps/server/data/resource-icons/manifest.json).
Cada entrada identifica producto o familia, archivo PNG, URL de origen y SHA-256.
Se incluyen 40 aplicaciones y las familias Windows 7, Windows 8.1/10/Server,
Windows 11 y macOS. Las versiones y ediciones de una misma familia comparten logo.
Los iconos de menor tamaño mantienen su resolución original; ninguno supera 512 px
por dimensión.

Fuentes: [Dashboard Icons](https://github.com/homarr-labs/dashboard-icons), fijado al
commit `83f32e08257b66fbd971ac8d7645f5b38d52e85d`,
[Simple Icons 13.21.0](https://github.com/simple-icons/simple-icons/tree/13.21.0),
[PowerToys](https://github.com/microsoft/PowerToys) y las páginas oficiales de
Chaos/Enscape, voidtools, WinSCP, WinRAR, Nitro y TeamViewer. Se conservan las marcas
de sus titulares para identificar los productos. Dashboard Icons utiliza Apache-2.0
y Simple Icons CC0; sus licencias no sustituyen los derechos sobre las marcas.

Desde la raíz, previsualizar sin escribir:

```bash
pnpm --filter @metis/server exec node --env-file=../../.env --import tsx src/import-resource-icons.ts
```

Para aplicar la carga solicitada, añadir `--apply` al comando. Este comando comprueba
archivos, huellas y PNG antes de escribir. Requiere un administrador inicial activo,
registra sus revisiones, prepara las plantillas y amplía las especificaciones antiguas
solo con el campo Icono, preservando sus valores anteriores. Conserva iconos existentes
y es reejecutable. No cambia flags de administración o asociación del servidor.

Las pruebas con persistencia y la auditoría Playwright utilizan exclusivamente una
instalación desechable de `metis_desk_test`; la carga de los catálogos locales es la
operación de datos solicitada, independiente de esas pruebas.

## Verificación de esta entrega

- Catálogo local: 40/40 aplicaciones y 38/38 SO con PNG; Icono opcional en las
  tres plantillas. Segunda ejecución: 0 guardados y 78 iconos conservados.
- Resources: 126 pruebas correctas. PNG/HTTP: 3 pruebas correctas, incluyendo
  límites, corrupción, animación y rechazo de píxeles no decodificables.
- Integración SO/HTTP/MariaDB: 12 pruebas correctas sobre base desechable; incluye
  guardado y lectura de un PNG de 512 px, historial e idempotencia.
- Playwright MCP: recorridos de SO y aplicaciones correctos, con carga y retirada
  por teclado, archivos inválidos, conservación del valor anterior, fichas,
  búsqueda, paginación y tamaños estrechos/amplios. Cada recorrido utiliza 15
  compañías y una principal con al menos 50 personas, activos, recursos, perfiles
  y puestos; cada catálogo global dispone de 51 productos sintéticos.
- Compilación y typecheck dirigido de Resources, Server y Web correctos. Los
  archivos modificados de esta implementación pasan Biome y las reglas de espaciado.
- `pnpm typecheck` general se detiene en `packages/shadcn-ui/src/components/calendar.tsx`
  por el tipo opcional de `locale`. `pnpm lint` y `pnpm check` generales detectan
  incidencias ajenas al cambio. `pnpm test`, ejecutado con MariaDB desechable,
  se detiene en dos aserciones de `companies-page.test.tsx`: «Personas (1)» y
  «Esta persona no tiene acceso a Metis Desk». No se han modificado esas áreas.

Skills consultadas: `rdx-solid`, `ux-inputs-and-forms`, `shadcn` y
`vercel-react-best-practices`. Han orientado el uso de contratos y persistencia
existentes, la conservación del valor ante errores, las etiquetas y ayuda
accesibles y la lectura de archivos desde el evento de selección. Los auditores
especializados mencionados por la skill de formularios no están instalados;
se han realizado las comprobaciones disponibles directamente con Playwright MCP.

## Ampliación a todos los listados — 27 de octubre de 2026

El icono se representa junto al nombre en catálogos globales y de compañía,
inventario local de SO y aplicaciones, selectores, instalaciones, SO actuales,
configuraciones e historiales de aplicaciones, entornos y resúmenes de puestos,
mapa de software y sugerencias de coincidencias. El nombre permanece como etiqueta
accesible y el adorno no interfiere con el clic de fila, el foco ni la selección.
Las referencias públicas incorporan el PNG para los dos ámbitos; no se infiere una
imagen por coincidencia de nombre y no se modifican los datos de las compañías.

Verificación de esta ampliación:

- 128 pruebas de Resources y 84 de rdx-ui correctas.
- 14 pruebas de integración HTTP/MariaDB correctas, incluyendo PNG global/local,
  resolución de SO local y exclusión de referencias de otra compañía.
- Playwright MCP: PNG decodificado en el catálogo global de aplicaciones y SO,
  catálogo combinado de compañía, SO local, selector mixto, instalaciones y resumen
  del puesto. Se mantienen recorridos de búsqueda, paginación, teclado, selección,
  responsive y gates cerrados, con 15 compañías y los volúmenes sintéticos del
  procedimiento. Evidencias locales sin sesión en
  `.artifacts/playwright/authenticated-9qcb5enx`, `authenticated-cpta18j4` y
  `authenticated-y722zwbl`.
- Compilación y comprobaciones dirigidas de tipos y formato correctas.
- `pnpm test` mantiene dos fallos de `companies-page.test.tsx`; las otras 311
  pruebas de Companies pasan. `pnpm typecheck` general mantiene el error de vendor
  descrito anteriormente. `pnpm lint` y `pnpm check` siguen señalando incidencias
  fuera de los archivos de esta ampliación.

Skills: `ux-tables` como principal, complementada por `shadcn`,
`vercel-react-best-practices` y `rdx-solid`: imagen compacta junto a la identidad,
composición compartida, etiquetas de texto conservadas y datos procedentes de las
consultas existentes. No se han instalado los auditores especializados ausentes.