{"id":30043272,"url":"https://github.com/andre-maia51/project-finances","last_synced_at":"2026-04-13T06:02:24.651Z","repository":{"id":307008000,"uuid":"1023125336","full_name":"andre-maia51/project-finances","owner":"andre-maia51","description":"API RESTful para um sistema de controle financeiro pessoal, com autenticação JWT, construída com Java, Spring Boot e totalmente containerizada com Docker.","archived":false,"fork":false,"pushed_at":"2025-08-01T23:56:46.000Z","size":57,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-07T04:57:52.805Z","etag":null,"topics":["docker","docker-compose","flyway","java","jpa","maven","postgresql","rest-api","spring-boot","spring-security-jwt"],"latest_commit_sha":null,"homepage":"","language":"Java","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/andre-maia51.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-20T15:24:42.000Z","updated_at":"2025-08-01T23:55:36.000Z","dependencies_parsed_at":"2025-07-29T00:24:41.016Z","dependency_job_id":"4a49376a-ba21-4a4e-b6b0-ab987f2c151c","html_url":"https://github.com/andre-maia51/project-finances","commit_stats":null,"previous_names":["andre-maia51/project-finances"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/andre-maia51/project-finances","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andre-maia51%2Fproject-finances","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andre-maia51%2Fproject-finances/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andre-maia51%2Fproject-finances/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andre-maia51%2Fproject-finances/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andre-maia51","download_url":"https://codeload.github.com/andre-maia51/project-finances/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andre-maia51%2Fproject-finances/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278791607,"owners_count":26046582,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-07T02:00:06.786Z","response_time":59,"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":["docker","docker-compose","flyway","java","jpa","maven","postgresql","rest-api","spring-boot","spring-security-jwt"],"created_at":"2025-08-07T04:57:50.520Z","updated_at":"2025-10-07T14:36:59.265Z","avatar_url":"https://github.com/andre-maia51.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# API de Controle de Despesas\n\n![Java](https://img.shields.io/badge/Java-21-blue?logo=openjdk)\n![Spring Boot](https://img.shields.io/badge/Spring_Boot-3.5.3-green?logo=spring)\n![PostgreSQL](https://img.shields.io/badge/PostgreSQL-blue?logo=postgresql)\n![Docker](https://img.shields.io/badge/Docker-blue?logo=docker)\n\n## 📖 Sobre o Projeto\n\nÉ uma API RESTful para gestão de finanças pessoais, desenvolvida como um projeto de aprofundamento em tecnologias de back-end modernas. A aplicação permite que utilizadores se registem, autentiquem de forma segura e giram as suas finanças pessoais através da criação de contas, categorias e lançamento de transações (receitas e despesas).\n\nO grande diferencial deste projeto é a sua arquitetura, que é inteiramente containerizada com Docker, garantindo um ambiente de desenvolvimento e produção consistente, seguro e fácil de configurar.\n\n## ✨ Features Principais\n\n-   **Ambiente Totalmente Dockerizado**: A aplicação e a base de dados PostgreSQL rodam em contentores orquestrados pelo Docker Compose, permitindo que todo o ambiente seja iniciado com um único comando.\n-   **Autenticação e Autorização com JWT**: Sistema de segurança completo usando Spring Security para proteger os endpoints. O fluxo inclui registo de utilizador com encriptação de senha (BCrypt) e um endpoint de login que gera um Token JWT para autenticação stateless.\n-   **CRUD Completo e Seguro por Utilizador**:\n    -   Gestão completa de **Contas** (`POST`, `GET`, `PUT`, `DELETE`).\n    -   Gestão completa de **Categorias** (`POST`, `GET`, `PUT`, `DELETE`).\n    -   Gestão completa de **Transações** (`POST`, `GET`, `PUT`, `DELETE`)\n-   **Regras de Negócio Robustas**: A exclusão de contas ou categorias é bloqueada caso existam transações associadas, garantindo a integridade do histórico financeiro.\n-   **Configuração Segura**: Utilização de variáveis de ambiente (`.env`) para gerir dados sensíveis, sem expor credenciais no controlo de versões.\n-   **Migrations com Flyway**: O esquema da base de dados é criado e versionado de forma automática e segura.\n\n## 🛠️ Tecnologias Utilizadas\n\n-   **Java 21**\n-   **Spring Boot 3.5.3**\n-   **Spring Security**\n-   **JWT (Auth0 Java JWT)**\n-   **Spring Data JPA**\n-   **PostgreSQL**\n-   **Flyway**\n-   **Docker \u0026 Docker Compose**\n-   **Maven**\n-   **Lombok**\n\n## 🚀 Como Executar o Projeto\n\nGraças ao Docker, configurar e executar o projeto é extremamente simples.\n\n### Pré-requisitos\n-   **Docker**\n-   **Docker Compose**\n\n### Configuração\n\n1.  **Clone o repositório:**\n    ```bash\n    git clone [https://github.com/andre-maia51/project-finances.git](https://github.com/andre-maia51/project-finances.git)\n    cd project-finances\n    ```\n\n2.  **Crie e configure o arquivo de ambiente:**\n    -   Copie o arquivo de exemplo `.env.example` para um novo arquivo chamado `.env`.\n        ```bash\n        cp .env.example .env\n        ```\n    -   Abra o arquivo `.env` e preencha as variáveis com os seus valores desejados (utilizador, senha e nome do banco de dados).\n\n3.  **Suba o ambiente com Docker Compose:**\n    ```bash\n    docker-compose up --build\n    ```\n    Este comando irá construir a imagem da sua aplicação Spring Boot, baixar a imagem do PostgreSQL e iniciar os dois contentores, já conectados e configurados.\n\nA API estará disponível em `http://localhost:8080`.\n\n## 📡 API Endpoints\n\n### Autenticação\n\n#### Registar um novo utilizador\n-   **Método**: `POST`\n-   **URL**: `/users/register`\n-   **Body**: `UserDTO`\n\n#### Fazer login\n-   **Método**: `POST`\n-   **URL**: `/login`\n-   **Body**: `LoginDTO`\n-   **Resposta**: `TokenDataDTO` com o token JWT.\n\n---\n**⚠️ Os endpoints abaixo requerem autenticação (Bearer Token).**\n---\n\n### Contas (Accounts)\n\n-   `POST /accounts`: Criar uma nova conta.\n-   `GET /accounts`: Listar todas as contas do utilizador autenticado.\n-   `GET /accounts/{id}`: Obter os detalhes de uma conta específica.\n-   `PUT /accounts/{id}`: Atualizar o nome de uma conta.\n-   `DELETE /accounts/{id}`: Apagar uma conta (só é permitido se não tiver transações associadas).\n\n### Categorias (Categories)\n\n-   `POST /categories`: Criar uma nova categoria.\n-   `GET /categories`: Listar todas as categorias do utilizador autenticado.\n-   `GET /categories/{id}`: Obter os detalhes de uma categoria específica.\n-   `PUT /categories/{id}`: Atualizar o nome e a descrição de uma categoria.\n-   `DELETE /categories/{id}`: Apagar uma categoria (só é permitido se não tiver transações associadas).\n\n### Transações (Transactions)\n\n-   `POST /transactions`: Lançar uma nova transação (receita ou despesa).\n-   `GET /transactions`: Listar todas as transações do utilizador.\n    -   **Filtro opcional:** `GET /transactions?year={ano}\u0026month={mes}`\n-   `PUT /transactions/{id}`: Atualizar os detalhes de uma transação.\n-   `DELETE /transactions/{id}`: Apagar uma transação (o saldo da conta é recalculado).\n\n## 👨‍💻 Autor\n\n**André Maia**\n\n-   **GitHub:** [@andre-maia51](https://github.com/andre-maia51)\n-   **LinkedIn:** [andre-maia-cunha](https://www.linkedin.com/in/andre-maia-cunha/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandre-maia51%2Fproject-finances","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandre-maia51%2Fproject-finances","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandre-maia51%2Fproject-finances/lists"}