docs: documentacion completa — README, guia de uso, instalacion, API POS
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
272
docs/INSTALACION.md
Normal file
272
docs/INSTALACION.md
Normal file
@@ -0,0 +1,272 @@
|
||||
# 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
|
||||
|
||||
```bash
|
||||
cd /home/Autopartes/pos
|
||||
python3 app.py
|
||||
```
|
||||
|
||||
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=simple
|
||||
WorkingDirectory=/home/Autopartes/pos
|
||||
ExecStart=/usr/bin/python3 app.py
|
||||
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` |
|
||||
Reference in New Issue
Block a user