microservice-backoffice

1. OBJETIVO DO REPOSITÓRIO

Este documento consolida as informações técnicas e de arquitetura do projeto "microservice-backoffice", um microserviço NestJS responsável por gestão completa de clientes, planos de assinatura, pagamentos, instâncias (tenants) e integração com gateway de pagamentos Asaas. Implementa sistema completo de backoffice para gestão de clientes e suas assinaturas, fornecendo APIs RESTful para operações CRUD, webhooks de pagamento e controle de instâncias multi-tenant.

2. ÚLTIMA REVISÃO

• 15/09/2025 - Revisão e atualização da documentação (Equipe)

3. TECNOLOGIAS UTILIZADAS

Backend

Node.js, NestJS 10.0.0, TypeScript 5.1.3, Prisma 6.2.1

Swagger 8.1.1, class-validator, Axios 1.7.9

date-fns 4.1.0, nanoid 5.1.2

Jest 29.5.0 (testes), ESLint, Prettier

Repositórios: Local/GitHub

Frontend

Não aplicável (API pura)

Banco de Dados

PostgreSQL (via Prisma ORM), Soft delete implementado

Ferramentas de Conexão e Infraestrutura

Docker Compose (PostgreSQL), Prisma migrations, Integração com Asaas

4. FUNCIONALIDADES E DOMÍNIOS

Sistema completo de backoffice com os seguintes domínios:

Domínios Principais

Clientes: Gestão completa de dados empresariais e responsáveis

Planos: Catálogo de planos de assinatura com preços e configurações

Assinaturas: Controle de assinaturas vinculadas a clientes e planos

Pagamentos: Webhook e gestão de eventos de pagamento

Tenants: Instâncias multi-tenant com controle de status

Integração Asaas: Gateway de pagamentos externo

Funcionalidades por Domínio

Clientes: CRUD completo, validação de CNPJ único, soft delete, recuperação

Planos: Criação/edição, controle de ativação/desativação, visibilidade

Assinaturas: Criação, cancelamento, recuperação, relacionamento com pagamentos

Pagamentos: Webhook para eventos do Asaas, captura de status

Tenants: Criação sem assinatura, ativação/inativação, relacionamentos

5. ARQUITETURA FRONTEND

Não aplicável - API pura sem frontend próprio

6. ARQUITETURA BACKEND

Controllers

CustomersController (/customers), PlansController (/plans), SubscriptionsController (/subscriptions)

PaymentsController (/events/payments), TenantsController (/tenants), AsaasService (integração)

Features

Gestão completa de clientes, planos, assinaturas, pagamentos, tenants

Integração com gateway Asaas, sistema de eventos, soft delete

Repositories

5 repositórios Prisma especializados (Customers, Plans, Subscriptions, Payments, Tenants)

Entities

Customer, Plan, Subscription, Payment, Tenant, Placeholder

Helper/Utilities

AsaasService, EventsService, AuthService, ValidationPipe, Swagger

7. ROTAS E ENDPOINTS

8. ESTRUTURA DE DADOS, TABELAS E VIEWS

Modelos Prisma

Customer: id (UUID, PK), externalId (String, unique), company, cnpj (unique), fantasyName, endereço completo, dados do responsável, timestamps, soft delete

Plan: id (UUID, PK), name, slug, description, price (Float), isActive, isVisible, timestamps, soft delete

Subscription: id (UUID, PK), externalId, customer (FK), plan (FK), payments (FK), status, timestamps

Payment: id (UUID, PK), externalId, status, subscription (FK), value, createdAt

Tenant: id (UUID, PK), status (default: "pending"), customer (FK), plan (FK), subscription (optional FK), timestamps, soft delete

Placeholder: id (UUID, PK), createdAt

Relacionamentos

Customer -> Subscriptions, Plan -> Subscriptions, Subscription -> Payments, Customer -> Tenants, Plan -> Tenants

9. CONFIGURAÇÃO E VARIÁVEIS

Arquivo principal

docker-compose.yml

Variáveis principais

DATABASE_URL (PostgreSQL), PORT (3000), ASAAS_URL, ASAAS_TOKEN

Configurações Docker

PostgreSQL: porta 5432, database "db_backoffice"; Volumes para persistência

Configurações NestJS

CORS habilitado, Swagger em /api, Validação global, Logs estruturados

10. TREEVIEW DA ARQUITETURA

