metis-desk/docs/architecture/resources-global-scope/14-r2-3-catalogo-global.md

# R2.3 — Catálogo global de aplicaciones

Fecha: 24 de octubre de 2026. Implementación sobre las decisiones ratificadas de R2.0 y las
preparaciones R2.1a, R2.1b y R2.2. Este documento describe esta fase; los informes anteriores
conservan su estado histórico.

## 1. Estado de implementación

Backend y cliente del catálogo implementados dentro de Resources. La definición sigue siendo
un Resource con `scope=global`, `companyId=NULL`, UUID propio, valores e historial relacionales.
El catálogo está deshabilitado por defecto. La habilitación de prueba se realiza exclusivamente
en instalaciones desechables con `metis_desk_test`, después de migración y preflight.

Los gates de aceptación de esta fase se satisfacen con las validaciones de §3 y §18–22.
Los checks globales conservan los fallos ajenos descritos en §22. No se ha habilitado ni migrado la base habitual.

## 2. Prerrequisitos comprobados

HEAD inicial `34b8f915381de02f9e13334634455074a5dc55ee`; Node 24.20.0 y PNPM 11.25.0,
coincidente con packageManager. Sequelize 6.37.8; MariaDB 11.8 mediante la imagen fijada del
lanzador. El árbol inicial incluía las fases anteriores y cambios concurrentes de interfaz,
listados y puestos de trabajo. Se conservaron sus archivos y se guardaron copias/huellas antes
de implementar para distinguir las contribuciones de esta fase.

Se consultaron los contratos 01–13 de esta serie y las fuentes de capas, composición, HTTP,
identificadores y pruebas, además de AGENTS, DESIGN, estructura web, patrón de listados,
diálogos, matriz de skills y procedimiento Playwright. Se contrastaron las APIs instaladas.

Skills consultadas: rdx-solid para dominio, fronteras y pruebas; ux-tables como principal del
listado; frontend-design, ux-dashboard, ux-microcopy, ux-empty-states, shadcn,
vercel-composition-patterns y vercel-react-best-practices según el encargo. También
ux-inputs-and-forms y ux-navigation para formulario y navegación. Influyeron en jerarquía,
reutilización de primitivas, mensajes recuperables, estados separados, componentes por
responsabilidad y ausencia de estado remoto duplicado. No se introdujo un dashboard de métricas.
No se instalaron dependencias, skills ni auditores especializados de seguridad/SQL/accesibilidad.
Las comprobaciones de navegador descritas aquí utilizan Playwright MCP, sin atribuirles una
auditoría especializada externa.

## 3. Gates abiertos y cerrados

| Gate | Estado de esta entrega |
| --- | --- |
| G1 backend | Implementado: comandos, persistencia, UUID, historial e idempotencia; integración propia validada. |
| G2 autorización | Identity real y CSRF; matriz de seguridad validada. |
| G3 contratos | DTO mínimo/administrativo separados, validación estricta y compatibilidad local verificadas. |
| G4 UI | Validado con Playwright MCP, 23 comprobaciones y revisión de capturas en seis anchos. |
| G5 consumidores | Cumplido: las puertas de selección mixta, instalaciones globales y configuraciones globales permanecen cerradas; regresiones locales verificadas. |
| G6 validación | Pruebas propias, regresiones, typecheck dirigido, Biome/ESLint, build e inspección visual correctos. Deuda global ajena declarada en §22. |

Las puertas de catálogo y administración son independientes de las de consumidores. Solo
`RESOURCE_GLOBAL_CATALOG_ENABLED=true` abre altas/edición/reactivación tras preflight.
`RESOURCE_GLOBAL_SOFTWARE_ENABLED` y `RESOURCE_GLOBAL_PROFILE_ENABLED` siguen rechazando `true`;
`mixedSelection` continúa siendo literalmente false. La capacidad de administrar se deriva de
Identity, nunca de un flag recibido del navegador.

## 4. Archivos principales

