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

5.9 KiB

Raw Blame History

Puesta en marcha

Entorno

El repositorio está en /home/david/dev/metis-desk, dentro de WSL2 Ubuntu-24.04. Necesita Node.js 24.x, PNPM 11.25.0 y Docker disponible desde WSL. No depende de paquetes locales de factuges-erp.

Desde una terminal Ubuntu-24.04:

cd /home/david/dev/metis-desk
pnpm install --frozen-lockfile
pnpm db:up
pnpm dev

pnpm db:up genera .env con secretos locales si no existe e inicia MariaDB en un volumen persistente. No crea usuarios de la aplicación. El servidor aplica las migraciones al arrancar.

Abrir http://localhost:5173. La primera apertura permite crear el administrador inicial; las siguientes muestran el acceso. La API escucha en 127.0.0.1:3001 y la base de datos en 127.0.0.1:3307.

Una vez autenticado, Inicio utiliza /dashboard y cada sección tiene URL propia. Se pueden abrir o recargar directamente /dashboard, /catalogs o /companies/:companyId. Consultar Rutas del cliente para las fichas, los filtros y el requisito de fallback de la SPA en producción.

Consultar Usuarios y acceso para la configuración inicial y protección de cuentas. No borrar el volumen para actualizar o reiniciar: contiene usuarios, compañías, contactos y sedes.

Si se cambia PORT, configurar API_PROXY_TARGET al arrancar Vite (por defecto http://127.0.0.1:3001). Si cambia el origen del navegador, actualizar APP_ORIGIN en .env.

Acceso desde la red local

La dirección de acceso es http://192.168.0.2:5173. Vite escucha en la red de WSL y redirige /api a la API interna. En WSL2 con NAT se necesita además reenviar el puerto desde Windows, siguiendo el procedimiento de Microsoft.

El script versionado scripts/enable-lan-access.ps1 detecta la IPv4 de eth0 en Ubuntu-24.04, comprueba que Vite responde, configura el reenvío TCP y crea una regla de firewall para el perfil privado y la subred local. La interfaz de Windows con IP 192.168.0.2 debe tener perfil Privado. Mantener pnpm dev ejecutándose en WSL.

Copiar el script a una carpeta de Windows y ejecutarlo desde PowerShell como administrador, en esa carpeta:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\enable-lan-access.ps1

La excepción de ejecución solo afecta a ese proceso. Se pueden indicar -Distribution, -ListenAddress y -Port si cambian los valores. Comprobar el puerto anunciado por Vite: si 5173 está ocupado, puede usar otro.

En .env, establecer APP_ORIGIN=http://192.168.0.2:5173 y reiniciar pnpm dev para permitir guardar datos desde la dirección LAN. Solo se admite un origen: con esa configuración, las operaciones desde localhost serán rechazadas. No se publican el puerto de la API ni el de MariaDB.

Volver a ejecutar el script después de un cambio de IP de WSL. El script actualiza el destino del mismo reenvío. Si cambia la IP de Windows o el puerto, retirar primero las reglas anteriores y actualizar también APP_ORIGIN.

Para retirar el acceso con los valores predeterminados, ejecutar en PowerShell como administrador:

netsh interface portproxy delete v4tov4 listenaddress=192.168.0.2 listenport=5173 protocol=tcp
Remove-NetFirewallRule -Name 'MetisDesk-WSL-LAN-192.168.0.2-5173'

El script reinicia IP Helper (iphlpsvc) después de configurar las reglas para que aplique el reenvío; esto interrumpe brevemente otros reenvíos gestionados por ese servicio. Espera hasta diez segundos a que aparezca el listener IPv4 y comprueba una respuesta HTTP 200 a través de la IP de Windows, sin usar el proxy del sistema, antes de anunciar éxito. Si falla, muestra los reenvíos y los listeners y conserva las reglas para diagnóstico. Esta comprobación local no garantiza acceso desde otro dispositivo: verificarlo también desde la red local. El reinicio manual del servicio resolvió el fallo observado; el script actualizado queda pendiente de ejecución en Windows.

Diagnóstico de conexión con MariaDB

Docker debe estar iniciado y accesible desde WSL. Comprobar el servicio sin mostrar las credenciales:

docker compose ps -a
docker compose logs --tail=50 database
pnpm db:up

pnpm db:up espera a que MariaDB esté saludable antes de terminar y conserva el volumen existente. El contenedor utiliza restart: unless-stopped: vuelve a arrancar tras reiniciar Docker o ante una salida inesperada, salvo que se haya detenido explícitamente. Si se usa docker compose stop o down, es necesario ejecutar de nuevo pnpm db:up. Nunca usar down -v para resolver una conexión: elimina los datos.

El backend ejecutado en WSL conecta a 127.0.0.1:3307; el puerto interno del contenedor es 3306. Después de recuperar la base de datos, reiniciar el backend si había terminado con un error de arranque: el modo watch espera cambios en archivos y no se reactiva por arrancar Docker.

Verificaciones

pnpm typecheck
pnpm lint
pnpm test
pnpm check
pnpm build

La base local debe estar encendida para las pruebas de integración. Estas solo usan metis_desk_test. La compilación genera apps/server/dist y apps/web/dist.

Para ejecutar la API compilada, parar primero el servidor de desarrollo:

pnpm --filter @metis/server start

Alcance

Hay acceso, sesiones persistentes, gestión de usuarios, compañías con personas, departamentos y sedes, inventario, recursos, puestos, perfiles y configuraciones. Inicio muestra indicadores, avisos y actividad. El plan de desarrollo recoge las funciones disponibles y los pendientes; las funciones retiradas se describen en funcionalidades archivadas. Las tablas nuevas se crean al arrancar la API mediante migraciones explícitas.

La API compilada todavía no sirve la interfaz estática. El despliegue, proxy HTTPS, backups y recuperación de acceso se definirán en una entrega posterior.

5.9 KiB Raw Blame History