metis-desk/docs/architecture/decision-catalogo-global-sistemas-operativos.md

# Decisión aprobada — Catálogo global de sistemas operativos

Fecha: 25 de octubre de 2026. Estado: aprobada por la solicitud de implementación y sus decisiones D-SO-01–07. La [auditoría original](auditoria-catalogo-global-sistemas-operativos.md) se conserva como evidencia histórica; este documento describe la decisión implementada.

## Identidad y propiedad

Cada producto es un `Resource` global, con UUID v7 al crear, sin compañía y con la plantilla stock real `template:os`. No se crea otro catálogo de dominio. Las copias de plantilla, los recursos integrados, las licencias globales y las plantillas con campos particulares quedan excluidos. Las aplicaciones conservan su plantilla y sus proyecciones específicas.

La identidad comercial tiene cinco atributos declarativos:

| Atributo | Campo stock | Regla para publicar activo |
| --- | --- | --- |
| Fabricante/proveedor | `field:provider` | Texto no vacío |
| Familia | `field:os_family` | Texto no vacío |
| Versión principal del producto | `field:os_product_version` | Texto no vacío |
| Estado de edición | `field:os_edition_state` | `known` o `not_applicable` |
| Edición | `field:software_edition` | Texto con `known`; vacío con `not_applicable` |

`unknown` significa información todavía desconocida. Nunca se infiere «no aplicable» de un texto vacío. Los borradores inactivos pueden estar incompletos; una edición declarada conocida necesita texto incluso en borrador. El nombre comercial de un producto activo o ya publicado debe contener familia, versión principal y edición conocida, respetando límites de palabras. No se rellena automáticamente.

`field:description` y `field:url` son información documental. `SoftwareInstallation.version` sigue representando la versión instalada; no se añade build ni otro identificador de producto.

## Publicación y correcciones

La identidad queda fijada desde la **primera publicación activa**, aunque todavía no tenga instalaciones. Es una regla conservadora, anterior al primer uso, que evita depender de consultas al ORM de Companies desde Resources. Los borradores nunca publicados pueden corregirse antes de activar. Para publicar se exige una revisión explícita de la identidad enviada y el catálogo.

Tras publicar se permiten cambios documentales e identidad equivalente tras normalizar Unicode NFC, espacios y mayúsculas/minúsculas. Cambiar fabricante, familia, release, estado de edición o edición semánticamente requiere otro UUID. La validación se aplica en los casos de uso, en el repositorio global y durante la propagación de especificaciones. La desactivación no elimina esta protección. Todas las correcciones conservan revisiones.

No se cambia el `resourceId` de instalaciones existentes. No hay fusión, adopción, sucesión D08.2, ni normalización masiva de particulares.

## Duplicados y coordinación

La comparación utiliza los cinco atributos, normalización NFC, compactación de espacios y comparación sin distinguir mayúsculas. Conserva tildes, puntuación y distinciones comerciales: Pro/Professional, Desktop/Server, releases diferentes y desconocido/no aplicable no se equiparan automáticamente.

La revisión administrativa devuelve la identidad calculada y productos equivalentes. El formulario vincula el consentimiento a esa identidad; un cambio semántico exige revisar otra vez. El servidor compara la identidad declarada como revisada con las características reales. La revisión no reserva un nombre ni sustituye la comprobación transaccional.

Las altas y ediciones globales toman el lock exclusivo del catálogo existente. Antes de persistir se comparan productos SO globales mediante lectura actual dentro de esa transacción. Una identidad completa equivalente, incluso en un borrador inactivo, se rechaza con `OS_DUPLICATE`; un reintento con el mismo UUID y valores originales conserva la idempotencia existente.

La garantía cubre los escritores de la aplicación que respetan esta coordinación. **No existe una UNIQUE SQL semántica sobre EAV** ni equivalencia comercial por sinónimos; una escritura SQL externa puede eludir la policy. La propagación conserva los valores de identidad y rechaza retirar sus bindings de una plantilla ya utilizada por productos globales.

## Contratos, propósitos y seguridad

Los DTO públicos de SO son `GlobalOperatingSystemReference` y `GlobalOperatingSystemDetail`: UUID, plantilla, nombre, `kind: os`, `scope: global`, disponibilidad, identidad comercial y destino `/catalogs/global-operating-systems/:id`. El detalle añade descripción y URL. No incluyen notas administrativas, actores ni revisiones.

El propósito `software-installation` admite aplicaciones y SO particulares/globales elegibles. `application-configuration` continúa admitiendo exclusivamente aplicaciones. Los servicios públicos por transacción revalidan ámbito, disponibilidad y propósito antes de escribir; la licencia sigue siendo particular de la compañía. No se accede al ORM de otro módulo.