- `modules/resources/src/api/application/global-resource.*`: puerto, captura de especificación y comandos.
- `modules/resources/src/api/domain/resource.aggregate.ts`: operaciones globales explícitas.
- `modules/resources/src/api/infrastructure/persistence/sequelize-global-resource.repository.ts`:
  transacciones, administración, historial y replay persistido.
- Los mappers, escritura relacional, especificaciones de revisión y propagación de plantilla de Resources.
- `modules/resources/src/api/infrastructure/http/global-resource.routes.ts`, `module.ts` y DTO comunes.
- `apps/server/src/config/database.ts` e `infrastructure/http/identity-runtime.ts`: configuración y composición.
- `modules/resources/src/web/global-applications/{list,detail,shared}/`: cliente del catálogo.
- Navegación, rutas y catálogo general de Companies; locales es/en de ambos módulos.
- `packages/rdx-ui/src/components/cursor-entity-table.tsx`: composición genérica de listado remoto.
- `apps/server/src/global-applications.integration.test.ts`, pruebas de dominio, contratos,
  representación web y rutas; actualización de expectativas R2.2.
- `scripts/resource-scope-test.py`, `scripts/visual-audit.py`,
  `scripts/global-applications-ui-audit.py` y script raíz `test:global-applications`.
- Este informe y precisiones normativas de componentes, listado remoto y rutas del cliente.

No se modifica implementación vendor, archive ni auditoría histórica por esta fase.

## 5. Servicios y endpoints

Base `/api/resource-global-applications`, autenticada y con el CSRF existente para POST.

| Método / ruta | Contrato y autorización |
| --- | --- |
| GET `/` | Resumen mínimo paginado; sesión ordinaria suficiente. |
| GET `/:id` | Detalle mínimo de producto global elegible; local/ausente devuelve 404. |
| GET `/capabilities` | Usuario y authVersion de la sesión, capacidad derivada, estado del catálogo y posibilidad actual de crear. |
| GET `/template` | Especificación global de serie disponible para alta; exige administrador inicial. |
| GET `/:id/admin` | Valores y especificación actuales con revisionId; administrador inicial. |
| GET `/:id/history` | Revisiones administrativas por cursor; administrador inicial. |
| POST `/` | Alta 201 o replay 200 con creationId UUIDv7. |
| POST `/:id/update` | Edición con plantilla fija; revisión esperada opcional en HTTP y enviada por la interfaz. |
| POST `/:id/status` | Desactivación/reactivación, sin borrado físico. |

No existe endpoint de borrado global. Los errores esperables mantienen 400/401/403/404/409.
La infraestructura produce respuesta saneada y diagnóstico con requestId; no devuelve SQL ni
mensajes internos. Las rutas de candidatos/referencias de R2.2 conservan su política propia.

## 6. Autorización Identity

Se reutiliza `canManageGlobalResources` y `requireGlobalResourceManager`: usuario activo,
authVersion vigente, isInitialAdmin y coincidencia con el marcador bootstrap persistido.
Se revalida en servidor por petición. Sin permisos delegables ni tablas de grants/revokes.
Las mutaciones globales de plantilla y campos conservan el mismo guard, incluido scope codificado.
El cliente usa capacidades para presentar acciones; todos los POST vuelven a comprobar Identity.

## 7. Contratos DTO

Summary/detail mínimos solo contienen identidad, plantilla, nombre, ámbito, actividad y los
campos aprobados de producto: proveedor y, en detalle, URL/descripción. Nunca notas, actores,
especificaciones completas, revisiones, consumidores o instalaciones.

El DTO administrativo separado añade values, specification y revisionId. El historial tiene
su propia respuesta paginada con snapshots y actor. Los schemas Zod son fuente de tipos y
validación en ambos extremos. Scope, companyId, actor e integración extra se rechazan en los
payloads. Los DTO legacy locales permanecen con compañía obligatoria y sin scope.

## 8. Modelo Resource y plantilla

