Revisión de buenas prácticas

Revisión realizada el 2026-10-08 conforme a AGENTS.md y a los documentos de arquitectura de capas, composición, flujo HTTP, contratos, pruebas y modelo DDD e identificadores. Se consultaron también el patrón de listados y los componentes de interfaz.

Alcance y método

Se inventariaron estructura, dependencias, configuración y patrones antes de modificar código. La revisión combinó inspección estructural de todos los archivos TypeScript propios con lectura por áreas, fronteras y patrones repetidos, comprobaciones de referencias y pruebas dirigidas. No equivale a una certificación de seguridad ni a una comprobación manual de cada interacción.

El inventario final contiene 756 archivos TypeScript/TSX propios, incluidas pruebas:

Área	Archivos	Responsabilidades inspeccionadas
apps/server	31	Arranque, configuración, cierre, HTTP, logging e integraciones
apps/web	8	Composición React, idioma, proveedores, dashboard integrado y pruebas
modules/core	11	Contratos de salud, rutas, acceso HTTP y pantalla técnica
modules/identity	38	Usuarios, sesiones, autenticación, contraseñas y formularios
modules/companies	460	Compañías, personas, departamentos, sedes, accesos, perfiles, correo, carpetas, aplicaciones, certificados, impresoras, teletrabajo, remotos, procesos, tickets, intervenciones, plantillas y dashboard
modules/assets	136	Catálogos, marcas, inventario, relaciones, puestos y asistencia
modules/resources	63	Catálogos, inventario, características e integraciones
packages/rdx-ddd y rdx-utils	9	Identidad, entidades, agregados, Value Objects, Result y Maybe

Se inspeccionaron además scripts, configuración TypeScript/Biome/PNPM, composition roots y exports para entender sus contratos. No se alteraron dependencias, APIs públicas, schemas HTTP, lógica de migraciones ni persistencia como parte de esta refactorización. Los errores de entrada HTTP malformada sí se corrigieron en el middleware común.

La implementación de packages/shadcn-ui está excluida de cambios por AGENTS.md. Sus APIs se consultaron para consumir los patrones existentes. Se preservó el cambio local del usuario en packages/shadcn-ui/src/styles/globals.css. No se imprimieron ni versionaron archivos .env.

Orden de trabajo

Inspección global y lectura normativa, con clasificación de patrones y riesgos.
Componentes propios compartidos, composición de identidad y formularios de accesos.
Catálogos e inventarios de activos y recursos; asistencia y relaciones.
Compañías, perfiles, configuraciones, procesos, tickets e intervenciones.
Fronteras HTTP, contraseñas, datos persistidos, logging y ciclo de vida del servidor.
Inventario completo y separación de modales, incluidos wrappers y altas anidadas.
Paneles del dashboard, navegación lateral y búsqueda global.
Convenciones de imports de tipos, revisión del diff y validaciones globales.

Los primeros cambios ya quedaron incorporados en el commit 7f336df durante la revisión. La extracción de modales, las últimas convenciones y la documentación se entregan en el working tree posterior a 6bb9845; no se ha creado otro commit automáticamente.

Incumplimientos corregidos

Varios componentes significativos en un mismo TSX: se separaron responsabilidades reales, sin convertir fragmentos triviales de JSX en componentes artificiales.
Formularios, historiales y confirmaciones implementados dentro de listados: ahora viven en componentes modales propios. El inventario enumera los 81 componentes que construyen una interacción modal y sus ficheros, incluidas variantes ya independientes antes de esta revisión.
Estructuras modales repetidas para una misma entidad: se reutilizan diálogos de compañía, persona, departamento, sede, marca y herramienta de asistencia entre sus consumidores.
Copias locales de datos de consulta usados solo para visualizar: se conservan identificadores y se deriva el dato actual desde TanStack Query. Los borradores de edición deliberados siguen siendo locales. No se agregaron efectos ni memoización preventiva.
Dashboard y shell con responsabilidades mezcladas: paneles independientes para trabajo, avisos, actividad, compañías e indicadores; búsqueda local en WorkspaceHeader y navegación en WorkspaceSidebar. Se mantienen query keys, cancelación de consultas y navegación.
Imports de valores y tipos mezclados: se separaron 237 declaraciones mixtas en import type y los imports de runtime correspondientes. Una comparación de tokens y bindings verificó que 193 ficheros de esta última fase solo cambian imports, no lógica ni imports de runtime.
Cast de JSON persistido: se usa unknown antes de la validación del dashboard.
Promesa de envío en AccessForm: se utiliza la mutación con gestión explícita del resultado y del error, sin descartar una promesa rechazada de mutateAsync.
Código sin consumidores y variables no utilizadas: retirada tras comprobar referencias.
Logging SQL habilitado: desactivado para no emitir parámetros sensibles de sesiones o usuarios.
Cuerpos HTTP inválidos tratados como errores internos: clasificación de errores del parser con respuestas seguras 400/413/415; errores inesperados conservan respuesta genérica 500.
Hash scrypt con segmentos sobrantes aceptado: rechazo explícito y prueba de regresión.
Cierre del servidor repetible y errores de cierre: protección contra señales duplicadas, observación del cierre y conservación del error original cuando falla la limpieza.

