# 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