feat: AR-VINchecker v1.0 — VIN report generator with AI analysis

FastAPI server querying NHTSA/EPA APIs, generating PDF reports with risk scoring, and local Ollama AI analysis via DealAnalyzer. Security hardened: XSS fix, SSRF protection, CORS restricted. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-07-03 11:40:35 -04:00
commit dc3ec90109
18 changed files with 1970 additions and 0 deletions
@@ -0,0 +1,256 @@
+# Claude Code Prompt — AR-VINChecker
+## App de Reporte de Historial Vehicular por VIN (100% gratis, sin APIs de pago)
+
+---
+
+## CONTEXTO DEL PROYECTO
+
+Desarrollar una aplicación de escritorio Python/PySide6 llamada **AR-VinReport** que genere reportes PDF profesionales de historial vehicular usando exclusivamente APIs públicas y gratuitas del gobierno de EE.UU. La app es para uso personal/profesional en evaluación de vehículos en subastas (Copart, IAAI) antes de pujar.
+
+**Ruta del proyecto:** `D:\Proyectos Software\AR-VinChecker\`
+**Usuario:** Jairo — ingeniero naval en South Florida, evalúa vehículos en subastas para inversión.
+
+---
+
+## LO QUE HACE LA APP
+
+### Input (pantalla principal)
+El usuario ingresa manualmente los datos que ve en el listing de la subasta:
+- VIN (17 caracteres)
+- Odómetro (millas)
+- Daño primario (ej: "Normal Wear")
+- Daño secundario (ej: "Damage History")
+- Título (ej: "NY - Certificate of Title")
+- Precio de bid actual ($)
+- Nombre/URL de la subasta (opcional)
+- URL de foto del vehículo (opcional, para incluir en el PDF)
+
+### Procesamiento automático (al hacer click en "Generate Report")
+La app consulta en paralelo:
+
+1. **NHTSA VPIC API** — Decode del VIN:
+   - Make, Model, Year, Trim, Body Style
+   - Engine type, displacement, cylinders
+   - Drive type, transmission
+   - Plant country of manufacture
+   - URL: `https://vpic.nhtsa.dot.gov/api/vehicles/decodevin/{VIN}?format=json`
+
+2. **NHTSA Recalls API** — Recalls activos:
+   - Lista de recalls por make/model/year
+   - Descripción del componente afectado
+   - Si está abierto o cerrado
+   - URL: `https://api.nhtsa.gov/recalls/recallsByVehicle?make={make}&model={model}&modelYear={year}`
+
+3. **NHTSA Complaints API** — Quejas de propietarios:
+   - Total de quejas registradas
+   - Top 5 componentes con más quejas
+   - URL: `https://api.nhtsa.gov/complaints/complaintsByVehicle?make={make}&model={model}&modelYear={year}`
+
+4. **NHTSA Investigations API** — Investigaciones de seguridad abiertas:
+   - URL: `https://api.nhtsa.gov/investigations/investigationsByVehicle?make={make}&model={model}&modelYear={year}`
+
+5. **EPA FuelEconomy API** — Eficiencia y specs:
+   - MPG ciudad/highway, o kWh/100mi si es EléctricoF
+   - URL: `https://www.fueleconomy.gov/ws/rest/vehicle/menu/options?year={year}&make={make}&model={model}`
+
+6. **Foto del vehículo** — Si el usuario pegó una URL, descargarla e incluirla en el PDF.
+
+### Output — PDF Profesional
+Generar un PDF de 1-2 páginas con:
+
+**Header:**
+- Logo "AR-VinReport" (texto estilizado si no hay imagen)
+- Fecha y hora del reporte
+- VIN consultado
+
+**Sección 1 — Identificación del Vehículo**
+- Foto del vehículo (si se proporcionó URL)
+- Tabla: Year / Make / Model / Trim / Body
+- Tabla: Engine / Transmission / Drive / Plant
+
+**Sección 2 — Datos del Listing de Subasta**
+- Tabla: Odómetro / Daño Primario / Daño Secundario / Título / Bid
+
+**Sección 3 — Recalls NHTSA**
+- Total de recalls encontrados
+- Lista con: fecha, componente, descripción breve
+- Badge verde "0 RECALLS" o rojo "X RECALLS ACTIVOS"
+
+**Sección 4 — Quejas de Propietarios**
+- Total de quejas
+- Top 5 componentes problemáticos con conteo
+- Gráfico de barras horizontal simple (matplotlib)
+
+**Sección 5 — Investigaciones de Seguridad**
+- Lista de investigaciones abiertas si las hay
+
+**Sección 6 — Eficiencia EPA**
+- MPG o kWh/100mi
+- Estimado de costo anual de combustible/electricidad
+
+**Sección 7 — Análisis de Riesgo (generado por la app)**
+- Score de riesgo calculado: 0-100
+  - +20 puntos si título es Salvage
+  - +15 puntos por cada recall activo (max 30)
+  - +10 si daño secundario no es "None"
+  - +10 si quejas > 50
+  - -10 si odómetro < 60,000 millas
+  - -15 si título es Certificate of Title (limpio)
+- Badge: BAJO RIESGO (verde) / RIESGO MEDIO (amarillo) / ALTO RIESGO (rojo)
+
+**Footer:**
+- "Datos de NHTSA.gov y EPA.gov — Información pública oficial del gobierno de EE.UU."
+- "Este reporte no reemplaza un Carfax o inspección física"
+
+---
+
+## STACK TÉCNICO
+
+```
+Python 3.11+
+PySide6          — GUI de escritorio
+requests         — llamadas HTTP a las APIs
+reportlab        — generación de PDF profesional
+matplotlib       — gráfico de barras de quejas
+Pillow (PIL)     — manejo de imagen del vehículo
+```
+
+---
+
+## ESTRUCTURA DEL PROYECTO
+
+```
+D:\Proyectos Software\AR-VinReport\
+├── main.py                    ← Entry point, lanza la GUI
+├── requirements.txt
+├── src/
+│   ├── __init__.py
+│   ├── gui/
+│   │   ├── __init__.py
+│   │   ├── main_window.py     ← Ventana principal PySide6
+│   │   └── styles.py          ← QSS stylesheet oscuro profesional
+│   ├── api/
+│   │   ├── __init__.py
+│   │   ├── nhtsa.py           ← Todas las llamadas a NHTSA
+│   │   └── epa.py             ← Llamadas a EPA FuelEconomy
+│   ├── report/
+│   │   ├── __init__.py
+│   │   └── pdf_generator.py   ← Generación del PDF con reportlab
+│   └── utils/
+│       ├── __init__.py
+│       ├── vin_validator.py   ← Validación de VIN (17 chars, checksum)
+│       └── risk_score.py      ← Cálculo del score de riesgo
+├── assets/
+│   └── logo.png               ← Logo AR-VinReport (crear simple si no existe)
+├── output/                    ← PDFs generados se guardan aquí
+└── docs/
+    ├── LOGBOOK.md
+    ├── LIBRARIES.md
+    └── modules/
+        ├── gui_log.md
+        ├── api_log.md
+        └── report_log.md
+```
+
+---
+
+## GUI — DISEÑO DE LA VENTANA PRINCIPAL
+
+Estilo oscuro profesional, consistente con las otras apps AR Suite (AR-ShipDesign, AR-Autopilot, etc.).
+
+**Layout:**
+```
+┌─────────────────────────────────────────────────────┐
+│  AR-VinReport  v1.0        [dark theme]             │
+├──────────────────┬──────────────────────────────────┤
+│  INPUT PANEL     │  STATUS / PREVIEW                │
+│                  │                                  │
+│  VIN: [_______]  │  ┌──────────────────────────┐   │
+│  Odometer: [___] │  │ Waiting for VIN...        │   │
+│  Primary dmg:[_] │  │                           │   │
+│  Secondary: [__] │  │ [Progress steps show      │   │
+│  Title: [______] │  │  here during fetch]       │   │
+│  Bid ($): [____] │  │                           │   │
+│  Auction: [____] │  └──────────────────────────┘   │
+│  Photo URL:[___] │                                  │
+│                  │  [GENERATE PDF REPORT]  ← botón  │
+│  [FETCH DATA]    │  [OPEN OUTPUT FOLDER]            │
+└──────────────────┴──────────────────────────────────┘
+```
+
+Al hacer click en FETCH DATA:
+- Mostrar progress en el panel derecho paso a paso:
+  - ✅ VIN válido: 1FTVW1EL1NWG14881
+  - ⏳ Consultando NHTSA VPIC...
+  - ✅ Vehículo: 2022 Ford F-150 Lightning Pro
+  - ⏳ Consultando recalls...
+  - ✅ 8 recalls encontrados
+  - ⏳ Consultando quejas...
+  - ✅ 95 quejas registradas
+  - ⏳ Consultando EPA...
+  - ✅ Eficiencia: 2.0 kWh/mi
+  - ✅ Foto descargada
+  - 🟡 Score de riesgo: 35/100 — RIESGO MEDIO
+  - ✅ Reporte generado: output/VIN_20260703_143022.pdf
+
+---
+
+## INSTRUCCIONES PARA CLAUDE CODE
+
+1. **Leer este prompt completo antes de escribir código.**
+
+2. **Crear toda la estructura de carpetas** del proyecto primero.
+
+3. **Empezar por el módulo API** (`src/api/nhtsa.py`) y probarlo con el VIN de prueba `1FTVW1EL1NWG14881` (2022 Ford F-150 Lightning Pro).
+
+4. **Verificar que las APIs respondan** antes de construir la GUI. Las APIs de NHTSA son HTTP GET simples sin autenticación.
+
+5. **Construir la GUI** una vez confirmado que los datos llegan correctamente.
+
+6. **Construir el PDF** con reportlab, no con weasyprint ni html2pdf — reportlab da más control sobre el layout.
+
+7. **Al final de la sesión**, crear y poblar los archivos de documentación:
+   - `docs/LOGBOOK.md` — siguiendo el formato del app-organizer skill
+   - `docs/LIBRARIES.md` — documentando cada librería usada
+   - `docs/modules/api_log.md`, `gui_log.md`, `report_log.md`
+
+8. **El PDF generado** debe guardarse en `output/` con nombre: `{VIN}_{YYYYMMDD}_{HHMMSS}.pdf`
+
+9. **Manejo de errores**: si una API no responde, mostrar "No data available" en esa sección del PDF — nunca crashear.
+
+10. **El validador de VIN** debe verificar:
+    - Exactamente 17 caracteres
+    - No contiene I, O, Q (caracteres prohibidos en VINs)
+    - Checksum digit válido (posición 9)
+
+---
+
+## VIN DE PRUEBA
+
+```
+VIN:            1FTVW1EL1NWG14881
+Odometer:       57,909 mi
+Primary damage: Normal Wear
+Secondary:      Damage History
+Title:          NY - Certificate of Title
+Bid:            $4,100
+Auction:        Copart
+```
+
+Usar este VIN para todas las pruebas durante el desarrollo.
+
+---
+
+## CRITERIO DE ÉXITO
+
+La sesión es exitosa cuando:
+- [ ] `python main.py` lanza la ventana sin errores
+- [ ] Al ingresar el VIN de prueba y hacer FETCH DATA, se obtienen datos reales de NHTSA
+- [ ] El botón GENERATE PDF crea un archivo PDF en `output/`
+- [ ] El PDF tiene: foto (si se dio URL), specs del vehículo, recalls, quejas, score de riesgo
+- [ ] El PDF se abre correctamente en cualquier visor
+- [ ] Documentación de logbook creada y poblada
+
+---
+
+*Prompt generado por Claude — AR Suite / Prisa Yachts LLC — Julio 2026*