# Agent Handoff — Análise de Desvalorização de Veículos Elétricos

> **Documento de Transição / Handoff do Projeto**  
> **Última Atualização:** 24/Jul/2026 00:05 (Lisboa)  
> **Versão do Modelo:** v4.3 (18 variantes + Engine Centralizado v4.2 + Sync Supabase + Matriz da Garagem com Destaque de Custo, Km e Garantia de Bateria 2028)  
> **Repositório GitHub (Vercel):** https://github.com/tetobot247/carros_vercel  
> **Branch principal:** `main`

---

## 📌 EM QUE PONTO ESTÁ O PROJETO (ESTADO ATUAL)

O projeto encontra-se **100% funcional, testado, limpo de erros e publicado em produção na Vercel**.

1. **Hub Principal (`index.html`)**:
   - Ponto de entrada central agregando as 11 ferramentas e dashboards de análise.
   - Gestão de ofertas na garagem (adicionar, editar, remover e sincronização nuvem com Supabase).
   - Barra de navegação flutuante `#appHubNav` e sincronização global.

2. **A Minha Garagem & Matriz Exclusiva (`pages/comparativo-garagem.html`)**:
   - Permite guardar ofertas reais com preço de compra, quilometragem, ano e link direto do anúncio (armazenamento local `localStorage` + sync cloud Supabase).
   - **Matriz da Garagem Reformulada**:
     - **Eixo Y (Linhas Verticais)**: Preço de Compra Anunciado (€21k a €35k em 15 linhas).
     - **Eixo X (Colunas Horizontais)**: Faixas de Custo Mensal Esperado (<€180/m, 180-200, ..., >€500/m em 13 colunas).
     - **Destaque do Custo Mensal (€/mês)**: Elemento visual principal em cada quadrado da matriz, apresentado em pill escura com tipografia de peso máximo (`font-weight: 900`) e contraste elevado a dourado (`#ffd60a`).
     - **Encodagem Visual de Quilometragem (Km)**: Odómetro codificado visualmente por pontos luminosos de rodagem (`🟢 <60k km`, `🟡 60k–100k km`, `🟠 >100k km`).
     - **Garantia da Bateria Restante em 2028**: Cada quadrado exibe a indicação de **meses** e **km** de margem de garantia de bateria restantes no momento da venda (Dez/2028) (ex: `⚡12m·35k` ou `⚡0m` se expirada em 2028).
     - **Layout Mobile Ultraminiaturizado**: Otimizado para smartphones (ex: Galaxy S25 Ultra ~412px) com **0% de scroll horizontal**.

3. **Mega Matriz de Todas as Ofertas (`pages/mega-matriz-todas-ofertas.html`)**:
   - Renderização síncrona instantânea (1ms) sem travamentos.
   - Filtros por pílulas de custo mensal (€/mês) operacionais com destaque para ofertas selecionadas e esbatimento (`.cell-dimmed`) das restantes.

4. **Motor Centralizado & Sincronização Nuvem (`js/engine.js`)**:
   - Exporta o objeto global `window.CarEngine` com todas as regras de cálculo, parâmetros globais (28 meses de posse, 21.000 km adicionados), escada de penalização de garantia de bateria e integração REST UPSERT com o Supabase.

---

## 🎯 OBJETIVO DO PROJETO

O utilizador (Porto, Portugal) pretende comprar um carro elétrico usado em **Agosto/2026** e vendê-lo em **Dezembro/2028** (28 meses de posse, 750 km/mês = 21.000 km adicionados). O projeto calcula a **desvalorização mensal (€/mês)** para cada combinação de modelo × ano de fabrico × quilometragem de compra × preço de compra, para determinar qual carro custa menos por mês de posse.

---

## 🚀 ARQUITETURA E DEPLOY NA VERCEL

### 📁 Estrutura de Pastas Organizada
- **`index.html`**: O **Hub Principal ("A Roda Central")**, de onde partem e para onde regressam todas as análises.
- **`pages/`**: Todas as 11 ferramentas e dashboards de análise quantitativa.
- **`js/engine.js`**: Motor de cálculo centralizado (`window.CarEngine`) e sistema de navegação automática (`initHubNavigation`).
- **`css/styles.css`**: Design system unificado (Glassmorphic dark mode, variáveis CSS, `.app-nav-bar` e `.garage-cell-badge`).
- **`img/cars/`**: Banco de imagens de design automóvel 3D (`tesla_model_3.png`, `hyundai_ioniq_5.png`, `renault_megane_etech.png`).
- **`data/`**: Dados JSON reutilizáveis (`garagem.json`, `valores-revenda.json`).
- **`docs/`**: Documentação técnica e handoff (`HANDOFF.md`, `regras-calculo.md`).
- **`server.py`**: Servidor HTTP Python local para ambiente de desenvolvimento local offline.

---

### ⚠️ REGRA CRÍTICA DE DEPLOY NA VERCEL (GIT AUTHOR)

