CoéPay

Sistema web para gestão de cobranças via PIX, com criação de cobranças, geração de link público para pagamento, cálculo automático de juros, QR Code PIX, upload de comprovantes, painel administrativo, relatórios, notificações, suporte e estrutura inicial para planos pagos.

Sumário

Sobre o projeto
Principais funcionalidades
Stack utilizada
Arquitetura do projeto
Estrutura de pastas
Como rodar localmente
Variáveis de ambiente
Banco de dados
Modelos principais
Rotas da API
Fluxo de cobrança
Sistema de juros
PIX e QR Code
Upload de comprovantes
Autenticação
Notificações
Relatórios
Planos e assinatura
Suporte
Supabase
Scripts úteis
Pontos de atenção
Melhorias futuras
Boas práticas de segurança

Sobre o projeto

O CoéPay é uma aplicação web desenvolvida para facilitar a cobrança de valores por PIX.

A plataforma permite que um usuário cadastre cobranças, defina valores, vencimentos, taxa de juros, método de cálculo, chave PIX e dados do devedor. Após isso, o sistema gera automaticamente um link público de cobrança. Esse link pode ser enviado para o devedor, que acessa uma tela com as informações da dívida, o valor atualizado, a chave PIX, o QR Code e a opção de enviar comprovante.

O objetivo principal é centralizar o controle de cobranças e pagamentos em um painel simples, permitindo acompanhar cobranças ativas, vencidas e pagas.

Principais funcionalidades

Cadastro e login de usuários.
Login com Google.
Recuperação de senha por e-mail.
Configuração de chave PIX padrão do usuário.
Criação de cobranças com dados do devedor.
Geração automática de hash e link público da cobrança.
Página pública de cobrança acessível por link.
Geração de QR Code PIX.
Cálculo de juros simples ou compostos.
Juros por período diário, mensal ou anual.
Marcação manual de cobrança como paga.
Upload de até 2 comprovantes por cobrança.
Listagem de cobranças ativas, vencidas e pagas.
Dashboard com indicadores financeiros.
Página de cobranças pagas.
Página de relatórios.
Sistema de notificações.
Página de planos.
Estrutura de assinatura com Stripe e Supabase Functions.
Página de suporte com envio de e-mail e anexo.
Página de futuras implementações e sugestões.

Stack utilizada

Frontend

React 18
TypeScript
Vite
Tailwind CSS
shadcn/ui
Radix UI
React Router DOM
TanStack React Query
Supabase JS
Google OAuth
QRCode
Recharts
Date-fns
Lucide React
Sonner / Toasts

Backend

Node.js
Express 5
JavaScript ES Modules
Sequelize
PostgreSQL
bcrypt / bcryptjs
Passport
Google OAuth 2.0
Multer
Nodemailer
Validator
Express Session
dotenv

Banco e serviços externos

PostgreSQL como banco principal do backend.
Supabase para funções, sugestões, realtime e estrutura auxiliar.
Stripe para checkout, assinatura e portal do cliente.
Gmail SMTP ou outro SMTP compatível para envio de e-mails.

Arquitetura do projeto

O projeto está dividido em três blocos principais:

Frontend React/TypeScript
        |
        | HTTP fetch
        v
Backend Node/Express
        |
        | Sequelize ORM
        v
PostgreSQL

Além disso, existe uma camada Supabase usada para:

funções Edge;
validação experimental de comprovante;
planos/assinaturas com Stripe;
sugestões de funcionalidades;
realtime em tabela cobrancas.

A aplicação principal de cobranças usa o backend Express e a tabela devedores.

Estrutura de pastas

