ninho. — finanças inteligentes da família

Assistente financeiro privado para a família: cada pessoa vê só os próprios detalhes (extrato, lojas, comprovantes, conversas) e a casa vê apenas totais do que cada um marcar como familiar. Feito a partir do Caderno de produto v0.3 (PDF do projeto).

• App web instalável (PWA) — abre no navegador do celular e instala como app.
• APK Android — o mesmo app empacotado com Capacitor.
• Banco Neon (Postgres, São Paulo) — dados reais, com regras de privacidade e de dinheiro no próprio banco.

O que já funciona

Área	O que faz
Contas e login	Cadastro com e-mail e senha, família com código de convite, até 6 integrantes. Opção de começar com 7 meses de dados de exemplo (você + Mãe, Pai e Irmão fictícios).
Visão geral	Receitas, despesas e saldo da família, pendências, gráfico de 7 meses, “para onde foi o dinheiro”, transações recentes e o que a Nia percebeu.
Meu financeiro	Gastos do mês, categorias, entradas × saídas, regras automáticas. Tudo privado.
Nossa família	Só agregados: nenhum extrato, loja ou nome de quem comprou. Metas da família e aviso genérico de dados incompletos.
Transações	Busca, filtros (pendentes, familiares, pessoais, ignoradas), meses, exportação CSV. Toque para dividir a compra em várias categorias, cada parte pessoal ou familiar — a soma fecha centavo por centavo.
Importar extrato	CSV e OFX, com prévia. Reconhece sozinho Nubank (conta e cartão), Inter, C6 e Mercado Pago (fatura de cartão entra com o sinal certo). Reimportar não duplica (chave de idempotência). Pagamento de fatura vira transferência, não gasto.
Classificação automática	Regra da pessoa → histórico → palavras-chave → IA (opcional) → pendência. Depois de 2 confirmações iguais, o ninho aprende uma regra (que você pode desligar).
Resumo diário	Todas as pendências num lote, com classificação em um toque.
Assistente Nia	Responde com números calculados pelo banco (gastos, categorias, pendências, assinaturas, metas, família). Entende “comprei R$ 80 de comida e R$ 30 de limpeza no mercado” — digitado ou em mensagem de voz (transcrita pelo Whisper, você confere o texto antes de enviar) — e monta uma proposta para você confirmar.
Nota fiscal	Foto do cupom → itens e categorias (com chave de IA). Vincula à compra já lançada sem duplicar a despesa.
Assinaturas e alertas	Detecta assinaturas e contas recorrentes, aumento de preço, possível cobrança duplicada e gasto fora do padrão — só avisos, nada é apagado.
Saúde dos dados	Atualização de cada conta, cobertura, classificação, divergências e histórico de importações.
Metas	Pessoais e da família; na família todos veem o total, cada contribuição é privada.
Orçamento	Limite mensal por categoria, pessoal ou da casa (definido por quem administra). Aviso a partir de 80% na visão geral e pela Nia.
Contas da casa	Luz, internet, aluguel… divididos entre quem mora junto, centavo por centavo. Cada pessoa marca “Paguei minha parte” e a parte entra no financeiro dela como familiar. Dá para repetir no mês seguinte.
Saldos e compromissos	Saldo informado da conta + lançamentos seguintes = saldo de hoje, com a evolução de 6 meses. “Já comprometido no mês que vem”: assinaturas, contas fixas e a próxima parcela.
Metas ligadas	Um lançamento (ex.: Pix para a poupança) pode contar para uma meta — e, se quiser, sempre que for o mesmo estabelecimento.
Fechamento do mês	“Seu mês em 5 números” e relatório em PDF (link de uso único que também funciona no APK).
Resumo diário	Notificação no horário escolhido (Web Push no navegador; lembrete local no APK), só com a quantidade de pendências — nunca lojas ou valores. Disparo de hora em hora pelo GitHub Actions (.github/workflows/digest.yml).
Senha e conta	Trocar senha; “Esqueci minha senha” com código (por e-mail, se o Resend estiver configurado, ou gerado por quem administra a família); papéis, remover integrante, sair da família e apagar a conta (LGPD).
Sem internet	Lançamentos feitos offline ficam no aparelho e são enviados quando a conexão volta, sem duplicar.
Notas guardadas	A foto da nota fiscal (comprimida no celular) fica guardada com a compra, visível só para o dono.
Fatura do cartão	Com o dia de fechamento e de vencimento, mostra a fatura fechada, a aberta e as próximas (com parcelas já previstas). Aviso 5 dias antes de vencer.
Contas a pagar	Boletos e contas com repetição (mensal/anual) e lembrete; “Paguei” lança a despesa e avança para o próximo vencimento. Sazonais (IPVA, IPTU, material escolar) sugerem quanto guardar por mês.
Saldo previsto	30, 60 ou 90 dias à frente: saldo de hoje + salário − contas − faturas − assinaturas, com o dia mais apertado e o aviso “pode ficar negativo”.
Orçamento acumulado	Opcional por categoria: o que sobrou (ou faltou) no mês passado passa para o mês seguinte.
Etiquetas	Marque compras de uma viagem, reforma ou festa e veja o total — de várias categorias.
Imposto de Renda	Saúde e educação do ano (com limite da educação), ajuste item a item e PDF para o contador.
Patrimônio e dívidas	Contas + bens − dívidas − cartões, com a evolução mês a mês. Plano para quitar dívidas: bola de neve × avalanche, com meses e juros de cada um.
Lista de desejos	Compras grandes da casa com votos; vira meta da família em um toque.
Desafios	Mês sem delivery, dias sem gastar, gastar menos que no mês passado, tudo organizado — o progresso vem dos lançamentos.
Mesada	Quem administra define valor, semana/mês e limite; entra sozinha como receita de quem recebe.
Captura automática (APK 0.5.0)	Lê os avisos de compra e Pix dos apps de banco (só bancos conhecidos; códigos e propagandas são ignorados) e lança para revisar. Ao importar o extrato, liga ao lançamento sem duplicar.
Compartilhar com o ninho	Comprovante de Pix (imagem), nota fiscal ou texto do banco enviados pelo “Compartilhar” do celular viram proposta de lançamento. Widget e atalhos: “Nova despesa”, “Nia” e “Resumo”.
Cesta da família	Os produtos das notas fiscais das compras da família ao longo dos meses: o que ficou mais caro ou mais barato. Só totais — nunca quem comprou nem onde; compras pessoais ficam de fora.
Nia (planejamento)	Também responde sobre fatura, contas a pagar, saldo previsto, patrimônio e desafios — sem IA, com os números do banco.
Quem deve a quem	“Paguei o mercado, você me deve metade”: saldo com cada pessoa, “acertar tudo” e pedido pelo WhatsApp. Só as duas pessoas envolvidas veem.
Divisão justa	Contas da casa divididas na proporção da renda. Cada um informa a própria renda; a família vê só a porcentagem.
Combinados e reunião do mês	Regras da casa (“acima de R$ 500 a gente conversa”, com lembrete ao lançar) e pauta pronta de 10 minutos com totais da família e as decisões anotadas.
Valores a receber	Reembolso do plano/empresa, restituição, dinheiro emprestado: aviso quando atrasa e “Recebi” vira receita.
Custo dos bancos	Tarifas, juros, IOF, anuidade e multas do ano, com dica para cortar cada um.
Benefícios e pontos	VR/VA como conta; pontos, milhas e cashback com aviso 30 dias antes de vencer. Aviso de dinheiro parado na conta.
Reserva de emergência	Quantos meses do custo essencial a reserva cobre (meta de 6, ou 12 para renda variável).
Documentos e garantias	Garantias, seguros, contratos e documentos com foto e aviso antes de vencer; privados ou visíveis para a família.
E se eu faltar?	Bilhete para uma pessoa de confiança (nunca senhas), liberado já ou só depois de N dias sem abrir o app.
Golpes e segurança	Alerta de Pix alto para quem nunca recebeu e de compras pequenas em série (teste de cartão clonado), com dicas.
Renda variável e MEI	“Salário para si mesmo” sugerido pelos meses fracos, simulação do colchão e lembretes de DAS, carnê-leão e INSS.
Modo simples e acompanhamento	Letras maiores e poucas telas; com autorização, um filho acompanha totais, contas e alertas de golpe dos pais — nunca as compras.
Modo criança	Quanto sobrou da mesada, cofrinhos com “Guardar” e desafios.
Parcelar ou à vista?	Juro escondido do parcelado, comparação com o rendimento e o teto de 30% da renda em parcelas.
Grandes momentos	Simulador de bebê, mudança, casamento, carro, faculdade, viagem e aposentadoria; vira meta da família.
Lista de compras	Uma lista para a casa toda, com preço previsto pelas notas da cesta.
Privacidade	Botão para ocultar valores, todas as consultas filtradas pelo dono, testes de isolamento.
Primeiros passos e tema	Guia na tela inicial para quem acabou de chegar (conta, movimentações, família, orçamento, meta). Tema claro, escuro ou automático (Configurações → App).

