# Klavo API

## Visão geral do sistema

O backend é uma API REST construída com NestJS para suportar a plataforma `Klavo`, uma solução de gestão de contratos, cobrança, clientes e licenças SaaS. A aplicação foi projetada para operar em ambiente multi-tenant, com camada de segurança, controle de acesso por perfil (RBAC) e integração com serviços de fila via Redis/Bull.

## Funcionalidades principais

- Multi-tenant com isolamento de dados por tenant
- Gestão de usuários e autenticação JWT
- Controle de acesso baseado em perfis e permissões (RBAC)
- Gestão de clientes e produtos/serviços
- Criação e gerenciamento de propostas
- Emissão e controle de contratos
- Processamento de cobranças e pagamentos
- Gestão fiscal e emissão de documentos fiscais eletrônicos
- Assinaturas eletrônicas
- Administração do ambiente SaaS

## Arquitetura e componentes

### Tecnologia

- Node.js + TypeScript
- NestJS como framework principal
- PostgreSQL como banco de dados relacional
- TypeORM para ORM
- Redis + Bull para filas e processamento assíncrono
- Swagger para documentação de API
- Helmet para proteção de cabeçalhos HTTP
- ValidationPipe do NestJS para validação de requests

### Entrypoint

- `src/main.ts`: Inicializa o servidor NestJS, aplica `helmet`, habilita CORS, configura prefixo global da API (`api/v1` por padrão), ativa validação global e monta a documentação Swagger.
- O serviço escuta na porta `process.env.PORT` ou `3000`.

### Módulos principais registrados em `AppModule`

- `AuthModule`: autenticação, JWT, autenticação de usuários
- `TenantsModule`: administração de tenants e dados multi-tenant
- `RbacModule`: gerenciamento de perfis, permissões e regras de acesso
- `ClientsModule`: cadastro e gestão de clientes
- `ProductsModule`: cadastro e gestão de produtos/serviços
- `ProposalsModule`: gerenciamento de propostas comerciais
- `ContractsModule`: gestão de contratos e documentos contratuais
- `PaymentsModule`: cobranças e pagamentos
- `FiscalModule`: dados fiscais, notas e integração tributária
- `SignaturesModule`: assinaturas eletrônicas
- `SaasModule`: componentes de gestão de produto SaaS
- `AdminModule`: administração geral do sistema

## Banco de dados e modelo de dados

A aplicação utiliza PostgreSQL com suporte a extensões `uuid-ossp` e `pgcrypto`.

O esquema `docs/schema.sql` mostra que o sistema contém tabelas para:

- `tenants`: dados dos clientes corporativos da plataforma
- `roles`, `permissions`, `role_permissions`: RBAC de perfis e permissões granulares
- `users`, `user_permissions`: usuários do tenant e overrides de permissão
- `clients`: cadastro de clientes/tomadores de serviço
- `products`: registro de produtos e serviços oferecidos

O banco de dados é configurado pelo `TypeOrmModule.forRootAsync` em `AppModule`, com credenciais e host obtidos via variáveis de ambiente.

## Operação e execução

Scripts relevantes em `package.json`:

- `npm run build`: compila o NestJS para `dist`
- `npm run start`: executa o build compilado
- `npm run start:dev`: inicia em modo watch para desenvolvimento
- `npm run migration:run`: roda migrations do TypeORM
- `npm run migration:revert`: reverte migrations
- `npm run seed`: executa seeds de dados
- `npm run test`: executa testes com Jest
- `npm run lint`: executa ESLint

## Observações adicionais

- A API expõe documentação Swagger em `/{prefix}/docs`, onde `prefix` é geralmente `api/v1`.
- A aplicação está preparada para ser usada em containerização (há `Dockerfile` e `docker-compose.yml`).
- O sistema foi construído com foco em gestão empresarial de contratos e cobrança, com suporte para múltiplas empresas/tenants e políticas de acesso segregadas.