Solo se permite la definición de serie real `stockKey=template:application`, propietario global,
kind template, campos globales válidos y sin integración. Un nombre traducido o renombrado no
cambia la elegibilidad. Una copia local, usage application o plantilla de otro tipo no la adquiere.
La raíz conserva templateId. `createGlobal`, `updateGlobal` y
`synchronizeGlobalSpecification` son explícitas; las operaciones locales siguen rechazando globales.

## 9. Persistencia y preflight

No hay tabla nueva, JSON de persistencia, compañía ficticia ni índice UNIQUE por nombre global.
Se reutilizan raíces, características, revisiones y especificaciones relacionales de Resource.
El arranque habilitado exige el esquema scoped de R2.1b y CHECK/FKs activos tanto en sesión
como globalmente; rechaza esquema legacy o parcial y plantilla incompatible. No ejecuta
expansión de ámbito automáticamente.

La escritura adquiere primero catálogo Resources global y después raíz; la propagación mantiene
el orden catálogo → compañías y prepara todos los cambios antes de escribirlos en una transacción.
No se generan proyecciones SMB, directorio, Access ni soporte para un producto global.
Las revisiones previas no se sobrescriben. Administración carga la revisión actual; historial
limita primero identidades en SQL y lee solo los snapshots de esa página, con actores en lote.

## 10. Ciclo de vida e idempotencia

creationId es el UUID v7 de la raíz. Bajo bloqueo transaccional, el primer POST crea una sola
revisión. La repetición del mismo actor y valores originales normalizados reutiliza la raíz y
responde 200 con su estado actual, incluso después de edición o reinicio. Otro payload/actor o
colisión con raíz local falla con RESOURCE_CREATION_CONFLICT. Sin tabla de idempotencia adicional.

La edición y el estado comparan expectedRevisionId cuando se aporta: una actualización concurrente
produce RESOURCE_UPDATE_CONFLICT. El formulario lo envía y conserva su borrador ante conflicto.
Los cambios semánticamente iguales no añaden revisión. Desactivar conserva UUID, valores e historia;
reactivar exige de nuevo validez de obligatorios. Si una plantilla añade un obligatorio, puede
desactivarse el producto incompleto, pero no reactivarse sin completarlo. Con el catálogo cerrado
se permiten lectura, historial, replay conocido y desactivación de seguridad; se impiden alta nueva,
edición y reactivación.

La propagación de estructura alcanza globales y locales atómicamente y conserva los snapshots
anteriores. No modifica asociaciones operativas ni adopta recursos locales.

## 11. Navegación

Entrada en Catálogos globales y acceso desde su navegación lateral. URLs reales
`/catalogs/global-applications` y `/catalogs/global-applications/:UUID`. Breadcrumb dentro del
contexto global; retorno con criterios de listado. No hay selector ni compañía ficticia.
Un UUID particular no puede consultarse como producto global. Las acciones de formulario son
modales independientes; los destinos de ficha son enlaces.

## 12. Listado

Mantiene cabecera, búsqueda/filtros, estado/configuración, tabla y pie del patrón oficial.
Acción de alta a la derecha, solo para gestor y disponible únicamente si catálogo/plantilla lo
permiten. Columnas reales: nombre, proveedor, estado y acciones. Celdas ausentes muestran `—`.
La tabla reutiliza contenido, configuración, acciones y estados RDX, con primitivas shadcn.
La API no ofrece total: se informa rango visible y Página N, sin inventar un total de resultados.
Paginación por cursor en servidor, tamaños 10/25/50/100 en UI y orden por nombre.

## 13. Detalle

La ficha mínima sirve al usuario ordinario, incluidos inactivos. El administrador obtiene
características y notas de su endpoint, acciones y revisiones paginadas. Los valores de
características se presentan mediante un componente propio compartido entre ficha e historial,
reutilizando FieldSections y DetailField; no se copia íntegramente la ficha local ni se introduce
información de instalaciones, licencias, usuarios consumidores o utilización transversal.

## 14. Formularios y coincidencias

