npm package: @marcos_feitoza/personal-finance-market-data-crypto
Description: Este projeto é um microsserviço independente responsável por buscar dados de mercado para criptomoedas.
Latest version: 1.0.6

# Serviço de Dados de Mercado (Cripto) - Personal Finance

Este projeto é um microsserviço independente responsável por buscar dados de mercado para criptomoedas.

## Propósito

Este serviço atua como um proxy e um adaptador para a API da **CoinGecko**. Sua responsabilidade é fornecer dados de mercado, como preços ao vivo e validação de ativos, para outros serviços no sistema, centralizando a lógica de acesso a dados de criptomoedas em um único lugar.

Em produção, o acesso do frontend deve ocorrer via `backend-core` (`/api/core-crypto/*`), mantendo este serviço como backend interno.

## Tecnologias

- **Framework**: FastAPI
- **Fonte de Dados**: Biblioteca `pycoingecko`
- **Deploy**: Docker & Kubernetes (via Helm)
- **Dependências Locais**:
  - `personal-finance-backend-shared`: Para utilitários compartilhados, como o de logging.

---

## Como Começar

### Pré-requisitos

- Python 3.9+
- Docker
- Acesso ao repositório `personal-finance-backend-shared` no mesmo nível de diretório.

### Instalação

1.  Navegue até o diretório raiz do monorepo.
2.  Instale as dependências. O uso de um ambiente virtual (`venv`) é recomendado.
    ```bash
    pip install -r personal-finance-backend-market-data-crypto/requirements.txt
    ```
    *Nota: O `requirements.txt` deste serviço espera que a `personal-finance-backend-shared` seja instalada em modo editável.*

---

## Como Executar

### Localmente para Desenvolvimento

A partir do diretório raiz (`finace`), execute o seguinte comando para iniciar o servidor com hot-reload:

```bash
uvicorn personal-finance-backend-market-data-crypto.app.main:app --reload --app-dir .
```
Isso iniciará o serviço em `http://127.0.0.1:8000`.

### Via Docker (Produção)

1.  Navegue para o diretório deste serviço (`personal-finance-backend-market-data-crypto`).
2.  O script `dockerbuild.sh` automatiza o processo de:
    - Copiar a biblioteca compartilhada para um diretório local temporário.
    - Construir a imagem Docker multiplataforma.
    - Publicar a imagem no Docker Hub.
    ```bash
    ./dockerbuild.sh
    ```
3.  O deploy no Kubernetes é gerenciado pelo Argo CD a partir do Helm chart em `/helm`.

---

## Estrutura da API

- **`GET /api/crypto/prices`**: Busca os preços atuais para uma lista de IDs de criptomoedas.
  - **Exemplo**: `/api/crypto/prices?ids=bitcoin,ethereum`
  - **Resposta**:
    ```json
    {
      "bitcoin": 68000.50,
      "ethereum": 3500.25
    }
    ```

- **`GET /api/crypto/validate/{query}`**: Valida uma criptomoeda por ID, símbolo ou nome.
  - **Exemplo**: `/api/crypto/validate/btc`
  - **Resposta**:
    ```json
    {
      "id": "bitcoin",
      "symbol": "btc",
      "name": "Bitcoin"
    }
    ```

- **`GET /api/crypto/health`**: Endpoint de Health Check.

## Logging

O serviço utiliza um sistema de **logging estruturado (JSON)** centralizado na `personal-finance-backend-shared`.

- **Correlation ID**: Todas as requisições que chegam com um header `X-Correlation-ID` (propagado pelo `core-service`) usarão este ID em todos os seus logs. Se nenhuma ID for recebida, uma nova será gerada. Isso permite rastrear uma operação através de todos os microsserviços.
- **Filtragem**: Por ser JSON, os logs são facilmente pesquisáveis e filtráveis em ferramentas de monitoramento.

## Resiliência (estado atual)

- Erros de rate-limit da CoinGecko (`429`) são tratados explicitamente.
- Falhas inesperadas preservam logging com stack trace para facilitar diagnóstico.