# Onboarding de clientes Windows — Navis / Triton Móvil Guía paso a paso para dar de alta un nuevo cliente en el SaaS y dejar el CLI de sincronización funcionando en su servidor Windows. --- ## Requisitos previos - Acceso al panel SaaS: `https://saas.navisapp.eu` - Acceso de administrador (bootstrap ya realizado) - El servidor Windows del cliente tiene: - Firebird instalado y accesible - Base de datos `.fdb` disponible - Conexión a Internet hacia `https://api.navisapp.eu` --- ## Paso 1 — Crear el cliente en el SaaS 1. Accede a `https://saas.navisapp.eu` e inicia sesión como admin. 2. Ve a **Clientes**. 3. Haz clic en **Nuevo cliente**. 4. Rellena: - **Nombre**: nombre de la empresa (p. ej. `Taller Náutico Martínez`). - **Subdominio**: identificador único para la PWA (p. ej. `nautica-martinez`). Se convertirá a minúsculas automáticamente. 5. Haz clic en **Crear**. El sistema genera automáticamente una API Key y muestra un modal: ``` API Key generada tk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx Guarda esta clave ahora. No se volverá a mostrar. ``` 6. Haz clic en **Copiar** y guárdala en un lugar seguro. También anota el subdominio, lo necesitarás más adelante. > Si pierdes la clave, puedes generar una nueva desde el listado de clientes (icono de llave → Rotar API key), pero esto invalidará la anterior y tendrás que actualizarla en el servidor Windows. --- ## Paso 2 — Crear el primer usuario de la PWA 1. En el listado de clientes, haz clic en el icono **Usuarios** del cliente recién creado. 2. Haz clic en **Nuevo usuario**. 3. Rellena los campos obligatorios: - Nombre completo - Email - Contraseña - Rol (normalmente `admin` para el primer usuario) 4. Guarda. El cliente ya puede acceder a su PWA en: ``` https://{subdominio}.navisapp.eu ``` Por ejemplo: ``` https://nautica-martinez.navisapp.eu ``` --- ## Paso 3 — Preparar el servidor Windows del cliente ### 3.1 Archivos necesarios Copia en una carpeta del servidor Windows (por ejemplo `C:\Nauticus\`): - `nauticus-cli.exe` - `login.bat` - `run-sync-once.bat` - `run-sync.bat` - `.env.example` > Los archivos `.bat` y `.env.example` están en `apps/cli/` del repositorio. El `.exe` se genera con `GOOS=windows GOARCH=amd64 go build -o nauticus-cli.exe .` desde `apps/cli`. ### 3.2 Crear el archivo de entorno Copia `.env.example` a `.env` en la misma carpeta y rellena los valores reales: ```bat TRITON_API_KEY=tk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx FB_PASSWORD=tu_password_firebird ``` - `TRITON_API_KEY`: la clave copiada en el Paso 1. - `FB_PASSWORD`: contraseña del usuario Firebird (por defecto suele ser `masterkey`). > **Muy importante:** el archivo debe llamarse exactamente `.env`, no `.env.txt`. > Windows oculta las extensiones de archivos conocidas, por lo que puedes verlo como `.env` aunque en realidad sea `.env.txt`. > > Para comprobarlo, abre `cmd.exe` en la carpeta y ejecuta: > ```bat > dir > ``` > Si ves `.env.txt`, renómbralo con: > ```bat > rename .env.txt .env > ``` > > También evita usar el Bloc de notas de Windows para crear el archivo, porque puede añadir una marca BOM al principio que impide que los `.bat` lo lean correctamente. Es mejor usar VS Code, Notepad++ o el propio cmd: > ```bat > echo TRITON_API_KEY=tk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx > .env > echo FB_PASSWORD=masterkey >> .env > ``` ### 3.3 Crear el fichero de configuración `.nauticus.yaml` Crea el fichero `%USERPROFILE%\.nauticus.yaml` (por ejemplo `C:\Users\Administrador\.nauticus.yaml`) con el siguiente contenido: ```yaml api_url: "https://api.navisapp.eu" interval: 300 firebird_host: "localhost" firebird_port: 3050 firebird_user: "SYSDBA" companies: - name: "Taller Náutico Martínez" tenant_id: "nautica-martinez" database: "C:\\Firebird\\data\\YATE.fdb" ``` Ajusta: - `name`: nombre del cliente tal como aparece en el SaaS. **Debe coincidir exactamente** (mayúsculas, minúsculas y tildes incluidas); si no, el login devolverá `401 invalid credentials`. - `tenant_id`: el subdominio elegido en el Paso 1. - `database`: ruta completa al fichero `.fdb` en el servidor Windows. Usa doble barra invertida `\\`. - `firebird_host`, `firebird_port`, `firebird_user`: según la instalación Firebird del cliente. --- ## Paso 4 — Probar la conexión y sincronización ### 4.1 Login Abre una terminal (`cmd.exe`) en la carpeta donde están los archivos y ejecuta: ```bat login.bat ``` Si todo es correcto, el CLI guardará los tokens JWT en `%USERPROFILE%\.nauticus\tokens\`. > **Alternativa recomendada si los `.bat` dan problemas:** usa los scripts `.ps1` con PowerShell. Hacen clic derecho → "Ejecutar con PowerShell" o desde una terminal de PowerShell: > ```powershell > .\login.ps1 > ``` > Los scripts de PowerShell leen el `.env` de forma más robusta y no sufren los problemas de codificación BOM ni extensiones ocultas de Windows. ### 4.2 Sincronización de prueba Ejecuta una sincronización única: ```bat run-sync-once.bat ``` Verás el progreso por tabla (clientes, embarcaciones, órdenes de trabajo, etc.). Si hay errores, revisa: - Que `TRITON_API_KEY` sea correcta. - Que `FB_PASSWORD` sea correcta. - Que Firebird esté accesible en `firebird_host:firebird_port`. - Que la ruta del `.fdb` sea correcta. ### 4.3 Sincronización bidireccional (PWA → Firebird) Por defecto, el CLI sincroniza **Firebird → PostgreSQL** (datos del ERP a la PWA). A partir de la versión actual, también soporta sincronización inversa para ciertos registros creados o modificados en la PWA (por ejemplo, **horas trabajadas** en los partes). Para activarlo, debes configurar el **mapping outbound**: 1. En la carpeta del CLI, ve a `mappings\outbound\`. 2. Copia `time_entries.example.yaml` a `time_entries.yaml`. 3. Edita `time_entries.yaml` con la tabla y columnas de Firebird de ese cliente: ```yaml postgres_table: "time_entries" firebird_table: "Y00XX" operation: "insert" columns: HORAS: "hours" FECHA: "entry_date" NOTAS: "notes" CODIGO_OT: "work_order_firebird_id" CODIGO_CAP: "chapter_firebird_id" CODIGO_TEC: "technician_firebird_id" ``` > **Importante:** la tabla y columnas de Firebird dependen del ERP de cada cliente. Debes conocer el esquema Firebird destino para configurar este mapping. Si no está configurado, el CLI simplemente omitirá la sincronización outbound. ### 4.4 Sincronización continua Cuando la sincronización de prueba funcione, ejecuta: ```bat run-sync.bat ``` Esto mantiene un bucle que sincroniza cada 300 segundos (5 minutos), configurable en `interval` del `.nauticus.yaml`. Para dejarlo ejecutándose permanentemente, configúralo como un servicio de Windows o programalo con el Programador de tareas. --- ## Paso 5 — Verificar en la PWA 1. Accede a `https://{subdominio}.navisapp.eu`. 2. Inicia sesión con el usuario creado en el Paso 2. 3. Comprueba que aparezcan los datos sincronizados (clientes, embarcaciones, órdenes de trabajo, etc.). --- ## Resumen de archivos y variables | Elemento | Dónde se configura | Ejemplo | |----------|-------------------|---------| | API Key | `.env` (`TRITON_API_KEY`) | `tk_abc123...` | | Password Firebird | `.env` (`FB_PASSWORD`) | `masterkey` | | URL del backend | `.nauticus.yaml` (`api_url`) | `https://api.navisapp.eu` | | Conexión Firebird | `.nauticus.yaml` | host, puerto, usuario | | Empresa y base de datos | `.nauticus.yaml` (`companies`) | nombre, tenant_id, ruta `.fdb` | | Intervalo de sincro | `.nauticus.yaml` (`interval`) | `300` (segundos) | --- ## Seguridad - El fichero `.env` contiene credenciales. Protégelo con permisos adecuados en el servidor Windows. - El fichero `.nauticus.yaml` es texto plano; no guarda la API Key ni la contraseña de Firebird, solo la configuración de conexión. - Los tokens JWT se guardan en `%USERPROFILE%\.nauticus\tokens\`. Es una carpeta oculta del usuario. - Si rotas la API Key desde el SaaS, recuerda actualizar `TRITON_API_KEY` en el `.env` del cliente. --- ## Solución de problemas comunes ### “No se encontró el archivo .env” Asegúrate de haber copiado `.env.example` a `.env` y de haberlo rellenado. ### “authentication required” o “invalid api key” La API Key es incorrecta o ha sido rotada. Genera una nueva desde el SaaS y actualiza `.env`. ### No se detecta el subdominio en la PWA Asegúrate de acceder con la URL correcta: `https://{subdominio}.navisapp.eu`. Si usas una IP o dominio diferente, la PWA no podrá resolver el tenant. ### Error de conexión a Firebird Verifica que Firebird esté arrancado, que el puerto 3050 esté abierto y que la ruta del `.fdb` sea correcta.