Las rutas `/api/resource-global-operating-systems` comparten repositorio, historial, autorización, CSRF y locks con las aplicaciones, con instancias configuradas por tipo. Los UUID de otro tipo no permiten administrar su raíz desde esta superficie. La administración requiere el guard público de Identity; no se confía en un tipo, compañía o permiso enviado por el navegador.

## Compatibilidad y gates

El header `X-Metis-Resources-Contract: 3` negocia SO globales en candidatos, referencias e instalaciones. El contrato `2` mantiene aplicaciones globales y SO particulares. Un cliente anterior que encuentre SO globales en su contexto recibe `409 RESOURCE_CLIENT_UPGRADE_REQUIRED`, sin omitir registros ni devolver variantes incompatibles. Las listas, coincidencias R2.6 y DTO de aplicaciones siguen filtrando exclusivamente aplicaciones. Los headers negociados llevan `Vary`.

| Configuración | Predeterminado | Responsabilidad |
| --- | --- | --- |
| `RESOURCE_GLOBAL_OS_CATALOG_ENABLED` | `false` | Altas, edición y reactivación administrativa de SO |
| `RESOURCE_GLOBAL_OS_SOFTWARE_ENABLED` | `false` | Candidatos y nuevas asociaciones SO; requiere también catálogo SO |

Los flags de aplicaciones no abren SO. Las capabilities v3 añaden `operatingSystemSelection` y `operatingSystemAssociation`; las respuestas v2 conservan su forma anterior. El apagado de flags no impide lectura de fichas, resolución histórica, historial, desactivación o retirada legítima. Cambiar versión instalada sigue sujeto a las reglas vigentes de disponibilidad y estados de `SoftwareInstallation`.

## Persistencia y evolución

Se reutilizan el esquema scoped, características EAV normalizadas, especificaciones y revisiones relacionales. No hay DDL nuevo ni JSON persistido. La migración scoped R2.1b previa sigue siendo requisito obligatorio; el arranque comprueba esquema, CHECK y FKs antes de habilitar cualquier catálogo global.

`evolveOperatingSystemTemplate` añade los tres bindings nuevos, opcionales, conservando UUID, nombres, orden y campos personalizados anteriores. El seed ejecuta esta evolución una vez al introducir la definición stock `field:os_edition_state`, en la transacción del catálogo. Un catálogo nuevo recibe además el binding URL. Los posteriores arranques son idempotentes y no reponen personalizaciones retiradas. Las especificaciones y revisiones particulares existentes no se reescriben ni se vuelven obligatorias retrospectivamente.

## Presentación y convivencia

Se reutiliza la administración visual global mediante un contexto de tipo, API, claves de caché y textos específicos. El formulario utiliza React Hook Form, Zod, primitivas existentes y revisión de identidad separada; los campos y estados nuevos tienen traducciones es/en. Los enlaces de producto del listado compartido usan texto de primer plano y subrayado para mantener contraste sobre filas resaltadas.

El selector remoto mezcla productos sin prioridad automática por procedencia. Identifica fabricante, familia, release, edición y origen. Las altas rápidas siguen creando recursos particulares. Activos, puestos, panel, historial y mapa resuelven el destino por tipo y scope; el selector compartido de SO actual conserva ambos. La caché se invalida por catálogo, UUID y dependencias afectadas.

## Despliegue y rollback

1. Desplegar lectores y contrato 3 con los dos flags SO cerrados.
2. Confirmar R2.1b, integridad activa y evolución de plantilla; verificar las pruebas del entorno objetivo.
3. Desplegar frontend v3 y preparar administración autorizada.
4. Abrir únicamente catálogo SO, revisar productos y publicar identidades completas.
5. Abrir asociación SO tras verificar selectores y consumidores entre compañías.
6. Repetir las comprobaciones del entorno objetivo antes de una habilitación general.

La activación de un entorno desplegado necesita autorización separada. Esta intervención solo abre gates en instalaciones desechables de `metis_desk_test`.

El rollback operativo cierra primero asociación y después administración. Conserva productos, instalaciones, licencias e historiales; permite consultar y retirar mediante los estados existentes. **Después de persistir SO globales no se debe volver a un backend anterior a estos lectores**: el rollback seguro consiste en apagar gates manteniendo código compatible. Un frontend v2 encontrará un error controlado en contextos con SO globales y debe actualizarse. No se realiza una migración inversa, borrado ni reasignación.