Autoparts-DB/docs/INSTALACION.md

Guia de Instalacion -- Nexus Autoparts

Instrucciones para instalar y poner en marcha el sistema Nexus Autoparts POS.

---

Requisitos del sistema

Componente	Minimo	Recomendado
OS	Linux (Debian 12 / Ubuntu 22.04 / Raspberry Pi OS)	Debian 13 o Ubuntu 24.04
Python	3.11+	3.12+
PostgreSQL	15+	16+
RAM	2 GB	4 GB
Disco	20 GB (SSD recomendado)	50 GB SSD
Red	LAN	LAN + acceso a internet para TecDoc y timbrado CFDI

---

Instalacion paso a paso

1. Instalar dependencias del sistema

sudo apt update && sudo apt install -y \
    python3 python3-pip python3-venv \
    postgresql postgresql-client \
    git

2. Configurar PostgreSQL

# Crear usuario y base de datos maestra (catalogo TecDoc)
sudo -u postgres createuser nexus -P
# Cuando pida password: nexus_autoparts_2026

sudo -u postgres createdb nexus_autoparts -O nexus
sudo -u postgres psql -c "ALTER ROLE nexus CREATEDB;"

El permiso CREATEDB es necesario porque el sistema crea una base de datos separada por cada tenant (cliente).

3. Clonar el repositorio

git clone https://git.consultoria-as.com/consultoria-as/Autoparts-DB.git /home/Autopartes

4. Instalar dependencias Python

pip install -r /home/Autopartes/pos/requirements.txt --break-system-packages

O con un entorno virtual:

python3 -m venv /home/Autopartes/venv
source /home/Autopartes/venv/bin/activate
pip install -r /home/Autopartes/pos/requirements.txt

5. Cargar schema de la base maestra (catalogo)

sudo -u postgres psql nexus_autoparts < /home/Autopartes/vehicle_database/sql/schema.sql

6. Crear el primer tenant

cd /home/Autopartes/pos
python3 -c "
from services.tenant_manager import provision_tenant
result = provision_tenant(
    'Mi Refaccionaria',
    rfc='RFC000000AAA',
    owner_name='Admin',
    owner_pin='1234'
)
print(result)
"

Esto crea:

• Una entrada en la tabla maestra de tenants
• Una base de datos tenant_mi_refaccionaria con todas las tablas del POS
• Un empleado "Admin" con rol "owner" y PIN 1234

7. Aplicar migraciones

cd /home/Autopartes/pos
python3 -c "
from tenant_db import get_tenant_conn_by_dbname
conn = get_tenant_conn_by_dbname('tenant_mi_refaccionaria')
cur = conn.cursor()
with open('migrations/v1.1_pos_tables.sql') as f:
    cur.execute(f.read())
conn.commit()
print('Migraciones aplicadas correctamente')
"

8. Iniciar el POS

Desarrollo:

cd /home/Autopartes/pos
python3 app.py

Produccion (Gunicorn):

pip install gunicorn --break-system-packages
sudo mkdir -p /var/log/nexus-pos
cd /home/Autopartes/pos
./run.sh

Acceder desde el navegador:

http://[IP-del-servidor]:5001/pos/login
PIN: 1234

9. (Opcional) Iniciar la web publica

cd /home/Autopartes/dashboard
python3 server.py

Acceder: http://[IP-del-servidor]:5000

---

Importar datos TecDoc

Para tener el catalogo de partes OEM y aftermarket:

cd /home/Autopartes

# Fase 1: descargar datos de TecDoc API a archivos JSON
python3 scripts/import_tecdoc.py download

# Fase 2: importar JSON a PostgreSQL
python3 scripts/import_tecdoc.py import

# Ver progreso
python3 scripts/import_tecdoc.py status

El script es resumible: si se interrumpe, al volver a ejecutar salta los archivos ya descargados.

---

Instalacion como servicio (systemd)

POS (puerto 5001)

Crear el archivo /etc/systemd/system/nexus-pos.service:

[Unit]
Description=Nexus Autoparts POS
After=postgresql.service
Wants=postgresql.service

[Service]
Type=notify
WorkingDirectory=/home/Autopartes/pos
ExecStartPre=/bin/mkdir -p /var/log/nexus-pos
ExecStart=/usr/local/bin/gunicorn -c gunicorn.conf.py "app:create_app()"
Restart=always
RestartSec=5
User=root
Environment=PYTHONUNBUFFERED=1

[Install]
WantedBy=multi-user.target

Web publica (puerto 5000)

Crear el archivo /etc/systemd/system/nexus-web.service:

[Unit]
Description=Nexus Autoparts Web Publica
After=postgresql.service
Wants=postgresql.service

[Service]
Type=simple
WorkingDirectory=/home/Autopartes/dashboard
ExecStart=/usr/bin/python3 server.py
Restart=always
RestartSec=5
User=root
Environment=PYTHONUNBUFFERED=1

[Install]
WantedBy=multi-user.target

Activar los servicios

sudo systemctl daemon-reload
sudo systemctl enable nexus-pos nexus-web
sudo systemctl start nexus-pos nexus-web

# Verificar estado
sudo systemctl status nexus-pos
sudo systemctl status nexus-web

---

Instalacion en Raspberry Pi 5

El POS esta optimizado para correr en Raspberry Pi 5.

Hardware recomendado

Componente	Especificacion	Precio aprox.
Raspberry Pi 5	8 GB RAM	$80 USD
SSD NVMe	256 GB (via HAT M.2)	$30 USD
Case con ventilador	Oficial o Argon	$15 USD
Fuente USB-C	5V 5A oficial	$12 USD
MicroSD	32 GB (solo para boot)	$5 USD
Total		~$142 USD

Pasos adicionales para RPi 5

1. Instalar Raspberry Pi OS (64-bit, Debian Bookworm)
2. Configurar boot desde SSD NVMe (no usar MicroSD como disco principal)
3. Seguir los mismos pasos de instalacion de arriba
4. Para acceso desde tablets/celulares en la misma red LAN, usar la IP local del RPi

Rendimiento esperado

• Consultas de catalogo: < 200ms
• Busqueda de partes: < 500ms
• Transacciones POS: < 100ms
• Soporte simultaneo: 3-5 terminales sin degradacion

---

Verificacion post-instalacion

# Verificar que PostgreSQL esta corriendo
sudo systemctl status postgresql

# Verificar que el POS responde
curl http://localhost:5001/pos/health
# Debe responder: {"status":"ok"}

# Verificar la base maestra
sudo -u postgres psql nexus_autoparts -c "SELECT count(*) FROM parts;"

# Verificar tenant
sudo -u postgres psql tenant_mi_refaccionaria -c "SELECT name, role FROM employees;"

---

Troubleshooting

Problema	Solucion
psycopg2 no instala	sudo apt install libpq-dev python3-dev y reinstalar
Puerto 5001 ocupado	sudo lsof -i :5001 para ver que proceso lo usa
"Tenant not found"	Verificar que provision_tenant se ejecuto correctamente
PIN bloqueado	Esperar 15 minutos o reiniciar el servicio POS
Base de datos no conecta	Verificar credenciales en pos/config.py