# Agente Financeiro

Aplicativo de finanças pessoais com interface mobile, API própria e integração
com agentes de IA. O projeto nasceu como laboratório de estudos sobre FastAPI,
React Native, OpenWebUI e Model Context Protocol (MCP), mas também busca resolver
um problema real: registrar gastos em linguagem natural e acompanhar o orçamento
mensal.

> **Status:** em desenvolvimento. O fluxo local funciona, mas autenticação
> multiusuário e RLS ainda estão em implementação. Não use em produção nem
> armazene dados financeiros sensíveis antes de concluir os itens de segurança.

## Funcionalidades

- Registro, consulta, busca e exclusão de gastos.
- Salário fixo, meta de economia e saldo mensal disponível.
- Relatório e limite de gastos por categoria.
- Alertas quando uma categoria se aproxima ou ultrapassa seu orçamento.
- Conversa em linguagem natural por meio do OpenWebUI.
- Servidor MCP Streamable HTTP com nove ferramentas financeiras.
- Persistência no PostgreSQL do Supabase.

## Arquitetura

```text
Expo / React Native
        |
        v
FastAPI REST  <------  servidor MCP  <------  cliente de IA
        |
        v
Supabase PostgreSQL + Auth + RLS
```

A arquitetura final manterá o OpenWebUI invisível atrás da FastAPI. Dessa forma,
a chave do OpenWebUI permanece no servidor e o aplicativo envia apenas o access
token do usuário autenticado no Supabase.

Leia [a explicação do MCP](docs/MCP.md) para entender o protocolo e o caminho de
uma chamada de ferramenta.

## Tecnologias

| Camada | Tecnologias |
| --- | --- |
| Mobile | Expo SDK 54, React Native 0.81, React 19, TypeScript |
| API | Python 3.12, FastAPI, Pydantic, Supabase SDK |
| Agente | OpenWebUI e MCP Python SDK 2.1 |
| Dados | Supabase/PostgreSQL |
| Infraestrutura | Docker Compose e GitHub Actions |

## Estrutura do repositório

```text
.
├── backend/                 # API FastAPI, MCP, testes e migrações SQL
│   ├── app/
│   ├── migrations/
│   └── tests/
├── frontend/                # Aplicativo Expo/React Native
├── docs/                    # Arquitetura, MCP e roadmap
├── docker-compose.yml       # API
└── docker-compose.mcp.yml   # Extensão do Compose para o MCP
```

## Pré-requisitos

- Docker com Docker Compose; ou
- Python 3.12 e Node.js 20.19 ou superior dentro da versão 20.
- Um projeto Supabase.
- OpenWebUI somente para testar o chat com IA.

## Configuração local

### 1. Backend

```bash
cp backend/.env.example backend/.env
```

Preencha no arquivo local:

```dotenv
SUPABASE_URL=https://SEU_PROJETO.supabase.co
SUPABASE_KEY=SUA_CHAVE_ANON_OU_PUBLISHABLE
```

Nunca envie `.env`, access tokens, JWT secrets ou chaves administrativas para o
GitHub.

Para executar API e MCP juntos:

```bash
docker compose -f docker-compose.yml -f docker-compose.mcp.yml up --build
```

- Documentação da API: <http://localhost:8000/docs>
- Healthcheck da API: <http://localhost:8000/health>
- Endpoint MCP: <http://localhost:8001/mcp>
- Healthcheck do MCP: <http://localhost:8001/health>

### 2. Frontend

```bash
cp frontend/.env.example frontend/.env
cd frontend
npm ci
npm start
```

Troque `EXPO_PUBLIC_LOCAL_IP` pelo IP da máquina que executa a API. Variáveis
`EXPO_PUBLIC_*` são incluídas no aplicativo compilado e nunca devem conter
segredos.

O chat atual ainda usa a integração direta de desenvolvimento com o OpenWebUI.
Antes de uma distribuição real, ele será substituído pela rota protegida
`/agent` da FastAPI.

## Testes

Backend:

```bash
cd backend
python -m pip install -r requirements-mcp.txt
pytest
```

Frontend:

```bash
cd frontend
npm ci
npx tsc --noEmit
npx expo-doctor
```

Cada pull request executa verificações automáticas no GitHub Actions.

## Banco de dados e RLS

As migrações ficam em `backend/migrations/`. A migração
`002_multi_user_rls.sql` contém um placeholder proposital e **não deve ser
executada** até que o backend encaminhe corretamente o JWT Supabase ao PostgREST.

Ordem planejada:

1. Implementar login pelo Supabase Auth.
2. Criar um cliente Supabase isolado por requisição.
3. Migrar os registros existentes para o UUID do proprietário.
4. Ativar e testar as políticas RLS com dois usuários diferentes.

## Contribuição

Consulte [CONTRIBUTING.md](CONTRIBUTING.md) para convenções de branches, commits,
testes e pull requests.

## Segurança

Este projeto manipula informações financeiras. Não publique dados reais em
issues, logs, screenshots ou fixtures. Leia [SECURITY.md](SECURITY.md) antes de
relatar uma vulnerabilidade.

## Roadmap

O planejamento técnico está em [docs/ROADMAP.md](docs/ROADMAP.md).

## Licença

Nenhuma licença de código aberto foi escolhida ainda. Até que um arquivo
`LICENSE` seja adicionado, todos os direitos permanecem reservados ao autor.