coepay/
├── README.md
├── .gitignore
│
├── backend/
│   ├── package.json
│   ├── .env
│   ├── README_CONFIGURACOES.md
│   ├── README_JUROS.md
│   ├── README_COMPROVANTES.md
│   ├── migration_add_comprovante.sql
│   ├── migration_add_metodo_calculo.sql
│   ├── migration_add_pix_cobranca.sql
│   │
│   └── src/
│       ├── server.js
│       ├── config/
│       │   ├── db.js
│       │   ├── mail.js
│       │   └── passport-setup.js
│       ├── controllers/
│       │   ├── authController.controller.js
│       │   ├── devedor.controller.js
│       │   ├── notificacao.controller.js
│       │   ├── suporte.controller.js
│       │   ├── upload.controller.js
│       │   └── webhook.controller.js
│       ├── middlewares/
│       │   └── upload.middleware.js
│       ├── models/
│       │   ├── initModels.js
│       │   ├── user.model.js
│       │   ├── devedor.model.js
│       │   └── notificacao.model.js
│       ├── routes/
│       │   ├── authRoutes.routes.js
│       │   ├── devedor.routes.js
│       │   ├── notificacao.routes.js
│       │   ├── suporte.routes.js
│       │   ├── upload.routes.js
│       │   └── webhook.routes.js
│       ├── uploads/
│       ├── utils/
│       │   └── juros.js
│       └── test/
│           └── testEmail.js
│
├── frontend/
│   ├── package.json
│   ├── vite.config.ts
│   ├── tailwind.config.ts
│   ├── components.json
│   ├── index.html
│   │
│   └── src/
│       ├── App.tsx
│       ├── main.tsx
│       ├── index.css
│       ├── components/
│       │   ├── AppLayout.tsx
│       │   ├── AppSidebar.tsx
│       │   ├── ConfirmarPagamentoModal.tsx
│       │   ├── cobranca-publica/
│       │   ├── dashboard/
│       │   ├── sugestoes/
│       │   └── ui/
│       ├── hooks/
│       │   ├── useCobrancas.ts
│       │   ├── useNotifications.ts
│       │   └── useSubscription.ts
│       ├── integrations/
│       │   └── supabase/
│       ├── pages/
│       │   ├── Index.tsx
│       │   ├── Login.tsx
│       │   ├── Dashboard.tsx
│       │   ├── CobrancaPublica.tsx
│       │   ├── CobrancasPagas.tsx
│       │   ├── Configuracoes.tsx
│       │   ├── Planos.tsx
│       │   ├── Relatorios.tsx
│       │   ├── FuturasImplementacoes.tsx
│       │   ├── Suporte.tsx
│       │   └── NotFound.tsx
│       └── utils/
│           ├── pix.ts
│           └── formatarData.ts
│
└── supabase/
    ├── config.toml
    ├── functions/
    │   ├── check-subscription/
    │   ├── create-checkout/
    │   ├── customer-portal/
    │   └── validar-comprovante/
    └── migrations/

Como rodar localmente

Pré-requisitos

Antes de rodar o projeto, instale:

Node.js 18 ou superior;
npm;
PostgreSQL;
uma conta Google Cloud para OAuth, caso queira login com Google;
uma conta SMTP, caso queira envio de e-mails;
Supabase CLI, caso queira rodar as functions/migrations do Supabase;
Stripe CLI, caso queira testar assinatura.

1. Clonar o projeto

git clone <url-do-repositorio>
cd coepay

2. Configurar o backend

Entre na pasta do backend:

cd backend

Instale as dependências:

npm install

Crie o arquivo .env com base no exemplo abaixo:

PORT=3000
NODE_ENV=development

DB_NAME=coepay
DB_USER=postgres
DB_PASS=sua_senha
DB_HOST=localhost

SESSION_SECRET=sua_chave_secreta

GOOGLE_CLIENT_ID=seu_google_client_id
GOOGLE_CLIENT_SECRET=seu_google_client_secret
GOOGLE_CALLBACK_URL=http://localhost:3000/auth/google/callback

MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
EMAIL_USER=seu_email@gmail.com
EMAIL_PASS=sua_senha_de_app

Rode o backend:

npm run dev

Servidor esperado:

http://localhost:3000

Para rodar sem nodemon:

npm start

3. Configurar o frontend

Em outro terminal, entre na pasta do frontend:

cd frontend

Instale as dependências:

npm install

Crie o arquivo .env:

VITE_GOOGLE_CLIENT_ID=seu_google_client_id

Rode o frontend:

npm run dev

Aplicação esperada:

http://localhost:5173

Variáveis de ambiente

Backend

