Este documento detalha a arquitetura e os protocolos de integração entre o NexarGrid (Gestão de Escalas) e o iMedNet (CRM Proprietário do iMedGroup). O objetivo desta integração é garantir que os dados cadastrais de médicos e unidades sejam sincronizados de forma consistente, mantendo o iMedNet como a “Fonte da Verdade” (Source of Truth) para informações corporativas.

# 1. Princípios de Integração

A integração segue o padrão Unidirectional Data Flow (Fluxo Unidirecional) para dados mestres:

• iMedNet (CRM) -> NexarGrid: Dados de Médicos (Rostered), Unidades (Projects) e Contratos. O NexarGrid atua como consumidor passivo dessas informações.
• NexarGrid -> iMedNet (CRM): Dados de Produção (Plantões Realizados) para fins de inteligência de negócios e relacionamento.

# 1.1 Camada Anticorrupção (ACL)

Para evitar o acoplamento direto entre o modelo de dados legado do CRM e o modelo de domínio do NexarGrid, implementamos uma Anti-Corruption Layer (ACL).

• Função: Receber webhooks ou eventos do iMedNet, traduzir os DTOs externos para comandos do domínio NexarGrid (ex: CreateRostered, UpdateProfessionalLicense) e postar no barramento NATS.
• Benefício: Se o esquema do CRM mudar, apenas a ACL precisa ser ajustada, protegendo o núcleo do NexarGrid.

# 2. Fluxos de Sincronização

# 2.1 Onboarding de Médicos (Novo Cadastro)

Quando um novo médico é credenciado no iMedGroup via CRM, ele deve ser automaticamente provisionado no NexarGrid para ser escalado.

# 2.2 Atualização Cadastral

Alterações críticas no CRM (ex: mudança de especialidade ou renovação de CRM/RQE) disparam atualizações imediatas.

• Gatilho: Edição no cadastro do médico no iMedNet.
• Ação no NexarGrid: O serviço Rostered atualiza os metadados.
• Impacto: Se a especialidade mudar, o CollisionDetector pode revalidar escalas futuras para garantir conformidade com regras de qualificação.

# 2.3 Bloqueio e Compliance (Offboarding)

Se um médico for bloqueado no CRM (ex: pendência jurídica ou administrativa), o NexarGrid deve impedir novas alocações imediatamente.

1. Evento: PhysicianBlocked { reason: "Compliance", effectiveDate: "2026-01-05" }
2. Ação Imediata: O status do Rostered muda para Suspended.
3. Ação Reativa: O sistema varre escalas futuras (ShiftItems com status Assigned) e gera alertas para os gestores realizarem a substituição.

# 3. Mapeamento de Dados (Data Mapping)

A tabela abaixo define a tradução dos campos do iMedNet para o NexarGrid.

Entidade	Campo iMedNet (Origem)	Campo NexarGrid (Destino)	Observações
Médico	id_medico (INT)	externalId (String)	Chave de idempotência.
	nome_completo	name	-
	cpf	taxId	Usado para unicidade fiscal.
	crm_numero + crm_uf	licenseNumber + licenseState	Fundamental para validação legal.
	especialidades (Array)	specialties (Array)	Mapeado para tags de qualificação.
	status_cadastro	status	Ativo -> Active, Bloqueado -> Suspended.
Unidade	id_unidade	externalId	-
	nome_fantasia	name	-
	centro_custo	costCenter	Usado para agrupamento financeiro.

# 4. Tratamento de Erros e Resiliência

Como sistemas distribuídos podem falhar, a integração adota estratégias defensivas:

• Filas de Dead Letter (DLQ): Mensagens de integração malformadas ou que falham no processamento são enviadas para uma DLQ no NATS para análise manual.
• Idempotência: O processamento de eventos verifica o externalId. Se um evento de “Criação” for recebido duas vezes, o segundo é ignorado (ou tratado como atualização).
• Retry Exponencial: Falhas temporárias (ex: banco de dados indisponível) acionam retentativas automáticas com backoff exponencial.

---

# 5. Próximos Passos da Integração

• [ ] Fase 1: Sincronização unidirecional de Médicos (CRM -> Nexar).
• [ ] Fase 2: Sincronização de Unidades e Centros de Custo.
• [ ] Fase 3: Retorno de dados de produção (Plantões Realizados) para o CRM calcular LTV (Lifetime Value) do médico.

# 6. Exemplos de Payloads (JSON)

Abaixo estão os exemplos canônicos dos payloads esperados pela API de Integração (Webhook Receiver).

# 6.1 Evento: Criação de Médico (PhysicianCreated)

Este evento deve ser disparado assim que o cadastro do médico for aprovado no CRM.

{
  "event": "physician.created",
  "timestamp": "2026-01-05T14:30:00Z",
  "data": {
    "externalId": "MED-8842",
    "name": "Dra. Ana Clara Souza",
    "taxId": "123.456.789-00",
    "email": "[email protected]",
    "phone": "+5511999998888",
    "professionalLicense": {
      "number": "123456",
      "state": "SP",
      "type": "CRM"
    },
    "specialties": [
      "Cardiologia",
      "Clínica Médica"
    ],
    "status": "ACTIVE"
  }
}

# 6.2 Evento: Atualização de Status (PhysicianStatusChanged)

Utilizado para bloquear ou desbloquear um profissional.

{
  "event": "physician.status_changed",
  "timestamp": "2026-02-10T09:15:00Z",
  "data": {
    "externalId": "MED-8842",
    "previousStatus": "ACTIVE",
    "newStatus": "SUSPENDED",
    "reason": "Documentação vencida (RQE)",
    "effectiveDate": "2026-02-10"
  }
}

# 6.3 Evento: Sincronização de Unidade (UnitUpserted)

Utilizado para criar ou atualizar dados de hospitais e centros de custo.

{
  "event": "unit.upserted",
  "timestamp": "2026-01-05T10:00:00Z",
  "data": {
    "externalId": "UNIT-001",
    "name": "Hospital Santa Catarina - UTI Adulto",
    "costCenter": "CC-2024-HSC-UTI",
    "address": {
      "street": "Av. Paulista, 200",
      "city": "São Paulo",
      "state": "SP",
      "zipCode": "01310-100"
    },
    "active": true
  }
}