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

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

### 2. Configurar PostgreSQL

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

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

### 4. Instalar dependencias Python

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

O con un entorno virtual:

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

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

### 6. Crear el primer tenant

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

```bash
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:**
```bash
cd /home/Autopartes/pos
python3 app.py
```

**Produccion (Gunicorn):**
```bash
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

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

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

```ini
[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`:

```ini
[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

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

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

---

## Servicios Systemd (Produccion)

Despues de la instalacion, copiar los servicios y habilitarlos:

```bash
sudo cp systemd/*.service systemd/*.timer /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now nexus-pos.service nexus.service nexus-celery.service nexus-quart.service
sudo systemctl enable --now nexus-mv-refresh.timer nexus-cache-warm.timer
```

## Monitoreo (Opcional)

Levantar Prometheus + Grafana:

```bash
cd docker
docker compose -f docker-compose.monitoring.yml up -d
```

- Grafana: http://servidor:3001 (admin / nexus2026)
- Prometheus: http://servidor:9090

## PWA (Instalable)

El POS ya incluye Service Worker y manifest. Al abrir cualquier pagina del POS en Chrome/Edge, aparecera un banner para instalar la app. Requiere HTTPS en produccion para el prompt automatico.

## Tests E2E (Playwright)

```bash
npm install
npx playwright test
```