Variável	Descrição
`PORT`	Porta onde o backend irá rodar. Padrão: `3000`.
`NODE_ENV`	Ambiente da aplicação: `development` ou `production`.
`DB_NAME`	Nome do banco PostgreSQL.
`DB_USER`	Usuário do PostgreSQL.
`DB_PASS`	Senha do PostgreSQL.
`DB_HOST`	Host do PostgreSQL.
`SESSION_SECRET`	Chave usada pela sessão Express.
`GOOGLE_CLIENT_ID`	Client ID do Google OAuth.
`GOOGLE_CLIENT_SECRET`	Client Secret do Google OAuth.
`GOOGLE_CALLBACK_URL`	URL de callback do Google OAuth.
`MAIL_HOST`	Host SMTP para envio de e-mails.
`MAIL_PORT`	Porta SMTP. Normalmente `587`.
`EMAIL_USER`	E-mail remetente.
`EMAIL_PASS`	Senha de app do e-mail remetente.

Frontend

Variável	Descrição
`VITE_GOOGLE_CLIENT_ID`	Client ID usado pelo `GoogleOAuthProvider`.

Supabase Functions

Variável	Descrição
`SUPABASE_URL`	URL do projeto Supabase.
`SUPABASE_ANON_KEY`	Chave pública anon do Supabase.
`SUPABASE_SERVICE_ROLE_KEY`	Chave service role usada em funções seguras.
`STRIPE_SECRET_KEY`	Chave secreta da Stripe.
`LOVABLE_API_KEY`	Chave usada pela função de validação de comprovante com IA.

Banco de dados

O backend usa PostgreSQL via Sequelize.

A conexão fica em:

backend/src/config/db.js

Por padrão, se as variáveis de ambiente não forem definidas, o backend usa valores fallback presentes no código. Para um ambiente correto, configure sempre o .env.

Os models são sincronizados no início do servidor por:

await sequelize.sync({ alter: true });

Essa configuração cria/atualiza tabelas automaticamente, mas em produção o recomendado é usar migrations controladas.

Modelos principais

User

Arquivo:

backend/src/models/user.model.js

Tabela:

users

Campos principais:

Campo	Tipo	Descrição
`id`	integer	ID autoincremental do usuário.
`name`	string	Nome do usuário.
`email`	string	E-mail único do usuário.
`password`	string	Senha criptografada. Pode ser nula para login Google.
`pix`	string	Chave PIX padrão do usuário.
`provider`	string	Origem do login. Exemplo: `manual` ou `google`.
`provider_id`	string	ID externo do provedor, usado no Google login.

Observações:

A senha é criptografada automaticamente antes de criar ou atualizar o usuário.
O método validPassword compara senha informada com hash salvo.

Devedor / Cobrança

Arquivo:

backend/src/models/devedor.model.js

Tabela:

devedores

Campos principais:

Campo	Tipo	Descrição
`id`	integer	ID autoincremental da cobrança.
`user_id`	integer	ID do usuário dono da cobrança.
`nome`	string	Nome do devedor.
`email`	string	E-mail do devedor. Opcional.
`telefone`	string	Telefone do devedor. Opcional.
`valor`	float	Valor original da cobrança.
`data_vencimento`	date	Data de vencimento.
`taxa_juros`	float	Taxa de juros. Opcional.
`tipo_juros`	string	Período dos juros: `diario`, `mensal` ou `anual`.
`metodo_calculo`	string	Método: `simples` ou `composto`.
`descricao`	text	Descrição da cobrança.
`whatsapp_devedor`	string	WhatsApp do devedor.
`pix_cobranca`	string	PIX específico da cobrança.
`status`	enum	`ativa`, `vencida` ou `paga`.
`hash`	string	Identificador público único da cobrança.
`link`	string	Link público da cobrança.
`pago`	boolean	Indica se a cobrança foi paga.
`pago_em`	date	Data de pagamento.
`comprovante_url`	string	URL do comprovante anexado.

Hooks importantes:

Antes de validar, gera hash com UUID caso ainda não exista.
Antes de validar, gera link no padrão /cobranca/:hash.
Antes de criar, define o status inicial como ativa ou vencida.

NotificacaoLida

Arquivo:

backend/src/models/notificacao.model.js

Tabela:

notificacoes_lidas

Campos:

Campo	Tipo	Descrição
`user_id`	integer	ID do usuário.
`cobranca_id`	integer	ID da cobrança.
`created_at`	date	Data em que foi marcada como lida.

Essa tabela evita que a mesma notificação seja exibida repetidamente para o usuário.

Rotas da API

Base local:

http://localhost:3000

Autenticação

Prefixo:

/auth