FormDialog, FormBody/FormActions, FormSection, FieldSections, FormLabel, ContextHelp y controles
existentes de características de Resource. Plantilla fija, nombre obligatorio y campos reales;
sin selección de compañía o plantilla alternativa. Ayuda al final antes del pie. Formulario RHF
con schema existente; obligatorios dinámicos y errores de operación. Pending deshabilita controles
y cancelación; el diálogo no se cierra durante guardado. Guardar cierra solo después del éxito.

En alta, búsqueda indicativa limitada a diez resultados y enlace al catálogo paginado para revisión.
El administrador confirma expresamente que ha revisado el catálogo y se trata de un producto distinto.
Las coincidencias de recuperación no se califican como equivalencia ni como aviso fuerte D07.
No se implementa similitud difusa, consolidación, detección global/local ni fusión de R2.6.
Los homónimos siguen siendo válidos por UUID; una equivalencia confirmada se reutiliza abriendo
la ficha existente, sin POST nuevo. No se promete detección exhaustiva ni unicidad semántica automática.

## 15. Búsqueda y paginación

Se reutiliza la normalización compartida aprobada en R2.2: mayúsculas/tildes y substring literal
en nombre/proveedor; conserva ñ, números y signos según el helper. `%` y `_` no son comodines SQL.
Filtros, búsqueda y orden determinista preceden al límite, con UUID como desempate.
El servidor lee metadatos mínimos, sin inventario/historial por fila; no se afirma coste constante
ni índice de substring. El cliente carga páginas, no todo el catálogo.

q, active, sort, direction, pageSize, cursor y page permanecen en URL. Cambio de criterios reinicia
cursor/pila. La ficha conserva contexto. Una URL recargada no conserva la pila anterior de cursores:
Anterior vuelve a inicio. Una página posterior vacía ofrece volver a primera página. Las ediciones
concurrentes pueden desplazar resultados entre páginas; no se promete snapshot de toda la búsqueda.

## 16. Caché e invalidación

Raíz `resource-global-applications`, separada de inventarios locales. Lista por criterios y detalle
mínimo por UUID. Administración e historial incluyen actorId y authVersion; plantilla administrativa
también. Un guard de fallos retira cachés administrativas ante 401/403. El logout existente elimina
consultas ajenas a la sesión. Las vistas administrativas no presentan datos previos tras error de permiso.

Mutaciones invalidan listas globales, detalle del UUID y administración/historial de ese UUID, más
las claves de candidatos/referencias previstas, sin invalidar inventarios de todas las compañías.
Los listados conservan useListQuery y su refresco de 60 segundos. El borrador del formulario es una
copia de edición explícita con revisión esperada; no se sobrescribe por un refetch.

## 17. Privacidad

La lectura pública autenticada no reutiliza DTO ni caché administrativos. Las pruebas comprueban
la ausencia de notas, historia, especificación completa, actores, compañías e instalaciones.
Los campos de producto se proyectan mediante whitelist. No aparecen claves de licencia ni
referencias operativas en la pantalla. Los datos de pruebas y capturas son sintéticos.

## 18. Pruebas HTTP y de seguridad

Suite R2.3 con runtime de producción, bootstrap/login real, cookies en memoria y CSRF real.
Incluye ordinario rechazado, administración separada, origen/token incorrectos, campos prohibidos,
plantilla incorrecta, UUID local/inexistente, no borrado y respuestas saneadas. Se vuelve a ejecutar
R2.2 para flag administrativo falso, marcador bootstrap, authVersion, guard de catálogo y resolución.

## 19. MariaDB y regresiones locales

`python3 scripts/resource-scope-test.py --catalog --regressions`: 11/11 pruebas R2.3 y 50/50
regresiones HTTP/MariaDB, sin omitidas. Incluye dos POST concurrentes para una identidad, edición
concurrente, replay posterior, historia paginada, final de cursor vacío, homónimos, rollback por
fallo tras INSERT, recuperación, propagación y reinicio del runtime con puerta cerrada.

