API Kanban Ninja

Uma API REST para gerenciamento de tarefas em kanban construída com Django e Django Ninja, oferecendo autenticação JWT e operações CRUD completas para tarefas e contas de usuário.
Este projeto foi desenvolvido como material de apoio para o Mini Curso Descomplicando o Desenvolvimento Web com Python e Django em Sobral na V SECS, ministrado por Mateus Martins.

📋 Funcionalidades

• Gerenciamento de Tarefas: Criar, listar, visualizar, atualizar e excluir tarefas
• Sistema de Contas: Gerenciamento completo de contas de usuário
• Autenticação JWT: Login seguro com tokens de acesso e refresh
• Prioridades: Sistema de prioridades (Baixa, Média, Alta)
• Status de Tarefas: Controle de status (Pendente, Em Progresso, Concluída e Cancelada)
• Rastreamento de Datas: Datas de criação, atualização e vencimento
• Atribuição de Usuários: Tarefas podem ser atribuídas a usuários específicos
• Documentação Automática: OpenAPI/Swagger integrado

🚀 Configuração do Ambiente

Pré-requisitos

• Python 3.12 ou superior
• uv ou qualquer outro gerenciador de pacotes python

Instalação do uv

Se você ainda não tem o uv instalado, execute:

# No macOS e Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# No Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Ou via pip
pip install uv

Configuração do Projeto

1. Clone o repositório

   git clone https://github.com/mateus-dev-me/api-kanban-ninja
   cd api-kanban-ninja
   

2. Crie o ambiente virtual

   uv venv
   

   Isso criará um ambiente virtual na pasta .venv

3. Ative o ambiente virtual

   Linux/macOS:

   source .venv/bin/activate
   

   Windows:

   .venv\Scripts\Activate
   

4. Instale as dependências

   uv pip install -r pyproject.toml --group dev
   

5. Configure o banco de dados

   task migrations
   

6. Crie um superusuário (opcional)

   python manage.py createsuperuser
   

7. Execute o servidor de desenvolvimento

   task run
   

A API estará disponível em http://localhost:8000

🔗 Endpoints da API

🏠 Documentação

A documentação da API está disponível em /docs

🔐 Autenticação

Método	Endpoint	Descrição
POST	/token	Login - Obter token de acesso
POST	/refresh	Renovar token de acesso

👥 Gerenciamento de Contas

Método	Endpoint	Descrição
POST	/accounts	Criar nova conta de usuário
GET	/accounts	Listar todas as contas
GET	/accounts/<pk>	Obter detalhes de uma conta
PUT	/accounts/<pk>	Atualizar dados da conta
DELETE	/accounts/<pk>	Excluir conta

📝 Gerenciamento de Tags

Método	Endpoint	Descrição
POST	/tags	Criar uma nova tag
GET	/tags	Listar todas as tags
DELETE	/tags/<tag_id>	Excluir uma tag existente
PUT	/tags/<tag_id>	Atualizar os dados de uma tag

📝 Gerenciamento de Tarefas

Método	Endpoint	Descrição
POST	/tasks	Criar nova tarefa
GET	/tasks	Listar todas as tarefas
GET	/tasks/<pk>	Obter detalhes de uma tarefa
PUT	/tasks/<pk>	Atualizar tarefa
DELETE	/tasks/<pk>	Excluir tarefa

🚀 Características Técnicas

Performance e Indexação

• Ordenação otimizada: Tarefas ordenadas por prioridade, data de vencimento e data de criação
• Índices de banco: Índices compostos para consultas eficientes por status/data e usuário/status
• Relacionamentos eficientes: Foreign keys com related_name para queries reversas otimizadas

Arquitetura

• Django Ninja: Framework moderno para APIs REST
• JWT Authentication: Autenticação stateless e segura
• OpenAPI Integration: Documentação automática e interativa
• Model Choices: Enums tipados para status e prioridades
• Soft Relationships: SET_NULL para preservar histórico quando usuários são removidos

📊 Casos de Uso

