Stoix Backend

API REST construída com NestJS, autenticação JWT e ORM Prisma sobre PostgreSQL.

Sumário

1. Visão Geral
2. Stack Técnica
3. Modelos (Prisma)
4. Autenticação & Autorização
5. Endpoints Principais
6. Como Rodar Localmente
7. Scripts NPM
8. Variáveis de Ambiente
9. Migrações & Prisma
10. Testes
11. Estrutura de Pastas
12. Roadmap / Próximos Passos

---

1. Visão Geral

Este projeto fornece uma API de usuários e tarefas, com cadastro/login, emissão de token JWT, controle de acesso por papéis (roles) e operações CRUD de tarefas com verificação de propriedade.

2. Stack Técnica

• Node.js / TypeScript
• NestJS 10
• Prisma ORM (PostgreSQL)
• JWT (@nestjs/jwt)
• Bcrypt para hashing de senhas
• Class-Validator / Class-Transformer para validação
• ESLint + Prettier para qualidade de código
• Jest / Supertest para testes

3. Modelos (schema Prisma simplificado)

model user {
  id       Int    @id @default(autoincrement())
  email    String @unique
  name     String
  password String
  tasks    task[]
  roles    role[] @default([USER])
}

model task {
  id          Int      @id @default(autoincrement())
  title       String
  description String?
  completed   Boolean  @default(false)
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt
  author      user?    @relation(fields: [authorId], references: [id])
  authorId    Int?
}

enum role {
  USER
  ADMIN
  MODERATOR
  EDITOR
}

4. Autenticação & Autorização

Fluxo:

1. SignUp cria usuário (senha hash com bcrypt) e já retorna access_token.
2. Login valida credenciais e devolve access_token JWT com payload: sub, username, roles.
3. AuthGuard valida o token em rotas protegidas.
4. RolesGuard (em user.controller) filtra acesso baseado no decorator @Roles().
5. TaskOwnershipGuard garante que apenas o autor manipule a própria task.

5. Endpoints Principais

Auth /auth

Método	Rota	Body	Descrição
POST	/signup	{ email, password, name }	Cria usuário e retorna JWT
POST	/login	{ email, password }	Autentica e retorna JWT

User /user

Método	Rota	Auth	Descrição
GET	/	JWT	Dados do usuário autenticado
GET	/all	JWT + role ADMIN	Lista todos usuários

Task /task

Método	Rota	Auth	Body / Param	Descrição
POST	/	JWT	{ title, description? }	Cria task vinculada ao usuário
PATCH	/:id	JWT + dono	{ title?, description? }	Atualiza task
GET	/:id	JWT + dono	-	Retorna task específica
DELETE	/:id	JWT + dono	-	Remove task

Obs: Endpoint de listagem geral de tasks não implementado ainda.

6. Como Rodar Localmente

Pré-requisitos: Node 18+, PostgreSQL em execução e string de conexão.

# instalar dependências
npm install

# configurar variáveis (.env)
cp .env.example .env  # (crie se não existir)

# gerar cliente Prisma
npx prisma generate

# aplicar migrações (cria tabelas)
npx prisma migrate dev --name init

# iniciar em desenvolvimento (watch)
npm run start:dev

API por padrão em: http://localhost:3000

7. Scripts NPM

Script	Descrição
start	Inicia (carrega .env)
start:dev	Watch mode
start:prod	Executa build transpilado (dist)
build	Transpila TypeScript
lint	ESLint com autofix
format	Prettier nos arquivos fonte
test	Testes unitários
test:e2e	Testes end-to-end
test:cov	Cobertura de testes

8. Variáveis de Ambiente

Criar arquivo .env com, por exemplo:

DATABASE_URL="postgresql://USER:PASS@localhost:5432/stoix?schema=public"
JWT_SECRET="uma_chave_segura"

Certifique-se de usar secret forte em produção.

9. Migrações & Prisma

• Schema principal: prisma/schema.prisma
• Gerar cliente: npx prisma generate
• Nova migração: npx prisma migrate dev --name descricao
• Visualizar DB: npx prisma studio

10. Testes

Executar:

npm run test        # unit
npm run test:e2e    # e2e
npm run test:cov    # cobertura

Arquivos de teste e2e em test/.

11. Estrutura de Pastas (resumo)

src/
  auth/        (signup, login, JWT)
  user/        (endpoints de usuário, roles)
  task/        (CRUD de tasks + guards de propriedade)
  role/        (Roles decorator e guard)
  database/    (Prisma service/module)
  exceptions/  (exceções custom)
  middlewares/ (middlewares futuros)
prisma/        (schema e migrações)
generated/     (cliente Prisma gerado)

12. Roadmap / Próximos Passos

• Listagem paginada de tasks do usuário
• Marcar task como concluída / toggle
• Refresh token / logout
• Auditoria de alterações
• Documentação OpenAPI (Swagger)
• Rate limiting

---

Ajuda adicional ou contribuição, abra uma issue ou PR.