Volumen propio SQL: 15 compañías; principal con 50 personas, activos, perfiles, puestos y aplicaciones
locales; las otras catorce con aplicación local. Se crean 31 aplicaciones globales en los escenarios.
Las pruebas verifican que el inventario local sigue devolviendo solo sus 50 recursos y que los
POST de software/perfil rechazan globales. SMB, Access, remoto, licencias, directorio y proyecciones
se cubren mediante las 50 regresiones existentes, vueltas a ejecutar en esta fase.

La primera ejecución de regresiones detectó un campo obligatorio que la propia fixture R2.3 dejaba
en la plantilla compartida. Se corrigió la restauración de la plantilla antes de las demás suites;
la repetición pasa. El fallo inicial de historial por tokenización SQL `<:position` se corrigió y
su consulta y extremo vacío quedaron cubiertos. Una comprobación adicional detectó que la
reactivación reconstruía los valores sin exigir nuevos obligatorios; se corrigió para validar
con ResourceValues.create al activar y conservar reconstruct solo al desactivar. La prueba HTTP
que fallaba antes queda incluida en la repetición. No se atribuyen esos fallos a deuda anterior.

## 20. Playwright MCP

Recorrido completado e inspeccionado: **23 comprobaciones, 15 capturas**. Procedimiento: `bash scripts/setup-playwright-wsl.sh` y
`python3 scripts/visual-audit.py --global-applications --check`. Reutiliza Docker/MCP stdio fijado,
login real y limpieza del procedimiento existente, sin instalar Chromium en WSL ni modificar la
configuración global. El modo R2.3 migra con escritores detenidos y reinicia solo su API temporal
con el catálogo habilitado. Sirve una copia del build mediante Vite preview para que cambios HMR
concurrentes del workspace no reinicien el formulario durante la prueba.

La preparación de navegador usa HTTP público sobre instalación vacía: 15 compañías; principal con
50 personas/perfiles/puestos, 51 activos y al menos 50 aplicaciones locales; 51 aplicaciones globales
tras el alta interactiva. No ejecuta fixtures destructivas de integración ni toca una BD existente.
Credenciales aleatorias solo en memoria; no se conservan cookies, storageState ni contraseñas.

El recorrido verifica catálogo vacío, alta y nombre obligatorio, ficha e historial, edición,
desactivación/reactivación, filtro de inactivos, búsqueda, siguiente/anterior, contexto de retorno,
Escape, devolución de foco y Tab. El usuario ordinario consulta sin alta, edición, menú vacío ni
historial. Se comprobaron 1600, 1440, 1280, 1024, 768 y 390 px, sin desbordamiento horizontal de
la página. La tabla conserva su desplazamiento horizontal interno y acciones fijadas en móvil.

Los estados de error y carga se indujeron reteniendo/fallando exclusivamente el GET de listado;
se verificó Reintentar y recuperación. Las altas, edición, estado e historial anteriores utilizan
HTTP y SQL reales. Las capturas de esos estados y las de formulario, escritorio, móvil y lectura
ordinaria fueron inspeccionadas. No se probaron lectores de pantalla ni todos los atajos de un
navegador; se declara la verificación concreta de teclado/foco, no una certificación WCAG.

Los intentos iniciales detectaron selectores de prueba por etiqueta que incluían el indicador de
obligatorio y una recarga HMR concurrente; se corrigió el selector por rol/nombre accesible y se
usó el build inmutable. La ampliación de carga requirió liberar la petición retenida antes de
retirar su handler. Los recorridos finales completados sustituyen esos intentos de diagnóstico.

## 21. Capturas

Evidencias portables, exclusivamente sintéticas, junto a este informe:

- [Listado 1600 px](evidence-r2-3/r23-list-1600.png), [1440](evidence-r2-3/r23-list-1440.png),
  [1280](evidence-r2-3/r23-list-1280.png), [1024](evidence-r2-3/r23-list-1024.png),
  [768](evidence-r2-3/r23-list-768.png), [390](evidence-r2-3/r23-list-390.png).
