first commit

docs/21_ENGINEERING_GUIDELINES.md

@@ -0,0 +1,66 @@
+# Engineering Guidelines
+
+## Objetivo
+Garantir consistência técnica no desenvolvimento com agentes de IA e reduzir deriva arquitetural entre sessões.
+
+## Regras gerais
+- Usar TypeScript em todo o projeto
+- Preferir server-side validation para mutações críticas
+- Manter regras de negócio fora dos componentes visuais
+- Manter o domínio explícito e nomeado
+- Evitar abstrações prematuras
+
+## Backend dentro do Next.js
+Na V1, o backend deve viver dentro do projeto Next.js.
+
+Usar:
+- Route Handlers quando for necessário expor endpoints
+- Server Actions quando fizer sentido para mutações simples ligadas à UI
+- camada `server/services` para regras de negócio
+- camada `server/repositories` para acesso aos dados
+
+## Prisma
+- Modelar entidades do domínio com nomes claros
+- Usar migrations versionadas
+- Evitar queries complexas diretamente em componentes
+- Centralizar acesso à base de dados em repositórios ou queries server-side
+
+## Validação
+- Usar Zod para validar inputs e payloads
+- Reutilizar schemas entre UI e servidor quando fizer sentido
+- Nunca confiar apenas na validação do cliente
+
+## UI
+- Usar Tailwind CSS
+- Usar shadcn/ui como base de componentes
+- Criar componentes reutilizáveis para estados, tabelas, filtros e formulários
+- Priorizar rapidez operacional sobre efeitos visuais
+
+## Estado e dados
+- Preferir dados carregados no servidor
+- Evitar estado global desnecessário na V1
+- Só introduzir state management adicional se surgir necessidade clara
+
+## Segurança
+- Usar Supabase Auth para autenticação base
+- Proteger rotas privadas
+- Gerir segredos por `.env`
+- Não expor chaves sensíveis no cliente
+
+## Storage
+- Usar Supabase Storage apenas quando a funcionalidade de imagens/anexos estiver confirmada
+- Definir políticas mínimas de acesso antes de ativar uploads reais
+
+## Qualidade de código
+- Cada feature deve ser desenvolvida com documentação mínima
+- Atualizar `16_DECISIONS_LOG.md` quando houver decisões relevantes
+- Atualizar `17_PROGRESS.md` no fim de marcos importantes
+- Atualizar `18_AGENT_HANDOFF.md` no fim de cada sessão relevante
+
+## O que evitar
+- microserviços
+- backend separado na V1
+- GraphQL
+- lógica de negócio espalhada por componentes
+- modelos demasiado genéricos
+- dependências pesadas sem necessidade clara