# 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:

```bash
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 `/tickets`, `/catalogs` o
`/companies/:companyId`. Consultar [Rutas del cliente](rutas-del-cliente.md) para
las fichas, los filtros y el requisito de fallback de la SPA en producción.

Consultar [Usuarios y acceso](usuarios-y-acceso.md) 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

En este equipo se utiliza http://192.168.0.2:5173. Vite usa server.host: true y la orden de desarrollo respeta esa configuración. En WSL2 con NAT, esto permite conexiones dentro de la red de WSL, pero no elimina la necesidad de reenviar el puerto desde Windows. El script activar.ps1 obtiene la IPv4 actual de Ubuntu-24.04 y configura el reenvío desde 192.168.0.2:5173 hacia esa dirección en WSL. La API y MariaDB siguen escuchando únicamente en loopback. La regla de cortafuegos se limita al perfil privado y a equipos de la subred local.

Ejecutar activar.ps1 desde PowerShell como administrador y mantener pnpm dev en WSL. Los scripts activar.ps1 y desactivar.ps1 están en la carpeta metis-desk-lan del espacio de trabajo de Windows. Para acceder y guardar datos desde la dirección de red, establecer APP_ORIGIN=http://192.168.0.2:5173 en .env y reiniciar pnpm dev. Solo se permite un origen: con esa configuración, las operaciones desde localhost serán rechazadas. Si cambia la dirección de este ordenador, retirar el reenvío anterior, actualizar los scripts y APP_ORIGIN y volver a activarlo. La activación requiere privilegios de Windows. El reenvío y la regla privada están activados y se ha comprobado la respuesta HTTP y la sesión por la dirección LAN. Si WSL cambia de dirección después de reiniciar, volver a ejecutar activar.ps1 para actualizar el destino. La comprobación desde un segundo equipo depende de disponer de ese equipo en la red.

## Diagnóstico de conexión con MariaDB

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

```bash
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

```bash
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:

```bash
pnpm --filter @metis/server start
```

## Alcance

Hay acceso, sesiones persistentes, gestión de usuarios, compañías clientes con contactos y sedes y una página inicial que comprueba la conexión. Inventario y tickets siguen pendientes. 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.