1. Criação de Tarefas: Usuários podem criar tarefas com prioridades e datas de vencimento
2. Atribuição de Trabalho: Tarefas podem ser atribuídas a usuários específicos
3. Acompanhamento de Status: Progresso das tarefas desde "Pendente" até "Finalizada"
4. Gestão de Prioridades: Sistema de três níveis para organização
5. Controle de Prazos: Rastreamento de datas de vencimento e tarefas em atraso
6. Auditoria: Timestamps automáticos para criação e atualização

🔧 Autenticação JWT

A API utiliza autenticação JWT, portanto certifique-se de:

1. Fazer login via /token para obter o token de acesso
2. Incluir o token no header: Authorization: Bearer <seu-token>
3. Renovar tokens quando necessário via /refresh

📚 Documentação Interativa

Acesse /docs para explorar a API interativamente com Swagger UI, onde você pode:

• Visualizar todos os endpoints disponíveis
• Testar requisições diretamente no navegador
• Ver schemas de dados e exemplos
• Entender os códigos de resposta HTTP

🧪 Desenvolvimento

📁 Estrutura do Projeto

api-kanban-ninja/
├── apps/                    # Contém as aplicações modulares do Django
│   ├── accounts/            # Gerenciamento de contas de usuário
│   ├── core/                # Funcionalidades e modelos compartilhados/abstratos
│   └── tasks/               # Gerenciamento de tarefas
├── config/                  # Configurações centrais do projeto Django
│   ├── settings/            # Configurações de ambiente (base, dev, prod)
│   ├── asgi.py              # Configuração ASGI
│   ├── wsgi.py              # Configuração WSGI
│   └── urls.py              # URLs principais do projeto
├── manage.py                # Utilitário de linha de comando do Django
├── pyproject.toml           # Arquivo de configuração do projeto (PEP 621) e dependências
├── README.md                # Este arquivo
└── LICENSE                  # Licença do projeto

🏗️ config/ - Configurações Centrais

config/
├── __init__.py
├── asgi.py                  # Ponto de entrada para servidores ASGI compatíveis
├── settings/                # Módulo de configurações
│   ├── __init__.py
│   ├── base.py              # Configurações base, comuns a todos os ambientes
│   ├── dev.py               # Configurações específicas para desenvolvimento
│   └── prod.py              # Configurações específicas para produção
├── urls.py                  # Declarações de URL de nível de projeto, incluindo rotas da API
└── wsgi.py 

📱 Apps - Aplicações Modulares

Cada subdiretório em apps/ representa uma aplicação Django, promovendo a separação de responsabilidades.

apps/core/ - Funcionalidades Compartilhadas

Contém código reutilizável por outras aplicações, como modelos abstratos, schemas base, e utilitários.

apps/core/
├── abstracts/               # Modelos abstratos base
│   ├── __init__.py
│   └── models.py            # Ex: TimeStampedModel para `created_at` e `updated_at`
├── api.py                   # Pode conter endpoints de API centrais/comuns ou utilitários para a API
├── apps.py                  # Configuração da aplicação Django 'core'
├── factories.py             # Factories (e.g., com Factory Boy) para criação de objetos em testes
└── schemas.py    

apps/accounts/ - Gerenciamento de Usuários

Responsável pela autenticação, autorização e gerenciamento de perfis de usuário.

apps/accounts/
├── api.py                   # Endpoints da API relacionados a contas (usando Django Ninja)
├── apps.py                  # Configuração da aplicação Django 'accounts'
├── schemas.py               # Schemas Pydantic para validação e serialização de dados de contas
└── security.py              # Lógica de segurança, como manipulação de JWT e permissões

apps/tasks/ - Gestão de Tarefas

Implementa a lógica de negócio para criação, atualização, listagem e exclusão de tarefas.

apps/tasks/
├── admin.py                 # Configuração para o Django Admin (opcional, para gerenciar tarefas via UI admin)
├── api.py                   # Endpoints da API para tarefas (usando Django Ninja)
├── apps.py                  # Configuração da aplicação Django 'tasks'
├── managers.py              # Custom QuerySet managers para o modelo Task (se houver lógicas de consulta complexas)
├── migrations/              # Migrações do banco de dados para o modelo Task
│   ├── 0001_initial.py
├── models.py                # Definição do modelo de dados Task e seus Enums
└── schemas.py               # Schemas Pydantic para validação e serialização de dados de tarefas