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
• 100+ endpoints API organizados en 15+ 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, graficos en tiempo real
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 + install prompt
Data import	TecDoc via Apify, NHTSA VIN API
Monitoreo	Prometheus + Grafana (Docker)
Tests E2E	Playwright
BNPL	APLAZO / Kueski / Clip (stub)
ERP Sync	Aspel / CONTPAQi / SAP / Odoo (stub)
WhatsApp	Baileys webhook + Meta Cloud API (stub)

---

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

---

Infraestructura Desplegada

Servicio	Puerto	Estado
POS (Gunicorn)	5001	Production
Dashboard (Flask)	5000	Production
Quart Async Catalog	5002	Production
Prometheus	9090	Docker
Grafana	3001	Docker
Meilisearch	7700	Docker
Metabase	3000	Docker

Quick Start

Requisitos

• Python 3.11+
• PostgreSQL 15+
• Linux (Debian/Ubuntu/Raspberry Pi OS)

Web publica (catalogo)

cd /home/Autopartes/dashboard
pip install -r ../requirements.txt
python3 server.py
# Acceder: http://localhost:5000

POS

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

# 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 para instrucciones detalladas.

---

Documentacion

Documento	Descripcion
docs/GUIA-DE-USO.md	Guia de uso del POS (espanol)
docs/INSTALACION.md	Guia de instalacion (espanol)
docs/API-POS.md	Referencia completa de la API del POS
docs/API.md	API del catalogo publico
docs/ARCHITECTURE.md	Arquitectura del sistema
docs/DATABASE.md	Esquema de base de datos

---

Nexus Autoparts -- Tu conexion directa con las partes que necesitas