67 lines
2.3 KiB
Markdown
67 lines
2.3 KiB
Markdown
# 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
|