Rodax_Software/metis-desk
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
7777192d20
metis-desk/docs/revision-de-buenas-practicas.md
David ba562ad06f Refactor documentation for clarity and accuracy 
- Updated examples in "estructura-web-por-entidades-y-operaciones.md" to reflect correct entity names and directory structures.
- Clarified modal usage and component interactions in "impresoras-del-perfil.md".
- Adjusted component descriptions in "logotipos-de-companias.md" for consistency.
- Revised persistence model details in "normalizacion-de-la-persistencia.md" to remove outdated references and clarify relationships.
- Enhanced dialog patterns in "patron-de-dialogos.md" with specific guidelines for field labels and validation.
- Specified component reuse in "patron-de-listados-de-entidades.md" to include @repo/rdx-ui components.
- Updated implementation status in "personas-y-departamentos.md" to reflect current features and pending tasks.
- Clarified project scope and initial setup instructions in "plan-de-desarrollo.md" and "puesta-en-marcha.md".
- Improved descriptions of workstation management in "puestos-de-trabajo.md" for better understanding of active/inactive states.
- Enhanced resource management details in "recursos-campos-y-plantillas.md" to clarify relationships and pending features.
- Revised best practices review in "revision-de-buenas-practicas.md" to reflect current project status and components.
- Updated teleworking documentation in "teletrabajo.md" to include references to remote technical assistance.
- Clarified user account management in "usuarios-y-acceso.md" to emphasize the importance of account deactivation.
2026-10-15 17:48:46 +02:00

156 lines
10 KiB
Markdown
Raw Blame History

# Revisión de buenas prácticas
Informe de una revisión anterior, no un inventario ni una instrucción de implementación
vigente. Las cifras y resultados corresponden al cierre de aquella revisión. Para trabajar
sobre el código actual, consultar `AGENTS.md`, las guías normativas y las
[funcionalidades archivadas](funcionalidades-archivadas.md).
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, plantillas de procesos 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
1. Inspección global y lectura normativa, con clasificación de patrones y riesgos.
2. Componentes propios compartidos, composición de identidad y formularios de accesos.
3. Catálogos e inventarios de activos y recursos; asistencia y relaciones.
4. Compañías, perfiles, configuraciones, procesos y sus plantillas.
5. Fronteras HTTP, contraseñas, datos persistidos, logging y ciclo de vida del servidor.
6. Inventario completo y separación de modales, incluidos wrappers y altas anidadas.
7. Paneles del dashboard, navegación lateral y búsqueda global.
8. 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](inventario-de-modales.md) 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.
- Lectura de persistencia: se usa unknown antes de validar las filas y reconstruir los objetos 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/workspace/ y modules/companies/src/web/dashboard/: espacio de
trabajo, página del dashboard y componentes de navegación, búsqueda y paneles.
- modules/companies/src/web/access/: formularios en shared/ui, altas rápidas en create/ui
y listado en list/ui.
- 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
1. **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.
2. **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.
Reference in New Issue View Git Blame Copy Permalink