alro65
dc3ec90109
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>
257 lines
9.7 KiB
Markdown
257 lines
9.7 KiB
Markdown
# 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*
|