Redator Técnico para Documentação de Projeto em Linguagem Simples

# FORME.md - Guia Completo do Projeto --- ## 1. O Panorama Geral (Visão Geral do Projeto) Este projeto é uma plataforma que permite [descrição do que faz]. Em termos simples: [explicação de uma frase]. Ele resolve o problema de [problema] para [público-alvo], oferecendo [benefício principal]. **O problema que resolve:** [descrição do problema e para quem] **Como os usuários interagem:** O usuário chega, [passo 1 - ação inicial], depois [passo 2 - ação intermediária], e finalmente [passo 3 - resultado]. Todo o processo leva cerca de [tempo estimado]. **Uma analogia para entender tudo:** Imagine que este sistema é um restaurante. A **interface** que o usuário vê é o salão - bonito, acolhedor, onde o cliente faz o pedido. O **backend** é a cozinha - onde todo o trabalho pesado acontece, invisível para o cliente. O **banco de dados** é o estoque e o arquivo de receitas - onde guardamos todos os ingredientes e o histórico de pedidos. E os **serviços externos** (pagamento, email) são os fornecedores - a gente liga pra eles quando precisa de algo específico. --- ## 2. Arquitetura Técnica - A Planta Baixa ### Diagrama da Arquitetura ``` ┌─────────────────────────────────────────────────────────────┐ │ FRONTEND (O Salão) │ │ O que o usuário vê e interage │ └─────────────────────────┬───────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ API/BACKEND (A Cozinha) │ │ Onde a lógica de negócio acontece │ └──────────┬──────────────────┬──────────────────┬────────────┘ │ │ │ ▼ ▼ ▼ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ BANCO DE │ │ SERVIÇOS │ │ ARMAZEN. │ │ DADOS │ │ EXTERNOS │ │ ARQUIVOS │ │ (O Estoque) │ │(Fornecedores)│ │ (Depósito) │ └──────────────┘ └──────────────┘ └──────────────┘ ``` ### Tour pela Arquitetura **O Salão (Frontend):** É tudo que o usuário vê e toca. Aqui acontece a interação - botões, formulários, listas. Pense nisso como o garçom que anota seu pedido. Ele não cozinha nada, mas é essencial para a experiência. **A Cozinha (Backend/API):** Todo o trabalho real acontece aqui. Quando o usuário faz algo no salão, o pedido vem pra cá. A cozinha verifica se temos os ingredientes (consulta o banco), prepara o prato (executa a lógica), e manda o resultado de volta pro salão. **O Estoque (Banco de Dados):** Onde guardamos tudo - usuários, pedidos, configurações. É o arquivo central que nunca pode ser perdido. **Os Fornecedores (Serviços Externos):** Serviços de terceiros que usamos para coisas específicas - pagamento, envio de emails, armazenamento de arquivos. ### Por que essa arquitetura? **Por que separar frontend e backend?** Porque são responsabilidades diferentes. O salão não precisa saber cozinhar, e a cozinha não precisa saber atender cliente. Separar permite que cada parte evolua independentemente. **Por que usar [tecnologia X] e não [alternativa óbvia]?** [Explicação específica do trade-off] **Decisões inteligentes:** [Destaque escolhas não-óbvias que o desenvolvedor fez] --- ## 3. Estrutura do Código - O Sistema de Arquivos ``` projeto/ ├── src/ │ ├── components/ → Peças de interface reutilizáveis │ ├── pages/ → As "telas" principais do app │ ├── services/ → Código que fala com APIs externas │ ├── utils/ → Funções auxiliares genéricas │ └── styles/ → Arquivos de estilo visual ├── public/ → Arquivos estáticos (imagens, ícones) ├── config/ → Configurações do projeto ├── tests/ → Testes automatizados └── docs/ → Documentação ``` ### O que vive em cada pasta **`src/components/`** - Pense como as peças de LEGO da interface. Botões, cards, formulários - tudo que é reutilizável fica aqui. Se você precisa criar uma nova tela, provavelmente vai montar usando peças daqui. **`src/pages/`** - As telas completas. Cada arquivo aqui é uma "página" que o usuário pode visitar. É aqui que você vai quando precisa criar uma nova funcionalidade visível. **`src/services/`** - O "telefone" do projeto. Todo código que faz chamadas para APIs externas ou para o backend fica aqui. Se algo não está carregando dados, é aqui que você investiga. **`src/utils/`** - Funções utilitárias - pequenas ferramentas que não se encaixam em nenhum outro lugar. Formatação de datas, validação de emails, etc. **`src/styles/`** - O "guarda-roupa" do app. Tudo que define cores, fontes, espaçamentos. ### Convenções de nomenclatura - **Arquivos de componentes** usam PascalCase (ex: `UserCard.tsx`) - **Funções utilitárias** usam camelCase (ex: `formatDate.ts`) - **Constantes** usam UPPER_SNAKE_CASE (ex: `MAX_RETRIES`) ### Pontos de entrada O app começa em `src/index.tsx` (ou `src/App.tsx`). É aqui que tudo é montado e inicializado. Pense como a porta de entrada do restaurante - tudo passa por aqui primeiro. --- ## 4. Conexões e Fluxo de Dados - Como as Coisas se Comunicam ### Ação 1: Usuário faz login Quando o usuário clica em "Entrar", aqui está o que acontece: 1. O formulário em `src/pages/Login.tsx` captura email e senha - é o cliente chamando o garçom 2. A função `login()` em `src/services/auth.ts` é acionada - o garçom leva o pedido pra cozinha 3. A cozinha (backend) verifica as credenciais no banco de dados - confere se o cliente é conhecido 4. Se correto, o backend gera um "token" (um crachá de identificação) e devolve pro frontend 5. O frontend guarda esse token e o usa em todas as próximas requisições - o cliente agora tem um crachá que prova quem é **Se o serviço de autenticação falhar:** O usuário vê uma mensagem de erro e não consegue entrar. Não há dados perdidos, mas a experiência é interrompida. ### Ação 2: Usuário cria um novo [item] 1. O usuário preenche o formulário e clica "Salvar" 2. O componente em `src/components/NewItemForm.tsx` valida os dados - o garçom confere se o pedido está completo 3. A função `createItem()` em `src/services/items.ts` envia os dados pro backend via API 4. O backend valida novamente (nunca confie só no frontend!) e salva no banco de dados 5. O backend retorna o item criado com um ID único 6. O frontend atualiza a lista na tela - o garçom traz a confirmação pro cliente **Se o banco de dados falhar:** O backend retorna um erro 500. O frontend mostra "Algo deu errado, tente novamente". O usuário não perde o que digitou (se o formulário mantém estado local). ### Ação 3: Usuário faz um pagamento 1. Usuário clica "Pagar" - o pedido vai pra cozinha 2. O backend chama o serviço de pagamento (Stripe/Pagar.me) - a cozinha liga pro fornecedor 3. O fornecedor processa o cartão e retorna confirmação 4. O backend registra o pagamento no banco - anota no livro caixa 5. O backend dispara um email de confirmação - manda o recibo pro cliente **Se o pagamento falhar:** O usuário vê uma mensagem clara de erro. O pedido não é confirmado. O sistema deve permitir tentar novamente sem duplicar cobranças (idempotência). ### Autenticação - Como o sistema sabe quem você é Usamos [JWT/OAuth/sessão]. Em termos simples: quando você faz login, o sistema te dá um "crachá digital" com validade de [X horas]. Cada vez que você faz algo, o sistema confere seu crachá. Se o crachá expira, você precisa fazer login de novo. --- ## 5. Escolhas Tecnológicas - A Caixa de Ferramentas | Tecnologia | O Que Faz Aqui | Por Que Esta | Cuidado Com | |-----------|----------------|-------------|-------------| | [Tecnologia 1] | [Função específica no projeto] | [Motivo da escolha vs alternativas] | [Limitação/trade-off] | | [Tecnologia 2] | [Função específica no projeto] | [Motivo da escolha vs alternativas] | [Limitação/trade-off] | | [Tecnologia 3] | [Função específica no projeto] | [Motivo da escolha vs alternativas] | [Limitação/trade-off] | **Custos:** [Resumo dos custos - gratuito? pago? baseado em uso?] --- ## 6. Ambiente e Configuração ### Variáveis de Ambiente | Variável | O Que Controla | Onde é Usada | |---------|---------------|-------------| | `DATABASE_URL` | Endereço do banco de dados - "onde fica o estoque" | Backend | | `API_KEY` | Chave secreta para serviços externos - "senha do fornecedor" | Serviços | | `JWT_SECRET` | Chave para assinar tokens de autenticação - "carimbo oficial" | Backend | ### Ambientes - **Desenvolvimento:** Roda na sua máquina. Banco de dados local. Dados de teste. - **Staging:** Ambiente de teste que imita produção. Usado antes de lançar mudanças. - **Produção:** O ambiente real que os usuários usam. Dados reais. Máximo cuidado. **Se você precisa mudar [X], atualize [Y] - mas cuidado porque [Z].** **Segredos e chaves:** As chaves de API e segredos NUNCA devem ser commitados no código. Eles ficam em variáveis de ambiente ou em um serviço de gerenciamento de segredos. --- ## 7. Lições Aprendidas - As Histórias de Guerra ### Bugs e Correções **Bug: [Descrição do bug]** - **Causa:** [Explicação simples do que causou] - **Correção:** [Como foi resolvido] - **Prevenção:** [Como evitar no futuro] **Bug: [Descrição do bug]** - **Causa:** [Explicação simples do que causou] - **Correção:** [Como foi resolvido] - **Prevenção:** [Como evitar no futuro] ### Armadilhas e Minas Terrestres - **Coisa que parece simples mas é complicada:** [Explicação] - **Se você mudar [X], cuidado porque afeta [Y] e [Z]:** [Explicação] - **Dívida técnica conhecida:** [O que é, por que existe, quando pagar] ### Descobertas - **Tecnologias exploradas:** [O que foi testado, o que funcionou, o que não funcionou] - **Se eu fosse começar de novo:** [O que faria diferente] ### Sabedoria de Engenharia - **Práticas que funcionaram:** [Lista de boas práticas] - **Padrões confiáveis:** [Padrões de código que provaram ser sólidos] - **Como engenheiros experientes pensam:** [Insight sobre mentalidade] --- ## 8. Cartão de Referência Rápida ### Como rodar o projeto localmente 1. **Pré-requisitos:** Instale [Node.js], [Docker], [etc.] 2. **Clone o repositório:** `git clone [URL]` 3. **Instale dependências:** `npm install` (ou `yarn install`) 4. **Configure variáveis de ambiente:** Copie `.env.example` para `.env` e preencha os valores 5. **Suba o banco de dados:** `docker-compose up -d` (se aplicável) 6. **Rode as migrações:** `npm run migrate` 7. **Inicie o servidor:** `npm run dev` 8. **Acesse:** `http://localhost:3000` ### URLs Importantes - **Produção:** [URL] - **Staging:** [URL] - **Admin:** [URL] - **Dashboard:** [URL] ### Quando algo quebrar | Problema | Onde Ir | Quem Chamar | |---------|---------|-------------| | Bug na interface | `src/components/` | [Pessoa responsável] | | Erro de API | `src/services/` | [Pessoa responsável] | | Problema de banco | Backend/DB | [Pessoa responsável] | | Falha de pagamento | Serviço de pagamento | [Pessoa responsável] | ### Comandos Mais Usados ```bash npm run dev # Inicia o servidor de desenvolvimento npm run build # Gera versão de produção npm run test # Roda os testes npm run lint # Verifica qualidade do código npm run migrate # Atualiza o banco de dados npm run deploy # Publica em produção ```