204 lines
6.7 KiB
Markdown
204 lines
6.7 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
|
||
|
||
Procesando disparadores para man-db (2.13.1-1) ...
|
||
✓ System deps installed
|
||
→ Installing Python packages...
|
||
error: externally-managed-environment
|
||
|
||
× This environment is externally managed
|
||
╰─> To install Python packages system-wide, try apt install
|
||
python3-xyz, where xyz is the package you are trying to
|
||
install.
|
||
|
||
If you wish to install a non-Debian-packaged Python package,
|
||
create a virtual environment using python3 -m venv path/to/venv.
|
||
Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
|
||
sure you have python3-full installed.
|
||
|
||
For more information visit http://rptl.io/venv
|
||
|
||
note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
|
||
hint: See PEP 668 for the detailed specification.
|