dev-cassiodevpro

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

Código completo e testado localmente: API Java, banco em Docker, front Next.js e esta documentação. As integrações externas estão prontas e aguardando só as chaves — veja Variáveis e chaves e o quadro.

Arquitetura

Front Next.js no Vercel, API Spring Boot (Java 17) e PostgreSQL em container Docker.

CamadaTecnologiaObservações
FrontNext.js 15 (App Router), React 19, TypeScript, Tailwind, Recharts, NextAuth v5Projeto Vercel agente-cassiodevpro. Proxy /api/backend/* injeta o token da API no servidor.
BackSpring Boot 3.3 (Java 17), Spring Security, JPA, Flyway, PDFBoxJWT stateless; agendamentos @Scheduled para lembretes e resumo diário.
BancoPostgreSQL 16 (Docker)Container agente-database, porta 5460 só em 127.0.0.1.
IADeepSeek (deepseek-chat), Whisper (Groq/OpenAI), modelo de visão compatível com OpenAIA DeepSeek recebe texto; áudio e imagem são convertidos em texto antes.
MensageriaTelegram Bot API (polling ou webhook), SMTP do GmailDesligados sem chave — nunca quebram a subida.
DocsHTML + JS puroProjeto 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)

TabelaConteúdo
usersContas (Google ou senha), papel ADMIN/USER, situação PENDING/ACTIVE/BLOCKED, Instagram, chat do Telegram
signup_requestsPedidos de acesso com @ do Instagram
transactionsReceitas/despesas, categoria, data, origem (MANUAL/AI/TELEGRAM)
eventsCompromissos com lembrete
notesNotas
messagesConversa com a secretária (web + Telegram)
notificationsAvisos do sino
telegram_link_tokensConvites de vínculo (só hash SHA-256)
audit_logAuditoria (procurador, aprovações, vínculos)
doc_tasksQuadro Kanban desta documentação

Portas e ambientes

Escolhidas para não conflitar com os outros projetos desta máquina.

ServiçoPortaJá 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 Java80958080 global-admin/pet-adaca · 8081 job-hunter · 9090 assinador local
Front (dev/start local)30353000 pet-adaca · 3010 job-hunter · 3020 global-admin
AmbienteFrontAPI
Localhttp://localhost:3035http://localhost:8095
Produçãohttps://agente-cassiodevpro.vercel.apphttps://129-121-55-185.sslip.io:8447 (VPS adaca-vps, nginx → 127.0.0.1:8095)
Docshttps://dev-cassiodevpro.vercel.app

Login e perfis

Mesmo esquema do pet-adaca: NextAuth conduz o Google e o backend valida o id_token.

  1. Usuário clica em Continuar com Google (NextAuth, prompt=select_account).
  2. O front envia o id_token para POST /api/auth/google; a API confere assinatura, emissor, audience e e-mail verificado.
  3. Conta ativa → a API devolve o JWT dela, que fica só no cookie httpOnly criptografado do NextAuth.
  4. Conta nova → vira pedido de acesso (PENDING) e o admin é avisado; a tela mostra “aguardando aprovação”.
PerfilPode
AdministradorTudo 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árioO próprio dashboard: finanças, agenda, notas, secretária e Telegram. Dados isolados por usuário no backend.
Administrador: 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.

  1. Administração → Usuários → Acessar como procurador.
  2. 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 campo act; a ação vai para a auditoria.
  3. 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.
  4. 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.

  1. Tela Solicitar acesso (/solicitar-acesso): nome, e-mail Google, Instagram (@ ou link do perfil) e mensagem.
  2. 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.
  3. O admin aprova ou recusa em Administração → Pedidos. Aprovado, o usuário recebe e-mail e entra com o Google.
O Instagram encerrou a API de login para contas pessoais (Basic Display, dez/2024). Por isso o Instagram é usado como identificação no pedido e o login continua pelo Google. Limite: 5 pedidos por IP a cada 15 minutos.

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.
A paleta azul/rosa foi validada para daltonismo (protanopia, deuteranopia, tritanopia) nos dois temas.

Finanças

Receitas e despesas por mês, filtros e lançamento manual, pela IA ou pelo Telegram.

#Regra
RF-01Tipo (receita/despesa), valor > 0 com 2 casas, categoria (padrão “Outros”), descrição opcional e data (padrão hoje).
RF-02Categorias sugeridas: Salário, Freelance, Investimentos, Alimentação, Moradia, Transporte, Saúde, Educação, Lazer, Assinaturas, Compras, Impostos, Outros — mais as já usadas.
RF-03Cada lançamento guarda a origem: MANUAL, AI (secretária no app) ou TELEGRAM, exibida como etiqueta.
RF-04Consulta 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-01Cada 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-02Nunca se abate: quando o mínimo ≤ juros do mês (saldo × taxa). A dívida fica destacada em vermelho.
RD-03Pagamento abate o saldo e, por padrão, lança a despesa em Finanças (categoria “Dívidas”). Saldo zerado = quitada.
RD-04Simulaçã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-05Valor extra mensal: definido pelo usuário ou sugerido (metade da sobra média dos últimos 3 meses).
RD-06Plano 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-07Todos 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-01Depó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-02Taxas 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-03Comparaçã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-04Todo 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-05Conteú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-01Tí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-02Lembrete: 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-03A cada minuto (REMINDERS_CRON) os lembretes vencidos vão para o sino e para o Telegram (se vinculado), uma vez só.
RA-04Todo dia às 07:00 (DAILY_SUMMARY_CRON) quem tem Telegram recebe os compromissos do dia e o saldo.
RA-05Compromissos criados pela IA saem em rosa com lembrete de 30 min (ajustável).
RA-06Google 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-07A 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-08Tokens 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.
Google Cloud → cliente OAuth: URIs de redirecionamento 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

EntradaComo é lidoChave
TextoDireto para a DeepSeekDEEPSEEK_API_KEY
Áudio (voz do Telegram, gravação no app, mp3/m4a/ogg/webm)Transcrição Whisper em portuguêsTRANSCRIPTION_API_KEY
Imagem (comprovante, nota fiscal, print)Modelo de visão transcreve e descreve valores, datas e itensVISION_API_KEY
PDF (fatura, extrato, boleto)PDFBox extrai o texto (até 30 páginas / 15 mil caracteres)—
TXT, CSV, OFXLido 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.

  1. Crie o bot no @BotFather e cole o token em TELEGRAM_BOT_TOKEN. Reinicie a API.
  2. 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.
  3. Ao tocar em Iniciar, o bot recebe /start TOKEN e liga o chat à conta. A página do app confirma sozinha.
No TelegramO que acontece
Texto livreVai para a secretária (cria lançamentos, compromissos, notas ou responde)
🎙️ Voz / áudioTranscreve, mostra a transcrição e processa
📷 FotoLê com visão e processa (maior resolução enviada)
📄 DocumentoPDF, imagem, áudio ou texto até 20 MB
/saldo /hoje /semana /notas /ajudaRespostas rápidas sem IA
Modo polling (padrão) não precisa de porta pública — funciona até no seu Mac. Modo webhook exige HTTPS: defina 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ávelPara quê
DB_PASSWORD, DB_PORT=5460Banco Docker
JWT_SECRETAssinatura dos tokens (32+ caracteres; openssl rand -base64 48)
ADMIN_EMAIL, ADMIN_PASSWORDAdministrador (senha só no .env)
GOOGLE_CLIENT_IDMesmo Client ID do front; valida o id_token
DEEPSEEK_API_KEYChave da DeepSeek (DEEPSEEK_MODEL=deepseek-chat)
TRANSCRIPTION_PROVIDER, TRANSCRIPTION_API_KEYÁudio → texto (groq ou openai)
VISION_BASE_URL, VISION_API_KEY, VISION_MODELImagem → texto
TELEGRAM_BOT_TOKEN, TELEGRAM_MODEBot do Telegram
MAIL_ENABLED, SMTP_USERNAME, SMTP_PASSWORDGmail com senha de app (avisos de cadastro)
FRONTEND_URL, CORS_ORIGINSLinks nos e-mails/Telegram e origens do site de docs

Front (Vercel)

VariávelPara quê
BACKEND_URLURL da API (HTTPS em produção). Só o servidor do Next usa.
AUTH_SECRETCriptografia do cookie de sessão (openssl rand -base64 32)
AUTH_GOOGLE_ID, AUTH_GOOGLE_SECRETOAuth do Google
AUTH_URL, AUTH_TRUST_HOST=trueURL pública do front
Google Cloud → Credenciais → ID do cliente OAuth (Aplicativo da Web). URIs de redirecionamento: 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'
O .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.

RotaQuem
POST /auth/login · POST /auth/googlePúblico
GET /auth/meLogado (traz actor no modo procurador)
POST /public/signup-requestsPúblico (5 por IP / 15 min)
GET/POST /finance/transactions · PUT/DELETE /finance/transactions/{id} · GET /finance/summary · GET /finance/categoriesLogado
GET /agenda/events?from&to · GET /agenda/upcoming · POST/PUT/DELETE /agenda/eventsLogado
GET/POST /notes · PUT/DELETE /notes/{id} · GET /notes?q=Logado
POST /assistant/chat (multipart: text, file) · GET/DELETE /assistant/messagesLogado
GET /telegram/status · POST/DELETE /telegram/linkLogado
POST /telegram/webhookTelegram (header secret)
GET /notifications · GET /notifications/unread · POST /notifications/{id}/read · POST /notifications/read-allLogado
GET /integrationsLogado (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/auditAdministrador
GET /docs/tarefasPú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.

Entrar para editar

Use o login de administrador do Agente (e-mail ou usuário + senha).

Demanda