docs: add console system documentation and design docs
Console README with usage instructions, keybindings reference, architecture overview, and test commands. Updated root README with console section, updated architecture diagram, and installation instructions. Includes approved design doc and implementation plan. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
189
console/README.md
Normal file
189
console/README.md
Normal file
@@ -0,0 +1,189 @@
|
||||
# AUTOPARTES Console - Sistema Pick/VT220
|
||||
|
||||
Interfaz de consola para el catálogo de autopartes, inspirada en los sistemas Pick/D3 con estética de terminal VT220. Funciona 100% con teclado.
|
||||
|
||||
## Requisitos
|
||||
|
||||
- Python 3.8+
|
||||
- SQLite 3 (incluido con Python)
|
||||
- Paquete `rich` (solo para modo moderno)
|
||||
|
||||
```bash
|
||||
pip install rich # Opcional, solo para --mode modern
|
||||
```
|
||||
|
||||
## Inicio Rápido
|
||||
|
||||
```bash
|
||||
# Modo VT220 (clásico, verde sobre negro)
|
||||
python -m console
|
||||
|
||||
# Modo moderno (Rich/TUI con colores)
|
||||
python -m console --mode modern
|
||||
|
||||
# Especificar base de datos
|
||||
python -m console --db /ruta/a/vehicle_database.db
|
||||
|
||||
# Ver versión
|
||||
python -m console --version
|
||||
```
|
||||
|
||||
## Modos de Visualización
|
||||
|
||||
### VT220 (por defecto)
|
||||
- Terminal clásica verde sobre negro
|
||||
- Caracteres de dibujo de cajas (box-drawing)
|
||||
- Compatible con cualquier terminal
|
||||
- Usa la librería `curses` (incluida en Python)
|
||||
|
||||
### Modern
|
||||
- Interfaz moderna con colores y estilos Rich
|
||||
- Tema azul/cian
|
||||
- Requiere `pip install rich`
|
||||
- Si `rich` no está instalado, cae automáticamente a modo VT220
|
||||
|
||||
## Menú Principal
|
||||
|
||||
```
|
||||
╔══════════════════════════════════════╗
|
||||
║ AUTOPARTES v1.0.0 ║
|
||||
║ Sistema de Catalogo de Autopartes ║
|
||||
╠══════════════════════════════════════╣
|
||||
║ 1. Buscar por Vehiculo ║
|
||||
║ 2. Buscar por Numero de Parte ║
|
||||
║ 3. Buscar por Texto ║
|
||||
║ 4. Decodificar VIN ║
|
||||
║ 5. Catalogo por Categoria ║
|
||||
║ ────────────────────────── ║
|
||||
║ 6. Admin: Partes ║
|
||||
║ 7. Admin: Fabricantes ║
|
||||
║ 8. Admin: Referencias Cruzadas ║
|
||||
║ 9. Import/Export ║
|
||||
║ ────────────────────────── ║
|
||||
║ S. Estadisticas del Sistema ║
|
||||
║ 0. Salir ║
|
||||
╚══════════════════════════════════════╝
|
||||
```
|
||||
|
||||
## Teclas de Función
|
||||
|
||||
| Tecla | Acción |
|
||||
|-------|--------|
|
||||
| `0-9` | Seleccionar opción del menú / saltar a campo |
|
||||
| `ENTER` | Confirmar selección |
|
||||
| `ESC` | Regresar / Cancelar |
|
||||
| `F1` | Ayuda / Lista de búsqueda |
|
||||
| `F2` | Modo edición |
|
||||
| `F3` | Buscar |
|
||||
| `F4` | Referencias cruzadas |
|
||||
| `F5` | Refrescar |
|
||||
| `F6` | Vehículos relacionados |
|
||||
| `F9` | Guardar |
|
||||
| `F10` | Menú principal |
|
||||
| `TAB` / `↓` | Siguiente campo |
|
||||
| `↑` | Campo anterior |
|
||||
| `PgUp/PgDn` | Navegación por páginas |
|
||||
| `←→` | Scroll horizontal (comparador) |
|
||||
|
||||
## Pantallas
|
||||
|
||||
### 1. Búsqueda por Vehículo
|
||||
Navegación jerárquica: Marca → Modelo → Año → Motor.
|
||||
Cada nivel muestra una lista filtrable con búsqueda incremental.
|
||||
|
||||
### 2. Búsqueda por Número de Parte
|
||||
Campo de entrada para número de parte. Busca en partes OEM, aftermarket y referencias cruzadas.
|
||||
|
||||
### 3. Búsqueda por Texto
|
||||
Búsqueda full-text (FTS5) en nombres y descripciones de partes con resultados paginados.
|
||||
|
||||
### 4. Decodificador VIN
|
||||
Ingresa un VIN de 17 caracteres. Consulta la API de NHTSA (con caché de 30 días) y muestra información del vehículo.
|
||||
|
||||
### 5. Catálogo por Categoría
|
||||
Navega: Categorías → Grupos → Partes, independiente de la selección de vehículo.
|
||||
|
||||
### 6-9. Administración
|
||||
- **Partes**: CRUD completo de partes OEM
|
||||
- **Fabricantes**: CRUD de fabricantes aftermarket
|
||||
- **Referencias Cruzadas**: CRUD de referencias cruzadas entre partes
|
||||
- **Import/Export**: Importar CSV, exportar JSON
|
||||
|
||||
### Detalle de Parte
|
||||
Vista completa de la parte con alternativas aftermarket. F4 para referencias cruzadas, F6 para vehículos compatibles.
|
||||
|
||||
### Comparador
|
||||
Columnas lado a lado: OEM vs alternativas aftermarket con barras de calidad, porcentaje de ahorro y scroll horizontal.
|
||||
|
||||
### Estadísticas
|
||||
Dashboard con contadores de la base de datos (marcas, modelos, partes, etc.) y métricas de cobertura.
|
||||
|
||||
## Arquitectura
|
||||
|
||||
```
|
||||
console/
|
||||
├── main.py # Punto de entrada, --mode vt220|modern
|
||||
├── config.py # Configuración (DB, colores, paginación)
|
||||
├── db.py # Capa de datos abstracta (SQLite)
|
||||
│
|
||||
├── core/
|
||||
│ ├── app.py # Controlador principal
|
||||
│ ├── screens.py # Clase base Screen
|
||||
│ ├── navigation.py # Pila de navegación y breadcrumbs
|
||||
│ └── keybindings.py # Constantes de teclas y registro
|
||||
│
|
||||
├── screens/
|
||||
│ ├── menu_principal.py # Menú principal (12 opciones)
|
||||
│ ├── vehiculo_nav.py # Drill-down: marca → modelo → año → motor
|
||||
│ ├── buscar_parte.py # Búsqueda por número de parte
|
||||
│ ├── buscar_texto.py # Búsqueda full-text (FTS)
|
||||
│ ├── vin_decoder.py # Decodificador VIN (API NHTSA)
|
||||
│ ├── catalogo.py # Categorías → grupos → partes
|
||||
│ ├── parte_detalle.py # Detalle con alternativas
|
||||
│ ├── comparador.py # Comparador OEM vs aftermarket
|
||||
│ ├── estadisticas.py # Dashboard de estadísticas
|
||||
│ ├── admin_partes.py # CRUD partes
|
||||
│ ├── admin_fabricantes.py # CRUD fabricantes
|
||||
│ ├── admin_crossref.py # CRUD referencias cruzadas
|
||||
│ └── admin_import.py # Import/Export CSV/JSON
|
||||
│
|
||||
├── renderers/
|
||||
│ ├── base.py # Interfaz abstracta BaseRenderer
|
||||
│ ├── curses_renderer.py # Modo VT220 (curses)
|
||||
│ └── textual_renderer.py # Modo moderno (Rich)
|
||||
│
|
||||
├── utils/
|
||||
│ ├── formatting.py # Formato de tablas, moneda, números
|
||||
│ └── vin_api.py # Cliente API NHTSA
|
||||
│
|
||||
└── tests/
|
||||
├── test_db.py # 36 tests - capa de datos
|
||||
├── test_core.py # 31 tests - keybindings, navigation, screens
|
||||
├── test_utils.py # 30 tests - utilidades de formato
|
||||
└── test_integration.py # 19 tests - integración con MockRenderer
|
||||
```
|
||||
|
||||
## Tests
|
||||
|
||||
```bash
|
||||
# Ejecutar todos los tests (116 total)
|
||||
python -m pytest console/tests/ -v
|
||||
|
||||
# Ejecutar por módulo
|
||||
python -m pytest console/tests/test_db.py -v
|
||||
python -m pytest console/tests/test_core.py -v
|
||||
python -m pytest console/tests/test_utils.py -v
|
||||
python -m pytest console/tests/test_integration.py -v
|
||||
```
|
||||
|
||||
## Capa de Datos
|
||||
|
||||
La clase `Database` en `db.py` abstrae todas las consultas SQL. Diseñada para migrar de SQLite a PostgreSQL cambiando solo la implementación interna.
|
||||
|
||||
Métodos principales:
|
||||
- `get_brands()`, `get_models()`, `get_years()`, `get_engines()`
|
||||
- `get_categories()`, `get_groups()`, `get_parts()`
|
||||
- `get_part()`, `get_alternatives()`, `get_cross_references()`
|
||||
- `search_parts()`, `search_part_number()`
|
||||
- `decode_vin()`, `get_stats()`
|
||||
- Métodos CRUD para administración
|
||||
Reference in New Issue
Block a user