{"id":51151478,"url":"https://github.com/hmartiins/mvp-fullstack-backend-puc-rio","last_synced_at":"2026-06-26T06:30:55.671Z","repository":{"id":348973106,"uuid":"1193971172","full_name":"hmartiins/mvp-fullstack-backend-puc-rio","owner":"hmartiins","description":"Controle de Gastos Pessoais - MVP Puc RIO","archived":false,"fork":false,"pushed_at":"2026-04-03T17:07:45.000Z","size":7166,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T18:57:47.341Z","etag":null,"topics":["backend","flask","openapi","python","swagger"],"latest_commit_sha":null,"homepage":"","language":"Python","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/hmartiins.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-27T19:24:07.000Z","updated_at":"2026-04-03T17:10:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hmartiins/mvp-fullstack-backend-puc-rio","commit_stats":null,"previous_names":["hmartiins/mvp-fullstack-backend-puc-rio"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/hmartiins/mvp-fullstack-backend-puc-rio","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hmartiins%2Fmvp-fullstack-backend-puc-rio","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hmartiins%2Fmvp-fullstack-backend-puc-rio/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hmartiins%2Fmvp-fullstack-backend-puc-rio/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hmartiins%2Fmvp-fullstack-backend-puc-rio/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hmartiins","download_url":"https://codeload.github.com/hmartiins/mvp-fullstack-backend-puc-rio/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hmartiins%2Fmvp-fullstack-backend-puc-rio/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34806448,"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-06-26T02:00:06.560Z","response_time":106,"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":["backend","flask","openapi","python","swagger"],"created_at":"2026-06-26T06:30:54.516Z","updated_at":"2026-06-26T06:30:55.657Z","avatar_url":"https://github.com/hmartiins.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 style=\"display: flex; align-items: center; gap: 20px;\"\u003e\n\u003cimg src=\".github/assets/logo-puc-rio.png\" alt=\"PUC-Rio\" height=\"80\" align=\"middle\"/\u003e Controle de Gastos Pessoais — API\n\u003c/h1\u003e\n\nAPI REST desenvolvida em **Python + Flask** para registro e consulta de gastos pessoais organizados por categorias. Utiliza **SQLite** como banco de dados, **SQLAlchemy** como ORM e expõe documentação interativa via **OpenAPI 3.0 (Swagger UI)**.\n\n---\n\n## Funcionalidades\n\n- Cadastro e listagem de **categorias** (ex.: Alimentação, Transporte, Lazer)\n- Registro de **despesas** com valor, data e descrição vinculada a uma categoria\n- Consulta de **resumo de gastos por categoria**\n- Filtragem de despesas por **intervalo de datas**\n- Validação automática de tipos e campos obrigatórios via **Pydantic**\n- Documentação interativa disponível em `/docs/swagger`\n\n---\n\n## Pré-requisitos\n\n- **[Python 3.10](https://www.python.org/downloads/release/python-3100/)** ou superior\n- **pip3**\n\n---\n\n## Instalação\n\n### 1. Clone o repositório\n\n```bash\ngit clone https://github.com/hmartiins/mvp-fullstack-backend-puc-rio.git\ncd mvp-fullstack-backend-puc-rio\n```\n\n### 2. Crie e ative o ambiente virtual\n\n**macOS / Linux:**\n\n```bash\npython3 -m venv venv\nsource venv/bin/activate\n```\n\n**Windows:**\n\n```bash\npython -m venv venv\nvenv\\Scripts\\activate\n```\n\n### 3. Instale as dependências\n\n```bash\npip install -r requirements.txt\n```\n\n---\n\n## Iniciando o servidor\n\n```bash\npython3 app.py\n```\n\nO servidor iniciará em `http://localhost:5001`.  \nO banco de dados será criado automaticamente em `database/gastos.db` na primeira execução.\n\n---\n\n## Documentação\n\nAcesse a interface interativa (Swagger) com todos os endpoints documentados:\n\n```\nhttp://localhost:5001/docs/swagger\n```\n\n---\n\n## Rotas disponíveis\n\n### Categorias\n\n| Método   | Rota               | Descrição                  |\n| -------- | ------------------ | -------------------------- |\n| `POST`   | `/categorias`      | Cadastrar nova categoria   |\n| `GET`    | `/categorias`      | Listar todas as categorias |\n| `DELETE` | `/categorias/\u003cid\u003e` | Deletar uma categoria      |\n\n### Despesas\n\n| Método   | Rota                | Descrição                                                      |\n| -------- | ------------------- | -------------------------------------------------------------- |\n| `POST`   | `/despesas`         | Cadastrar nova despesa                                         |\n| `GET`    | `/despesas`         | Listar todas as despesas                                       |\n| `GET`    | `/despesas/\u003cid\u003e`    | Buscar despesa por ID                                          |\n| `DELETE` | `/despesas/\u003cid\u003e`    | Deletar uma despesa                                            |\n| `GET`    | `/despesas/resumo`  | Total gasto por categoria                                      |\n| `GET`    | `/despesas/periodo` | Filtrar por período (query params: `data_inicio` e `data_fim`) |\n\n---\n\n## Exemplos de uso\n\n### Criar categoria\n\n```bash\ncurl -X POST http://localhost:5001/categorias \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"nome\": \"Alimentação\", \"descricao\": \"Refeições e mercado\"}'\n```\n\n### Criar despesa\n\n```bash\ncurl -X POST http://localhost:5001/despesas \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"descricao\": \"Almoço\",\n    \"valor\": 35.50,\n    \"data\": \"2024-03-15\",\n    \"categoria_id\": \"\u003cuuid-da-categoria\u003e\"\n  }'\n```\n\n### Filtrar por período\n\n```bash\ncurl \"http://localhost:5001/despesas/periodo?data_inicio=2024-01-01\u0026data_fim=2024-12-31\"\n```\n\n---\n\n## Estrutura do projeto\n\n```\ncontrole-gastos-api/\n├── app.py                  # Configuração da aplicação e handlers globais\n├── utils.py                # Funções utilitárias\n├── requirements.txt        # Dependências Python\n├── model/\n│   └── models.py           # Modelos SQLAlchemy (Categoria, Despesa)\n├── schemas/\n│   ├── categoria.py        # Schemas Pydantic de categorias\n│   ├── despesa.py          # Schemas Pydantic de despesas\n│   └── comum.py            # Schemas de resposta compartilhados\n├── service/\n│   ├── categoria_service.py  # Lógica de negócio de categorias\n│   ├── despesa_service.py    # Lógica de negócio de despesas\n│   └── exceptions.py         # Exceções de domínio (NotFoundError, ConflictError)\n├── routes/\n│   ├── categorias/         # Endpoints de categorias\n│   └── despesas/           # Endpoints de despesas\n├── database/               # Banco de dados SQLite (gerado automaticamente)\n└── .github/\n    └── workflows/\n        └── ci.yml          # Pipeline de CI (GitHub Actions)\n```\n\n---\n\n## Banco de dados\n\nO arquivo `gastos.db` é gerado automaticamente dentro da pasta `database/`. O esquema possui duas tabelas:\n\n- **categorias** — `id` (UUID), `nome` (único), `descricao`\n- **despesas** — `id` (UUID), `descricao`, `valor`, `data`, `categoria_id` (FK → categorias)\n\nPara recriar o banco do zero:\n\n```bash\nrm -f database/gastos.db \u0026\u0026 python3 app.py\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhmartiins%2Fmvp-fullstack-backend-puc-rio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhmartiins%2Fmvp-fullstack-backend-puc-rio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhmartiins%2Fmvp-fullstack-backend-puc-rio/lists"}