Método	Rota	Descrição
`POST`	`/auth/login`	Login com e-mail e senha.
`POST`	`/auth/signup`	Cadastro de usuário.
`POST`	`/auth/google`	Login com Google via token enviado pelo frontend.
`GET`	`/auth/getUser/:id`	Busca usuário por ID.
`PUT`	`/auth/:id`	Atualiza nome, e-mail e PIX do usuário.
`PUT`	`/auth/:id/updatePassword`	Atualiza senha do usuário.
`POST`	`/auth/recuperar-senha`	Gera senha temporária e envia por e-mail.

Exemplo de login:

POST /auth/login
Content-Type: application/json

{
  "email": "usuario@email.com",
  "password": "123456"
}

Exemplo de cadastro:

POST /auth/signup
Content-Type: application/json

{
  "name": "David",
  "email": "david@email.com",
  "password": "123456",
  "pix": "chave-pix-opcional"
}

Cobranças / Devedores

Prefixo:

/devedores

Método	Rota	Descrição
`GET`	`/devedores?user_id=:id`	Lista cobranças de um usuário.
`GET`	`/devedores/all`	Lista todas as cobranças.
`GET`	`/devedores/:id`	Busca uma cobrança por ID.
`GET`	`/devedores/hash/:hash`	Busca cobrança pelo hash público.
`POST`	`/devedores`	Cria nova cobrança.
`PUT`	`/devedores/:id/pagar`	Marca cobrança como paga.
`DELETE`	`/devedores/:id`	Exclui uma cobrança.

Exemplo de criação de cobrança:

POST /devedores
Content-Type: application/json

{
  "user_id": 1,
  "nome": "João da Silva",
  "email": "joao@email.com",
  "telefone": "21999999999",
  "valor": 150.75,
  "data_vencimento": "2026-06-30",
  "taxa_juros": 2,
  "tipo_juros": "mensal",
  "metodo_calculo": "composto",
  "descricao": "Cobrança referente ao serviço X",
  "whatsapp_devedor": "21999999999",
  "pix_cobranca": "chave-pix-especifica"
}

Exemplo para marcar como paga:

PUT /devedores/1/pagar
Content-Type: application/json

{
  "comprovante_url": "/uploads/comprovante.pdf"
}

Upload

Prefixo:

/upload

Método	Rota	Descrição
`POST`	`/upload/comprovante`	Faz upload de até 2 comprovantes.

O campo enviado no multipart/form-data deve ser:

comprovantes

Resposta esperada:

{
  "urls": [
    "/uploads/arquivo-1.pdf",
    "/uploads/arquivo-2.png"
  ]
}

Notificações

Prefixo:

/notifications

Método	Rota	Descrição
`GET`	`/notifications/:userId`	Lista notificações de pagamento ainda não lidas.
`PUT`	`/notifications/:userId/:cobrancaId/read`	Marca notificação como lida.

Suporte

Prefixo:

/suporte

Método	Rota	Descrição
`POST`	`/suporte/enviar`	Envia mensagem de suporte com anexo opcional.

Campos esperados no multipart/form-data:

Campo	Descrição
`assunto`	Assunto da mensagem.
`mensagem`	Texto da solicitação.
`emailUsuario`	E-mail do usuário.
`anexo`	Arquivo opcional. Aceita PNG, JPG/JPEG e PDF.

Webhook

Prefixo:

/webhook

Método	Rota	Descrição
`POST`	`/webhook/psp`	Marca cobrança como paga a partir de um PSP externo.

Exemplo:

{
  "cobrancaId": 1,
  "pagoEm": "2026-06-18T12:00:00.000Z"
}

Fluxo de cobrança

O usuário faz login.
O usuário acessa o painel.
O usuário cria uma cobrança informando devedor, valor e vencimento.
O backend salva a cobrança na tabela devedores.
O backend gera automaticamente:
- hash;
- link no formato /cobranca/:hash.
O usuário copia o link da cobrança.
O devedor acessa o link público.
O frontend busca a cobrança usando o hash.
O sistema calcula o valor atualizado com juros, se houver atraso.
O devedor visualiza a chave PIX e QR Code.
O devedor envia comprovante.
O sistema salva o comprovante e marca a cobrança como paga.
O usuário acompanha o pagamento no dashboard.

Sistema de juros

Arquivo responsável:

backend/src/utils/juros.js

