lambdadeveloper/afl repository overview

⁠AFL — Lista de Tarefas

Aplicação completa (API + Frontend PWA) para gerenciar uma lista de tarefas com autenticação JWT, empacotada com Docker Compose. Versões LTS/estáveis: Python 3.12, Node.js 22 LTS, NGINX 1.26 stable.

⁠Objetivos do projeto

Além de atender aos requisitos do desafio, este projeto procura demonstrar:

• arquitetura organizada e desacoplada;
• boas práticas com FastAPI e Angular;
• autenticação baseada em JWT;
• documentação automática da API (OpenAPI/Swagger);
• testes automatizados com cobertura mínima;
• ambiente totalmente reproduzível com Docker Compose;
• automação através de Makefile;
• pipeline de CI/CD com GitHub Actions;
• geração automática de badges e publicação de imagens Docker.

⁠Arquitetura

• Frontend: http://localhost:8080/
• API: http://localhost:8080/api
• Swagger: http://localhost:8080/doc

⁠Pré-requisitos

• Docker e Docker Compose.

⁠Primeiros passos

Clone o repositório e acesse o diretório do projeto:

git clone https://github.com/AFLca/desafio-tecnico.git
cd desafio-tecnico

⁠Variáveis de ambiente

Copie o arquivo de exemplo e ajuste se necessário:

cp .env.example .env

Conteúdo de .env.example:

⁠Executar com Makefile

O projeto inclui um Makefile (inspirado em cornerstone⁠) com os comandos principais:

⁠Subir a aplicação

Qualquer uma das formas abaixo sobe a stack completa (build + containers):

cp .env.example .env   # opcional — o make cria se faltar
make start

Ou com Docker Compose padrão:

cp .env.example .env   # necessário se ainda não existir
docker compose up --build --remove-orphans

(make start usa o equivalente em modo detached: docker compose up --build --remove-orphans -d.)

A aplicação ficará disponível em http://localhost:8080 (ou a porta definida em APP_PORT).

make stop    # pausa os containers
make down    # remove containers e rede
make clean   # limpeza completa (inclui volumes e imagens locais)

⁠Deploy (Docker Hub)

Requer login no Docker Hub (docker login) com acesso ao namespace lambdadeveloper:

make deploy

Imagens publicadas:

• lambdadeveloper/afl:api
• lambdadeveloper/afl:app
• lambdadeveloper/afl:nginx

⁠CI/CD (GitHub Actions)

Secrets / variables necessários no repositório:

⁠Equivalente com Docker Compose

docker compose build
docker compose up --build --remove-orphans
docker compose stop
docker compose down
docker compose logs -f

Para rodar em segundo plano (como o make start):

docker compose up --build --remove-orphans -d

⁠Desenvolvimento local (sem Docker)

⁠Backend

cd api
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
mkdir -p data
uvicorn app.main:app --reload --port 8000

• API: http://localhost:8000/api
• Swagger: http://localhost:8000/doc

⁠Frontend

cd app
npm install
npm start

O Angular Dev Server sobe em http://localhost:4200. Para apontar à API local, use um proxy ou acesse via Docker Compose.

Proxy de desenvolvimento sugerido (app/proxy.conf.json):

{
  "/api": { "target": "http://localhost:8000", "secure": false },
  "/doc": { "target": "http://localhost:8000", "secure": false },
  "/openapi.json": { "target": "http://localhost:8000", "secure": false }
}

E rode: ng serve --proxy-config proxy.conf.json

⁠Testes

⁠Cobertura (make coverage)

make coverage

Gera relatórios HTML/XML em docs/cover/api e docs/cover/app, e badges SVG em docs/badges/ (usadas no cabeçalho do README).

⁠Backend (Pytest + cobertura ≥ 90%)

cd api
pip install -r requirements.txt
pytest -v

O pytest falha automaticamente se a cobertura de app/ ficar abaixo de 90%.

Códigos HTTP cobertos pelos testes: 201 (criação), 204 (remoção), 401 (JWT inválido), 403 (tarefa de outro usuário), 404 (inexistente), 422 (validação).

⁠Frontend (Vitest)

cd app
npm install
npm test -- --watch=false

Inclui testes de páginas, componente de tarefa, serviços, guards e interceptor HTTP.

⁠Endpoints da API

⁠Autenticação

⁠Tarefas (requer Authorization: Bearer <token>)

Resposta da listagem: { items, total, skip, limit, has_more }.

Campos da tarefa: id, titulo, descricao, status, datahora_criacao, datahora_modificacao, usuario_id.

Status aceitos: pendente, concluida, cancelada.

Ordenação da listagem: pendentes → concluídas → canceladas; dentro de cada status, por datahora_modificacao decrescente. Em tarefas novas, datahora_modificacao inicia igual a datahora_criacao.

No frontend, a tela de tarefas tem topo e background fixos e listagem infinita (sem limite de carga — páginas sucessivas até esgotar). Concluídas usam #9cbc3c e canceladas #9ca2a6; ambas com título tachado. O botão check à direita do título conclui a tarefa.

⁠Cores do frontend / AFL

⁠PWA

O frontend é um Progressive Web App (manifest + Angular Service Worker). Em build de produção, o app pode ser instalado pelo navegador.