{"id":34595235,"url":"https://github.com/klebersoncollab/fastapibase","last_synced_at":"2026-05-27T06:01:34.981Z","repository":{"id":304706886,"uuid":"1018367289","full_name":"KlebersonCollab/FastAPIBase","owner":"KlebersonCollab","description":"Base Project using FastAPI","archived":false,"fork":false,"pushed_at":"2025-07-15T03:37:26.000Z","size":666,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-12-25T23:01:54.164Z","etag":null,"topics":["fastapi","python","rbac"],"latest_commit_sha":null,"homepage":"https://klebersoncollab.github.io/FastAPIBase/","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KlebersonCollab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-12T05:39:41.000Z","updated_at":"2025-07-15T03:37:29.000Z","dependencies_parsed_at":"2025-07-14T22:35:41.376Z","dependency_job_id":"2462dfc2-af45-4893-8876-4390e12285e7","html_url":"https://github.com/KlebersonCollab/FastAPIBase","commit_stats":null,"previous_names":["klebersoncollab/fastapibase"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/KlebersonCollab/FastAPIBase","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KlebersonCollab%2FFastAPIBase","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KlebersonCollab%2FFastAPIBase/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KlebersonCollab%2FFastAPIBase/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KlebersonCollab%2FFastAPIBase/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KlebersonCollab","download_url":"https://codeload.github.com/KlebersonCollab/FastAPIBase/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KlebersonCollab%2FFastAPIBase/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33553127,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-27T02:00:06.184Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fastapi","python","rbac"],"created_at":"2025-12-24T11:31:03.386Z","updated_at":"2026-05-27T06:01:34.917Z","avatar_url":"https://github.com/KlebersonCollab.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![CI](https://github.com/KlebersonCollab/FastAPIBase/actions/workflows/ci.yml/badge.svg)](https://github.com/KlebersonCollab/FastAPIBase/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n![Python](https://img.shields.io/badge/python-3.11%2B-blue)\n[![codecov](https://codecov.io/gh/KlebersonCollab/FastAPIBase/branch/master/graph/badge.svg)](https://codecov.io/gh/KlebersonCollab/FastAPIBase)\n[![GitHub Pages](https://img.shields.io/badge/docs-online-blue?logo=github)](https://klebersoncollab.github.io/FastAPIBase/)\n\n\u003e Documentação oficial: [https://klebersoncollab.github.io/FastAPIBase/](https://klebersoncollab.github.io/FastAPIBase/)\n\n# FastAPI Core – Documentação Completa\n\n## Índice\n\n- [Visão Geral](#visão-geral)\n- [Estrutura do Projeto](#estrutura-do-projeto)\n- [Configuração Inicial](#configuração-inicial)\n- [Ambientes e Variáveis](#ambientes-e-variáveis)\n- [Comandos Essenciais](#comandos-essenciais)\n- [CLI Administrativo (fast_admin.py)](#cli-administrativo-fast_adminpy)\n- [Autenticação e Autorização (RBAC)](#autenticação-e-autorização-rbac)\n- [Refresh Tokens](#refresh-tokens)\n- [Gestão de Usuários, Roles e Permissões](#gestão-de-usuários-roles-e-permissões)\n- [Criação de Novos Apps/Módulos](#criação-de-novos-appsmódulos)\n- [Migrações de Banco de Dados (Aerich)](#migrações-de-banco-de-dados-aerich)\n- [Exemplo de Fluxo Completo](#exemplo-de-fluxo-completo)\n- [CI/CD e Qualidade](#cicd-e-qualidade)\n- [Dicas de Manutenção e Boas Práticas](#dicas-de-manutenção-e-boas-práticas)\n- [Segurança](#segurança)\n\n---\n\n## Visão Geral\n\nEste projeto é um boilerplate FastAPI inspirado no Django, com:\n- Estrutura modular para apps plugáveis\n- Autenticação JWT com Refresh Tokens e rotação segura\n- RBAC (roles + permissions)\n- Migrações automáticas com Aerich\n- CLI administrativo moderno (`fast_admin.py`)\n- **Configuração por ambiente**: `.env.dev`, `.env.prod`, `.env.test`\n- **CI/CD**: Pipeline GitHub Actions para lint, testes e build Docker\n- **Arquitetura modular**: cada domínio (ex: auth, users) possui suas próprias camadas (routers, services, repositories, models, schemas, etc.)\n- **Logging estruturado**: eventos críticos logados em JSON\n\n---\n\n## Estrutura do Projeto\n\n```\n.\n├── core/\n│   ├── main.py                # Inicialização do FastAPI\n│   ├── config.py              # Configuração de lifespan e middlewares\n│   ├── routers.py             # Inclusão centralizada dos routers dos módulos\n│   ├── settings.py            # Configurações (Pydantic, multi-ambiente)\n│   ├── auth/                  # Módulo de autenticação e RBAC\n│   │   ├── routers.py         # Rotas/endpoints do módulo\n│   │   ├── services.py        # Lógica de negócio do módulo\n│   │   ├── repositories.py    # Acesso a dados do módulo\n│   │   ├── models.py\n│   │   ├── schemas.py\n│   │   ├── permissions.py\n│   ├── users/                 # Módulo de usuários\n│   │   ├── routers.py\n│   │   ├── services.py\n│   │   ├── repositories.py\n│   │   ├── models.py\n│   │   ├── schemas.py\n│   ├── security/              # Utilitários de segurança\n│   │   └── security.py\n├── migrations/                # Migrações do Aerich\n├── pyproject.toml             # Dependências e config do Aerich\n├── aerich.ini                 # Configuração do Aerich\n├── fast_admin.py              # CLI administrativo (criação de superusuário, migrações, etc)\n├── .env.dev/.env.prod/.env.test # Configs por ambiente\n├── .github/workflows/ci.yml   # Pipeline CI/CD\n└── README.md                  # (você está aqui!)\n```\n\n---\n\n## Configuração Inicial\n\n1. **Instale as dependências:**\n   ```bash\n   uv pip install --system .\n   ```\n\n2. **Configure o ambiente:**\n   - Defina a variável `ENV` para `dev`, `prod` ou `test`.\n   - O settings carrega automaticamente `.env.dev`, `.env.prod` ou `.env.test`.\n   - Exemplo para desenvolvimento:\n     ```bash\n     export ENV=dev\n     cp .env.dev .env.dev  # Edite conforme necessário\n     ```\n\n3. **Configure o banco de dados:**\n   - Por padrão, usa SQLite (`sqlite://db.sqlite3`).\n   - Para usar Postgres, edite `.env.prod` e defina `DATABASE_URL`.\n\n---\n\n## Ambientes e Variáveis\n\n- `.env.dev` – Desenvolvimento\n- `.env.prod` – Produção\n- `.env.test` – Testes automatizados\n\nExemplo de `.env.dev`:\n```\nSECRET_KEY=dev-secret-key\nDATABASE_URL=sqlite://db.sqlite3\nREDIS_URL=redis://localhost:6379/0\nAPI_KEYS=[\"dev-api-key\"]\n```\n\n---\n\n## Comandos Essenciais\n\n### Instalar dependências\n```bash\nuv pip install --system .\n```\n\n### Rodar o servidor\n```bash\nuv run uvicorn core.main:app --reload\n```\n\n### Rodar Testes\n```bash\nENV=test PYTHONPATH=. uv run pytest\n```\n\n---\n\n## CLI Administrativo (`fast_admin.py`)\n\nO CLI oferece comandos para administração do projeto:\n\n- **Criar superusuário:**\n  ```bash\n  uv run python fast_admin.py createsuperuser\n  ```\n- **Rodar migrações:**\n  ```bash\n  uv run python fast_admin.py migrate\n  ```\n- **Inicializar banco:**\n  ```bash\n  uv run python fast_admin.py init-db\n  ```\n\nVocê pode expandir o CLI facilmente para outros comandos administrativos.\n\n---\n\n## Autenticação e Autorização (RBAC)\n\n- **Login:**  `POST /auth/token` (OAuth2, retorna JWT e Refresh Token)\n- **Proteção de rotas:**  Use o decorator `Depends(check_permissions([Permissions.X]))` para exigir permissões.\n- **Roles:**  Usuários podem ter múltiplas roles, cada role tem permissões.\n- **Permissões disponíveis:**  Veja em `core/auth/permissions.py`.\n- **Alteração de senha:**  `POST /users/me/change-password`\n- **Recuperação de senha:**  `POST /auth/request-password-reset` e `POST /auth/reset-password`\n- **Atualização de perfil:**  `PATCH /users/me` (restrito a campos não sensíveis)\n\n---\n\n## Refresh Tokens\n\n- **Obtenção:** Ao fazer login em `POST /auth/token`, você receberá um `refresh_token` junto com o `access_token`.\n- **Uso:** Utilize o `refresh_token` para obter um novo `access_token` sem precisar fazer login novamente.\n  `POST /auth/refresh` (envie o `refresh_token` no corpo da requisição).\n- **Rotação e revogação:** Tokens são rotacionados a cada uso e revogados imediatamente, com blacklist persistente em Redis.\n\n---\n\n## Gestão de Usuários, Roles e Permissões\n\n### Usuários\n- CRUD completo em `/users/` (exceto campos sensíveis)\n- Alteração de senha e perfil via endpoints próprios\n\n### Roles\n- Criar role: `POST /auth/roles/`\n- Listar roles: `GET /auth/roles/`\n- Atualizar role: `PUT /auth/roles/{role_id}`\n- Deletar role: `DELETE /auth/roles/{role_id}`\n\n### Permissões\n- Definidas em `core/auth/permissions.py`.\n\n### Atribuir/Revogar Roles de Usuários\n- Atribuir role: `POST /auth/users/{user_id}/roles/{role_id}`\n- Revogar role: `DELETE /auth/users/{user_id}/roles/{role_id}`\n\n---\n\n## Criação de Novos Apps/Módulos\n\n1. Crie um diretório dentro de `core/` (ex: `blog/`).\n2. Adicione arquivos `models.py`, `routers.py`, `schemas.py`, `services.py`, `repositories.py` conforme necessário.\n3. Importe e inclua o router no `core/routers.py`.\n4. Adicione os models no `TORTOISE_ORM` em `main.py`.\n\n\u003e **Dica:** Mantenha a separação entre routers, services e repositories para garantir testabilidade e organização.\n\n---\n\n## Migrações de Banco de Dados (Aerich)\n\n- **Configuração:**  Veja `aerich.ini` e `pyproject.toml`.\n- **Comandos:**\n  ```bash\n  uv run python fast_admin.py migrate\n  uv run python fast_admin.py init-db\n  ```\n- **Exemplo de migração:**  Veja arquivos em `migrations/`.\n\n---\n\n## Exemplo de Fluxo Completo\n\n1. **Clone o projeto e instale dependências**\n2. **Configure o ambiente e banco**\n3. **Crie superusuário**\n4. **Rode o servidor**\n5. **Acesse `/docs` para testar a API**\n6. **Crie apps, roles, atribua permissões e usuários conforme necessário**\n\n---\n\n## CI/CD e Qualidade\n\n- **Pipeline GitHub Actions**: Lint (Black, Ruff), testes automatizados, build Docker.\n- **Ambiente de testes isolado**: `.env.test` criado dinamicamente no CI.\n- **Comandos do workflow:**\n  - Lint: `uv run black --check .` e `uv run ruff check .`\n  - Testes: `ENV=test PYTHONPATH=. uv run pytest`\n  - Build Docker: `docker build -t fastapibase:ci .`\n- **Deploy:** Pronto para integração com Docker Hub ou outro registry (ajuste o workflow conforme sua infra).\n\n---\n\n## Dicas de Manutenção e Boas Práticas\n\n- Use sempre ambientes separados para dev, prod e test.\n- Rode lint e testes localmente antes de subir código.\n- Use o CLI para tarefas administrativas e migrações.\n- Proteja endpoints sensíveis com permissões.\n- Documente e versiona suas APIs.\n- Use logging estruturado para auditoria e troubleshooting.\n- Teste sempre em ambiente de desenvolvimento antes de ir para produção.\n\n---\n\n## Segurança\n\n- **Rotação e revogação de refresh tokens:**\n  - Tokens de refresh são rotacionados a cada uso e revogados imediatamente.\n  - Blacklist persistente em Redis impede reuso de tokens revogados.\n- **Logging estruturado:**\n  - Todos os eventos críticos de autenticação e revogação são logados em JSON com structlog.\n- **Testes automatizados de segurança:**\n  - Testes para brute force, privilege escalation e ausência de CSRF.\n- **Proteções adicionais:**\n  - CORS restritivo, TrustedHostMiddleware, GZipMiddleware, Rate Limiting, Headers de segurança, autenticação JWT.\n- **Ambiente seguro:**\n  - Use HTTPS em produção, configure variáveis sensíveis apenas em `.env.prod`.\n\n---\n\n**Este README cobre toda a estrutura, comandos, RBAC, migrações, CLI, ambientes, CI/CD, segurança e melhores práticas do seu projeto FastAPI!**\nSe quiser exemplos de payloads, fluxos de autenticação ou integração com frontend, posso complementar ainda mais.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fklebersoncollab%2Ffastapibase","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fklebersoncollab%2Ffastapibase","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fklebersoncollab%2Ffastapibase/lists"}