Se conservaron los encadenamientos con catch(next) en Express 4: convertirlos a handlers async sin propagación explícita habría introducido una regresión. Los schemas de dominio existentes y sus Value Objects no se sustituyeron por DTOs de transporte ni casts. El ORM permanece en Infrastructure; las referencias transversales de pruebas no son dependencias del dominio.

El análisis final del código propio no encontró any, non-null assertions, casts distintos de as const, import("...").Tipo, imports mixtos pendientes ni ficheros de producción con varios componentes principales. Esto describe las comprobaciones estructurales ejecutadas, no una garantía de ausencia de cualquier defecto posible.

Archivos especialmente modificados

modules/companies/src/web/components/companies-workspace.tsx, dashboard-page.tsx y sus componentes de navegación, búsqueda y paneles.
modules/companies/src/web/access/access-form.tsx, access-form-fields.tsx, access-quick-editor.tsx y access-workspace.tsx.
Listados y formularios de companies, assets y resources: diálogos editor/detail/history/create próximos a cada funcionalidad, enumerados en el inventario de modales.
modules/identity/src/web/components: composición del espacio, gestión de usuarios y formularios de contraseña con FormActions.
apps/server/src/app.ts, index.ts y config/database.ts.
modules/identity/src/api/infrastructure/security/scrypt-password-hasher.ts.
modules/companies/src/api/infrastructure/persistence/sequelize-dashboard.repository.ts.
apps/server/src/app.test.ts, scrypt-password-hasher.test.ts y apps/web/src/app.test.tsx.

Se integró el contenido exclusivo de los antiguos support-history.tsx, application-history.tsx, certificate-history.tsx y printer-history.tsx en sus respectivos componentes *-history-dialog.tsx. No se eliminó la funcionalidad; las versiones anteriores son recuperables desde Git.

Validaciones ejecutadas

Entorno comprobado: WSL/bash, Node.js v24.20.0 y PNPM 11.25.0, conforme a package.json.

Comando	Resultado
pnpm --filter @metis/companies typecheck y test	Correctos
pnpm --filter @metis/assets typecheck y test	Correctos
pnpm --filter @metis/resources typecheck y test	Correctos
pnpm --filter @metis/identity typecheck y test	Correctos
pnpm --filter @metis/web test	Correcto; se amplió la cobertura del dashboard con datos reales en es/en
pnpm --filter @metis/server test	Correcto; HTTP real e integración MariaDB en la base exclusiva de pruebas
pnpm typecheck	Correcto: 10 tareas; última ejecución con 9 resultados de caché y web recompilado
pnpm lint	Correcto, sin diagnósticos
pnpm test	Correcto: 9 tareas sin caché; incluye HTTP real e integración MariaDB
pnpm check	Correcto, sin diagnósticos
pnpm build	Correcto: servidor y web; primera ejecución compiló, repetición usó caché
git diff --check	Correcto

Se aplicaron comprobaciones Biome dirigidas tras cada grupo de cambios. El sandbox no permite abrir sockets para las pruebas HTTP; esas pruebas se ejecutaron con permiso ampliado, utilizando la base metis_desk_test que el propio runner configura y verifica. No se modificó una base de producción. Los errores intermedios de tipos introducidos durante las extracciones se corrigieron antes de las validaciones finales.

Pendientes y revisión humana

Prueba interactiva de modales y navegación. Área: componentes enumerados en el inventario. Las pruebas de render estático y lint no verifican foco, Escape, portales ni interacción real. No se ejecutó navegador ni E2E interactivo. Propuesta: comprobar alta/edición/cancelación, envío pendiente, error y selección anidada en es/en y anchura móvil. No requiere cambiar contratos ni introducir una librería de pruebas automáticamente.
Tamaño del bundle web. Área: apps/web/vite.config.ts y composición de los módulos web. Vite advierte de un chunk JS de aproximadamente 1,20 MB minificado (330 kB gzip), por encima de 500 kB. La compilación termina correctamente. No se añadió code splitting sin medir la carga y decidir fronteras de carga diferida y fallbacks. Propuesta: evaluar el perfil de carga y acordar después qué espacios cargar de manera diferida; no silenciar el aviso aumentando el límite.

No se detectó un bloqueo que requiriera cambiar contratos, modelo de datos o arquitectura.

9.9 KiB Raw Blame History