# 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