- [Catálogo vacío](evidence-r2-3/r23-01-empty.png), [alta](evidence-r2-3/r23-02-create.png),
  [detalle administrativo](evidence-r2-3/r23-03-detail.png),
  [inactivo](evidence-r2-3/r23-04-inactive.png), [detalle móvil](evidence-r2-3/r23-detail-390.png).
- [Sin coincidencias](evidence-r2-3/r23-no-matches.png), [error recuperable](evidence-r2-3/r23-error.png),
  [carga](evidence-r2-3/r23-loading.png), [detalle ordinario](evidence-r2-3/r23-ordinary-detail.png).
- [Manifest de comprobaciones y SHA-256](evidence-r2-3/report.json).

Las capturas de intentos interrumpidos permanecen solo como diagnóstico local. No contienen
credenciales y no se presentan como validación completada.

## 22. Validación técnica y deuda anterior

- Resources: 98/98 pruebas, incluidas nuevas de dominio y representación mínima es/en.
- Identity: 11/11 casos en la ejecución del monorepo de esta fase.
- R2.2 seguridad: 11/11, más 50/50 regresiones.
- Typecheck dirigido a los once paquetes con script, excluyendo únicamente vendor: correcto.
- Build servidor/web: correcto; aviso existente de bundle mayor de 500 kB.
- Biome sobre los 54 archivos de código/contratos de esta fase: correcto, sin errores ni avisos.
- ESLint sobre sus TypeScript/TSX: correcto, incluido espaciado.
- Persistencia R2.1b: 13/13 pruebas repetidas, sin omitidas, con retirada del contenedor.
- `git diff --check` y compilación Python de los lanzadores: correctos.

Se ejecutaron además comprobaciones globales. `pnpm typecheck` sigue fallando en vendor
calendar.tsx:165 (TS2375 locale de DayPicker). No se cambia vendor. Las suites amplias ejecutadas
con credenciales del contenedor, sin cargar `.env`, mantienen dos fallos anteriores de representación
en Companies y el fallo de Identity HTTP que espera 404 en una ruta archivada y recibe 401 en
identity.test.ts:82. El equivalente seguro usa `--monorepo`; no se ejecuta el script global que carga
`.env` contra la base habitual. `pnpm lint` global devuelve 15 errores, un aviso y cinco informaciones; `pnpm check`
devuelve 192 errores, un aviso y cinco informaciones en el árbol compartido. El conjunto propio
comprobado por separado queda limpio. Se conserva la deuda y las modificaciones concurrentes
ajenas; no se atribuyen todos los cambios del árbol a esta fase.
Estas limitaciones no se ocultan ni se reparan ampliando el alcance.

## 23. Limitaciones

Sin concesión delegable, ACL operador–compañía, adopción, equivalencia automática, unicidad semántica,
importación masiva, productos sembrados ni licencias globales. No hay total exacto de búsqueda ni
snapshot entre páginas. La comprobación visual no sustituye auditoría especializada de accesibilidad
ni pruebas de lectores de pantalla. No se establece un SLA de rendimiento con esta fixture.

La operación sobre una instalación habitual requiere backup/preflight y despliegue coordinado de
R2.1b conforme a su runbook. Esta entrega no ejecuta esa activación.

## 24. Condiciones de R2.4/R2.5

Mantener las tres puertas de consumidores cerradas hasta sus fases. Para abrir instalaciones o
configuraciones globales se necesita implementar el comando correspondiente y su transacción de
asociación, validar propósito/actividad/pertenencia bajo bloqueo de catálogo y compañía, preservar
resolución histórica y estados locales, mantener licencias locales y añadir pruebas de concurrencia,
reintentos, aislamiento y selector mixto. Que una aplicación pueda leerse en el catálogo o resolverse
mínimamente no autoriza asociarla. La consolidación de duplicados requiere la fase y autorización
propias de R2.6; no deriva de la apertura de este catálogo.