Regras de dinheiro (garantidas no banco)

• Dinheiro em centavos inteiros (bigint), nunca float.
• A transação importada é preservada; categorias ficam em transaction_allocations.
• Soma das divisões = valor da transação: um trigger adiado no Postgres recusa qualquer gravação que não feche.
• UNIQUE (pessoa, conta, id externo) impede importar a mesma linha duas vezes.
• A visão da família só lê divisões scope = 'family' e nunca devolve linhas individuais.

Tecnologia

Camada	Escolha	Por quê
App	React 19 + Vite + TypeScript, PWA	Roda no navegador do celular e instala como app, sem loja.
Android	Capacitor 8	Gera o APK a partir do mesmo código.
API	Uma função serverless na Vercel (api/router.ts)	Plano grátis, deploy automático a cada git push. A função usa Request/Response padrão: dá para mover para Neon Functions sem reescrever.
Banco	Neon Postgres (São Paulo) + migrations SQL	Plano grátis, @neondatabase/serverless (HTTP).
Login	Próprio (scrypt + token Bearer)	Funciona igual no navegador, PWA e APK. O Neon Auth usa cookies de outro domínio, que o WebView do Android pode bloquear; a troca fica isolada em server/auth.ts.
IA	Groq (grátis) ou qualquer API compatível com a da OpenAI	Texto, imagem e voz (Whisper). Sem chave a Nia funciona por regras. O AI Gateway do Neon exige plano pago e não está na região de São Paulo.
Testes	Vitest + Playwright	Vitest: centavos, importadores, regras, alertas e frases faladas. Playwright (npm run test:e2e, fora do CI): cadastro, lançar despesa, revisar compras e importar extrato, no celular e no computador, com a API simulada em e2e/fake-api.ts.