> [!IMPORTANT]
> **Autenticação de Commits no Plano Hobby da Vercel:**
> A Vercel bloqueia o deploy se os commits do Git forem gravados com um email local genérico (ex: `luiz@mac.local`), apresentando o erro:
> *"The Deployment was blocked because GitHub could not associate the committer with a GitHub user. Hobby teams do not support collaboration."*
>
> **Configuração Obrigatória do Git:**
> Certifique-se sempre de que o Git está configurado com o utilizador e email associados à conta do GitHub:
> ```bash
> git config user.name "tetobot247"
> git config user.email "lhmissio@gmail.com"
> ```

---

## 🚗 MODELOS COBERTOS (18 VARIANTES)

### 5 Famílias / Plataformas (`brand`):

| Brand ID | Nome | Cor CSS | Anos | Nº Variantes |
|----------|------|---------|------|--------------|
| `tesla` | Tesla Model 3 SR/RWD (LFP) | `#ff3b30` (vermelho) | 2021-2024 | 4 |
| `tesla_lr` | Tesla Model 3 Long Range AWD (NMC) | `#ff9f0a` (laranja) | 2021-2024 | 4 |
| `ioniq5_58` | IONIQ 5 58 kWh (Standard Range) | `#5ac8fa` (azul claro) | 2021-2022 | 2 |
| `ioniq5` | IONIQ 5 Long Range (72.6–84 kWh) | `#32ade6` (azul) | 2021-2024 | 4 |
| `megane` | Megane E-Tech EV60 | `#af52de` (roxo) | 2021-2024 | 4 |

---

## 📐 MOTOR DE CÁLCULO CENTRALIZADO (`js/engine.js`)

### Parâmetros Globais

```javascript
var M = 28;           // Meses de posse (Ago/2026 -> Dez/2028)
var KPM = 750;        // Km por mês
var TKM = 21000;      // Km total adicionado (M × KPM)
var LFPR = 0.5;       // Redutor LFP (50%)
```

### Escada de Penalização de Garantia de Bateria (`WS[]`)

```javascript
var WS = [
    {m: 24, p: 0},        // ≥24 meses restantes → sem penalização
    {m: 18, p: 750},      // 18-23 meses
    {m: 12, p: 1500},     // 12-17 meses
    {m: 6,  p: 2000},     // 6-11 meses
    {m: 0,  p: 2500},     // 0-5 meses
    {m: -999, p: 3000}    // Expirada
];
```

### Cálculo de Garantia Efetiva no Momento da Venda (Dez/2028)

```javascript
function getEffectiveWarranty(c, buyKm) {
    var mTime = wMonths(c);
    var saleKm = buyKm * 1000 + TKM;
    var kmLeft = c.wk - saleKm;
    var mKm = Math.floor(kmLeft / 750);
    var effMonths = Math.min(mTime, mKm);
    return {
        mTime: mTime,
        saleKm: saleKm,
        kmLeft: kmLeft,
        effMonths: effMonths,
        limitingFactor: (mKm < mTime) ? 'Quilometragem' : 'Tempo'
    };
}
```

---

## ⚙️ HISTÓRICO DE VERSÕES

| Versão | Data | Alterações |
|--------|------|------------|
| **v1.0** | Jul/2026 | Modelo base: 3 modelos (Tesla M3, IONIQ 5 LR, Megane) |
| **v2.0** | 22/Jul/2026 | Penalização de garantia de bateria e redutor LFP (50%) |
| **v3.0** | 22/Jul/2026 | Expansão 2021-2024 (12 variantes) |
| **v4.0** | 22/Jul/2026 | Expansão para 18 variantes (Tesla LR + IONIQ 58k) |
| **v4.1** | 23/Jul/2026 | Motor centralizado `engine.js` + Design System `styles.css` + Hub `index.html` |
| **v4.2** | 23/Jul/2026 | Sincronização nuvem Supabase + Suporte a múltiplos anúncios por modelo |
| **v4.3** | 24/Jul/2026 | **Matriz de Garagem Refinada:** Destaque de Custo Mensal, Encodagem visual de Km (`🟢🟡🟠`) e Garantia Restante em 2028 (`⚡12m·35k`) |

---

## 🔴 DÍVIDA TÉCNICA & RECOMENDAÇÕES PARA O PROJETO

### Prioridade Alta
1. **Atualizar `regras-calculo.md`**: Incluir a escada de penalização `WS[]` e parâmetros por modelo para manter a documentação teórica 100% síncrona com `engine.js`.
2. **Timeout no Sync Supabase (`js/engine.js`)**: Adicionar um `AbortController` com timeout de 4s na função `saveGarageOffers()` para evitar bloqueios de rede em ligações lentas.

### Prioridade Média
3. **Suporte PWA (Progressive Web App)**: Criar um `service-worker.js` e `manifest.json` para permitir a consulta 100% offline dos dashboards e estimadores diretamente no smartphone do utilizador durante visitas a standes de automóveis.
4. **Organização de Ficheiros Legado**: Mover `pages/matrizes-km-granular.html` e `pages/matrizes-km-granular-v2.html` para uma pasta `pages/legacy/`.

---

## 📋 CHECKLIST DE INTEGRIDADE

Para verificar se todas as subpáginas importam e executam o motor `engine.js` corretamente:

```bash
git status
```
Resultado esperado: **working tree clean**, repositório sincronizado com a Vercel.