# Visão Geral

O backend do NexarGrid é construído sobre o framework MoleculerJS, uma estrutura progressiva para microsserviços em Node.js. Esta escolha arquitetural permite alta escalabilidade, tolerância a falhas e desenvolvimento modular.

# Framework MoleculerJS

O MoleculerJS fornece a espinha dorsal para a comunicação entre serviços, descoberta de serviços, balanceamento de carga e tratamento de falhas.

# Características Principais Utilizadas:

• Service Broker: Gerencia a comunicação local e remota entre serviços.
• Transporter (NATS): Utilizado para mensageria assíncrona e eventos entre nós.
• API Gateway (Moleculer-Web): Expõe os serviços via REST/HTTP.
• Caching (Redis): Cache distribuído para otimização de performance.

# Principais Serviços

Abaixo estão descritos os serviços core do sistema de gestão de escalas. Para a lista completa de endpoints, consulte a Referência da API.

# 1. CalendarGrid Service (calendargrid)

Responsável pela estrutura visual e lógica das escalas. Gerencia a grade de horários, dias e a disposição visual dos plantões.

# 2. ShiftPack Service (shiftPack)

Gerencia os pacotes de plantão (conjuntos de turnos). É o núcleo do planejamento, permitindo criar rascunhos de escalas mensais, clonar escalas anteriores e gerenciar slots de trabalho.

# 3. ShiftItem Service (shiftItem)

Gerencia a unidade atômica de trabalho: o plantão individual. Controla a atribuição de médicos (rostered), horários específicos, status (agendado, realizado, cancelado) e valores.

# 4. Rostered Service (rostered)

Gerencia os profissionais escalados (médicos). Mantém o cadastro, especialidades e vínculos com as unidades/projetos.

# 5. Payment Service (payment)

Motor de cálculo financeiro. Aplica regras de pagamento (Payment Rules) aos plantões realizados para gerar os valores a serem faturados e pagos.

# 6. Collision Service (collision)

Serviço de validação que impede conflitos de horário (ex: mesmo médico em dois lugares ao mesmo tempo) e garante o cumprimento de regras de descanso (interjornada).

# 7. PublishFSM Service (publishFSM)

Máquina de estados finitos (Finite State Machine) que orquestra o processo de publicação de escalas, garantindo que todas as validações sejam atendidas antes de tornar a escala visível para os médicos.

# Comunicação entre Serviços

A comunicação ocorre de duas formas:

1. Chamadas RPC (Request-Response): Para operações síncronas onde um serviço precisa de dados imediatos de outro (ex: shiftItem chamando rostered para validar um médico).
2. Eventos (Pub/Sub): Para operações assíncronas e desacopladas (ex: shiftItem emite evento shift.created, e collision escuta para verificar conflitos em background).

# Padrões de Requisição e Resposta

Todas as respostas da API seguem um padrão JSON consistente:

• Sucesso (2xx): Retorna o objeto ou array de dados diretamente ou encapsulado em uma propriedade data.
• Erro (4xx/5xx): Retorna um objeto de erro com code, message e type.

Para detalhes técnicos de cada endpoint, consulte o documento 07-API-REFERENCE.md.