v11.0 · 151 Fases
API & Dados Fases 119 Implementado · ~6 min (1.122 palavras) SQLiteETLNHTSA
📄 docs/28-banco-global-veiculos-etl-cache-fase-119.md ↗

28 — Fase 119 — Construtor do Banco de Dados Global de Veículos (ETL Offline & Cache Inteligente)

A Fase 119 implementa o pipeline ETL offline (zenith_db_builder.py) que gera o banco unificado zenith_vehicle_db.sqlite ("Dicionário Físico e Eletrônico") para consumo 100% offline pela interface do carro, FastAPI backend, simulador e subsistemas ADAS / CAN / DSP / Gêmeo Digital 3D (Fase 118) sem depender de internet durante a condução.

Zenith AutoOS: 11.0.0 Fases: 151 Guias: 33 Idioma: PT-BR

Categoria: API & Dados Fases: 119 Status: Implementado SQLite: stack ETL: stack NHTSA: stack

🏠 README · 📚 Documentação · ⬅️ 27 · Branding · 29 · Segurança ADAS ➡️

📑 Neste guia — 5 seções · ~5 min de leitura

Catálogo de veículos no configurador
157.358+ veículos: ETL offline, cache anti-duplicação e consultas por marca/modelo/ano.


1. Arquitetura ETL & Prioridade das Fontes

Diagrama Mermaid
flowchart LR
    BAK["NHTSA vPIC .bak<br/>(MDF binário offset 8704)"] -->|"Prioridade 1: Custo Zero"| ETL["zenith_db_builder.py"]
    JSON118["zenith_vehicle_db.json<br/>(Perfis Flagship CarPC)"] --> ETL
    OPENDBC["Comma.ai OpenDBC (.dbc)<br/>+ OBDb (PIDs/UDS)"] -->|"GitHub Open Source"| ETL
    WHEEL["Wheel-Size / Auto-Data /<br/>Charm.li / Wikidata"] -->|"Cache Estrito"| ETL
    CAR2DB["Car2DB v3 API"] -->|"Rate-Limit Safe"| ETL
    STEADY["SteadyAPI /v1/vehicles/details<br/>(Teto rígido 500 req/mês)"] -->|"Só se faltar peso/potência/vel."| ETL
    ETL --> SQLITE["zenith_vehicle_db.sqlite<br/>(Single-file journal_mode=DELETE)"]
    SQLITE --> VDP["VehicleDatabaseParser<br/>(zenith_settings_manager.py)"]
    VDP --> HMI["Godot HMI / Backend /<br/>Simulador / ADAS / CAN / DSP"]

Prioridade 1 — Extração Local Zero-Custo (NHTSA .bak em Pure-Python)

  • NhtsaBakExtractor lê diretamente as páginas de 8192 bytes do arquivo MDF SQL Server embutido dentro do backup MTF (vPICList_lite_2026_11.bak, offset 8704), decodificando registros FixedVar (_decode_sql_record) e o null bitmap (_is_col_null) sem exigir instância local do Microsoft SQL Server.
  • No catálogo local extraído na build inicial:
    • 157.351 combinações únicas (Make, Model, Year) extraídas do NHTSA .bak (vehicles_total = 157.358 após fusão com os 9 perfis CarPC curados)
    • 32.444 pares de catálogo Make_Model (nhtsa_catalog_models) e 346 modelos de motor (nhtsa_engines)
    • 12.139 fabricantes distintos (distinct_makes) e 31.870 modelos distintos (distinct_models)
    • Campos ausentes em registros sem especificação publicada ficam em branco (NULL, "", [] ou {}), preservados sem invenção de valores fictícios para preenchimento incremental posterior.

Prioridade 2 — APIs Externas, Fontes Abertas & Proteção Anti-Duplicação

  • OpenDBC & OBDb: Sincronização de perfis CAN (.dbc, IDs hex BO_ e sinais SG_) e PIDs/UDS proprietários (Mode 22 / atuadores), preenchendo automaticamente 372 veículos com proprietary_pids_json.
  • Car2DB v3 (v3.api.car2db.com): Throttle conservador + consulta indexada por Marca/Modelo/Ano quando disponível no escopo da conta.
  • SteadyAPI (api.steadyapi.com/v1/vehicles/details):
    • Teto mensal absoluto de STEADYAPI_MONTHLY_LIMIT = 500 requisições/mês gravado na tabela api_quota_ledger (peso credits_cost = 3 por chamada).
    • Orçamento adicional por execução via --steady-budget sem alterar o limite mensal de 500 na tabela.
    • Só é consultado se faltarem especificação de peso (curb_weight_kg), potência (power_hp) ou velocidade máxima (speed_max_kmh) após as fontes gratuitas.
  • Fontes Abertas Adicionais: Wheel-Size, Auto-Data, Charm.li e Wikidata SPARQL. Domínios protegidos por desafio anti-bot/Cloudflare (ex.: Crutchfield / PaintRef) são detectados via _is_antibot_response() e imediatamente ignorados/registrados no cache sem qualquer tentativa de contorno.

2. Schema SQLite de 6 Domínios (zenith_vehicle_db.sqlite)

A tabela principal vehicles armazena os 6 domínios do "Dicionário Físico e Eletrônico" normalizados por chave (make_norm, model_norm, year):

