Este projeto é uma aplicação backend construída com FastAPI, projetada para gerenciar usuários, papéis, permissões e transações em um sistema baseado em Role-Based Access Control (RBAC). A API suporta autenticação via JWT, autorização granular, auditoria de ações e integração com um banco de dados usando SQLAlchemy como ORM.
Este projeto utiliza o FastAPI para servir uma API
Sobre o Projeto • Tecnologias • Requisitos • Arquitetura • Como Usar • Como Contribuir • Licença
Este projeto é uma aplicação backend construída com FastAPI, projetada para gerenciar usuários, papéis, permissões e transações em um sistema baseado em Role-Based Access Control (RBAC). A API suporta autenticação via JWT, autorização granular, auditoria de ações e integração com um banco de dados usando SQLAlchemy como ORM.
- Autenticação: Login de usuários com geração de tokens JWT.
- Autorização: Controle de acesso baseado em papéis e permissões.
- Gerenciamento de Usuários: Criação, atualização, listagem e exclusão de usuários.
- Gestão de Papéis e Permissões: Atribuição de papéis a usuários e permissões a papéis.
- Auditoria: Registro de informações de auditoria (usuário, IP, data de criação/atualização).
- Testes Automatizados: Suporte a testes com pytest e cobertura de código.
O projeto é estruturado para ser modular, escalável e seguir boas práticas de desenvolvimento, como separação de responsabilidades e uso de ferramentas modernas de desenvolvimento Python.
Este projeto utiliza as seguintes tecnologias e ferramentas:
- Linguagem: Python 3.12
- Framework: FastAPI - Framework web para construção de APIs.
- ORM: SQLAlchemy - Mapeamento objeto-relacional.
- Banco de Dados: SQLite - Banco de dados leve e embarcado.
- Gerenciador de Dependências: Uv Astral - Gerenciamento de dependências e ambientes virtuais.
- Migrações: Alembic - Gerenciamento de migrações de banco de dados.
- Testes: pytest com pytest-cov para cobertura de testes.
- Linting e Formatação: Ruff, Blue, e isort para manter o código limpo.
- Autenticação: python-jose para JWT e bcrypt para hash de senhas.
Para rodar ou contribuir com o projeto, você precisará das seguintes ferramentas instaladas:
| Ferramenta | Versão | Instalação (Linux/macOS) |
|---|---|---|
| Python | 3.12 | asdf install python 3.12 ou similar |
| UV | Latest | `curl -LsSf https://astral.sh/uv/install.sh |
| Git | Latest | sudo apt install git (Linux) ou brew install git (macOS) |
| SQLite | Latest | Geralmente pré-instalado, ou sudo apt install sqlite3 |
Nota: Recomendamos o uso do asdf para gerenciar versões do Python. Consulte o arquivo .python-version para a versão exata do Python utilizada.
A estrutura do projeto é organizada para promover modularidade e facilitar a manutenção. Abaixo está a organização dos arquivos e diretórios:
FastAPI/
├── app/ # Código-fonte principal da aplicação
│ ├── api/ # Definição de rotas, controladores e esquemas
│ │ ├── assignment/ # Endpoints para designações (usuário-papel)
│ │ ├── authentication/ # Endpoints para autenticação (login, JWT)
│ │ ├── authorization/ # Endpoints para autorizações (papel-transação)
│ │ ├── role/ # Endpoints para gerenciamento de papéis
│ │ ├── transaction/ # Endpoints para gerenciamento de transações
│ │ ├── user/ # Endpoints para gerenciamento de usuários
│ ├── database/ # Configuração do banco de dados (SQLAlchemy)
│ ├── models/ # Modelos ORM para as entidades do sistema
│ ├── utils/ # Funções utilitárias (segurança, configurações, etc.)
│ ├── startup.py # Inicialização da aplicação FastAPI
├── migrations/ # Scripts de migração do banco de dados (Alembic)
├── seeds/ # Scripts de seeds para a aplicação
├── tests/ # Testes automatizados (pytest)
├── DOCS/ # Documentação detalhada
├── .secrets/ # Arquivos sensíveis (ex.: SECURITY_API_SECRET_KEY)
├── .env-semple # Modelo para arquivo de configuração .env
├── alembic.ini # Configuração do Alembic
├── uv.lock # Lockfile do uv com dependências fixas
├── pyproject.toml # Configuração do projeto e dependências
├── .gitignore # Arquivos e pastas ignorados pelo Git
├── .tool-versions # Versões das ferramentas utilizadasO projeto utiliza um modelo de dados baseado em RBAC, com as seguintes entidades principais:
- User: Representa os usuários do sistema.
- Role: Papéis que definem permissões.
- Assignment: Associa usuários a papéis.
- Transaction: Operações do sistema (ex.: criar, listar, excluir).
- Authorization: Associa papéis a transações, definindo permissões.
Para informações técnicas detalhadas sobre o projeto, consulte os documentos específicos:
- Diagrama ER: DOCS/MODELS.png - Visualização completa das entidades e seus relacionamentos no banco de dados.
- Guia Completo: DOCS/PERMISSIONS.MD - Documentação detalhada sobre:
- Como um usuário novo ganha permissões
- Como criar novas permissões no sistema
- Estrutura hierárquica de roles
- Cenários práticos de uso
- Sistema de segurança e validações
- Fluxo Técnico: DOCS/FLUXOGRAMA.MD - Mapeamento completo dos fluxos da aplicação:
- Pontos de entrada (endpoints)
- Pontos de decisão (middlewares e validações)
- Pontos de saída (respostas e persistência)
- Agrupamentos naturais do sistema
- Guia Completo: DOCS/DEPLOYMENT.md - Documentação detalhada sobre:
- Configuração do ambiente de produção com Docker
- Setup com PostgreSQL e Docker Compose
- Comandos para gerenciamento de containers
- Backup e restauração do banco de dados
- Considerações de segurança e performance
- Troubleshooting de problemas comuns
Siga os passos abaixo para configurar e executar o projeto localmente.
git clone https://github.com/jvras58/FastAPI
cd FastAPIEste repositório esta organizando em um devcontainer. E para instacia-lo no VSCODE é recomendado as seguintes configurações:
- Name: Remote Development
- Id: ms-vscode-remote.vscode-remote-extensionpack
- Description: An extension pack that lets you open any folder in a container, on a remote machine, or in WSL and take advantage of VS Code's full feature set.
- Version: 0.25.0
- Publisher: Microsoft
- VSCode Marketplace Link: https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-extensionpack
É obrigatório ter o Docker Engine já instalado e cunfigurado. Para mais informações de como instalar o Docker Engine em seu SO, ver em:
- Instruções para instalação do Docker Engine: Ver o link
- Com o pack de extenções instalado,
- Realize o clone/fork deste repositório,
- Abra o diretorio deste repositorio no VSCODE como um projeto,
- Use o Comando Dev Containers: Reopen in Container da paleta de comandos do VSCODE. (F1, Ctrl+Shift+P).
Depois da compilação do container o VSCode abrirá o repositório em um ambiente encapsulado e executando diretamente de dentro do container como configurado nas definições do /.devconainer.
Crie o arquivo .env baseado no modelo fornecido:
cp .env-semple .envEdite o arquivo .env com as configurações adequadas. Exemplo:
DB_URL="sqlite:///database.db"
SECURITY_ALGORITHM="HS256"
SECURITY_ACCESS_TOKEN_EXPIRE_MINUTES=30
Crie o diretório .secrets e adicione o arquivo SECURITY_API_SECRET_KEY com um valor seguro:
mkdir .secrets
echo "SUA_CHAVE_SECRETA_AQUI" > .secrets/SECURITY_API_SECRET_KEYAtive o ambiente virtual e instale as dependências com o UV:
uv sync
uv installEntre no ambiente virtual: source activate_env.sh
Execute as migrações para criar as tabelas no banco de dados: A) aplique as migrations existentes:
alembic upgrade headb) Suba os seedings de RBAC e de usuario admin
task setup_dbInicie o servidor FastAPI com o comando:
task runA API estará disponível em:
- URL Local: http://localhost:8000
- Documentação Interativa: http://localhost:8000/api/v1/docs (Swagger UI)
- Documentação Alternativa: http://localhost:8000/api/v1/redoc (ReDoc)
Para rodar os testes automatizados e verificar a cobertura:
task testO relatório de cobertura será gerado em htmlcov/index.html.
Contribuições são sempre bem-vindas! Para contribuir com o projeto:
- Fork o repositório
- Crie uma branch para sua feature (
git checkout -b feature/nova-feature) - Commit suas mudanças (
git commit -m 'Adiciona nova feature') - Push para a branch (
git push origin feature/nova-feature) - Abra um Pull Request
- Siga as convenções de código estabelecidas
- Escreva testes para novas funcionalidades
- Mantenha a documentação atualizada
- Use mensagens de commit descritivas
Este projeto está licenciado sob a MIT License. Veja o arquivo LICENSE para mais detalhes.
Se tiver dúvidas ou sugestões, entre em contato:
- Autores: jvras jvras58@gmail.com