O sistema suporta dois métodos de cálculo:

juros simples;
juros compostos.

E três períodos:

diário;
mensal;
anual.

Juros simples

Fórmula:

M = C * (1 + i * n)

Onde:

M = montante final;
C = capital inicial;
i = taxa em decimal;
n = número de períodos.

No sistema:

diario: usa quantidade de dias vencidos;
mensal: usa dias vencidos dividido por 30;
anual: usa dias vencidos dividido por 365.

Juros compostos

Fórmula:

M = C * (1 + i)^n

No sistema:

diario: usa quantidade de dias vencidos;
mensal: usa meses completos;
anual: usa anos completos.

Quando o valor atualizado é calculado

O backend calcula valor_atual ao:

listar cobranças;
buscar uma cobrança por ID;
buscar cobrança por hash.

Se a cobrança já foi paga, o cálculo usa pago_em como data de referência. Se ainda não foi paga, usa a data atual.

PIX e QR Code

Arquivo principal:

frontend/src/utils/pix.ts

O sistema possui duas possibilidades de PIX:

PIX padrão do usuário

Salvo em:

users.pix

Configurado na página:

/configuracoes

PIX específico da cobrança

Salvo em:

devedores.pix_cobranca

Regra de prioridade

1. Se a cobrança tiver pix_cobranca, usa o PIX específico da cobrança.
2. Se não tiver, usa o PIX padrão do usuário.

O QR Code PIX é gerado no frontend usando payload EMVCo com:

domínio BR.GOV.BCB.PIX;
chave PIX;
valor;
nome;
cidade;
CRC16.

Upload de comprovantes

O upload usa:

Multer

Arquivos relacionados:

backend/src/middlewares/upload.middleware.js
backend/src/controllers/upload.controller.js

Pasta onde os arquivos são salvos:

backend/src/uploads/

O backend serve os uploads em:

/uploads

Exemplo de URL pública local:

http://localhost:3000/uploads/nome-do-arquivo.pdf

A rota aceita até 2 arquivos no campo:

comprovantes

Autenticação

O projeto possui três fluxos principais:

Login manual

Usuário informa e-mail e senha.
Backend busca usuário pelo e-mail.
Backend compara senha usando bcrypt.
Retorna dados básicos do usuário.

Cadastro manual

Usuário informa nome, e-mail, senha e PIX opcional.
Backend verifica se já existe e-mail cadastrado.
Backend cria usuário com senha criptografada.

Login com Google

Frontend usa GoogleOAuthProvider.
Frontend envia o credential/token para o backend.
Backend decodifica o JWT do Google.
Backend cria ou atualiza o usuário com provider google.

Notificações

Arquivos principais:

backend/src/controllers/notificacao.controller.js
frontend/src/hooks/useNotifications.ts
frontend/src/components/dashboard/NotificationBell.tsx

A API do backend lista cobranças pagas ainda não marcadas como lidas.

No frontend também existe lógica para tipos como:

pagamento confirmado;
vencimento próximo;
cobrança vencida.

A tabela notificacoes_lidas registra quais notificações o usuário já viu.

Relatórios

Página:

frontend/src/pages/Relatorios.tsx

A página de relatórios organiza informações em abas/componentes, como:

visão geral;
performance;
juros;
análise temporal.

Indicadores comuns:

total de cobranças;
total a receber;
total recebido;
cobranças vencidas;
cobranças ativas;
cobranças pagas;
próximos vencimentos;
juros acumulados;
distribuição por status.

Planos e assinatura

Página:

frontend/src/pages/Planos.tsx

Hook:

frontend/src/hooks/useSubscription.ts

Funções Supabase:

supabase/functions/check-subscription
supabase/functions/create-checkout
supabase/functions/customer-portal

Planos previstos:

Free

R$ 0/mês.
Limite de cobranças.
Recursos básicos.

Basic

R$ 15,90/mês.
Mais cobranças.
Juros compostos automáticos.
Relatórios básicos.
Notificações de vencimento.

Premium

R$ 39,90/mês.
Cobranças ilimitadas.
Relatórios avançados.
Notificações personalizadas.
Suporte prioritário.

Observação: a estrutura Stripe/Supabase existe, mas alguns botões e fluxos aparecem como indisponíveis ou ainda dependem de integração final.

Suporte

Página:

frontend/src/pages/Suporte.tsx

Rota backend:

POST /suporte/enviar

Funcionalidades:

envio de assunto;
envio de mensagem;
envio do e-mail do usuário;
anexo opcional;
e-mail para suporte;
e-mail de confirmação para o usuário.

Tipos de anexo permitidos:

PNG;
JPG/JPEG;
PDF.

Supabase

O projeto possui pasta Supabase com migrations e functions.

Migrations

As migrations criam/alteram:

tabela users;
tabela cobrancas;
realtime na tabela cobrancas;
RLS;
tabela sugestoes;
trigger updated_at.

Functions

Function	Descrição
`check-subscription`	Verifica assinatura do usuário.
`create-checkout`	Cria sessão de checkout na Stripe.
`customer-portal`	Abre portal do cliente Stripe.
`validar-comprovante`	Validação experimental de comprovante com IA.

Scripts úteis

Backend

cd backend
npm install
npm run dev
npm start

Frontend

cd frontend
npm install
npm run dev
npm run build
npm run preview
npm run lint

Pontos de atenção

1. Ordem das rotas `/devedores/all` e `/devedores/:id`

No arquivo de rotas, a rota dinâmica /:id aparece antes de /all.

Isso pode fazer o Express interpretar /all como se fosse um ID.

Recomendado:

router.get("/all", listarTodosDevedores);
router.get("/:id", buscarDevedorPorId);

2. Limite do plano grátis

Existe inconsistência entre alguns trechos do código e textos da interface.

Em alguns lugares o plano grátis aparece como 5 cobranças; em outro trecho há verificação com número maior.

Recomendado: centralizar os limites em uma constante, por exemplo:

const LIMITES_PLANO = {
  free: 5,
  basic: 25,
  premium: Infinity,
};

3. Login manual e Supabase Auth são sistemas diferentes

O login principal usa backend Express e localStorage.

A assinatura usa Supabase Auth em useSubscription.

Se o usuário não estiver autenticado no Supabase Auth, o hook tende a retornar plano free, mesmo que ele esteja logado pelo backend.

Recomendado: escolher uma estratégia única de autenticação ou sincronizar os dois fluxos.

4. Supabase Realtime aponta para `cobrancas`

O backend principal usa a tabela:

devedores

Mas algumas partes Supabase usam:

cobrancas

Recomendado: padronizar a entidade principal ou criar sincronização clara entre elas.

5. URLs hardcoded

Alguns arquivos do frontend usam:

http://localhost:3000

Recomendado: criar uma variável de ambiente:

VITE_API_URL=http://localhost:3000

E usar no código:

const API_URL = import.meta.env.VITE_API_URL;

6. `.env` e uploads não devem ir para o Git

O projeto possui arquivos sensíveis/locais que devem ser ignorados:

backend/.env
frontend/.env
backend/src/uploads/*

Recomendado adicionar ao .gitignore:

.env
.env.local
backend/.env
frontend/.env
backend/src/uploads/*
!backend/src/uploads/.gitkeep
node_modules/
dist/
build/

7. Validação de comprovante com IA ainda não está totalmente integrada

Existe função Supabase:

validar-comprovante

Mas o fluxo principal do frontend/backend marca a cobrança como paga após upload do comprovante.

Recomendado: decidir se o pagamento será:

aprovado automaticamente;
aprovado manualmente;
aprovado por IA;
aprovado por webhook de PSP.

Melhorias futuras

Algumas melhorias recomendadas para evoluir o projeto:

Criar autenticação com JWT no backend.
Proteger rotas do backend por usuário autenticado.
Criar middleware de autenticação.
Substituir URLs hardcoded por VITE_API_URL.
Padronizar nomes: devedores ou cobrancas.
Criar migrations oficiais para todas as tabelas do backend.
Remover sequelize.sync({ alter: true }) em produção.
Melhorar regras de plano Free/Basic/Premium.
Integrar Stripe completamente ao login usado pela aplicação.
Integrar validação de comprovante com IA.
Adicionar status intermediário: aguardando_validacao.
Criar tela administrativa para validar comprovantes.
Criar envio automático por WhatsApp.
Criar templates de mensagem para cobrança.
Criar logs de auditoria.
Criar testes unitários e de integração.
Criar Docker Compose para backend, frontend e PostgreSQL.
Criar deploy com frontend estático e backend separado.

Boas práticas de segurança

Antes de colocar o projeto em produção:

Não versionar arquivos .env.
Trocar todas as chaves expostas.
Usar HTTPS.
Criar autenticação JWT ou sessão segura.
Proteger rotas por usuário autenticado.
Validar ownership da cobrança antes de alterar/excluir.
Limitar tamanho de uploads.
Validar extensão e MIME type dos arquivos.
Usar rate limit em login, recuperação de senha e suporte.
Armazenar uploads em storage externo, como S3 ou Supabase Storage.
Não usar sequelize.sync({ alter: true }) em produção.
Usar migrations versionadas.
Configurar CORS apenas para domínios permitidos.
Configurar cookies seguros em produção.
Remover logs sensíveis.

Exemplo de fluxo completo para teste local

Rodar PostgreSQL.
Criar banco coepay.
Configurar backend/.env.
Rodar backend:

cd backend
npm run dev

Configurar frontend/.env.
Rodar frontend:

cd frontend
npm run dev

Abrir:

http://localhost:5173

Criar uma conta.
Configurar PIX padrão.
Criar uma cobrança.
Copiar o link público.
Abrir /cobranca/:hash.
Enviar comprovante.
Conferir no painel se a cobrança foi marcada como paga.

Status do projeto

O CoéPay já possui uma base funcional completa para um MVP de cobranças PIX.

O projeto contém:

frontend estruturado;
backend com API REST;
banco PostgreSQL via Sequelize;
autenticação manual e Google;
criação e gerenciamento de cobranças;
cálculo de juros;
geração de QR Code PIX;
upload de comprovantes;
dashboard;
relatórios;
suporte;
estrutura de planos e Supabase Functions.

Ainda existem pontos que precisam ser padronizados antes de produção, principalmente autenticação, segurança das rotas, integração Supabase/Stripe e padronização entre devedores e cobrancas.

Imagens do Projeto:

Início

Login:

Painel de Controle:

Cobranças pagas:

Planos:

Suporte:

Tela de cobrança:

Name		Name	Last commit message	Last commit date
backend		backend
public		public
src		src
supabase		supabase
.env		.env
.gitignore		.gitignore
README.md		README.md
bun.lockb		bun.lockb
components.json		components.json
eslint.config.js		eslint.config.js
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.ts		tailwind.config.ts
tsconfig.app.json		tsconfig.app.json
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vite.config.ts		vite.config.ts

Latest commit

History

Folders and files

Repository files navigation

CoéPay

Sumário

Sobre o projeto

Principais funcionalidades

Stack utilizada

Frontend

Backend

Banco e serviços externos

Arquitetura do projeto

Estrutura de pastas

Como rodar localmente

Pré-requisitos

1. Clonar o projeto

2. Configurar o backend

3. Configurar o frontend

Variáveis de ambiente

Backend

Frontend

Supabase Functions

Banco de dados

Modelos principais

User

Devedor / Cobrança

NotificacaoLida

Rotas da API

Autenticação

Cobranças / Devedores

Upload

Notificações

Suporte

Webhook

Fluxo de cobrança

Sistema de juros

Juros simples

Juros compostos

Quando o valor atualizado é calculado

PIX e QR Code

PIX padrão do usuário

PIX específico da cobrança

Regra de prioridade

Upload de comprovantes

Autenticação

Login manual

Cadastro manual

Login com Google

Notificações

Relatórios

Planos e assinatura

Free

Basic

Premium

Suporte

Supabase

Migrations

Functions

Scripts úteis

Backend

Frontend

Pontos de atenção

1. Ordem das rotas /devedores/all e /devedores/:id

2. Limite do plano grátis

3. Login manual e Supabase Auth são sistemas diferentes

4. Supabase Realtime aponta para cobrancas

5. URLs hardcoded

6. .env e uploads não devem ir para o Git

7. Validação de comprovante com IA ainda não está totalmente integrada

Melhorias futuras

Boas práticas de segurança

Exemplo de fluxo completo para teste local

Status do projeto

Imagens do Projeto:

Início

Login:

Painel de Controle:

Cobranças pagas:

Planos:

1. Ordem das rotas `/devedores/all` e `/devedores/:id`

4. Supabase Realtime aponta para `cobrancas`

6. `.env` e uploads não devem ir para o Git