Domínio Campos Principais na Tabela vehicles Consumidores AutoOS
1. Metadados & Chave Primária vehicle_key, make, model, year, make_norm, model_norm, generation, year_range, trim, body_style, wmi_codes_json Garage Configurator (Fase 118)
2. Rede & Telemetria primary_protocol, can_profile, can_baud_rate, kline_protocol, kline_baud, can_ids_json, proprietary_pids_json, active_test_actuators_json, ecu_rom_size_kb, ecu_rom_type, dbc_file ESP32 / SocketCAN / UDS (Fases 7, 71, 75, 79)
3. Física & Geometria wheelbase_mm, track_width_front_mm, track_width_rear_mm, curb_weight_kg, gvwr_kg, length_mm, width_mm, height_mm, tire_size_oem, rim_inches, tire_diameter_mm, tire_circumference_m, wheel_bolt_pattern ADAS Radar 3D, Pothole & Velocímetro (Fases 4, 14, 103, 104)
4. Powertrain & Energia engine_code, engine_displacement_l, engine_config, redline_rpm, rpm_max, speed_max_kmh, gear_ratios_json, final_drive_ratio, alternator_max_amps, oil_capacity_l, oil_viscosity_spec Smart Grid, Shift Light, Marcha & Tribologia (Fases 42–50, 85, 88)
5. Acústica & NVH cabin_volume_l, cabin_dimensions_cm_json, speaker_config_json, time_alignment_default_cm_json, nvh_idle_rpm, nvh_idle_freq_hz, nvh_harmonics_hz_json CamillaDSP Auto-EQ / Diagnóstico NVH (Fases 31–40, 108)
6. Design & Gêmeo Digital 3D model_3d_asset_path, glb_filename, default_paint_hex, oem_paint_codes_json Godot Showcase 3D & PBR Clearcoat (Fases 96, 114)

Tabelas auxiliares de governança e cache:

  • api_request_cache: índice único por (provider, request_key) e índice parcial único (provider, make_norm, model_norm, year) WHERE year > 0 AND make_norm != '' AND model_norm != ''.
  • api_quota_ledger: controle transacional mensal por (provider, period_ym).
  • nhtsa_catalog_models, nhtsa_engines, opendbc_profiles, obdb_signalsets, etl_runs.

3. Garantia Estrita Zero-Duplicação (Rate-Limit Safe)

  1. Antes de qualquer HTTP GET, ZenithApiEnricher.enrich_vehicle() verifica:
    • Se o veículo normalizado (make_norm, model_norm, year) já existe em vehicles (has_vehicle);
    • Se (provider, make_norm, model_norm, year) ou request_key já está registrado em api_request_cache.
  2. Normalização canônica (normalize_key_part) garante que variantes como "Lexus / ES 300 / 1998" e "lexus / ES300 / 1998" apontem para a mesma chave lexus + es300 + 1998.
  3. Toda resposta HTTP é gravada com COMMIT imediato em api_request_cache, api_quota_ledger e vehicles logo após o retorno da requisição — evitando repetição mesmo se etapas posteriores falharem.
  4. Ao finalizar o pipeline, VehicleSQLiteStore.finalize_offline_image() executa checkpoint WAL e alterna para PRAGMA journal_mode=DELETE, gerando um arquivo único portátil (~85.7 MB no build inicial) próprio para RootFS SquashFS read-only.

4. Integração Offline na Fase 118 & Endpoints API

O parser zenith_settings_manager.py (VehicleDatabaseParser) abre zenith_vehicle_db.sqlite em modo SQLite somente-leitura sem carregar os 157 mil registros em RAM no boot (preservando < 10 ms no startup e fallback automático para zenith_vehicle_db.json quando explicitado):

  • lookup(brand, model, year) e lookup_by_id(vehicle_id) devolvem os campos esperados pela Fase 118 e o dicionário completo não fabricado em specs_dictionary.
  • Novos endpoints paginados/indexados em backend/app/routers/settings.py e zenith_simulator_core.py:
    • GET /api/garage/brands, GET /api/garage/models?brand=..., GET /api/garage/years?brand=...&model=...
    • GET /api/garage/search?q=...&brand=...&model=...&year=...&enriched_only=...
    • GET /api/garage/specs/{vehicle_id}

5. Uso via CLI & Validação

bash
# 1. Pipeline completo: NHTSA .bak + Flagships + OpenDBC/OBDb + Enriquecimento com cache estrito
python zenith_db_builder.py --sync-opendbc --sync-obdb --enrich-flagships --steady-budget 5

# 2. Re-execução idempotente sem reconsultar NHTSA nem repetir HTTP GETs já cacheados (http_requests_made = 0)
python zenith_db_builder.py --skip-bak --enrich-flagships --steady-budget 5

# 3. Apenas estatísticas do banco offline
python zenith_db_builder.py --stats

# 4. Suíte automatizada FASE 119
python -m unittest -v tests.test_zenith_db_builder

⬅️ 27 · Branding · ⬆️ Topo · 📚 Índice · 29 · Segurança ADAS ➡️

Zenith AutoOS 11.0 · Documentação técnica · Novembro de 2026 · README principal