urutau gestão

Gestão financeira simples para pequenas empresas brasileiras de comércio e serviços. Mostra ao dono, numa tela só, quanto a empresa faturou, gastou, lucrou, quanto deve e quanto deve pagar de imposto no mês.

Rodando localmente

Jeito mais fácil (sem Docker): instale o Node.js 22, crie um banco grátis em neon.tech (botão Connect → copie a connection string) e, na pasta do projeto:

npm install
npm run iniciar     # pede a connection string, cria as tabelas e os dados de exemplo, e abre o site

Abra http://localhost:3000. Nas próximas vezes, npm run iniciar (ou npm run dev) já basta.

Com Docker (Postgres local):

cp .env.example .env
npm install
docker compose up -d
npm run db:reset          # zera o banco local, aplica migrações e cria a empresa de exemplo
npm run dev               # http://localhost:3000

Acessos de exemplo (senha urutau123):

E-mail	Papel	O que vê
[email protected]	Dono	Tudo; tem também uma segunda empresa (MEI)
[email protected]	Colaborador	Lança vendas/despesas e vê só o que lançou
[email protected]	Contador	Painel e lançamentos, somente leitura
[email protected] e borel@ (sócios), vinicius@, wanderley@, matheus@ (equipe)	Equipe Urutau	Central Urutau (/admin): a área de cada pessoa com metas, anotações e clientes; todas as empresas

Empresas de exemplo do dono@: Padaria e Café Urutau (Simples, Anexos I e III, com funcionários e dívidas), Marina Doces (MEI perto do limite anual), Estúdio Urutau Design (Simples Anexo V com Fator R, que passa para o Anexo III depois de contratar) e Urutau Manutenção Industrial (Lucro Presumido, com adicional do IRPJ e encargos) e Urutau Veículos (revenda de carros, o primeiro cliente piloto: clientes e três vendas do WhatsApp esperando conferência).

Publicar (Vercel + Neon)

1. Banco: crie um projeto em neon.tech e copie a connection string.

2. Site: em vercel.com, Add New → Project e importe este repositório. Em Environment Variables, crie DATABASE_URL com a connection string do Neon (se usar a integração Neon da Vercel, DATABASE_URL e DATABASE_URL_UNPOOLED são criadas sozinhas).

3. Deploy. O build (vercel-build) aplica as migrações antes de compilar.

4. Contas: crie a sua em /criar-conta. Para ter as empresas de exemplo no banco publicado, rode uma vez no seu computador, com uma senha nova (as de exemplo ficariam públicas):

   DATABASE_URL="<connection string do Neon>" SEED_SENHA="uma-senha-forte" npm run db:seed
   

npm run db:reset recusa apagar um banco que não seja local.

