Microservice HR

1. OBJETIVO

Este documento consolida as informações técnicas e de arquitetura do projeto "microservice-hr", um microserviço desenvolvido em NestJS que gerencia recursos humanos, incluindo cadastro de pessoas, funcionários, endereços e contatos. O serviço implementa Clean Architecture com separação clara de responsabilidades e utiliza Prisma ORM para persistência de dados PostgreSQL. O microserviço oferece APIs REST completas para gestão de entidades de RH com autenticação JWT, documentação Swagger e testes automatizados.

2. ÚLTIMA REVISÃO

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

3. TECNOLOGIAS UTILIZADAS

Backend

Node.js v20+, NestJS v10.0.0 (framework), TypeScript v5.1.3, Prisma ORM v5.21.1, JWT (jsonwebtoken v9.0.2), Passport (autenticação), Swagger (documentação), Class-validator v0.14.1, Class-transformer v0.5.1 (validação), bcrypt v5.1.1 (hash), Jest v29.5.0 (testes), ESLint, Prettier (qualidade de código)

Frontend

Não aplicável (API pura)

Banco de Dados

PostgreSQL v14 (principal), Prisma Migrations para versionamento do schema

Ferramentas de Conexão e Infraestrutura

Docker Compose v3.8 (PostgreSQL + App), Docker multi-stage build para produção, Prisma Migrations para controle de schema

4. FUNCIONALIDADES E DOMÍNIOS

Person

Gestão de pessoas (física/jurídica/estrangeira) com suporte a PersonType (CORPORATE, INDIVIDUAL, FOREIGN), validação de dados com enums (TaxRegime, CivilStatus, Gender) e campos opcionais para flexibilidade

Employee

Gestão de funcionários vinculados a pessoas com relacionamento One-to-One, suporte a PositionType (FULL_TIME, PART_TIME, CONTRACTOR, INTERN) e EmploymentStatus (ACTIVE, INACTIVE, SUSPENDED)

Address

Gestão de endereços (residencial/comercial) com relacionamento Many-to-One com Person, suporte a AddressType (RESIDENTIAL, COMMERCIAL) e estados brasileiros via enum BrazilianState

Contact

Gestão de contatos (email, telefone, etc.) com relacionamento Many-to-One com Person e suporte a primaryContact para contato principal

5. ARQUITETURA FRONTEND

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

6. ARQUITETURA BACKEND

Clean Architecture com separação de responsabilidades:

Controllers/Endpoints:

• PersonController: CRUD completo de pessoas (/persons) com documentação Swagger completa e exemplos
• EmployeeController: CRUD de funcionários (/employees) com validação de relacionamento com Person
• AddressController: CRUD de endereços (/addresses) com validação de dados de endereço
• ContactController: CRUD de contatos (/contact) - Estrutura básica implementada (vazia)

Services (Lógica de Negócio):

• PersonService: Validação de dados e tratamento de exceções, integração com PersonRepository
• EmployeeService: Validação de relacionamento com Person, tratamento de exceções NotFoundException
• AddressService: Validação de dados de endereço
• ContactService: Validação de dados de contato

Repositories (Persistência):

• PersonRepository: Métodos CRUD completos com Prisma ORM
• EmployeeRepository: Relacionamento com Person via foreign key
• AddressRepository: Relacionamento com Person via foreign key
• ContactRepository: Relacionamento com Person via foreign key

Entities/DTOs:

• Person: id, type, name, tradeName, taxId, identity, issuingAgency, taxRegime, civilStatus, gender, birthDate, nationality, profession, createdAt
• Employee: id, personId, position, salary, hiringDate, employmentStatus, isPJ
• Address: id, personId, addressType, postalCode, state, city, district, street, number, additionalInfo
• Contact: id, personId, contactType, contactValue, primaryContact
• DTOs: CreatePersonDto, UpdatePersonDto, CreateEmployeeDto, CreateContactDto, UpdateContactDto com validação class-validator e documentação Swagger

Guards/Middlewares:

• AuthGuard: Validação JWT para autenticação com verificação de Bearer token, validação com JWT_SECRET e tratamento de exceções UnauthorizedException
• MockAuthGuard: Guard mock para desenvolvimento
• AllExceptionsFilter: Filtro global de exceções com tratamento padronizado de erros HTTP e logs estruturados de exceções

Helper/Utilities:

• PrismaService: Singleton para conexão com banco
• SecurityModule: Configuração global do AuthGuard

7. ROTAS E ENDPOINTS

PersonController:

• GET /persons - Listar todas as pessoas
• GET /persons/:id - Buscar pessoa por ID
• POST /persons - Criar nova pessoa
• PUT /persons/:id - Atualizar pessoa
• DELETE /persons/:id - Remover pessoa

Outros Controllers:

• EmployeeController: CRUD de funcionários (/employees)
• AddressController: CRUD de endereços (/addresses)
• ContactController: CRUD de contatos (/contact)

8. ESTRUTURA DE DADOS, TABELAS E VIEWS

Banco de Dados PostgreSQL:

Tabelas Principais:

• Person: Dados básicos de pessoas
  • Campos: id, type, name, tradeName, taxId, identity, issuingAgency, taxRegime, civilStatus, gender, birthDate, nationality, profession, createdAt
  • Enums: PersonType (CORPORATE, INDIVIDUAL, FOREIGN), TaxRegime, CivilStatus, Gender
• Employee: Dados de funcionários
  • Campos: id, personId, position, salary, hiringDate, employmentStatus, isPJ
  • Enums: PositionType (FULL_TIME, PART_TIME, CONTRACTOR, INTERN), EmploymentStatus (ACTIVE, INACTIVE, SUSPENDED)
  • Relacionamento: One-to-One com Person
• Address: Endereços das pessoas
  • Campos: id, personId, addressType, postalCode, state, city, district, street, number, additionalInfo
  • Enums: AddressType (RESIDENTIAL, COMMERCIAL), BrazilianState
  • Relacionamento: Many-to-One com Person
• Contact: Contatos das pessoas
  • Campos: id, personId, contactType, contactValue, primaryContact
  • Relacionamento: Many-to-One com Person

Views:

Não implementadas

9. CONFIGURAÇÃO E VARIÁVEIS

Variáveis de ambiente:

• DATABASE_URL: String de conexão PostgreSQL
• JWT_SECRET: Chave secreta para validação JWT
• PORT: Porta da aplicação (padrão: 3000)
• NODE_ENV: Ambiente de execução (development/production)

Docker Compose para desenvolvimento:

• PostgreSQL v14 com volumes persistentes
• Configuração de rede app_network
• Variáveis de ambiente via .env

Docker multi-stage build para produção:

• Build otimizado com Node.js Alpine
• Migrações automáticas no startup
• Configuração de usuário não-root

10. TREEVIEW DA ARQUITETURA

