microservice-administrator

1. OBJETIVO

Microserviço NestJS responsável por gestão de unidades de negócio, modelos de propostas/contratos, configurações visuais, usuários, assinantes e empresas. Implementa Clean Architecture com DDD, multi-tenancy e integração com serviços externos.

2. ÚLTIMA REVISÃO

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

3. TECNOLOGIAS UTILIZADAS

Backend

Node.js, NestJS 11.0.10, TypeScript 5.7.3, Prisma 6.4.1

Swagger 11.0.5, Scalar API Reference 0.5.12, class-validator/transformer

AWS SQS SDK 3.750.0, Firebase Admin 13.1.0, Axios 1.7.9

Vitest 3.0.7 (testes), ESLint, Prettier

Repositórios: Local/GitHub

Frontend

Não aplicável (API pura)

Banco de Dados

PostgreSQL (via Prisma ORM), Multi-tenancy nativo

Ferramentas de Conexão e Infraestrutura

Docker Compose (PostgreSQL + App), Prisma migrations, Auth API externa, AWS SQS

4. FUNCIONALIDADES E DOMÍNIOS

• Gestão de Unidades: Criação com dados da empresa, configurações visuais, relacionamentos
• Modelos de Documentos: Propostas A4 (horizontal/vertical), contratos personalizáveis, modelo padrão
• Gestão de Usuários: CRUD completo, onboarding automatizado, bloqueio/desbloqueio
• Sistema de Assinantes: Gestão completa, validação CPF único, soft delete, recuperação
• Gestão de Empresas: Dados completos (CNPJ, endereço), validação única, integração unidades
• Configurações Visuais: Logos tema claro/escuro, cores personalizáveis, fontes customizáveis
• Integrações: Auth Service, AWS SQS, Firebase Admin, Prisma migrations
• Observabilidade: Swagger/Scalar documentação, logs estruturados, tratamento erros

5. ARQUITETURA FRONTEND

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

6. ARQUITETURA BACKEND

Controllers

UsersController (/users), UnitController (/unit), ProposalModelController (/proposal-models)

ContractModelController (/contract-models), SignersController (/signers), CompanyController (/companies)

SwaggerJsonController (documentação)

Features

Gestão completa de unidades, modelos de documentos, usuários, assinantes, empresas

Multi-tenancy nativo, integração Auth Service, AWS SQS messaging

Repositories

9 repositórios Prisma especializados (Users, Units, ProposalModel, ContractModel, Signers, Company, etc.)

Entities

User, Unit, UnitSettings, ProposalModel, ContractModel, Signer, Company, UserUnit, SignerUnit

Helper/Utilities

AuthService, SqsService, PrismaClientManager, ValidationPipe, Presenters, Error Handling

7. ROTAS E ENDPOINTS

8. ESTRUTURA DE DADOS, TABELAS E VIEWS

Principais tabelas

users, units, unit_settings, proposal_models, contract_models, signers, companies, user_units, signer_units

Relacionamentos

Multi-tenancy nativo, relacionamentos N:N entre usuários/assinantes e unidades

Enums

ProposalModelFormat (a4_horizontal, a4_vertical), ProposalModelModel (black_and_white, white_and_black)

Soft Delete

Implementado em todas as entidades principais para auditoria

9. CONFIGURAÇÃO E VARIÁVEIS

Arquivo principal

docker-compose.yml

Variáveis principais

DATABASE_URL (PostgreSQL), AUTH_API_URL (Auth Service), NODE_ENV, PORT (3000)

SQS_QUEUE_URL, AWS_REGION, AWSSETTINGS__ASTERAPPACCESSKEYID, AWSSETTINGS__ASTERAPPACCESSKEYSECRET

Configurações Docker

PostgreSQL: porta 5432, database "administrator"; App: porta 3000, hot reload

Volumes para persistência de dados

10. TREEVIEW DA ARQUITETURA

microservice-administrator/
├── src/
│   ├── auth/
│   │   ├── auth.service.ts          # Integração Auth Service
│   │   └── auth.module.ts           # Módulo de autenticação
│   ├── common/
│   │   ├── error-handling/          # Tratamento de erros
│   │   ├── sqs/                     # AWS SQS service
│   │   └── validation/              # Validações comuns
│   ├── core/
│   │   ├── entities/                # Entidades de domínio
│   │   ├── repositories/             # Interfaces de repositórios
│   │   └── use-cases/               # Casos de uso
│   ├── domain/
│   │   ├── entities/                # Entidades (8 arquivos)
│   │   ├── models/                  # Modelos de domínio
│   │   ├── repositories/            # Interfaces (9 arquivos)
│   │   └── use-case/                # Casos de uso (68 arquivos)
│   └── infra/
│       ├── app.module.ts            # Módulo principal
│       ├── main.ts                  # Bootstrap da aplicação
│       ├── database/
│       │   ├── prisma/              # Configuração Prisma
│       │   │   ├── repositories/    # Implementações (9 arquivos)
│       │   │   └── prisma.service.ts # Cliente Prisma
│       │   └── database.module.ts   # Módulo de banco
│       └── http/
│           ├── controllers/         # Controllers (7 arquivos)
│           ├── dto/                 # DTOs (22 arquivos)
│           ├── presenters/          # Presenters (9 arquivos)
│           ├── header.ts           # Decorator de headers
│           └── http.module.ts       # Módulo HTTP
├── prisma/
│   ├── schema.prisma               # Schema do banco
│   ├── migrations/                 # Migrations (53 arquivos)
│   └── seed.ts                     # Seeds de dados
├── test/                           # Testes (11 arquivos)
├── docker-compose.yml              # Orquestração
├── Dockerfile                      # Build produção
├── Dockerfile.dev                  # Build desenvolvimento
├── package.json                    # Dependências
├── tsconfig.json                   # Configuração TypeScript
├── vitest.config.ts               # Configuração testes
└── README.md                       # Documentação

11. INTEGRAÇÕES E DEPENDÊNCIAS

Serviços externos

Auth Service (autenticação), AWS SQS (messaging), Firebase Admin (notificações), PostgreSQL (banco)

Dependências principais

@nestjs/common/core, @nestjs/swagger, @scalar/nestjs-api-reference, @prisma/client

@aws-sdk/client-sqs, firebase-admin, class-validator/transformer, axios, vitest

12. INTEGRAÇÕES EXTERNAS

Auth Service

Integração com microserviço de autenticação para validação de usuários

AWS SQS

Messaging assíncrono para comunicação entre microserviços

Firebase Admin

Notificações push e serviços Firebase

PostgreSQL

Banco de dados principal com Prisma ORM

13. CONTROLE DE VERSÃO

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

14. SEGURANÇA E ACESSO

• Multi-tenancy nativo com isolamento por tenant
• Integração com Auth Service externo
• Validação rigorosa com class-validator
• Headers obrigatórios (x-tenant-id, authorization)
• Soft delete para auditoria
• CORS configurado, tratamento de erros centralizado
• Validação de CPF/CNPJ únicos

15. CONSIDERAÇÕES FINAIS

Microserviço Administrator robusto e bem estruturado em NestJS, seguindo Clean Architecture e DDD. Implementa gestão completa de unidades de negócio, modelos de documentos, usuários, assinantes e empresas. Preparado para produção com multi-tenancy, integrações externas, testes automatizados e documentação completa. Arquitetura modular permite fácil manutenção e extensão das funcionalidades administrativas do ecossistema Aster/UVA.