Agente Cassio Dev Pro
Agente financeiro, agenda, secretária e bloco de notas em um dashboard pessoal, com IA DeepSeek e ligação direta com o Telegram.
💰 Finanças
Receitas e despesas, saldo, comparação com o mês anterior e gráficos por mês e categoria.
📅 Agenda
Calendário mensal, lembretes no app e no Telegram e resumo diário às 7h.
📝 Notas
Bloco de notas com cores, etiquetas, fixar no topo e busca.
🤖 Secretária IA
Lê texto, imagem, PDF e áudio (com transcrição) e cria lançamentos, compromissos e notas.
✈️ Telegram
Mesma secretária no Telegram, vinculada à conta por link de uso único.
🛡️ Admin
Aprovação de cadastros pelo Instagram, acesso de procurador e auditoria.
Estado atual
Arquitetura
Front Next.js no Vercel, API Spring Boot (Java 17) e PostgreSQL em container Docker.
| Camada | Tecnologia | Observações |
|---|---|---|
| Front | Next.js 15 (App Router), React 19, TypeScript, Tailwind, Recharts, NextAuth v5 | Projeto Vercel agente-cassiodevpro. Proxy /api/backend/* injeta o token da API no servidor. |
| Back | Spring Boot 3.3 (Java 17), Spring Security, JPA, Flyway, PDFBox | JWT stateless; agendamentos @Scheduled para lembretes e resumo diário. |
| Banco | PostgreSQL 16 (Docker) | Container agente-database, porta 5460 só em 127.0.0.1. |
| IA | DeepSeek (deepseek-chat), Whisper (Groq/OpenAI), modelo de visão compatível com OpenAI | A DeepSeek recebe texto; áudio e imagem são convertidos em texto antes. |
| Mensageria | Telegram Bot API (polling ou webhook), SMTP do Gmail | Desligados sem chave — nunca quebram a subida. |
| Docs | HTML + JS puro | Projeto Vercel dev-cassiodevpro. Quadro salvo na API (/api/docs/tarefas). |
Fluxo de uma requisição
Navegador ──HTTPS──▶ Vercel: Next.js (agente-cassiodevpro)
│ /api/backend/* (proxy no servidor + Bearer do cookie httpOnly)
▼
Spring Boot :8095
├─▶ PostgreSQL :5460 (Docker)
├─▶ DeepSeek api.deepseek.com/chat/completions
├─▶ Whisper (Groq / OpenAI) ← áudio
├─▶ Visão (OpenAI-compatível) ← imagens
├─▶ Telegram api.telegram.org (polling/webhook)
└─▶ Gmail SMTP (avisos de cadastro)
Banco (Flyway V1)
| Tabela | Conteúdo |
|---|---|
users | Contas (Google ou senha), papel ADMIN/USER, situação PENDING/ACTIVE/BLOCKED, Instagram, chat do Telegram |
signup_requests | Pedidos de acesso com @ do Instagram |
transactions | Receitas/despesas, categoria, data, origem (MANUAL/AI/TELEGRAM) |
events | Compromissos com lembrete |
notes | Notas |
messages | Conversa com a secretária (web + Telegram) |
notifications | Avisos do sino |
telegram_link_tokens | Convites de vínculo (só hash SHA-256) |
audit_log | Auditoria (procurador, aprovações, vínculos) |
doc_tasks | Quadro Kanban desta documentação |
Portas e ambientes
Escolhidas para não conflitar com os outros projetos desta máquina.
| Serviço | Porta | Já em uso por outros projetos |
|---|---|---|
PostgreSQL (Docker agente-database) | 5460 (127.0.0.1) | 5432 pet-adaca · 5433 · 5440 job-hunter · 5450 global-admin · 3306/3307 MySQL |
| API Java | 8095 | 8080 global-admin/pet-adaca · 8081 job-hunter · 9090 assinador local |
| Front (dev/start local) | 3035 | 3000 pet-adaca · 3010 job-hunter · 3020 global-admin |
| Ambiente | Front | API |
|---|---|---|
| Local | http://localhost:3035 | http://localhost:8095 |
| Produção | https://agente-cassiodevpro.vercel.app | https://129-121-55-185.sslip.io:8447 (VPS adaca-vps, nginx → 127.0.0.1:8095) |
| Docs | https://dev-cassiodevpro.vercel.app | |
Login e perfis
Mesmo esquema do pet-adaca: NextAuth conduz o Google e o backend valida o id_token.
- Usuário clica em Continuar com Google (NextAuth,
prompt=select_account). - O front envia o
id_tokenparaPOST /api/auth/google; a API confere assinatura, emissor, audience e e-mail verificado. - Conta ativa → a API devolve o JWT dela, que fica só no cookie httpOnly criptografado do NextAuth.
- Conta nova → vira pedido de acesso (PENDING) e o admin é avisado; a tela mostra “aguardando aprovação”.
| Perfil | Pode |
|---|---|
| Administrador | Tudo do próprio painel + Administração: aprovar/recusar pedidos, bloquear contas, acesso de procurador, auditoria, editar o quadro desta documentação. Entra também por e-mail e senha. |
| Usuário | O próprio dashboard: finanças, agenda, notas, secretária e Telegram. Dados isolados por usuário no backend. |
cassiodevpro@gmail.com. A senha não está no código: vem de ADMIN_PASSWORD no .env e é gravada com BCrypt a cada subida. No login por senha pode-se digitar só o usuário (antes do @). 5 tentativas erradas bloqueiam por 15 minutos.Acesso de procurador
O administrador entra na conta de outro usuário para ajudar, com tudo registrado.
- Administração → Usuários → Acessar como procurador.
- A API (
POST /api/admin/impersonate/{id}) emite um token de no máximo 60 minutos com o usuário alvo e o admin no campoact; a ação vai para a auditoria. - O NextAuth guarda o token do admin à parte e passa a usar o do alvo. Uma faixa rosa mostra “Modo procurador” com o botão Voltar para minha conta.
- Durante o procurador a Administração fica bloqueada (403) e cada requisição confere se o admin continua ativo.
Cadastro pelo Instagram
Novos usuários pedem acesso informando o @ do Instagram; o pedido chega ao Google do administrador.
- Tela Solicitar acesso (
/solicitar-acesso): nome, e-mail Google, Instagram (@ ou link do perfil) e mensagem. - A API normaliza o perfil (
instagram.com/fulano→@fulano), grava o pedido e avisa o admin no sino e por e-mail no Gmail (cassiodevpro@gmail.com) com o link do perfil e o link para aprovar. - O admin aprova ou recusa em Administração → Pedidos. Aprovado, o usuário recebe e-mail e entra com o Google.
Dashboard e gráficos
Visual de vidro translúcido (estilo das versões atuais da Apple) em pedra, rosa e azul, com modo claro e escuro automáticos.
- Indicadores: saldo total, receitas e despesas do mês (com variação contra o mês anterior) e resultado do mês.
- Receitas × despesas dos últimos 6 meses (barras agrupadas, azul = receitas, rosa = despesas) com dica ao passar o mouse e botão Ver tabela.
- Despesas do mês por categoria (barras horizontais ordenadas; acima de 7 categorias o resto vira “Outras”).
- Próximos compromissos e notas recentes; sino de avisos no topo.
Finanças
Receitas e despesas por mês, filtros e lançamento manual, pela IA ou pelo Telegram.
| # | Regra |
|---|---|
| RF-01 | Tipo (receita/despesa), valor > 0 com 2 casas, categoria (padrão “Outros”), descrição opcional e data (padrão hoje). |
| RF-02 | Categorias sugeridas: Salário, Freelance, Investimentos, Alimentação, Moradia, Transporte, Saúde, Educação, Lazer, Assinaturas, Compras, Impostos, Outros — mais as já usadas. |
| RF-03 | Cada lançamento guarda a origem: MANUAL, AI (secretária no app) ou TELEGRAM, exibida como etiqueta. |
| RF-04 | Consulta por período de até 3 anos; resumo calcula saldo total, mês atual, mês anterior, 6 meses e categorias. |
Dívidas de longo prazo
Cadastro das dívidas, simulação de quitação e plano diário da IA para eliminá-las.
| # | Regra |
|---|---|
| RD-01 | Cada dívida tem nome, credor, tipo (cartão, cheque especial, empréstimo, consignado, financiamento, acordo, outros), saldo devedor, juros ao mês (%), pagamento mínimo e dia de vencimento. |
| RD-02 | Nunca se abate: quando o mínimo ≤ juros do mês (saldo × taxa). A dívida fica destacada em vermelho. |
| RD-03 | Pagamento abate o saldo e, por padrão, lança a despesa em Finanças (categoria “Dívidas”). Saldo zerado = quitada. |
| RD-04 | Simulação mês a mês com juros compostos: só mínimos, avalanche (extra na de maior juro) e bola de neve (extra na de menor saldo); o mínimo de quem quita reforça a próxima. Quando nunca quita, mostra os juros dos próximos 12 meses. |
| RD-05 | Valor extra mensal: definido pelo usuário ou sugerido (metade da sobra média dos últimos 3 meses). |
| RD-06 | Plano diário da IA às 07:30 (DEBT_STRATEGY_CRON) para quem tem dívida ativa: diagnóstico, estratégia, quanto pagar em cada dívida, saídas para as que nunca se abatem (renegociação, portabilidade, troca por dívida mais barata), uso do cofrinho e uma micro-ação do dia. Vai para a tela, o sino e o Telegram (/dividas gera na hora). |
| RD-07 | Todos os números (juros, prazos, totais) são calculados no backend; a IA só interpreta e escreve, proibida de fazer contas novas. |
Cofrinho e investimentos
Dinheiro guardado com análise educativa de onde rende mais, usando as taxas oficiais do Banco Central.
| # | Regra |
|---|---|
| RC-01 | Depósitos e retiradas (retirada não pode passar do saldo); meta com nome e barra de progresso. Não entra como despesa em Finanças. |
| RC-02 | Taxas do Banco Central (API SGS, cache de 6 h): Selic meta (432), CDI anualizado (4389), IPCA 12 meses (13522), poupança no mês (195). |
| RC-03 | Comparação em 12 meses, líquida de IR regressivo: poupança, Tesouro Selic, CDB 100% CDI (liquidez diária), CDB 110% CDI (prazo), LCI/LCA 90% CDI (isentas) e Tesouro IPCA+. |
| RC-04 | Todo depósito dispara a análise da IA (tela, sino e Telegram; /cofrinho gera na hora): primeiro compara com os juros das dívidas, depois reserva de emergência (6× gasto médio) com liquidez diária, e o excedente em prazos maiores. |
| RC-05 | Conteúdo educativo, sem citar bancos ou produtos de marca, sempre com o aviso: não é recomendação de investimento; decisões grandes com profissional certificado (CVM/ANBIMA). |
Agenda e lembretes
Calendário mensal com lista do dia, cores e lembretes.
| # | Regra |
|---|---|
| RA-01 | Título e início obrigatórios; fim depois do início; “dia todo” opcional; local, descrição e cor (azul, rosa, pedra, verde, laranja, roxo). |
| RA-02 | Lembrete: sem, na hora, 10 min, 30 min, 1 h ou 1 dia antes (até 7 dias). Mudou o horário, o lembrete volta a valer. |
| RA-03 | A cada minuto (REMINDERS_CRON) os lembretes vencidos vão para o sino e para o Telegram (se vinculado), uma vez só. |
| RA-04 | Todo dia às 07:00 (DAILY_SUMMARY_CRON) quem tem Telegram recebe os compromissos do dia e o saldo. |
| RA-05 | Compromissos criados pela IA saem em rosa com lembrete de 30 min (ajustável). |
| RA-06 | Google Agenda: cada usuário conecta qualquer conta Google (botão na tela Agenda, mediante autorização do escopo calendar.events). Criar, editar ou excluir — no app, pela IA ou pelo Telegram — reflete na agenda principal dessa conta, com lembrete e cor. Ao conectar, os compromissos dos próximos 6 meses são enviados. |
| RA-07 | A sincronização roda em segundo plano: falha no Google nunca impede salvar no app; a última falha aparece no cartão. Autorização revogada no Google desconecta e avisa no sino. |
| RA-08 | Tokens do Google criptografados no banco (AES-256-GCM); “state” do OAuth assinado, 10 min, sem valor como sessão. Desconectar revoga o acesso no Google. |
http://localhost:8095/api/google-calendar/callback e https://129-121-55-185.sslip.io:8447/api/google-calendar/callback; ativar a Google Calendar API; incluir o escopo calendar.events na tela de consentimento. Variáveis do backend: GOOGLE_CLIENT_SECRET e BACKEND_PUBLIC_URL.Bloco de notas
Notas com título, texto, etiquetas, cor e fixar no topo.
- Busca em título, conteúdo e etiquetas (sem diferenciar maiúsculas).
- Fixadas primeiro, depois as editadas mais recentemente.
- “anota: …”, áudios longos e PDFs que você pedir para resumir viram notas pela secretária.
Secretária IA (DeepSeek)
Entende o que você escreve, fala ou envia e grava os dados no backend.
Como o anexo vira texto
| Entrada | Como é lido | Chave |
|---|---|---|
| Texto | Direto para a DeepSeek | DEEPSEEK_API_KEY |
| Áudio (voz do Telegram, gravação no app, mp3/m4a/ogg/webm) | Transcrição Whisper em português | TRANSCRIPTION_API_KEY |
| Imagem (comprovante, nota fiscal, print) | Modelo de visão transcreve e descreve valores, datas e itens | VISION_API_KEY |
| PDF (fatura, extrato, boleto) | PDFBox extrai o texto (até 30 páginas / 15 mil caracteres) | — |
| TXT, CSV, OFX | Lido como texto | — |
Resposta estruturada
A DeepSeek responde em JSON (response_format: json_object) com uma mensagem e uma lista de ações, e o backend grava cada uma:
{"reply": "Lancei R$ 52,90 em Alimentação e marquei o dentista na sexta às 14h.",
"actions": [
{"type":"transaction","kind":"EXPENSE","amount":52.90,"category":"Alimentação","description":"Mercado","date":"2026-10-17"},
{"type":"event","title":"Dentista","start":"2026-10-23T14:00","reminder_minutes":30},
{"type":"note","title":"Ideia","content":"…","tags":"ideias"}
]}
- O prompt leva data/hora atuais, categorias, saldo, gastos do mês, próximos compromissos e notas recentes — assim perguntas como “qual meu saldo?” são respondidas sem criar nada.
- Comprovantes e faturas viram um lançamento por valor; boletos futuros geram também um compromisso no vencimento.
- Últimas 12 mensagens entram como histórico; no máximo 30 ações por resposta.
- Sem
DEEPSEEK_API_KEY, a secretária avisa e mostra o texto lido do anexo.
Telegram
Ligação direta app ↔ Telegram, com o mesmo histórico da secretária.
- Crie o bot no @BotFather e cole o token em
TELEGRAM_BOT_TOKEN. Reinicie a API. - No app: Telegram → Conectar Telegram. A API gera um token aleatório de 192 bits (vale 15 min, uso único, guardado só como hash) e abre
t.me/SEU_BOT?start=TOKEN. - Ao tocar em Iniciar, o bot recebe
/start TOKENe liga o chat à conta. A página do app confirma sozinha.
| No Telegram | O que acontece |
|---|---|
| Texto livre | Vai para a secretária (cria lançamentos, compromissos, notas ou responde) |
| 🎙️ Voz / áudio | Transcreve, mostra a transcrição e processa |
| 📷 Foto | Lê com visão e processa (maior resolução enviada) |
| 📄 Documento | PDF, imagem, áudio ou texto até 20 MB |
/saldo /hoje /semana /notas /ajuda | Respostas rápidas sem IA |
TELEGRAM_MODE=webhook, TELEGRAM_WEBHOOK_URL=https://SUA-API/api/telegram/webhook e TELEGRAM_WEBHOOK_SECRET (32+ caracteres). Só uma instância por token pode fazer polling.Variáveis e chaves
Backend: .env na raiz (modelo em .env.example). Front: frontend/.env.local ou Environment Variables no Vercel.
Backend
| Variável | Para quê |
|---|---|
DB_PASSWORD, DB_PORT=5460 | Banco Docker |
JWT_SECRET | Assinatura dos tokens (32+ caracteres; openssl rand -base64 48) |
ADMIN_EMAIL, ADMIN_PASSWORD | Administrador (senha só no .env) |
GOOGLE_CLIENT_ID | Mesmo Client ID do front; valida o id_token |
DEEPSEEK_API_KEY | Chave da DeepSeek (DEEPSEEK_MODEL=deepseek-chat) |
TRANSCRIPTION_PROVIDER, TRANSCRIPTION_API_KEY | Áudio → texto (groq ou openai) |
VISION_BASE_URL, VISION_API_KEY, VISION_MODEL | Imagem → texto |
TELEGRAM_BOT_TOKEN, TELEGRAM_MODE | Bot do Telegram |
MAIL_ENABLED, SMTP_USERNAME, SMTP_PASSWORD | Gmail com senha de app (avisos de cadastro) |
FRONTEND_URL, CORS_ORIGINS | Links nos e-mails/Telegram e origens do site de docs |
Front (Vercel)
| Variável | Para quê |
|---|---|
BACKEND_URL | URL da API (HTTPS em produção). Só o servidor do Next usa. |
AUTH_SECRET | Criptografia do cookie de sessão (openssl rand -base64 32) |
AUTH_GOOGLE_ID, AUTH_GOOGLE_SECRET | OAuth do Google |
AUTH_URL, AUTH_TRUST_HOST=true | URL pública do front |
http://localhost:3035/api/auth/callback/google e https://agente-cassiodevpro.vercel.app/api/auth/callback/google.Rodar e publicar
Local
# 1) Banco (porta 5460)
docker compose up -d database
# 2) API (porta 8095) — lê o .env da raiz
cd backend && mvn spring-boot:run
# 3) Front (porta 3035)
cd frontend && cp .env.example .env.local && npm install && npm run dev
API em container
docker compose --profile api up -d --build # banco + API
Vercel
cd frontend && vercel --prod # projeto agente-cassiodevpro
cd docs-site && vercel --prod # projeto dev-cassiodevpro
VPS (produção)
docker compose --profile api build backend
docker save agente-backend:latest | gzip -1 | ssh adaca-vps 'gunzip | docker load'
scp docker-compose.yml docker-compose.prod.yml adaca-vps:/opt/agente-financeiro/
ssh adaca-vps 'cd /opt/agente-financeiro && docker compose -f docker-compose.yml -f docker-compose.prod.yml --profile api up -d --no-build'
.env de produção fica só na VPS (/opt/agente-financeiro/.env, permissão 600, segredos próprios). nginx em /etc/nginx/sites-available/agente-financeiro (porta 8447, liberada no ufw).No site de documentação, o endereço da API do quadro fica no topo de app.js (API). Sem API acessível, o quadro mostra a cópia local, em modo leitura.
API (endpoints)
Base /api. Todas exigem Bearer, exceto as marcadas como públicas.
| Rota | Quem |
|---|---|
POST /auth/login · POST /auth/google | Público |
GET /auth/me | Logado (traz actor no modo procurador) |
POST /public/signup-requests | Público (5 por IP / 15 min) |
GET/POST /finance/transactions · PUT/DELETE /finance/transactions/{id} · GET /finance/summary · GET /finance/categories | Logado |
GET /agenda/events?from&to · GET /agenda/upcoming · POST/PUT/DELETE /agenda/events | Logado |
GET/POST /notes · PUT/DELETE /notes/{id} · GET /notes?q= | Logado |
POST /assistant/chat (multipart: text, file) · GET/DELETE /assistant/messages | Logado |
GET /telegram/status · POST/DELETE /telegram/link | Logado |
POST /telegram/webhook | Telegram (header secret) |
GET /notifications · GET /notifications/unread · POST /notifications/{id}/read · POST /notifications/read-all | Logado |
GET /integrations | Logado (só indica o que está ligado) |
GET /admin/users · PATCH /admin/users/{id} · GET /admin/signup-requests · POST …/{id}/approve|reject · POST /admin/impersonate/{id} · GET /admin/audit | Administrador |
GET /docs/tarefas | Público |
POST /docs/tarefas · PUT/DELETE /docs/tarefas/{id} | Administrador |
Segurança
- Senha do admin só no
.env(fora do git), gravada com BCrypt (custo 12). - Token da API nunca chega ao JavaScript do navegador: fica no cookie httpOnly criptografado do NextAuth e o proxy do Next injeta o Bearer.
- JWT verificado a cada requisição + conferência no banco se a conta (e o admin, no procurador) continua ativa.
- Dados isolados por usuário em todas as consultas; recurso de outro usuário responde 404.
- Procurador limitado a 60 min, sem acesso à Administração, auditado.
- Banco preso em 127.0.0.1; chaves de IA/Telegram nunca saem do backend nem aparecem em logs.
- Vínculo do Telegram por token de uso único (hash SHA-256, 15 min); webhook com secret comparado em tempo constante.
- Limite de tentativas no login e no formulário de cadastro.
Quadro Kanban
Pendências e entregas do projeto. Leitura pública; edição com o login do administrador.