🕒 Foco Total — Módulo de Agendamento e Gestão de Tarefas

Este projeto faz parte do Módulo de Agendamento e Gestão de Tarefas, desenvolvido em uma estrutura monorepositório (monorepo) que integra o backend (Express.js) e o frontend (Next.js) dentro de um único repositório.

---

📂 Estrutura do Projeto

foco-total/

└── src/

├── backend/ → API com Express.js

└── frontend/ → Interface com Next.js

🧠 O que é um monorepo?

Um monorepo é um único repositório que contém múltiplos projetos relacionados.
No nosso caso:

• O backend fornece a API e a lógica de negócios.
• O frontend consome a API e exibe a interface ao usuário.

Ambos compartilham configurações, dependências e scripts comuns, o que facilita o desenvolvimento e a manutenção.

---

⚙️ Configuração e Execução

🔧 Pré-requisitos

• Node.js (versão 18 ou superior)
• npm (versão 8 ou superior)

---

🚀 Como executar o projeto

# Clone este repositório
git clone https://github.com/<seu-usuario>/<nome-do-repositorio>.git

# Acesse a pasta do projeto
cd foco-total

# Instale as dependências de todos os módulos (frontend + backend)
npm install

# Execute frontend e backend juntos
npm run dev

Se quiser rodar separadamente:

npm run dev:back   # Inicia o backend
npm run dev:front  # Inicia o frontend

---

🧩 Instalação de novas dependências

Dentro do monorepo, cada módulo tem seu próprio package.json.

• Para instalar dependências no backend:

  npm install <pacote> --workspace src/backend

• Para instalar dependências no frontend:

  npm install <pacote> --workspace src/frontend

Isso garante que cada pacote fique isolado no local certo, sem bagunçar o projeto todo.

---

🔐 Variáveis de Ambiente

As variáveis de ambiente devem ficar em um arquivo .env na raiz do projeto. Para referência, existe um modelo chamado .env.example.

Exemplo:

Backend

PORT=3000 DB_URL=postgres://user:senha@localhost:5432/focototal

Frontend

NEXT_PUBLIC_API_URL=http://localhost:3000

---

🧾 Scripts principais

Comando	Descrição
npm run dev:back	Inicia o backend com Nodemon
npm run dev:front	Inicia o frontend com Next.js
npm run dev	Inicia ambos simultaneamente (logs coloridos)

---

🧱 Tecnologias Utilizadas

• Node.js + Express.js → API e rotas do backend
• Next.js + React → Interface moderna do frontend
• Nodemon → Atualização automática durante o desenvolvimento
• Concurrently → Execução paralela do front e do back

---

💡 Dica: Caso ocorra algum erro de porta em uso, verifique se nenhuma outra aplicação está rodando em localhost:3000. O backend e o frontend podem usar portas diferentes conforme configurado no .env.

---

Observações importantes

📌 Guia de Contribuição

Este projeto segue um padrão de branches e commits para manter a organização e facilitar o trabalho em equipe.
Antes de contribuir, leia atentamente as instruções abaixo.

---

🌿 Padrão de Branches

Sempre crie uma branch nova a partir da main.
O formato deve ser:

Tipos de Branch

• Nova funcionalidade → feat/nome-da-funcionalidade
  Exemplo: feat/adicionar-tarefas

• Correção de bug → fix/nome-do-bug
  Exemplo: fix/contador-incorreto

• Refatoração (melhoria sem mudar regra de negócio) → refactor/nome-da-refatoracao
  Exemplo: refactor/estrutura-componentes

• Estilo/ajuste visual (CSS, Tailwind, layout) → style/nome-do-ajuste
  Exemplo: style/responsividade-lista

• Configuração (dependências, vite, eslint, etc.) → chore/nome-da-config
  Exemplo: chore/configurar-tailwind

• Documentação → docs/nome-do-doc
  Exemplo: docs/atualizar-readme

---

📝 Padrão de Commits (Conventional Commits)

Os commits devem seguir o padrão:

Tipos de Commits

• feat: → nova funcionalidade
  Ex: feat: adicionar input de nova tarefa

• fix: → correção de bug
  Ex: fix: corrigir erro ao remover tarefa

• refactor: → refatoração de código (sem mudar regra de negócio)
  Ex: refactor: melhorar performance da lista

• style: → mudanças visuais/estilo (não altera lógica)
  Ex: style: ajustar espaçamento no header

• chore: → alterações de configuração, build, dependências
  Ex: chore: instalar react-icons

• docs: → alterações na documentação
  Ex: docs: adicionar instruções de instalação no readme

---

✅ Boas práticas

• Nunca commitar diretamente na main.
• Use nomes de branch curtos, descritivos e em inglês.
• Faça commits pequenos e frequentes (não deixe tudo em um único commit).
• Ao abrir um Pull Request, escreva um título claro e uma descrição objetiva.

---

📄 Licença Este projeto é de uso interno e faz parte do módulo de desenvolvimento do sistema Foco Total.

---

🔄 Atualização: Backend API — Guia Completo

Esta seção foi atualizada para refletir as melhorias recentes: testes automatizados com Jest, sanitização de variáveis, validações centralizadas, logout, rate limiting condicionado e relacionamento Task ↔ Goal.

🌍 Porta e Endpoints Base

• Porta padrão atual: 3001 (configurável via PORT).
• Health check: GET /health → retorna status da API.
• Base da API (desenvolvimento): http://localhost:3001/api.

🔐 Variáveis de Ambiente (Backend / Raiz)

Arquivo de referência: .env.example na raiz. Crie um .env na raiz (carregado pelo backend e pelo frontend quando necessário). Principais variáveis usadas pelo backend:

PORT=3001
DATABASE_URL=postgres://usuario:senha@localhost:5432/focototal
JWT_SECRET=changeme-dev
RATE_LIMIT_WINDOW_MS=60000
RATE_LIMIT_MAX_REQUESTS=100
CORS_ORIGIN=http://localhost:3000
SWAGGER_ENABLED=true
SWAGGER_ROUTE=/docs
NODE_ENV=development

Variáveis consumidas pelo frontend (Next.js):

NEXT_PUBLIC_API_URL=http://localhost:3001/api
NEXT_PUBLIC_DEV_MODE=true

Em ambiente de teste (NODE_ENV=test) o rate limiter é automaticamente desativado para evitar falsos negativos nos testes.

🧪 Testes (Jest)

Os testes de API (controllers, middlewares, validações) rodam com Jest + Supertest.

Arquivos principais:

• src/backend/jest.config.js → Configuração geral (match dos testes, setup).
• src/backend/jest.setup.js → Carrega variáveis de ambiente (.env.test → .env → fallback) e evita hard-code de segredos.
• Diretório de testes: src/backend/__tests__/ (ex.: controllers/authController.test.js).

Execução:

cd src/backend
npm test

Para depurar: defina JEST_DEBUG=1 no ambiente para logs adicionais (segredos são redigidos).

▶️ Executando Apenas o Backend

cd src/backend
npm install        # caso não tenha feito na raiz
npm run dev        # nodemon + reload
npm start          # execução simples

Se o frontend chamar a API, assegure-se que NEXT_PUBLIC_API_URL aponta para a URL correta.

🗄️ Prisma (Banco de Dados)

Scripts (executar dentro de src/backend):

npm run prisma:generate  # gera cliente
npm run prisma:migrate   # aplica migrations
npm run prisma:studio    # visualização
npm run prisma:seed      # (opcional) popular dados

Relacionamento atual Task ↔ Goal (trecho relevante):

model Task {
  id      String  @id @default(uuid())
  title   String
  status  Status  @default(PENDING)
  userId  String
  goalId  String?  // opcional
  goal    Goal?    @relation(fields: [goalId], references: [id], onDelete: SetNull)
}

model Goal {
  id      String  @id @default(uuid())
  title   String
  target  Int
  current Int     @default(0)
  userId  String
  tasks   Task[]
}

Pontos-chave:

1. Task pode existir sem meta (goalId = null).
2. Vincular: enviar goalId no POST/PATCH de Task.
3. Desvincular: PATCH com goalId: null.
4. Exclusão de Goal mantém Tasks (SetNull).
5. Filtros suportados em /api/tasks: goalId, status, userId.
6. Listar tarefas de uma meta: GET /api/goals/:goalId/tasks.

🔑 Autenticação & Logout

Fluxo principal:

1. Registro → POST /api/auth/register (cria usuário, valida campos).
2. Login → POST /api/auth/login (retorna token JWT).
3. Rotas protegidas exigem header Authorization: Bearer <token>.
4. Logout → POST /api/auth/logout (invalidação lógica / limpeza lado cliente; backend pode opcionalmente manter lista de tokens revogados se necessário em evolução futura).

Validações aplicadas (exemplos):

• Email obrigatório e formato válido.
• Senha com comprimento mínimo definido.
• Impede registro duplicado (retorna status adequado).
• Middleware de autenticação rejeita token inválido ou expirado.

✅ Middlewares Relevantes

• authMiddleware → verifica e decodifica JWT, anexa usuário ao request.
• rateLimiter → aplicado em produção/desenvolvimento; ignorado em NODE_ENV=test.
• validate → esquemas centralizados em src/backend/validations/ para entradas (ex.: login, registro, tarefas).
• errorHandler (dentro de app.js) → garante resposta JSON consistente usando err.statusCode || 500.

📊 Exemplos de Requisição (Autenticação)

Registro:

POST /api/auth/register
Content-Type: application/json
{
  "name": "João Silva",
  "email": "joao@test.com",
  "password": "senha123"
}

Login:

POST /api/auth/login
Content-Type: application/json
{
  "email": "joao@test.com",
  "password": "senha123"
}

Logout:

POST /api/auth/logout
Authorization: Bearer <token>

🧪 Exemplo (Registro via PowerShell)

$response = Invoke-RestMethod -Uri 'http://localhost:3001/api/auth/register' -Method POST -ContentType 'application/json' -Body (@{name='João Silva';email='joao@test.com';password='senha123'} | ConvertTo-Json)
$response | ConvertTo-Json -Depth 5

🛡️ Rate Limiting

Configuração básica controlada por:

RATE_LIMIT_WINDOW_MS=60000
RATE_LIMIT_MAX_REQUESTS=100

Nos testes (NODE_ENV=test) o middleware retorna imediatamente (sem bloquear) para evitar falhas artificiais.

🧩 Estrutura dos Testes

Cada teste utiliza Supertest para simular chamadas HTTP sem subir um servidor externo persistente. Cuidados aplicados:

• Limpeza de dados entre cenários (quando necessário).
• Uso de variáveis de ambiente carregadas dinamicamente.
• Evita dependência de logs ou timeouts artificiais.

📌 Boas Práticas Internas Adotadas

• Nenhum segredo sensível hard-coded nos arquivos de teste.
• Fallback seguro para variáveis ausentes (placeholders não produtivos).
• Respostas de erro padronizadas ({ message, statusCode }).
• Validações centralizadas para reduzir duplicação em controllers.

🔄 Próximos Passos Sugeridos

• Adicionar seção mais detalhada de Swagger quando documentação estiver estável.
• Introduzir lista de tokens revogados para logout definitivo (se requisito surgir).
• Criar .env.test dedicado para isolamento completo do banco de testes.

---