consultoria-as
fb6ea31100
- README.md: project overview, features, quick start, API overview - docs/API.md: full endpoint reference with examples - docs/ARCHITECTURE.md: system diagram, DB schema, data pipeline, auth flow Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
206 lines
7.5 KiB
Markdown
206 lines
7.5 KiB
Markdown
# Nexus Autoparts
|
|
|
|
**Sistema de catalogo de autopartes con navegacion jerarquica, similar a 7zap.com/RockAuto.**
|
|
|
|
Plataforma SaaS que conecta talleres con bodegas/distribuidores. Permite buscar partes OEM y aftermarket por vehiculo (marca, modelo, ano, motor), gestionar inventario de bodegas, y consultar disponibilidad y precios en tiempo real.
|
|
|
|
## Tech Stack
|
|
|
|
| Componente | Tecnologia |
|
|
|------------|-----------|
|
|
| Backend | Python 3, Flask |
|
|
| Base de datos | PostgreSQL |
|
|
| ORM / SQL | SQLAlchemy (`text()` raw SQL) |
|
|
| Autenticacion | JWT (PyJWT) + bcrypt |
|
|
| Data import | TecDoc via Apify, NHTSA VIN API |
|
|
| Frontend | HTML/CSS/JS vanilla (sin framework) |
|
|
| Dependencias extra | openpyxl (Excel), csv (CSV import) |
|
|
|
|
## Estadisticas de la Base de Datos
|
|
|
|
- **1.4M+** partes OEM
|
|
- **300K+** partes aftermarket
|
|
- **13M+** cross-references (numeros alternos, supersesiones, intercambios)
|
|
- **12B+** vehicle-part links (fitment)
|
|
- **100+** marcas, miles de modelos, anos 1956-2026
|
|
|
|
## Features
|
|
|
|
- **Catalogo de autopartes** con navegacion jerarquica: Marca > Modelo > Ano > Motor > Categoria > Grupo > Parte
|
|
- **TecDoc integration** (via Apify) para importar datos OEM y aftermarket de Europa/Mexico
|
|
- **SaaS multi-tenant** con roles: `ADMIN`, `OWNER`, `TALLER`, `BODEGA`
|
|
- **JWT authentication** con access tokens (15 min) y refresh tokens (30 dias)
|
|
- **Gestion de inventario** para bodegas con mapeo flexible de columnas CSV/Excel
|
|
- **Disponibilidad de partes** en multiples bodegas con precios comparativos
|
|
- **Alternativas aftermarket** con cross-references por cada parte OEM
|
|
- **Panel de administracion** con gestion de usuarios, import/export CSV, CRUD de categorias/grupos/partes/fabricantes/fitment
|
|
- **Busqueda full-text** en el catalogo de partes (PostgreSQL `tsvector`)
|
|
- **Busqueda combinada** vehiculo + parte (e.g., "Toyota Corolla 2020 frenos")
|
|
- **VIN decoder** via NHTSA API con cache en base de datos
|
|
- **Diagramas explosionados** con hotspots clickeables
|
|
- **Vehicle-to-part linking** (12B+ vehicle_parts links)
|
|
|
|
## Quick Start
|
|
|
|
### Requisitos previos
|
|
|
|
- Python 3.8+
|
|
- PostgreSQL con la base `nexus_autoparts`
|
|
|
|
### Instalacion
|
|
|
|
```bash
|
|
cd /home/Autopartes
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
### Ejecutar el servidor
|
|
|
|
```bash
|
|
cd /home/Autopartes/dashboard
|
|
python3 server.py
|
|
```
|
|
|
|
El servidor arranca en `http://localhost:5000`.
|
|
|
|
### Importar datos de TecDoc
|
|
|
|
```bash
|
|
# Fase 1: descargar datos de TecDoc a 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
|
|
```
|
|
|
|
### Importar partes y linkar vehiculos
|
|
|
|
```bash
|
|
# Importar partes TecDoc (OEM + aftermarket)
|
|
python3 scripts/import_tecdoc_parts.py
|
|
|
|
# Importar datos en vivo desde TecDoc API
|
|
python3 scripts/import_live.py
|
|
|
|
# Crear links vehiculo-parte (fitment masivo)
|
|
python3 scripts/link_vehicle_parts.py
|
|
|
|
# Migrar datos aftermarket
|
|
python3 scripts/migrate_aftermarket.py
|
|
|
|
# Aplicar schema SaaS (roles, users, inventory tables)
|
|
python3 scripts/migrate_saas_schema.py
|
|
```
|
|
|
|
## Paginas del Dashboard
|
|
|
|
| Ruta | Archivo | Descripcion |
|
|
|------|---------|-------------|
|
|
| `/login.html` | `login.html` | Login con JWT |
|
|
| `/demo.html` | `demo.html` | Catalogo publico / demo |
|
|
| `/admin` | `admin.html` | Panel de administracion (ADMIN/OWNER) |
|
|
| `/bodega.html` | `bodega.html` | Gestion de inventario para bodegas |
|
|
| `/tienda.html` | `tienda.html` | Vista de tienda/catalogo para talleres |
|
|
| `/pos.html` | `pos.html` | Punto de venta |
|
|
| `/captura.html` | `captura.html` | Captura de partes |
|
|
| `/cuentas.html` | `cuentas.html` | Gestion de cuentas |
|
|
|
|
## API Overview
|
|
|
|
Documentacion completa en [`docs/API.md`](docs/API.md).
|
|
|
|
### Auth (`/api/auth/`)
|
|
- `POST /api/auth/register` - Registrar usuario (TALLER/BODEGA)
|
|
- `POST /api/auth/login` - Login, retorna access + refresh tokens
|
|
- `POST /api/auth/refresh` - Renovar access token
|
|
- `GET /api/auth/me` - Info del usuario autenticado
|
|
|
|
### Catalogo (`/api/`)
|
|
- `GET /api/brands` - Listar marcas
|
|
- `GET /api/models?brand=X` - Modelos por marca
|
|
- `GET /api/years?brand=X&model=Y` - Anos disponibles
|
|
- `GET /api/engines?brand=X&model=Y&year=Z` - Motores disponibles
|
|
- `GET /api/categories` - Categorias de partes (arbol jerarquico)
|
|
- `GET /api/parts?group_id=X` - Partes por grupo
|
|
- `GET /api/parts/{id}/alternatives` - Alternativas aftermarket
|
|
- `GET /api/parts/{id}/cross-references` - Cross-references
|
|
- `GET /api/search?q=...` - Busqueda combinada (vehiculos + partes + aftermarket)
|
|
|
|
### Inventario (`/api/inventory/`)
|
|
- `GET/PUT /api/inventory/mapping` - Mapeo de columnas CSV
|
|
- `POST /api/inventory/upload` - Subir CSV/Excel de inventario
|
|
- `GET /api/inventory/items` - Listar inventario propio
|
|
- `DELETE /api/inventory/items` - Limpiar inventario
|
|
|
|
### Disponibilidad y Aftermarket
|
|
- `GET /api/parts/{id}/availability` - Bodegas con stock (auth: TALLER/ADMIN/OWNER)
|
|
- `GET /api/parts/{id}/aftermarket` - Alternativas aftermarket + cross-refs (publico)
|
|
|
|
### Admin (`/api/admin/`)
|
|
- `GET /api/admin/users` - Listar usuarios (auth: ADMIN/OWNER)
|
|
- `PUT /api/admin/users/{id}/activate` - Activar/desactivar usuario
|
|
- `GET /api/admin/stats` - Estadisticas del catalogo
|
|
- CRUD completo: categories, groups, parts, manufacturers, aftermarket, crossref, fitment
|
|
- Import/Export CSV: `POST /api/admin/import/{type}`, `GET /api/admin/export/{type}`
|
|
|
|
### VIN Decoder
|
|
- `GET /api/vin/decode/{vin}` - Decodificar VIN via NHTSA API
|
|
- `GET /api/vin/{vin}/parts` - Partes para un VIN decodificado
|
|
- `GET /api/vin/{vin}/match?mye_id=X` - Vincular VIN manualmente a vehiculo
|
|
|
|
## Scripts
|
|
|
|
| Script | Funcion |
|
|
|--------|---------|
|
|
| `import_tecdoc.py` | Descarga datos de TecDoc API (vehiculos, modelos, marcas) a JSON |
|
|
| `import_tecdoc_parts.py` | Importa partes OEM y aftermarket desde TecDoc |
|
|
| `import_live.py` | Importacion en vivo desde TecDoc API |
|
|
| `link_vehicle_parts.py` | Genera links vehiculo-parte (fitment masivo) |
|
|
| `migrate_aftermarket.py` | Migra datos aftermarket a la estructura normalizada |
|
|
| `migrate_saas_schema.py` | Crea tablas SaaS: sessions, warehouse_inventory, roles, etc. |
|
|
| `import_phase1.py` | Importacion inicial fase 1 |
|
|
| `run_all_brands.sh` | Script auxiliar para importar todas las marcas |
|
|
|
|
## Configuracion
|
|
|
|
Archivo principal: [`config.py`](config.py)
|
|
|
|
| Variable | Default | Descripcion |
|
|
|----------|---------|-------------|
|
|
| `DATABASE_URL` | `postgresql://nexus:...@localhost/nexus_autoparts` | PostgreSQL connection string |
|
|
| `JWT_SECRET` | `nexus-saas-secret-change-in-prod-2026` | Secreto para firmar tokens JWT |
|
|
| `JWT_ACCESS_EXPIRES` | `900` (15 min) | Duracion del access token en segundos |
|
|
| `JWT_REFRESH_EXPIRES` | `2592000` (30 dias) | Duracion del refresh token en segundos |
|
|
|
|
## Arquitectura
|
|
|
|
Documentacion detallada en [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).
|
|
|
|
```
|
|
+------------------+
|
|
| TecDoc (Apify) |
|
|
+--------+---------+
|
|
|
|
|
download/import
|
|
|
|
|
v
|
|
+----------+ +--------+---------+ +----------------+
|
|
| Frontend |<--->| Flask Server |<--->| PostgreSQL |
|
|
| (HTML/JS)| | (server.py) | | nexus_autoparts|
|
|
+----------+ +--------+---------+ +----------------+
|
|
|
|
|
JWT auth (PyJWT)
|
|
|
|
|
+------------+------------+
|
|
| | |
|
|
TALLER BODEGA ADMIN
|
|
(consulta) (inventario) (gestion)
|
|
```
|
|
|
|
---
|
|
|
|
**Nexus Autoparts** - Tu conexion directa con las partes que necesitas
|