Registro de Decisões de Arquitetura — Zenith AutoOS
Este documento registra decisões tomadas durante a implementação autônoma das Fases 120-151.
🏠 README · 📚 Documentação · ⬅️ 39 · Eventos · 41 · GDExtension CAN ➡️
📑 Neste guia — 12 seções · ~4 min de leitura
- 🗺️ Visão geral em diagrama
- Decisão 001 — Barramento de eventos (Fase 120)
- Decisão 002 — Armazenamento de dados (Fase 120)
- Decisão 003 — Feature flags e configurações (Fase 120)
- Decisão 004 — Traduções (Fase 120)
- Decisão 005 — Segredos (Fase 120)
- Decisão 006 — Modo bancada (Todas as fases)
- Decisão 007 — Isolamento de falhas (Todas as fases)
- Decisão 008 — Prioridades de alerta (Todas as fases)
- Decisão 009 — Telas bloqueadas em movimento (Todas as fases)
- Decisão 010 — Buffer circular de sensores (Fase 120)
- Decisão 011 — Bloqueio de telas em movimento configurável (Todas as fases)
🗺️ Visão geral em diagrama
flowchart TB
ADR["ADRs 001–011"] --> CORE["Core<br/>EventBus · Settings · DB"]
ADR --> SAFETY["Segurança<br/>segredos · prioridades"]
ADR --> OPS["Operação<br/>simulate_mode · supervisor"]
ADR --> UX["UX<br/>telas bloqueadas em movimento"]
CORE --> PHASES["Fases 120–151"]
SAFETY --> PHASES
OPS --> PHASES
UX --> PHASES
style ADR fill:#64748B,color:#fff,stroke:#CBD5E1
style PHASES fill:#0A5C36,color:#fff,stroke:#C8A951
style SAFETY fill:#B45309,color:#fff,stroke:#FCD34DComo ler: o diagrama resume o fluxo principal deste guia; os detalhes, pinagens, endpoints e trechos de código aparecem nas seções abaixo.
Decisão 001 — Barramento de eventos (Fase 120)
Data: Início da implementação autônoma
Decisão: Usar um EventBus singleton em GDScript com sinais Godot, em vez de um barramento externo complexo.
Justificativa: Simplicidade, integração nativa com Godot 4, fácil mock em testes, isolamento de módulos.
Alternativa considerada: Message broker externo (MQTT interno). Rejeitado por adicionar dependência desnecessária para comunicação intra-processo.
Decisão 002 — Armazenamento de dados (Fase 120)
Data: Início da implementação autônoma
Decisão: SQLite com migrações versionadas na partição de dados gravável (user://data/).
Justificativa: Atende ao requisito de não gravar no sistema de arquivos raiz somente leitura. SQLite é leve, confiável e suportado por Godot via plugin ou GDNative.
Alternativa considerada: JSON simples. Rejeitado por não suportar consultas eficientes e migrações versionadas.
Decisão 003 — Feature flags e configurações (Fase 120)
Data: Início da implementação autônoma
Decisão: SettingsManager como Resource persistido em user://config/settings.tres, com feature flags booleanas por módulo.
Justificativa: Persistência nativa do Godot, fácil edição no Inspector, valores padrão seguros.
Alternativa considerada: Arquivo JSON customizado. Rejeitado por exigir serialização manual.
Decisão 004 — Traduções (Fase 120)
Data: Início da implementação autônoma
Decisão: Chaves de tradução em arquivos CSV por idioma (locales/pt-BR.csv, locales/en-US.csv, locales/es.csv).
Justificativa: Simples, editável, compatível com Godot Translation.
Alternativa considerada: Gettext/.po. Rejeitado por complexidade excessiva para este escopo.
Decisão 005 — Segredos (Fase 120)
Data: Início da implementação autônoma
Decisão: Nenhum segredo no código. Usar .env para variáveis de ambiente e .env.example documentado.
Justificativa: Atende ao requisito global de não commitar tokens/senhas.
Local: .env.example
Decisão 006 — Modo bancada (Todas as fases)
Data: Início da implementação autônoma
Decisão: Cada módulo tem simulate_mode booleano. Quando ativo, gera dados realistas sem hardware.
Justificativa: Permite desenvolvimento e testes sem depender de hardware físico.
Controle: Painel DevTools dispara cenários de simulação.
Decisão 007 — Isolamento de falhas (Todas as fases)
Data: Início da implementação autônoma
Decisão: Cada módulo encapsulado em try/catch com reinício automático via retries e timeout.
Justificativa: Um módulo que falha não derruba outro.
Mecanismo: ModuleSupervisor supervisiona módulos críticos.
Decisão 008 — Prioridades de alerta (Todas as fases)
Data: Início da implementação autônoma
Decisão: Três níveis: crítico (sempre exibe), segurança (sempre exibe), informativo (não exibe acima de 20 km/h).
Justificativa: Segurança do motorista em primeiro lugar.
Fonte: Regras globais fornecidas pelo usuário.
Decisão 009 — Telas bloqueadas em movimento (Todas as fases)
Data: Início da implementação autônoma
Decisão: Jogos, filmes, karaokê e espelhamento bloqueados na Central/Cluster acima de 20 km/h; permitidos nas telas traseiras.
Justificativa: Segurança viária.
Implementação: DisplayManager verifica velocidade antes de permitir conteúdo distrator.
Decisão 010 — Buffer circular de sensores (Fase 120)
Data: Início da implementação autônoma
Decisão: Buffer circular fixo de 60 segundos em RAM, chaveado por timestamp.
Justificativa: Baixo uso de RAM, acesso O(1), suporte à caixa-preta e clipes de vídeo.
Alternativa considerada: Gravar tudo em disco. Rejeitado por desgaste de flash e complexidade.
Decisão 011 — Bloqueio de telas em movimento configurável (Todas as fases)
Data: Implementação das Fases 120-151
Decisão: O bloqueio de conteúdo distrator (jogos, filmes, karaokê) na Central/Cluster acima de 20 km/h é controlado por feature flag display.lock_screens_above_speed (padrão: true). Pode ser desabilitado pelo usuário nas Configurações.
Justificativa: Segurança viária em primeiro lugar (valor padrão ativo), mas permite flexibilidade para uso em bancada, oficinas ou cenários específicos onde o bloqueio não é desejado.
Implementação: Verificada no RetroGamesRear._on_speed_changed() via SettingsManager.is_screen_lock_above_speed_enabled() e SettingsManager.get_screen_lock_speed_threshold().
⬅️ 39 · Eventos · ⬆️ Topo · 📚 Índice · 41 · GDExtension CAN ➡️
Zenith AutoOS 11.0 · Documentação técnica · Novembro de 2026 · README principal