Diferenças em relação ao caderno de produto (de propósito, para um protótipo grátis e testável no celular): Expo → React + Capacitor; Neon Auth → login próprio; Drizzle → SQL direto; Neon Functions → função na Vercel; Object Storage → fotos de nota guardadas comprimidas no próprio Postgres (só o dono acessa; limite de 300 por pessoa). Detalhes em “Próximos passos”.

Estrutura

api/router.ts            função única da Vercel (todas as rotas /api/*)
server/                  rotas, login, motor financeiro, importação, Nia, alertas, dados de exemplo
shared/                  tipos, categorias, dinheiro, datas e regras usadas no app e na API
src/                     telas (pages/), janelas (modals/), componentes e estilos
db/migrations/           SQL numerado: fonte da verdade do banco
public/                  manifesto do app, service worker e ícones
android/                 projeto Android (Capacitor) — gerado com `npx cap add android`
android-web/             o que vai dentro do APK (só a página "sem conexão"; o app abre o site publicado)
tests/                   testes (Vitest)

Rodando no computador

npm install
cp .env.example .env        # cole a DATABASE_URL do Neon
npm run db:migrate          # cria as tabelas
npm run dev:api             # API em http://localhost:8787
npm run dev                 # app em http://localhost:5173
npm test                    # testes
npm run test:e2e            # testes de tela (Chromium do Playwright; não precisa de banco)

Publicação

• Vercel (projeto novo-reposit-rio → https://ninho-financas-familia.vercel.app): importado deste repositório; cada git push na main publica. Variáveis: DATABASE_URL (obrigatória) e, se quiser IA, AI_API_KEY, AI_BASE_URL, AI_MODEL (ver .env.example).
• Banco: projeto ninho no Neon (região São Paulo). npm run db:migrate aplica as migrations.
• APK: public/download/ninho.apk (baixável em /download/ninho.apk e em Configurações → App). O GitHub Actions (.github/workflows/android.yml) compila o app a cada mudança; o APK de produção é gerado manualmente (Run workflow), assinado com a chave guardada nos secrets, e vira um rascunho de Release. O APK abre o site publicado, então atualizações do site chegam sem reinstalar; só é preciso gerar outro APK se mudar algo do Android (ícone, permissões, endereço).

Gerar o APK no computador

npx cap sync android                       # copia android-web/ (página "sem conexão") para o APK
cd android && ./gradlew assembleDebug      # teste local (chave de depuração da sua máquina)
# produção: ./gradlew assembleRelease com NINHO_KEYSTORE_FILE, NINHO_KEYSTORE_PASSWORD,
# NINHO_KEY_ALIAS e NINHO_KEY_PASSWORD (sem elas o build falha)

Ao mudar a versão em android/app/build.gradle, atualize public/download/version.json: o app instalado compara com ele e avisa “Nova versão do app”. Assinatura: a chave antiga (ninho-debug.keystore, até a v0.3.0) foi publicada no repositório e está comprometida. Como gerar e configurar a chave de produção, e como avisar quem precisa reinstalar: docs/assinatura-android.md.

IA da Nia (Groq, plano grátis)

Com AI_API_KEY configurada na Vercel, a Nia responde livremente (sempre com os números do banco), classifica estabelecimentos desconhecidos (lançamentos e importações), lê fotos de nota fiscal e transcreve mensagens de voz. O provedor é reconhecido pela chave:

Chave	Provedor	Modelos usados
gsk_…	Groq (grátis em console.groq.com)	qwen/qwen3.8-27b (texto e imagem) + whisper-large-v3-turbo (voz)
AIza…	Google Gemini	gemini-2.5-flash (sem voz)
sk-…	OpenAI	gpt-5-mini + whisper-1

Para trocar a chave: Vercel → projeto → Settings → Environment Variables → AI_API_KEY → Save → Deployments → Redeploy. O áudio das mensagens de voz é transcrito e descartado na hora; a foto da nota também não é guardada.

Próximos passos (roadmap do caderno)

• F5: Open Finance (Pluggy/Belvo) com adaptadores — só depois de validar o app com extratos importados.
• F6: domínio próprio para o e-mail de recuperação, backups e revisão LGPD completa.