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:
198
docs/plans/2026-02-14-pick-console-design.md
Normal file
198
docs/plans/2026-02-14-pick-console-design.md
Normal file
@@ -0,0 +1,198 @@
|
||||
# Pick-Style Console System - Design Document
|
||||
|
||||
**Date:** 2026-02-14
|
||||
**Status:** Approved
|
||||
|
||||
## Overview
|
||||
|
||||
Console-based autoparts catalog system inspired by Pick/D3 operating systems with VT220 terminal aesthetics. Runs entirely from keyboard in a real terminal (CLI), with two selectable rendering modes: classic VT220 (curses) and modern TUI (textual).
|
||||
|
||||
## Requirements
|
||||
|
||||
- **Platform:** Real CLI terminal (Python), no web browser
|
||||
- **Users:** Sales counter staff AND warehouse/admin personnel
|
||||
- **Style:** Pick-inspired with ANSI colors, box drawing, formatted tables
|
||||
- **Data:** Abstract DB layer (SQLite today, PostgreSQL migration planned)
|
||||
- **Renderers:** Two modes selectable via `--mode vt220|modern`
|
||||
- **Input:** 100% keyboard-driven with F-keys, menus, and incremental search
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ Capa de Presentación │
|
||||
│ ┌──────────┐ ┌───────────────┐ │
|
||||
│ │ curses │ │ textual │ │
|
||||
│ │ (VT220) │ │ (moderno) │ │
|
||||
│ └─────┬─────┘ └──────┬────────┘ │
|
||||
│ └────────┬────────┘ │
|
||||
│ Interface común │
|
||||
├─────────────────────────────────────┤
|
||||
│ Capa de Lógica / Screens │
|
||||
│ Menús, Navegación, Formularios, │
|
||||
│ Búsqueda, CRUD │
|
||||
├─────────────────────────────────────┤
|
||||
│ Capa de Datos (DB) │
|
||||
│ SQLite hoy → PostgreSQL mañana │
|
||||
└─────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
console/
|
||||
├── main.py # Entry point, --mode vt220|modern
|
||||
├── config.py # DB path, colors, key mappings
|
||||
├── db.py # Abstract DB layer (SQLite/PostgreSQL)
|
||||
│
|
||||
├── core/
|
||||
│ ├── screens.py # Screen base class
|
||||
│ ├── widgets.py # Lista, Formulario, Tabla, Barra
|
||||
│ ├── navigation.py # Screen stack, breadcrumb, history
|
||||
│ └── keybindings.py # F-keys, ESC, TAB mappings
|
||||
│
|
||||
├── screens/
|
||||
│ ├── menu_principal.py # Main menu (9 options + exit)
|
||||
│ ├── vehiculo_nav.py # Drill-down: brand → model → year → engine
|
||||
│ ├── buscar_parte.py # Search by part number
|
||||
│ ├── buscar_texto.py # Full-text search (FTS)
|
||||
│ ├── vin_decoder.py # VIN decoder (NHTSA API)
|
||||
│ ├── catalogo.py # Categories → groups → parts
|
||||
│ ├── parte_detalle.py # Part detail with alternatives
|
||||
│ ├── comparador.py # OEM vs aftermarket comparison
|
||||
│ ├── estadisticas.py # System statistics dashboard
|
||||
│ ├── admin_partes.py # Parts CRUD
|
||||
│ ├── admin_fabricantes.py # Manufacturers CRUD
|
||||
│ ├── admin_crossref.py # Cross-references CRUD
|
||||
│ └── admin_import.py # Import/Export CSV
|
||||
│
|
||||
├── renderers/
|
||||
│ ├── curses_renderer.py # VT220 mode (curses)
|
||||
│ └── textual_renderer.py # Modern mode (textual/rich)
|
||||
│
|
||||
└── utils/
|
||||
├── formatting.py # Table formatting, numbers, currency
|
||||
└── vin_api.py # NHTSA VIN API client
|
||||
```
|
||||
|
||||
## Screens
|
||||
|
||||
### Main Menu
|
||||
- 9 numbered options + 0 to exit
|
||||
- F-key bar at bottom
|
||||
- Header with system name and version
|
||||
|
||||
### 1. Vehicle Navigation (Drill-Down)
|
||||
- Sequential selection: Brand → Model → Year → Engine
|
||||
- Each step shows filterable list with incremental search
|
||||
- Arrow keys + ENTER to select, ESC to go back
|
||||
- Leads to categories/groups/parts for selected vehicle
|
||||
|
||||
### 2. Part Number Search
|
||||
- Single input field for part number
|
||||
- Searches OEM, aftermarket, and cross-references
|
||||
- Results show type, number, description, source
|
||||
- Select result to see full detail
|
||||
|
||||
### 3. Text Search (FTS)
|
||||
- Uses SQLite FTS5 full-text search
|
||||
- Searches part names and descriptions
|
||||
- Paginated results with relevance ranking
|
||||
|
||||
### 4. VIN Decoder
|
||||
- Input 17-character VIN
|
||||
- Calls NHTSA API (with cache)
|
||||
- Shows decoded vehicle info
|
||||
- Option to view compatible parts
|
||||
|
||||
### 5. Category Catalog
|
||||
- Browse: Categories → Groups → Parts
|
||||
- Independent of vehicle selection
|
||||
|
||||
### 6-9. Administration
|
||||
- CRUD screens with Pick-style positional forms
|
||||
- Numbered fields, TAB/arrow navigation
|
||||
- F1 for lookup lists on foreign key fields
|
||||
- F9 to save, ESC to cancel (with dirty check)
|
||||
- Import/Export CSV with file path input
|
||||
|
||||
### 10. Part Detail
|
||||
- Full part info in form layout (label.....: value)
|
||||
- Aftermarket alternatives table below
|
||||
- F4 for cross-references, F6 for vehicles
|
||||
|
||||
### 11. Part Comparator
|
||||
- Side-by-side columns: OEM vs aftermarket alternatives
|
||||
- Visual quality bars, savings percentage
|
||||
- Cross-reference numbers at bottom
|
||||
- Horizontal scroll if more than 3 columns
|
||||
|
||||
### 12. Statistics Dashboard
|
||||
- Database counters (brands, models, parts, etc.)
|
||||
- Coverage metrics (vehicles with parts, top brands)
|
||||
- VIN cache status
|
||||
|
||||
## Key Bindings
|
||||
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| 0-9 | Select menu option / jump to field |
|
||||
| ENTER | Confirm selection |
|
||||
| ESC | Go back / Cancel |
|
||||
| F1 | Help / Lookup list |
|
||||
| F2 | Edit mode |
|
||||
| F3 | Search |
|
||||
| F4 | Cross-references |
|
||||
| F5 | Refresh |
|
||||
| F6 | Related vehicles |
|
||||
| F9 | Save |
|
||||
| F10 | Main menu |
|
||||
| TAB / ↓ | Next field |
|
||||
| ↑ | Previous field |
|
||||
| PgUp/PgDn | Page navigation |
|
||||
| ←→ | Scroll columns (comparator) |
|
||||
|
||||
## Data Layer
|
||||
|
||||
Abstract interface with two implementations:
|
||||
|
||||
```python
|
||||
class Database:
|
||||
def get_brands() -> list
|
||||
def get_models(brand=None) -> list
|
||||
def get_vehicles(brand, model, year, engine) -> list
|
||||
def get_categories() -> list
|
||||
def get_groups(category_id) -> list
|
||||
def get_parts(group_id=None, mye_id=None) -> list
|
||||
def get_part(part_id) -> dict
|
||||
def get_alternatives(part_id) -> list
|
||||
def get_cross_references(part_id) -> list
|
||||
def search_parts(query) -> list
|
||||
def search_part_number(number) -> list
|
||||
def decode_vin(vin) -> dict
|
||||
def get_stats() -> dict
|
||||
# CRUD methods for admin...
|
||||
```
|
||||
|
||||
SQLite implementation reads directly from `vehicle_database.db`. PostgreSQL implementation will use psycopg2 with same interface.
|
||||
|
||||
## Renderer Interface
|
||||
|
||||
```python
|
||||
class Renderer:
|
||||
def init_screen()
|
||||
def clear()
|
||||
def draw_header(title, subtitle)
|
||||
def draw_footer(keys)
|
||||
def draw_menu(items, selected)
|
||||
def draw_table(headers, rows, page_info)
|
||||
def draw_form(fields, focused_field)
|
||||
def draw_detail(labels_values)
|
||||
def draw_comparison(columns)
|
||||
def draw_filter_list(items, filter_text, selected)
|
||||
def draw_stats(data)
|
||||
def get_key() -> key_event
|
||||
def show_message(text, type) # info/error/confirm
|
||||
```
|
||||
|
||||
Curses implementation uses box drawing chars, ANSI colors (green/amber on black). Textual implementation uses Rich widgets with modern styling.
|
||||
Reference in New Issue
Block a user