77 lines
1.8 KiB
Markdown
77 lines
1.8 KiB
Markdown
# billing-finance-core
|
|
|
|
Backend financeiro, billing, fiscal e CRM para uma plataforma SaaS multi-tenant.
|
|
|
|
## Visão geral
|
|
- **Multi-tenant desde o início** com isolamento por `tenantId`.
|
|
- **Sem autenticação própria**: confia no `identity-gateway` via JWT interno.
|
|
- **Core financeiro**: planos, assinaturas, invoices, pagamentos, conciliação.
|
|
- **Fiscal (base)**: estrutura para emissão de NFS-e.
|
|
- **CRM**: empresas, contatos e pipeline simples de negócios.
|
|
|
|
## Stack
|
|
- Node.js + TypeScript
|
|
- NestJS
|
|
- PostgreSQL + Prisma
|
|
- Docker
|
|
|
|
## Integração com identity-gateway
|
|
- Todas as rotas são protegidas por JWT interno.
|
|
- O token deve conter:
|
|
- `tenantId`
|
|
- `userId`
|
|
- `roles`
|
|
- O guard valida `issuer` e assina com `JWT_PUBLIC_KEY` ou `JWT_SECRET`.
|
|
|
|
## Modelo de dados (resumo)
|
|
- **Tenant**: empresa cliente
|
|
- **Plan**: preço, ciclo e limites
|
|
- **Subscription**: tenant + plano
|
|
- **Invoice**: contas a receber
|
|
- **Payment**: pagamentos com gateway
|
|
- **FiscalDocument**: base para NFS-e
|
|
- **CRM**: companies, contacts, deals
|
|
|
|
## Fluxo de cobrança
|
|
1. Criar plano
|
|
2. Criar assinatura
|
|
3. Gerar invoice
|
|
4. Criar pagamento via gateway
|
|
5. Receber webhook e conciliar
|
|
|
|
## Endpoints mínimos
|
|
```
|
|
POST /tenants
|
|
GET /tenants
|
|
POST /plans
|
|
GET /plans
|
|
POST /subscriptions
|
|
GET /subscriptions
|
|
POST /invoices
|
|
GET /invoices
|
|
POST /payments/:invoiceId
|
|
POST /webhooks/:gateway
|
|
GET /crm/companies
|
|
POST /crm/deals
|
|
GET /health
|
|
```
|
|
|
|
## Configuração local
|
|
```bash
|
|
cp .env.example .env
|
|
npm install
|
|
npm run prisma:generate
|
|
npm run prisma:migrate
|
|
npm run start:dev
|
|
```
|
|
|
|
## Docker
|
|
```bash
|
|
docker compose up --build
|
|
```
|
|
|
|
## Estrutura
|
|
- `src/core`: guard e contexto do tenant
|
|
- `src/modules`: domínios de negócio
|
|
- `prisma/`: schema e migrations
|
|
- `docs/`: documentação técnica
|