BrainWind/AGENTS.md

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.

⚠️ 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

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)

./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>.