# AGENTS.md — Guia para IAs no projeto VentoApp

> **Estado atual (jul/2026):** 8/8 marcos concluídos, 100% da NBR 6123:2023 coberta.
> Para histórico e roadmap detalhado, consulte [`PROGRESS.md`](./PROGRESS.md).

## ⚠️ Leia ANTES de começar

**Sempre leia `PROGRESS.md` primeiro** — ele contém:
- Estado exato do projeto
- Lista de tudo que foi entregue
- Roadmap priorizado de melhorias (M9.1, M9.2, ...)
- Convenções estabelecidas
- Onde encontrar cada coisa

## Comandos essenciais

```bash
cd /root/Apps/windapp/app

npm run dev        # vite dev com HMR (porta 5173)
npm run build      # tsc -b && vite build (produção)
npm run lint       # oxlint (sem correções automáticas)
npm test           # vitest run (38 testes, modo único)
npm run test:watch # vitest watch (modo interativo)
```

> **Atenção:** neste ambiente os binários em `node_modules/.bin/` perdem o bit de execução. Se um comando reclamar `Permission denied`, rode `chmod +x node_modules/.bin/<bin>` antes.

## Validação rápida (rode sempre após mudanças)

```bash
./node_modules/.bin/tsc -b           # 0 erros esperados
./node_modules/.bin/vitest run      # 38/38 esperados
./node_modules/.bin/oxlint          # 0 erros esperados
./node_modules/.bin/vite build      # ~2s, sem erros
```

## Arquitetura

- **Cálculo puro**: `src/lib/` — funções determinísticas sem dependência de React. Tipos readonly quando possível.
- **Tabelas da norma**: `src/lib/nbr-tables/` — todas as 36 tabelas + 3 anexos da NBR 6123:2023.
- **Modules (Strategy)**: `src/lib/modules/` — padrões de cálculo por tipo de estrutura (cylinder, vault, dome, truss, tower, bridge, dynamics).
- **Estado global**: `src/store/` — Zustand. Stores separadas por domínio (vento global, galpão).
- **UI**: `src/pages/` + `src/components/` — sem lógica de cálculo pesada.

## Estrutura de pastas (atual)

```
app/src/
├── lib/
│   ├── wind-kernel.ts          Motor matemático
│   ├── bilinear-interp.ts      Interpolação bilinear (sec. 3.2)
│   ├── log-interp.ts           Interpolação log-linear
│   ├── wind-direction.ts       Mudança de rugosidade (sec. 5.5)
│   ├── internal-pressure.ts    Cpi (sec. 6.3)
│   ├── neighborhood.ts         fᵥ (sec. 6.4)
│   ├── coefficients.ts         Cpe paredes/telhados (Tab. 6-12)
│   ├── excentricity.ts         ea, eb (sec. 6.1.4)
│   ├── friction.ts             Força de atrito (sec. 6.1.5)
│   ├── drag.ts                 Ca baixa/alta turbulência (Figs 4-5)
│   ├── comfort.ts              a_lim ISO 10137
│   ├── storage.ts              Persistência IndexedDB
│   ├── theme.tsx               Dark/light mode
│   ├── i18n.ts                 Strings pt-BR/en-US
│   ├── stations-lookup.ts      49 estações Anexo C
│   ├── export-pdf.tsx          PDF didático
│   ├── export-csv.ts           CSV estruturado
│   ├── modules/                Strategy pattern (7 módulos)
│   ├── nbr-tables/             36 tabelas + 3 anexos (~30 arquivos)
│   ├── hooks/useProjects.ts    Hook React
│   └── __tests__/              Vitest (5 suites, 38 testes)
├── components/
│   ├── ui/                     shadcn/ui
│   ├── three/                  Cylinder3D, Vault3D, Dome3D
│   ├── Warehouse3D.tsx         Galpão com zonas A-J
│   └── ExportMenu.tsx
├── pages/                       10 páginas (rotas)
├── store/                       Zustand
└── App.tsx                     Rotas + ThemeProvider + Layout
```

## Páginas (rotas atuais)

