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.
🏠 README · 📚 Documentação · ⬅️ 27 · Branding · 29 · Segurança ADAS ➡️
📑 Neste guia — 5 seções · ~5 min de leitura
157.358+ veículos: ETL offline, cache anti-duplicação e consultas por marca/modelo/ano.
1. Arquitetura ETL & Prioridade das Fontes
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)
NhtsaBakExtractorlê diretamente as páginas de8192bytes do arquivo MDF SQL Server embutido dentro do backup MTF (vPICList_lite_2026_11.bak, offset8704), 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.358apó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.
- 157.351 combinações únicas
Prioridade 2 — APIs Externas, Fontes Abertas & Proteção Anti-Duplicação
- OpenDBC & OBDb: Sincronização de perfis CAN (
.dbc, IDs hexBO_e sinaisSG_) e PIDs/UDS proprietários (Mode 22/ atuadores), preenchendo automaticamente 372 veículos comproprietary_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 = 500requisições/mês gravado na tabelaapi_quota_ledger(pesocredits_cost = 3por chamada). - Orçamento adicional por execução via
--steady-budgetsem alterar o limite mensal de500na 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.
- Teto mensal absoluto de
- Fontes Abertas Adicionais:
Wheel-Size,Auto-Data,Charm.lieWikidata 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)
- Antes de qualquer HTTP GET,
ZenithApiEnricher.enrich_vehicle()verifica:- Se o veículo normalizado
(make_norm, model_norm, year)já existe emvehicles(has_vehicle); - Se
(provider, make_norm, model_norm, year)ourequest_keyjá está registrado emapi_request_cache.
- Se o veículo normalizado
- Normalização canônica (
normalize_key_part) garante que variantes como"Lexus / ES 300 / 1998"e"lexus / ES300 / 1998"apontem para a mesma chavelexus+es300+1998. - Toda resposta HTTP é gravada com
COMMITimediato emapi_request_cache,api_quota_ledgerevehicleslogo após o retorno da requisição — evitando repetição mesmo se etapas posteriores falharem. - Ao finalizar o pipeline,
VehicleSQLiteStore.finalize_offline_image()executa checkpoint WAL e alterna paraPRAGMA journal_mode=DELETE, gerando um arquivo único portátil (~85.7 MBno 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)elookup_by_id(vehicle_id)devolvem os campos esperados pela Fase 118 e o dicionário completo não fabricado emspecs_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
# 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