212 lines
7.9 KiB
Markdown
212 lines
7.9 KiB
Markdown
# Nexus Autoparts
|
|
|
|
**POS + Catalogo de autopartes para refaccionarias mexicanas.**
|
|
|
|
Sistema integral que combina un catalogo publico de autopartes con un Punto de Venta multi-tenant, disenado para refaccionarias independientes. Incluye inventario, facturacion CFDI 4.0, contabilidad, y caja registradora.
|
|
|
|
---
|
|
|
|
## Dos Sistemas
|
|
|
|
| Sistema | Puerto | Descripcion |
|
|
|---------|--------|-------------|
|
|
| **Web publica** | 5000 | Landing page + catalogo publico con navegacion por vehiculo |
|
|
| **POS multi-tenant** | 5001 | Sistema de punto de venta completo, instalable como PWA |
|
|
|
|
### Web publica (puerto 5000)
|
|
|
|
- Landing page para talleres y refaccionarias
|
|
- Catalogo publico: Marca > Modelo > Ano > Motor > Categoria > Partes
|
|
- Selector de regiones: Mexico/USA/Canada, Europa, Asia, Todos
|
|
- Busqueda combinada vehiculo + parte
|
|
- VIN decoder via NHTSA API
|
|
- Diagramas explosionados con hotspots
|
|
|
|
### POS multi-tenant (puerto 5001)
|
|
|
|
- **Multi-tenant**: base de datos aislada por cliente
|
|
- **PWA**: instalable en tablets/celulares, modo offline
|
|
- **10 pantallas**: Login, Catalogo, Inventario, POS, Clientes, Facturacion, Contabilidad, Dashboard, Reportes, Configuracion
|
|
- **81+ endpoints API** organizados en 9 blueprints
|
|
- **2 temas**: Industrial oscuro + Moderno claro (toggle en sidebar)
|
|
- **Auth por PIN** con JWT + rate limiting + bloqueo por dispositivo
|
|
- **5 roles**: Dueno, Admin, Cajero, Almacenista, Contador
|
|
|
|
#### Modulos del POS
|
|
|
|
| Modulo | Funcionalidad |
|
|
|--------|--------------|
|
|
| Catalogo | Navegacion TecDoc por vehiculo, busqueda inteligente, stock local, alternativas, carrito |
|
|
| Inventario | CRUD productos, compras, ajustes, transferencias, toma fisica, alertas, reportes (ABC, valoracion, sin movimiento) |
|
|
| Punto de Venta | Ventas, cotizaciones, apartados, credito, atajos F1-F6, metodos de pago mixtos |
|
|
| Clientes | Datos fiscales, 3 tiers de precio, credito con limites, vehiculos, historial |
|
|
| Facturacion | CFDI 4.0 (Ingreso, Egreso, Pago), cola de timbrado, cancelacion SAT |
|
|
| Contabilidad | Polizas automaticas, catalogo SAT, balanza, estado de resultados, balance general, antiguedad |
|
|
| Caja Registradora | Apertura, movimientos, corte X, corte Z, multi-caja |
|
|
| Dashboard | Ventas del dia vs meta, cajas activas, alertas |
|
|
| Reportes | Financieros y operativos |
|
|
| Configuracion | Negocio, sucursales, empleados, roles, temas |
|
|
|
|
---
|
|
|
|
## Tech Stack
|
|
|
|
| Componente | Tecnologia |
|
|
|------------|-----------|
|
|
| Backend | Python 3, Flask |
|
|
| Base de datos | PostgreSQL (master + tenant DBs) |
|
|
| SQL | psycopg2 raw SQL (sin ORM) |
|
|
| Auth | JWT (PyJWT) + bcrypt PIN hashing |
|
|
| CFDI | lxml (XML builder CFDI 4.0) |
|
|
| Frontend | HTML/CSS/JS vanilla (sin framework) |
|
|
| Estilos | CSS custom properties (design tokens) |
|
|
| PWA | Service Worker + manifest |
|
|
| Data import | TecDoc via Apify, NHTSA VIN API |
|
|
|
|
---
|
|
|
|
## Base de Datos
|
|
|
|
| Metrica | Cantidad |
|
|
|---------|----------|
|
|
| Partes OEM | 1.5M+ |
|
|
| Partes aftermarket | 304K+ |
|
|
| Cross-references | 15.8M+ |
|
|
| Marcas TecDoc importadas | 6 (Toyota, Nissan, Renault, Ford, VW, Honda) |
|
|
| Rango de anos | 1956-2026 |
|
|
|
|
---
|
|
|
|
## Quick Start
|
|
|
|
### Requisitos
|
|
|
|
- Python 3.11+
|
|
- PostgreSQL 15+
|
|
- Linux (Debian/Ubuntu/Raspberry Pi OS)
|
|
|
|
### Web publica (catalogo)
|
|
|
|
```bash
|
|
cd /home/Autopartes/dashboard
|
|
pip install -r ../requirements.txt
|
|
python3 server.py
|
|
# Acceder: http://localhost:5000
|
|
```
|
|
|
|
### POS
|
|
|
|
```bash
|
|
cd /home/Autopartes/pos
|
|
pip install -r requirements.txt
|
|
|
|
# Crear primer tenant
|
|
python3 -c "
|
|
from services.tenant_manager import provision_tenant
|
|
result = provision_tenant('Mi Refaccionaria', rfc='RFC000000AAA', owner_name='Admin', owner_pin='1234')
|
|
print(result)
|
|
"
|
|
|
|
# Iniciar
|
|
python3 app.py
|
|
# Acceder: http://localhost:5001/pos/login
|
|
# PIN: 1234
|
|
```
|
|
|
|
### Importar datos TecDoc
|
|
|
|
```bash
|
|
# Descargar datos de TecDoc a JSON
|
|
python3 scripts/import_tecdoc.py download
|
|
|
|
# Importar JSON a PostgreSQL
|
|
python3 scripts/import_tecdoc.py import
|
|
|
|
# Ver progreso
|
|
python3 scripts/import_tecdoc.py status
|
|
```
|
|
|
|
---
|
|
|
|
## Estructura del Proyecto
|
|
|
|
```
|
|
/home/Autopartes/
|
|
dashboard/ # Web publica (puerto 5000)
|
|
server.py # Flask server principal
|
|
shared.css # CSS compartido
|
|
nav.js # Navegacion compartida
|
|
*.html # Paginas del dashboard
|
|
pos/ # POS multi-tenant (puerto 5001)
|
|
app.py # Flask app factory
|
|
config.py # Configuracion
|
|
tenant_db.py # Conexiones por tenant
|
|
middleware.py # Auth + permisos
|
|
blueprints/ # 9 blueprints (auth, config, inventory, y_ealog, pos, customers, cashregister, invoicing, accounting)
|
|
services/ # Logica de negocio (pos_engine, inventory_engine, cfdi_builder, accounting_engine, etc.)
|
|
templates/ # 10 HTML templates
|
|
static/ # CSS, JS, assets
|
|
migrations/ # SQL migrations
|
|
seed/ # Datos semilla
|
|
scripts/ # Import TecDoc, migraciones, utilidades
|
|
vehicle_database/ # Schema SQL maestro
|
|
docs/ # Documentacion
|
|
data/ # Datos TecDoc descargados (JSON)
|
|
```
|
|
|
|
---
|
|
|
|
## Deployment
|
|
|
|
El sistema puede correr en:
|
|
|
|
- **Servidor dedicado** o **VPS** (recomendado para produccion)
|
|
- **Raspberry Pi 5** (8GB RAM + SSD NVMe, ideal para refaccionaria individual)
|
|
|
|
Ver [docs/INSTALACION.md](docs/INSTALACION.md) para instrucciones detalladas.
|
|
|
|
---
|
|
|
|
## Documentacion
|
|
|
|
| Documento | Descripcion |
|
|
|-----------|-------------|
|
|
| [docs/GUIA-DE-USO.md](docs/GUIA-DE-USO.md) | Guia de uso del POS (espanol) |
|
|
| [docs/INSTALACION.md](docs/INSTALACION.md) | Guia de instalacion (espanol) |
|
|
| [docs/API-POS.md](docs/API-POS.md) | Referencia completa de la API del POS |
|
|
| [docs/API.md](docs/API.md) | API del catalogo publico |
|
|
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Arquitectura del sistema |
|
|
| [docs/DATABASE.md](docs/DATABASE.md) | Esquema de base de datos |
|
|
|
|
---
|
|
|
|
**Nexus Autoparts** -- Tu conexion directa con las partes que necesitas
|
|
|
|
nexus-1@raspberrypi:/home/Autopartes $ sudo mkdir -p /var/log/nexus-pos
|
|
nexus-1@raspberrypi:/home/Autopartes $ sudo systemctl restart nexus-pos
|
|
nexus-1@raspberrypi:/home/Autopartes $ sudo systemctl status nexus-pos
|
|
● nexus-pos.service - Nexus Autoparts POS
|
|
Loaded: loaded (/etc/systemd/system/nexus-pos.service; enabled; preset: enabled)
|
|
Active: activating (auto-restart) (Result: exit-code) since Sat 2026-04-18 02:01:06 EDT; 2s ago
|
|
Invocation: 53ad2c78e4da4d35abfdff6f6b664394
|
|
Process: 16135 ExecStart=/usr/local/bin/gunicorn -w 2 -b 0.0.0.0:5001 --timeout 120 app:app (code=exited, stat>
|
|
Main PID: 16135 (code=exited, status=4)
|
|
CPU: 1.740s
|
|
|
|
nexus-1@raspberrypi:/home/Autopartes $ sudo journalctl -u nexus-pos -f
|
|
abr 18 02:01:06 raspberrypi systemd[1]: nexus-pos.service: Main process exited, code=exited, status=4/NOPERMISSION
|
|
abr 18 02:01:06 raspberrypi systemd[1]: nexus-pos.service: Failed with result 'exit-code'.
|
|
abr 18 02:01:06 raspberrypi systemd[1]: nexus-pos.service: Consumed 1.740s CPU time.
|
|
abr 18 02:01:11 raspberrypi systemd[1]: nexus-pos.service: Scheduled restart job, restart counter is at 1.
|
|
abr 18 02:01:11 raspberrypi systemd[1]: Started nexus-pos.service - Nexus Autoparts POS.
|
|
abr 18 02:01:12 raspberrypi gunicorn[16146]: Failed to find attribute 'app' in 'app'.
|
|
abr 18 02:01:12 raspberrypi gunicorn[16147]: Failed to find attribute 'app' in 'app'.
|
|
abr 18 02:01:13 raspberrypi systemd[1]: nexus-pos.service: Main process exited, code=exited, status=4/NOPERMISSION
|
|
abr 18 02:01:13 raspberrypi systemd[1]: nexus-pos.service: Failed with result 'exit-code'.
|
|
abr 18 02:01:13 raspberrypi systemd[1]: nexus-pos.service: Consumed 1.524s CPU time.
|
|
abr 18 02:01:18 raspberrypi systemd[1]: nexus-pos.service: Scheduled restart job, restart counter is at 2.
|
|
abr 18 02:01:18 raspberrypi systemd[1]: Started nexus-pos.service - Nexus Autoparts POS.
|
|
abr 18 02:01:19 raspberrypi gunicorn[16156]: Failed to find attribute 'app' in 'app'.
|
|
abr 18 02:01:19 raspberrypi gunicorn[16157]: Failed to find attribute 'app' in 'app'.
|
|
abr 18 02:01:19 raspberrypi systemd[1]: nexus-pos.service: Main process exited, code=exited, status=4/NOPERMISSION
|