AR-VINchecker/AR-VinReport_ClaudeCode_Prompt.md

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