microservice-backoffice/
├── src/
│   ├── app.controller.ts            # Controller principal
│   ├── app.module.ts               # Módulo principal
│   ├── app.service.ts              # Service principal
│   ├── main.ts                     # Bootstrap da aplicação
│   ├── asaas/
│   │   ├── asaas.module.ts         # Módulo Asaas
│   │   ├── asaas.service.ts         # Service de integração
│   │   └── dto/                    # DTOs do Asaas (3 arquivos)
│   ├── auth/
│   │   ├── auth.module.ts          # Módulo de autenticação
│   │   ├── auth.service.ts         # Service de autenticação
│   │   └── auth.controller.ts      # Controller de autenticação
│   ├── customers/
│   │   ├── customers.controller.ts # Controller de clientes
│   │   ├── customers.service.ts    # Service de clientes
│   │   ├── customers.repository.ts # Repository de clientes
│   │   ├── customers.module.ts     # Módulo de clientes
│   │   ├── dto/                    # DTOs (2 arquivos)
│   │   └── interfaces/             # Interfaces (1 arquivo)
│   ├── database/
│   │   ├── database.module.ts      # Módulo de banco
│   │   └── prisma.service.ts       # Service Prisma
│   ├── events/
│   │   ├── events.module.ts        # Módulo de eventos
│   │   ├── events.service.ts       # Service de eventos
│   │   └── events.controller.ts   # Controller de eventos
│   ├── payments/
│   │   ├── payments.controller.ts  # Controller de pagamentos
│   │   ├── payments.service.ts     # Service de pagamentos
│   │   ├── payments.repository.ts  # Repository de pagamentos
│   │   ├── payments.module.ts      # Módulo de pagamentos
│   │   └── dto/                    # DTOs (1 arquivo)
│   ├── plans/
│   │   ├── plans.controller.ts     # Controller de planos
│   │   ├── plans.service.ts        # Service de planos
│   │   ├── plans.repository.ts     # Repository de planos
│   │   ├── plans.module.ts         # Módulo de planos
│   │   ├── dto/                    # DTOs (2 arquivos)
│   │   └── interfaces/             # Interfaces (1 arquivo)
│   ├── subscriptions/
│   │   ├── subscriptions.controller.ts # Controller de assinaturas
│   │   ├── subscriptions.service.ts     # Service de assinaturas
│   │   ├── subscriptions.repository.ts  # Repository de assinaturas
│   │   ├── subscriptions.module.ts      # Módulo de assinaturas
│   │   ├── dto/                         # DTOs (1 arquivo)
│   │   └── interfaces/                  # Interfaces (1 arquivo)
│   └── tenants/
│       ├── tenants.controller.ts    # Controller de tenants
│       ├── tenants.service.ts       # Service de tenants
│       ├── tenants.repository.ts    # Repository de tenants
│       ├── tenants.module.ts        # Módulo de tenants
│       └── dto/                     # DTOs (1 arquivo)
├── prisma/
│   ├── schema.prisma               # Schema do banco
│   ├── migrations/                 # Migrations (4 arquivos)
│   └── migrations.toml             # Configuração migrations
├── docker-compose.yml              # Orquestração PostgreSQL
├── Dockerfile                      # Build produção
├── package.json                    # Dependências
├── tsconfig.json                   # Configuração TypeScript
├── nest-cli.json                   # Configuração NestJS
└── README.md                       # Documentação

11. INTEGRAÇÕES E DEPENDÊNCIAS

Serviços externos

Asaas (gateway de pagamentos), PostgreSQL (banco de dados)

Dependências principais

@nestjs/common/core, @nestjs/swagger, @nestjs/axios, @prisma/client

class-validator, date-fns, nanoid, axios

12. INTEGRAÇÕES EXTERNAS

Asaas Gateway de Pagamentos

Criação de clientes no Asaas

Busca de clientes por CPF/CNPJ

Atualização de dados de clientes

Exclusão de clientes

Criação de assinaturas

Cancelamento de assinaturas

Webhook para eventos de pagamento

PostgreSQL

Banco de dados principal

Migrations versionadas

Soft delete implementado

Relacionamentos entre entidades

13. CONTROLE DE VERSÃO

• Repositório: Local/GitHub
• Versionamento semântico recomendado
• Docker para desenvolvimento
• Prisma migrations versionadas
• Scripts organizados (build, test, migrate)

14. SEGURANÇA E ACESSO

• Validação rigorosa com class-validator
• Soft delete para auditoria
• CORS configurado
• Tratamento de erros centralizado
• Logs estruturados
• Validação de CNPJ único
• Webhook seguro para eventos do Asaas

15. CONSIDERAÇÕES FINAIS

Microserviço Backoffice robusto e bem estruturado em NestJS, responsável por gestão completa de clientes, planos, assinaturas, pagamentos e instâncias. Implementa integração completa com gateway de pagamentos Asaas, sistema de eventos e soft delete para auditoria. Preparado para produção com documentação Swagger, testes automatizados e arquitetura modular. Sistema essencial para gestão de clientes e assinaturas do ecossistema Aster/UVA.