# TVDE — Mapa de Módulos

> Ficheiro vivo. Atualizar sempre que se criar/renomear um ficheiro ou função
> pública neste repo. Objetivo: qualquer pessoa (ou eu, Claude, numa conversa
> nova) percebe em 2 minutos o que existe e como está ligado.

## Ficheiros (site multi-documento, sem framework)

| Ficheiro | Papel | Liga para |
|---|---|---|
| `tvde-dashboard.html` | App principal — dashboard, motoristas, viaturas, manutenção, relatórios, alertas, documentos, parâmetros, config, login | `importartvde.html` (nav "Importar dados") |
| `importartvde.html` | Importador de dados externos (Bolt, Uber, Inosat, Prio, Via Verde) | `tvde-dashboard.html` (botão "Voltar ao dashboard") |

Preview local (VPS, porta 8081): `http://37.27.249.100:8081/tvde-dashboard.html`

## Dependências partilhadas
- Supabase JS (`@supabase/supabase-js@2`) via CDN, em ambos os ficheiros
- `xlsx@0.18.5` (SheetJS) — só em `importartvde.html`, para ler Prio e Via Verde
- Chart.js — só em `tvde-dashboard.html`, para o gráfico de faturação
- Credenciais Supabase (URL + anon key) hardcoded no `<script>` de cada ficheiro —
  **duplicadas nos dois ficheiros**, atualizar nos dois se mudarem

## Tabelas da BD usadas por cada módulo

**tvde-dashboard.html** usa: `motoristas`, `viaturas`, `atribuicoes`,
`planos_remuneracao`, `turnos_diarios`, `custos_viaturas`, `leituras_km`,
`reparacoes`, `documentos`, `parametros`, `alertas`, + views
`v_resumo_mensal_motorista`, `v_custo_viatura_mensal`, `v_score_motorista`,
`v_contrato_mensal`, `v_comissao_semanal`

**importartvde.html** usa: `motoristas`, `viaturas`, `atribuicoes`,
`turnos_diarios` (upsert)

## Funções-chave por ficheiro

### tvde-dashboard.html
- `navigate(page)` — router de páginas (SPA sem framework, troca `.active` em `.page`)
- `toggleMobileMenu(force)` — abre/fecha o drawer no mobile
- `carregarDashboard/Motoristas/Viaturas/Reparacoes/Documentos/Parametros/Relatorio` —
  um `carregarX` por página, chamado a partir de `navigate()`
- `guardarMotorista/Viatura/LeituraKm/Reparacao/Documento` — CRUD via modais
- `gerarAlertas/criarAlerta/resolverAlerta` — motor de alertas

### importartvde.html
- `processarFicheiros(files, tipo)` — dispatcher central; `tipo` ∈
  `bolt | uber | inosat | prio | viaverde`
- Por fonte: `ler<Fonte>()` (parse) → `mostrarPreview<Fonte>()` (preview) →
  `importar<Fonte>()` (grava em `turnos_diarios`)
- `matchMotorista(nome)` / `matchViatura(matricula)` — matching fuzzy partilhado
  por todas as fontes
- `registarHistorico()` / `carregarHistorico()` — histórico de importações
  (⚠️ hoje guardado em `localStorage`, não em BD — não sincroniza entre
  dispositivos/browsers, considerar migrar para uma tabela `import_historico`)

## Regras de negócio ativas (não mexer sem confirmar com o Bruno)
- Escalões Contrato: 50/55/60% sobre excedente aos 749,99€/1.499,99€ (objetivo 3.100€/mês)
- Escalões Comissão (semanal): 50/55/60% sobre 749,99€/999,99€ de valor líquido
- Portagens: Via Verde é a fonte oficial (substitui); Bolt/Uber são só referência
- Kms permitidos = faturação × 2,3

## Pendências conhecidas (ver também decisoes-e-pontos-situacao.md no VPS)
- Atribuições usam viatura placeholder (`00-00-00`) — falta reatribuir viaturas reais
- Aluguer: todos assumidos em "Aluguer 1500km" — confirmar se algum é 2000km
- Histórico de importações em `localStorage` (não partilhado/persistente)
- `motoristas.nif/telefone/email` todos nulos — dados de contacto por preencher