159 lines
7.2 KiB
Markdown
159 lines
7.2 KiB
Markdown
# 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>`. |