microservice-hr/
├── docker-compose.yml                 # Configuração Docker
├── Dockerfile                         # Imagem Docker
├── package.json                       # Dependências Node.js
├── prisma/
│   ├── migrations/                    # Migrações do banco
│   │   └── 20241031002634_init/
│   │       └── migration.sql
│   └── schema.prisma                  # Schema do banco de dados
├── src/
│   ├── app.module.ts                  # Módulo principal
│   ├── main.ts                        # Ponto de entrada
│   ├── domain/                        # Camada de domínio
│   │   ├── entities/                  # Entidades de negócio
│   │   │   ├── contact.entity.ts
│   │   │   ├── employee.entity.ts
│   │   │   ├── person.entity.ts
│   │   │   └── person.enums.ts
│   │   └── services/                  # Serviços de domínio
│   │       ├── address.service.ts
│   │       ├── contact.service.ts
│   │       ├── employee.service.ts
│   │       └── person.service.ts
│   ├── infrastructure/                # Camada de infraestrutura
│   │   ├── filters/                   # Filtros globais
│   │   │   └── all-exceptions.filter.ts
│   │   ├── guards/                    # Guards de autenticação
│   │   │   ├── auth.guard.ts
│   │   │   └── mock-auth.guard.ts
│   │   ├── prisma/                    # Configuração Prisma
│   │   │   ├── prisma.module.ts
│   │   │   ├── prisma.service.ts
│   │   │   └── repositories/          # Repositórios
│   │   │       ├── address.repository.ts
│   │   │       ├── contact.repository.ts
│   │   │       ├── employee.repository.ts
│   │   │       └── person.repository.ts
│   │   └── security/                  # Módulo de segurança
│   │       └── security.module.ts
│   ├── interfaces/                    # Interfaces e mocks
│   │   └── http/
│   │       └── __mocks__/
│   │           ├── address.mock.ts
│   │           └── person.mocks.ts
│   └── presentation/                  # Camada de apresentação
│       ├── controllers/               # Controllers REST
│       │   ├── address.controller.ts
│       │   ├── contact.controller.ts
│       │   ├── employee.controller.ts
│       │   └── person.controller.ts
│       ├── dtos/                      # Data Transfer Objects
│       │   ├── create-contact.dto.ts
│       │   ├── create-employee.dto.ts
│       │   ├── create-person.dto.ts
│       │   ├── update-contact.dto.ts
│       │   └── update-person.dto.ts
│       └── modules/                   # Módulos NestJS
│           ├── address.module.ts
│           ├── contact.module.ts
│           ├── employee.module.ts
│           └── person.module.ts
└── test/                              # Testes
    ├── app.e2e-spec.ts
    ├── jest-e2e.json
    └── setup.ts
      

11. INTEGRAÇÕES E DEPENDÊNCIAS

Dependências principais

Node.js, NestJS, TypeScript, Prisma ORM, JWT, Passport, Swagger, Class-validator, Class-transformer, bcrypt, Jest, ESLint, Prettier

Banco de Dados

PostgreSQL (principal)

Ferramentas

Docker Compose, Prisma Migrations

12. INTEGRAÇÕES EXTERNAS

Comunicação Interna

REST API com Swagger (/api), Endpoints padronizados CRUD, Validação de dados com class-validator, Tratamento de exceções global

Documentação

Swagger UI disponível em /api, Documentação automática dos endpoints, Exemplos de request/response, Autenticação Bearer configurada

13. CONTROLE DE VERSÃO

• Repositório: Local/GitHub
• Branch principal: main/master
• Estratégia: Git Flow (preparado)
• Migrações: Prisma Migrate

14. SEGURANÇA E ACESSO

Autenticação:

• JWT (jsonwebtoken) com Bearer Token
• AuthGuard para validação de tokens
• MockAuthGuard para desenvolvimento
• Variável de ambiente: JWT_SECRET

Autorização:

• Bearer Token obrigatório em endpoints protegidos
• Swagger com autenticação configurada
• Filtro global de exceções para tratamento de erros

15. CONSIDERAÇÕES FINAIS

O microservice-hr é um serviço bem estruturado seguindo Clean Architecture, com separação clara de responsabilidades entre as camadas de domínio, infraestrutura e apresentação. O uso do Prisma ORM facilita a manipulação de dados e migrações, enquanto o NestJS fornece uma base sólida para APIs REST. O serviço implementa um modelo de dados robusto para gestão de recursos humanos com suporte a diferentes tipos de pessoas e relacionamentos complexos.

Pontos Fortes:

• Arquitetura limpa e bem organizada seguindo Clean Architecture
• Documentação automática com Swagger UI (/api)
• Testes configurados e estruturados (Jest + E2E)
• Validação robusta de dados com class-validator
• Suporte completo a CRUD para todas as entidades principais
• Modelo de dados flexível com enums para validação
• Autenticação JWT implementada com guards
• Docker Compose para desenvolvimento local
• Migrações Prisma para controle de schema
• Tratamento global de exceções padronizado

O serviço está preparado para integração com outros microserviços do ecossistema Aster/UVA e pode ser facilmente expandido com novas funcionalidades de RH. A arquitetura modular permite adição de novos domínios sem impacto nas funcionalidades existentes.