5. Equipe Urutau: a primeira pessoa cria a conta em /criar-conta e roda DATABASE_URL="<connection string>" npm run admin -- seu@email. As outras entram pela própria Central, em Equipe → Pôr alguém na equipe (a senha provisória aparece uma vez; a pessoa troca em Minha conta). Quem é equipe vê a Central /admin e entra em qualquer empresa com os poderes do dono (com um aviso no topo).
6. Rotina diária: crie a variável CRON_SECRET (valor longo e aleatório). A Vercel chama /api/cron todo dia às 6h (horário de Brasília; vercel.json).
7. Site urutau.io: o site manda visitas, contatos, cliques no WhatsApp e o diagnóstico com POST /api/site/evento ({"tipo": "visita" | "contato" | "whatsapp" | "diagnostico", "pagina", "nome", "negocio", "contato", "mensagem", "dores": [], "tamanho"}). Contato e diagnóstico viram lead no Comercial. Só as origens de SITE_ORIGENS são aceitas (padrão: https://urutau.io,https://www.urutau.io).
8. Prospecção: o robô google-maps-scraper-kit roda num computador com Docker e gera um CSV; importe em Comercial → Prospecção. Use --full para vir latitude/longitude (mapa).

No celular: abra o link e use Compartilhar → Adicionar à Tela de Início (iPhone/Safari) ou ⋮ → Instalar app (Android/Chrome). O urutau abre em tela cheia, com ícone próprio.

Testes

npm test        # unitários + integração com Postgres (usa TEST_DATABASE_URL, recria o schema)
npm run lint    # checagem de tipos

Decisões de base

• Dinheiro em centavos (bigint no banco, inteiro no TS). Percentuais em pcm (1% = 1.000). Nenhum float em cálculo; arredondamento uma única vez, no fim, com divisão inteira (src/lib/dinheiro.ts).
• Multiempresa: toda tabela de negócio tem empresa_id, e as referências usam chave composta (empresa_id, id), então o próprio banco recusa misturar dados de empresas diferentes. Todo acesso passa por exigirAcesso / exigirPermissao (src/lib/servidor/acesso.ts).
• Papéis: matriz em src/lib/permissoes.ts.
• Cálculos são funções puras em src/lib/calculos/, testadas sem banco.
• Lucro × caixa: lucro usa a data da despesa/venda (competência); caixa usa a data em que o dinheiro entrou ou saiu.
• Imposto não conta duas vezes: a categoria "Impostos sobre vendas" (entra_no_lucro = false) aparece só no caixa, porque o lucro desconta o imposto estimado.
• Ponto de equilíbrio: cada categoria é fixa ou variável; PE = fixas × faturamento ÷ (faturamento − variáveis − impostos).
• Parâmetros com vigência: FGTS, INSS patronal, RAT, terceiros e CPP do MEI ficam em parametros_fiscais (com início e fim de vigência). A empresa pode sobrescrever valores em empresa_parametros (ex.: RAT ajustado pelo FAP).
• Folha mensal: cada funcionário gera uma linha por mês em folha_mensal (foto do custo). Meses passados ficam congelados; o mês atual é recalculado enquanto não for pago. folha_desde evita duplicar salários já lançados à mão. Custo = salário + FGTS + 13º (÷12) + férias com 1/3 (÷9) + FGTS das reservas + encargos (se o regime exigir) + benefícios. No caixa entram só salário, FGTS, encargos sobre o salário e benefícios: as reservas saem quando o 13º e as férias forem pagos.
• Dívidas: parcelas pela tabela Price, calculadas com frações exatas (BigInt). Os juros são despesa no mês do vencimento; a amortização só reduz o saldo e o caixa. O banco garante valor = juros + amortização em cada parcela.
• Impostos (src/lib/calculos/{simples,mei,presumido,impostos}.ts), sempre com o aviso "Valor estimado. Confirme com o seu contador.":
  • Simples: RBT12 = soma dos 12 meses anteriores (no início de atividade, mês × 12 ou média × 12, como na Resolução CGSN 140). Imposto = receita × (RBT12 × nominal − parcela a deduzir) ÷ RBT12, em fração exata. Cada natureza (comércio/serviço) usa o seu anexo com o mesmo RBT12. Fator R = folha 12 meses ÷ RBT12 (folha = salários + FGTS + INSS patronal + 13º pela reserva mensal + pró-labore); ≥ 28% → Anexo III.

Estrutura

src/
  app/                 telas (App Router)
    (publico)/         entrar, criar conta
    empresas/          escolher/criar empresa
    e/[empresaId]/     painel, vendas, despesas (e recorrentes), contas, funcionários, dívidas, impostos, relatórios, ajustes
  components/          UI compartilhada
  db/                  schema Drizzle, conexão, categorias e fontes padrão
  lib/
    calculos/          cálculos puros: painel, folha, dívidas, parâmetros, Simples, MEI, Presumido, guias, recorrentes, 13º/férias
    relatorios/        CSV e PDF
    servidor/          autenticação, acesso, consultas e server actions
drizzle/               migrações SQL
scripts/               migrate, reset, seed
tests/                 Vitest

Fases

1. ✅ Fundação: login, empresa, categorias, vendas, despesas e painel básico
2. ✅ Funcionários com custo real e dívidas com parcelas
3. ✅ Impostos: MEI, Simples Nacional (com Fator R) e Lucro Presumido
4. ✅ Relatórios (PDF/CSV/ZIP), despesas recorrentes, guias de impostos como contas a pagar, agenda de vencimentos e 13º/férias
5. ✅ Base do ecossistema: painel Urutau, perfis e módulos (revenda de veículos primeiro), clientes, caixa de conferência, auditoria, fila de tarefas e rotina diária
6. ✅ Central Urutau: a área de cada pessoa da equipe (metas do mês com ritmo, clientes sob responsabilidade, anotações), quem está online e em qual tela, o que aconteceu na equipe e nos clientes, e os sinais do site urutau.io
7. ✅ Comercial da Urutau: leads (site, diagnóstico, ligação, indicação, prospecção), funil em colunas, histórico de contatos com retorno marcado, propostas (mensal + entrada), mapa dos leads e importação do CSV do robô do Google Maps
8. ✅ Receita da Urutau: papéis sócio/equipe, clientes da Urutau com contratos (prazo, desconto, multa), serviços com quem executa, cobranças mensais, comissões que nascem quando o cliente paga (10% de quem trouxe + % de quem executa, regra congelada no contrato), custos, divisão teórica dos sócios com reserva de caixa, painel da Receita (só sócios) e Meus ganhos (cada pessoa)
9. Estoque de veículos e agenda de visitas/test drive (revenda); depois atendente no WhatsApp