first commit

docs/20_PROJECT_STRUCTURE.md

@@ -0,0 +1,162 @@
+# Project Structure
+
+## Objetivo
+Definir uma estrutura de projeto clara, previsível e adequada a desenvolvimento assistido por agentes de IA.
+
+## Estrutura de alto nível
+
+```text
+app/
+components/
+features/
+lib/
+server/
+prisma/
+docs/
+public/
+```
+
+## Estrutura recomendada detalhada
+
+```text
+src/
+  app/
+    (dashboard)/
+    api/
+    login/
+    layout.tsx
+    page.tsx
+
+  components/
+    ui/
+    shared/
+    layout/
+    tables/
+    forms/
+    status/
+
+  features/
+    suppliers/
+      components/
+      actions/
+      schemas/
+      utils/
+    purchase-orders/
+      components/
+      actions/
+      schemas/
+      utils/
+    receipts/
+      components/
+      actions/
+      schemas/
+      utils/
+    inventory/
+      components/
+      actions/
+      schemas/
+      utils/
+    listings/
+      components/
+      actions/
+      schemas/
+      utils/
+    sales/
+      components/
+      actions/
+      schemas/
+      utils/
+    shipments/
+      components/
+      actions/
+      schemas/
+      utils/
+    dashboard/
+      components/
+      queries/
+      utils/
+
+  lib/
+    auth/
+    utils/
+    constants/
+    validators/
+
+  server/
+    db/
+      client.ts
+    repositories/
+    services/
+    queries/
+    permissions/
+    audit/
+
+  prisma/
+    schema.prisma
+    migrations/
+    seeds/
+
+  docs/
+    *.md
+
+  public/
+    images/
+    icons/
+```
+
+## Regras de organização
+- `app/` contém rotas, layouts e entry points do Next.js
+- `components/` contém componentes reutilizáveis sem lógica de negócio forte
+- `features/` organiza a aplicação por domínio funcional
+- `server/` concentra lógica do lado do servidor
+- `prisma/` concentra schema, migrations e seeds
+- `docs/` contém a documentação do projeto
+
+## Padrão por feature
+Cada feature deve, idealmente, conter:
+- `components/`
+- `actions/`
+- `schemas/`
+- `utils/`
+
+Opcionalmente:
+- `queries/`
+- `types/`
+- `tests/`
+
+## Separação recomendada de responsabilidades
+
+### UI
+Componentes visuais, tabelas, formulários, badges, cards, filtros.
+
+### Actions / handlers
+Entradas da aplicação para mutações e operações ligadas ao utilizador.
+
+### Schemas
+Validação com Zod.
+
+### Services
+Regras de negócio e fluxos operacionais.
+
+### Repositories
+Acesso aos dados e queries Prisma.
+
+### Queries
+Leituras complexas e agregações para dashboard e listagens.
+
+## Convenções de naming
+- kebab-case para nomes de pastas de features
+- PascalCase para componentes React
+- camelCase para funções e variáveis
+- nomes explícitos e orientados ao domínio
+- evitar abreviações ambíguas
+
+## Estrutura inicial mínima da V1
+- auth
+- suppliers
+- purchase-orders
+- receipts
+- inventory
+- sales
+- shipments
+- dashboard