| Rota | Módulo | Tabelas |
|------|--------|---------|
| `/` | HomeMock | — |
| `/galpao` | Galpão retangular | 6, 7 |
| `/cilindro` | Silos, chaminés | 13 |
| `/abobada` | Abóbadas | 15-20 |
| `/cupula` | Cúpulas | 21, 22 |
| `/muros` | Muros/placas | 23 |
| `/cobertura-isolada` | Cob. isoladas | 24, 25 |
| `/barras` | Barras | 26-28 |
| `/pontes` | Pontes | 35, 36 |
| `/dinamica` | Dinâmica + vórtices | 31-34 |
| `/settings` | Tema + persistência | — |

## Convenções (manter!)

1. **TypeScript estrito**: zero `as any`, zero `// @ts-ignore`. Tipos `readonly` para tabelas.
2. **Sem comentários** exceto quando a matemática exige explicação.
3. **Imports absolutos**: `@/lib/...`, `@/components/...`, `@/store/...`.
4. **Componentes**: PascalCase em `.tsx`, kebab-case em arquivos utilitários `.ts`.
5. **Tailwind v4 + shadcn/ui**: usar `cn()` para merges, variantes do shadcn quando disponíveis.

## Princípios de cálculo (NÃO QUEBRAR)

1. **Não inventar constantes.** Toda fórmula deve vir da NBR 6123:2023.
2. **Tabela antes de fórmula.** Para S₂, usar a Tabela 3 (interpolação) por fidelidade à norma.
3. **Limites normativos.** Cpi em [-0,9 ; +0,9]. S₂ mínimo em z=5m. z_g como saturação.
4. **Cpi explícito.** Toda pressão é `p = q · (Cpe − Cpi)`. Nunca omitir Cpi.
5. **Tabela é readonly.** `Readonly<Record<...>>` previne mutação acidental.

## Workflow típico para adicionar funcionalidade

1. Identificar a seção/tabela da norma (ver `PROGRESS.md` roadmap).
2. Criar arquivo em `src/lib/nbr-tables/` com dados readonly (se aplicável).
3. Criar função de lookup (geralmente via `bilinearInterp` ou `linearInterp1D`).
4. Se aplicável, criar Strategy em `src/lib/modules/`.
5. Criar página em `src/pages/` consumindo o módulo.
6. Atualizar `App.tsx` com a rota.
7. Adicionar teste em `src/lib/__tests__/`.
8. Validar `npm run build` e `npm test`.

## Como retomar o trabalho

1. **Ler** `PROGRESS.md` → seção "Roadmap priorizado de melhorias"
2. **Escolher** um item (ex.: M9.1 — refinar tabelas)
3. **Implementar** seguindo o workflow acima
4. **Validar** com os 4 comandos da seção "Validação rápida"
5. **Atualizar** `PROGRESS.md` marcando o item como concluído

## Roadmap resumido (próximas iterações)

| ID | Item | Esforço | Impacto |
|----|------|---------|---------|
| **M9.1** | Refinar tabelas a partir do PDF real | 3 dias | Alto |
| **M9.2** | Cargas lineares (kN/m) por barra | 2 dias | Alto |
| **M9.3** | Screenshot 3D no PDF | 1 dia | Médio |
| **M9.4** | Export Ftool (.txt) | 2 dias | Médio |
| **M9.5** | Refatoração TypeScript (eliminar `void`) | 1 dia | Baixo |
| **M9.6** | 3D para muros/torres/pontes/barras | 3 dias | Médio |
| **M9.7** | Import JSON de projetos | 1 dia | Médio |
| **M9.8** | i18n completo (en-US) | 2 dias | Baixo |
| **M9.9** | Validação contra Blessmann | 2 dias | Alto |
| **M9.10** | Dark mode em gráficos SVG | 0.5 dia | Baixo |
| **M9.11** | Persistência em servidor (especulativo) | — | — |
| **M9.12** | Testes E2E com Playwright | 2 dias | Médio |

Detalhes completos em `PROGRESS.md`.

## Erros comuns

- `cannot find module '../bilinear-interp'` → caminho errado; arquivos em `src/lib/nbr-tables/` importam de `../bilinear-interp`, não `./`.
- Build rolldown falha → `npm install @rolldown/binding-linux-x64-gnu`.
- `oxlint permission denied` → `chmod +x node_modules/.bin/oxlint`.
- CSS variables sumindo → garantir `<ThemeProvider>` envolvendo a árvore em `App.tsx`.
- `vitest` não roda sem `vitest.config.ts` (já criado).
- Binários em `node_modules/.bin/` sem permissão → `chmod +x node_modules/.bin/<bin>`.