diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000..29d9669 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,401 @@ +# Nexus Autoparts — Guia de Instalacion + +Guia paso a paso para instalar una instancia de Nexus Autoparts POS en un servidor nuevo. + +Compatible con: **Raspberry Pi OS**, **Debian**, **Ubuntu**. Para Windows usar WSL. + +--- + +## Requisitos minimos + +| Componente | Minimo | Recomendado | +|---|---|---| +| RAM | 2 GB | 4 GB | +| Almacenamiento | 16 GB | 32 GB | +| SO | Raspberry Pi OS / Debian 12+ / Ubuntu 22+ | Debian 13 | +| Python | 3.11+ | 3.13 | +| PostgreSQL | 14+ | 16 | +| Node.js | 18+ | 20 | + +--- + +## Paso 1 — Clonar el repositorio + +```bash +sudo apt-get update && sudo apt-get install -y git +cd /home +sudo git clone https://git.consultoria-as.com/consultoria-as/Autoparts-DB.git Autopartes +sudo chown -R $(whoami):$(whoami) /home/Autopartes +cd /home/Autopartes +``` + +Si el certificado SSL da problemas: + +```bash +GIT_SSL_VERIFY=false sudo git clone https://git.consultoria-as.com/consultoria-as/Autoparts-DB.git Autopartes +``` + +--- + +## Paso 2 — Ejecutar el script de instalacion + +El script instala automaticamente: PostgreSQL, Python, Node.js, ffmpeg, todas las dependencias de pip, crea la base de datos, el tenant, el empleado owner y configura Gunicorn como servicio del sistema. + +```bash +sudo bash /home/Autopartes/scripts/setup_instance.sh "NOMBRE_NEGOCIO" "ID_INSTANCIA" "PIN" +``` + +**Parametros:** + +| Parametro | Descripcion | Ejemplo | +|---|---|---| +| NOMBRE_NEGOCIO | Nombre de la refaccionaria | `"Refacciones El Toro"` | +| ID_INSTANCIA | Identificador unico (sin espacios ni acentos) | `"refac-eltoro"` | +| PIN | PIN de 4 digitos para el login del dueno | `"1234"` | + +**Ejemplo completo:** + +```bash +sudo bash /home/Autopartes/scripts/setup_instance.sh "Refacciones El Toro" "refac-eltoro" "1234" +``` + +Al terminar, el script muestra: +- El tenant ID asignado +- El PIN del owner +- La IP local del servidor +- Instrucciones para arrancar + +**Anota el tenant_id** — lo necesitas para los siguientes pasos. + +--- + +## Paso 3 — Importar el catalogo TecDoc + +El catalogo de partes (1.5M+ partes OEM, 304K aftermarket, 15.8M cross-references) vive en la base de datos `nexus_autoparts`. Si esta es tu primera instalacion, necesitas cargar los datos desde un dump. + +### Opcion A — Dump desde otra instancia + +Desde la maquina que YA tiene el catalogo: + +```bash +# Exportar (en la maquina origen) +pg_dump -U nexus -h localhost nexus_autoparts > /tmp/nexus_catalog.sql + +# Copiar al nuevo servidor (via USB, SCP, o red) +scp /tmp/nexus_catalog.sql usuario@IP_NUEVA:/tmp/ +``` + +En el nuevo servidor: + +```bash +PGPASSWORD=nexus_autoparts_2026 psql -U nexus -h localhost -d nexus_autoparts < /tmp/nexus_catalog.sql +``` + +### Opcion B — Sin catalogo (solo inventario local) + +Si no necesitas el catalogo TecDoc (solo vas a cargar el inventario de la refaccionaria), salta este paso. El POS funciona sin el catalogo — simplemente el buscador de partes OEM no tendra datos. + +--- + +## Paso 4 — Importar inventario + +Prepara un archivo CSV con el inventario de la refaccionaria. Columnas aceptadas (los nombres son flexibles): + +```csv +numero_de_parte,nombre,marca,precio,existencia +FO-1234,Filtro de Aceite Tsuru,FRAM,185.50,12 +BP-5678,Bujia NGK Sentra,NGK,45.00,50 +BA-9012,Balata Delantera Jetta,WAGNER,320.00,8 +``` + +**Columnas requeridas:** `numero_de_parte` (o `codigo`, `clave`, `sku`), `nombre` (o `descripcion`) + +**Columnas opcionales:** `marca`, `precio` (o `precio_1`), `existencia` (o `stock`, `cantidad`), `costo`, `precio_2`, `precio_3`, `categoria`, `ubicacion`, `codigo_barras` + +El importador acepta nombres en espanol, ingles, y formato SICAR. + +### Primero verificar (dry run): + +```bash +cd /home/Autopartes/pos +python3 ../scripts/import_inventory.py --tenant=TENANT_ID --csv=ruta/al/inventario.csv --dry-run +``` + +### Importar de verdad: + +```bash +python3 ../scripts/import_inventory.py --tenant=TENANT_ID --csv=ruta/al/inventario.csv +``` + +Si el CSV tiene codificacion Latin-1 (comun en archivos de SICAR): + +```bash +python3 ../scripts/import_inventory.py --tenant=TENANT_ID --csv=inventario.csv --encoding=latin-1 +``` + +--- + +## Paso 5 — Configurar peers (red de bodegas) + +Para que esta instancia pueda ver el inventario de las otras refaccionarias en la red, edita el archivo de peers: + +```bash +nano /home/Autopartes/pos/peers.json +``` + +Ejemplo con 2 peers: + +```json +{ + "instance_name": "Refacciones El Toro", + "instance_id": "refac-eltoro", + "tenant_id": 12, + "peers": [ + { + "name": "Refacciones La Esquina", + "url": "http://192.168.10.20:5001", + "enabled": true + }, + { + "name": "AutoPartes Central", + "url": "http://192.168.10.30:5001", + "enabled": true + } + ], + "peer_timeout_seconds": 3 +} +``` + +**Importante:** El `tenant_id` debe coincidir con el que te dio el script de instalacion en el Paso 2. + +--- + +## Paso 6 — Arrancar el servicio + +```bash +# Arrancar +sudo systemctl start nexus-pos + +# Verificar que esta corriendo +sudo systemctl status nexus-pos + +# Ver logs en tiempo real +sudo journalctl -u nexus-pos -f +``` + +Para que arranque automaticamente al encender la maquina: + +```bash +sudo systemctl enable nexus-pos +``` + +### Arranque manual (sin Gunicorn): + +```bash +cd /home/Autopartes/pos +python3 app.py +``` + +--- + +## Paso 7 — Verificar + +Desde cualquier dispositivo en la misma red (PC, tablet, celular), abre un navegador: + +``` +http://IP_DEL_SERVIDOR:5001/pos/login +``` + +Login con el PIN que configuraste en el Paso 2. + +### Verificar la salud del sistema: + +```bash +curl http://localhost:5001/pos/health +# Debe responder: {"status": "ok"} + +curl http://localhost:5001/pos/api/peer/health +# Debe responder con el nombre de la instancia y conteo de inventario +``` + +--- + +## Paso 8 — WhatsApp (opcional) + +Para vincular un numero de WhatsApp al chatbot IA: + +1. Arranca el bridge de WhatsApp: + +```bash +cd /opt/whatsapp-bridge +npm install +nohup node server.js > /tmp/wa-bridge.log 2>&1 & +``` + +2. Abre el POS en el navegador → seccion WhatsApp +3. Click "Conectar WhatsApp" +4. Escanea el QR con el telefono que quieres vincular + +### Configurar el bridge como servicio: + +```bash +sudo cat > /etc/systemd/system/nexus-whatsapp.service << 'EOF' +[Unit] +Description=Nexus WhatsApp Bridge +After=network.target + +[Service] +User=root +WorkingDirectory=/opt/whatsapp-bridge +ExecStart=/usr/bin/node server.js +Restart=always +RestartSec=5 + +[Install] +WantedBy=multi-user.target +EOF + +sudo systemctl daemon-reload +sudo systemctl enable nexus-whatsapp +sudo systemctl start nexus-whatsapp +``` + +--- + +## Comandos utiles + +| Comando | Descripcion | +|---|---| +| `sudo systemctl start nexus-pos` | Arrancar el POS | +| `sudo systemctl stop nexus-pos` | Detener el POS | +| `sudo systemctl restart nexus-pos` | Reiniciar el POS | +| `sudo systemctl status nexus-pos` | Ver estado | +| `sudo journalctl -u nexus-pos -f` | Ver logs en vivo | +| `sudo systemctl start nexus-whatsapp` | Arrancar WhatsApp bridge | +| `curl localhost:5001/pos/health` | Verificar salud del POS | +| `curl localhost:21465/status` | Verificar WhatsApp bridge | + +--- + +## Estructura de archivos + +``` +/home/Autopartes/ +├── pos/ # Aplicacion Flask (POS) +│ ├── app.py # Punto de entrada +│ ├── config.py # Configuracion (DB, JWT, SMTP) +│ ├── peers.json # Configuracion de peers (red) +│ ├── blueprints/ # Endpoints REST +│ ├── services/ # Logica de negocio +│ ├── templates/ # Paginas HTML +│ └── static/ # CSS, JS, imagenes +├── dashboard/ # Servidor web publico (puerto 5000) +│ ├── server.py +│ ├── landing.html +│ └── catalog-public.html +├── scripts/ # Scripts de utilidad +│ ├── setup_instance.sh # Instalacion automatica +│ ├── import_inventory.py # Importar inventario CSV +│ └── seed_marketplace.py # Datos de prueba marketplace +├── sql/ # Migraciones de base de datos +├── pitch/ # Pitch deck para inversionistas +└── vehicle_database/ # Schema del catalogo de vehiculos +``` + +--- + +## Solucion de problemas + +### El POS no arranca + +```bash +# Ver el error exacto +sudo journalctl -u nexus-pos --no-pager -n 50 + +# Verificar que PostgreSQL esta corriendo +sudo systemctl status postgresql + +# Verificar que el puerto no esta ocupado +sudo fuser 5001/tcp +``` + +### No puedo acceder desde otro dispositivo + +```bash +# Verificar el firewall +sudo ufw status +# Si esta activo, abrir el puerto: +sudo ufw allow 5001/tcp + +# Verificar que el servicio escucha en todas las interfaces +ss -tlnp | grep 5001 +# Debe mostrar 0.0.0.0:5001, NO 127.0.0.1:5001 +``` + +### El inventario no se importo correctamente + +```bash +# Verificar cuantos items hay +cd /home/Autopartes/pos +python3 -c " +from tenant_db import get_tenant_conn +conn = get_tenant_conn(TENANT_ID) +cur = conn.cursor() +cur.execute('SELECT COUNT(*) FROM inventory WHERE is_active = TRUE') +print(cur.fetchone()[0], 'items en inventario') +conn.close() +" +``` + +### WhatsApp no genera QR + +```bash +# Limpiar sesion anterior y reiniciar +sudo rm -rf /opt/whatsapp-bridge/auth/ +sudo systemctl restart nexus-whatsapp +# Esperar 10 segundos, luego revisar +curl localhost:21465/status +``` + +### Los peers no se ven entre si + +```bash +# Desde esta maquina, verificar que el peer responde +curl http://IP_DEL_PEER:5001/pos/api/peer/health + +# Si no responde, verificar: +# 1. Que el POS del peer esta corriendo +# 2. Que estan en la misma red +# 3. Que el firewall permite puerto 5001 +ping IP_DEL_PEER +``` + +--- + +## Actualizaciones + +Para actualizar el sistema a la ultima version: + +```bash +cd /home/Autopartes +git pull origin main +sudo systemctl restart nexus-pos +``` + +Si hay migraciones de base de datos nuevas: + +```bash +# Aplicar migraciones al master +PGPASSWORD=nexus_autoparts_2026 psql -U nexus -h localhost -d nexus_autoparts -f sql/marketplace_schema.sql + +# Aplicar migraciones al tenant +PGPASSWORD=nexus_autoparts_2026 psql -U nexus -h localhost -d tenant_NOMBRE -f sql/marketplace_tenant_users.sql +``` + +--- + +## Soporte + +- **Email:** ialcarazsalazar@consultoria-as.com +- **WhatsApp:** +52 664 217 0990 +- **Gitea:** https://git.consultoria-as.com/consultoria-as/Autoparts-DB