Funcionamento
Endpoints
Permissões
Headers
Path parameters
Query parameters
Body
Response
Erros
Regras de negócio
Compliance
Variáveis de ambiente
Tempo médio de resposta
Requisitos não funcionais
Relacionado

Cap de SLA por protocolo clínico (AVC/Trauma) — API

Configura, por tenant e por unidade, um prazo mais curto para exames marcados com os protocolos clínicos AVC (STROKE) e Trauma (TRAUMA), que pode apertar o prazo já calculado pela política de prioridade e modalidade e, opcionalmente, disparar um achado crítico no exame. Esta página cobre só o cadastro do cap; a aplicação do cap num exame específico acontece no serviço interno ApplyDiagnosisSlaProtocolService (ver Motor de cálculo na visão geral do módulo), que não tem rota HTTP própria.

Funcionamento

Autentica e autoriza a permissão sla:read/sla:write/sla:delete no escopo do tenantId/unitId do path.
Confirma que o tenant está ativo (rotas de tenant) ou que a unidade está ativa e pertence a um tenant ativo (rotas de unidade). Não encontrado/inativo → 404.
Leitura (GET): tenant sem configuração própria devolve as duas regras (STROKE, TRAUMA) desabilitadas (source: SYSTEM). Unidade sem override próprio herda a configuração do tenant (source: TENANT, ou SYSTEM se o tenant também não tiver configurado).
Escrita (PUT): sempre substitui as duas regras de uma vez — não é possível configurar só AVC ou só Trauma. Confere a versão esperada do próprio escopo e, no caso de unidade, também a versão esperada do protocolo herdado do tenant.
Restaurar (DELETE, só unidade): remove o override completo da unidade; ela volta a herdar do tenant (ou do padrão do sistema, se o tenant também não tiver configuração).

Endpoints

Método	Rota	Descrição
GET	`/v1/tenants/:tenantId/sla-protocol-policy`	Lê a configuração de protocolo do tenant (ou os defaults desabilitados)
PUT	`/v1/tenants/:tenantId/sla-protocol-policy`	Substitui as regras `STROKE` e `TRAUMA` do tenant
GET	`/v1/units/:unitId/sla-protocol-policy`	Lê a configuração efetiva da unidade (própria, herdada do tenant, ou padrão)
PUT	`/v1/units/:unitId/sla-protocol-policy`	Substitui as regras `STROKE` e `TRAUMA` da unidade
DELETE	`/v1/units/:unitId/sla-protocol-policy`	Restaura a unidade para o valor herdado do tenant

Versão: v1

Swagger: Diagnosis — SLA policy · Rota (Dev): http://localhost:3000/v1/tenants/:tenantId/sla-protocol-policy

Lógica de decisão (autenticação, autorização, existência do escopo, validação e versão → desfechos):

Permissões

Rota	Guards	Permissão exigida	Escopo
`GET /tenants/:tenantId/sla-protocol-policy`	`JwtAuthenticationGuard`, `AuthorizationGuard`	`sla:read`	`tenant` (path `tenantId`)
`PUT /tenants/:tenantId/sla-protocol-policy`	idem	`sla:write`	`tenant` (path `tenantId`)
`GET /units/:unitId/sla-protocol-policy`	idem	`sla:read`	`unit` (path `unitId`)
`PUT /units/:unitId/sla-protocol-policy`	idem	`sla:write`	`unit` (path `unitId`)
`DELETE /units/:unitId/sla-protocol-policy`	idem	`sla:delete`	`unit` (path `unitId`)

Sem token → 401. Sem a permissão no escopo do path → 403.

Headers

Header	Obrigatório	Descrição
`Authorization`	Sim	`Bearer <token>`

Path parameters

Nome	Tipo	Obrigatório	Descrição
`tenantId`	uuid	Sim (rotas de tenant)	`ParseUUIDPipe` — formato inválido → `400`
`unitId`	uuid	Sim (rotas de unidade)	`ParseUUIDPipe` — formato inválido → `400`

Query parameters

DELETE /units/:unitId/sla-protocol-policy:

Nome	Tipo	Obrigatório	Default	Descrição
`expectedVersion`	integer ≥ 0	Sim	—	Versão do override de protocolo da unidade
`expectedTenantVersion`	integer ≥ 0	Sim	—	Versão do protocolo do tenant herdado

GET não recebe query parameters.

Body

ReplaceDiagnosisSlaProtocolPolicyRequest (tenant) / ReplaceDiagnosisUnitSlaProtocolPolicyRequest (unidade, estende o de tenant):

json
{
  "expectedVersion": 0,
  "expectedTenantVersion": 2,
  "rules": [
    { "protocol": "STROKE", "enabled": true, "slaMinutes": 30, "startsCriticalFinding": true },
    { "protocol": "TRAUMA", "enabled": true, "slaMinutes": 45, "startsCriticalFinding": false }
  ]
}

expectedTenantVersion só existe no corpo das rotas de unidade.

Campo	Tipo	Obrigatório	Validação
`expectedVersion`	integer	Sim	`@IsInt` `@Min(0)`; deve ser igual à versão atual do escopo, senão `409`
`expectedTenantVersion`	integer	Sim (só unidade)	`@IsInt` `@Min(0)`; deve ser igual à versão atual do tenant herdado, senão `409`
`rules`	array	Sim	precisa ter exatamente uma regra `STROKE` e uma `TRAUMA`, sem repetir e sem outro protocolo — senão `422 SLA_PROTOCOL_POLICY_INVALID`
`rules[].protocol`	enum `DiagnosisSlaProtocol`	Sim	`STROKE` ou `TRAUMA`
`rules[].enabled`	boolean	Sim	—
`rules[].slaMinutes`	integer \| `null`	Condicional	obrigatório (`1`–`59999`) quando `enabled: true`; pode ser `null` quando `enabled: false`
`rules[].startsCriticalFinding`	boolean	Sim	só tem efeito quando `enabled: true` (ver RN-04)

Response

200 — DiagnosisTenantSlaProtocolPolicyEnvelopeRestResponse (rotas de tenant):

json
{
  "data": {
    "configured": true,
    "source": "TENANT",
    "tenantId": "8f2a...-uuid",
    "version": 3,
    "rules": [
      { "protocol": "STROKE", "enabled": true, "slaMinutes": 30, "startsCriticalFinding": true },
      { "protocol": "TRAUMA", "enabled": true, "slaMinutes": 45, "startsCriticalFinding": false }
    ]
  }
}

200 — DiagnosisUnitSlaProtocolPolicyEnvelopeRestResponse (rotas de unidade):

json
{
  "data": {
    "configured": false,
    "source": "TENANT",
    "tenantId": "8f2a...-uuid",
    "tenantVersion": 3,
    "unitId": "b7a1...-uuid",
    "version": 0,
    "rules": [
      { "protocol": "STROKE", "enabled": true, "slaMinutes": 30, "startsCriticalFinding": true },
      { "protocol": "TRAUMA", "enabled": true, "slaMinutes": 45, "startsCriticalFinding": false }
    ]
  }
}

Campo	Tipo	Descrição
`configured`	boolean	Tenant: `true` se `version > 0`. Unidade: `true` só se a unidade tem override próprio (mesmo que o tenant esteja configurado)
`source`	enum `DiagnosisSlaRuleSource`	De onde veio a configuração efetiva: `SYSTEM`, `TENANT` ou `UNIT`
`version`	integer	Versão do escopo consultado (tenant, ou da unidade — `0` se não tiver override próprio)
`tenantVersion`	integer	(só resposta de unidade) versão atual do protocolo do tenant herdado
`rules[]`	array de 2	Sempre as duas regras, `STROKE` e `TRAUMA`, nesta ordem

Erros

Classe de erro	errorCode	Status	Quando ocorre
(validação de payload)	`BAD_REQUEST`	400	corpo ou path (`uuid`) inválidos
`ScopedResourceNotFoundError`	—	404	tenant/unidade inexistente, inativo ou fora do escopo autorizado
`DiagnosisSlaProtocolPolicyOverrideNotFoundError`	`SLA_PROTOCOL_POLICY_OVERRIDE_NOT_FOUND`	404	`DELETE` sem override de protocolo próprio na unidade
`DiagnosisSlaPolicyVersionConflictError`	`SLA_POLICY_VERSION_CONFLICT`	409	`expectedVersion` do próprio escopo divergente da versão atual
`DiagnosisSlaTenantVersionConflictError`	`SLA_TENANT_VERSION_CONFLICT`	409	(rotas de unidade) `expectedTenantVersion` divergente da versão atual do tenant
`DiagnosisSlaProtocolPolicyInvalidError`	`SLA_PROTOCOL_POLICY_INVALID`	422	`rules` não tem exatamente `STROKE` + `TRAUMA`, protocolo fora do enum, flag não booleana, ou duração ausente/fora de `1..59999` com `enabled: true`

Regras de negócio

ID	Regra	Comportamento esperado
RN-01	Só existem dois protocolos suportados	`STROKE` (AVC) e `TRAUMA` — qualquer `PUT` precisa enviar exatamente os dois, uma vez cada
RN-02	Escrita sempre substitui as duas regras juntas	não é possível atualizar só uma das duas
RN-03	Protocolo habilitado exige duração válida	`enabled: true` sem `slaMinutes` (ou fora de `1..59999`) → `422`
RN-04	`startsCriticalFindingWhenApplied` só é `true` quando `enabled: true`	flag existe mas não tem efeito com o protocolo desabilitado
RN-05	Herança: unidade → tenant → padrão do sistema	unidade sem override usa o do tenant; tenant sem configuração (`version = 0`) usa o padrão (as duas regras desabilitadas)
RN-06	Restaurar exige a versão do tenant conferida primeiro	mesmo removendo só o override da unidade, uma divergência na versão do tenant herdado bloqueia com `409 SLA_TENANT_VERSION_CONFLICT` antes de checar a versão da própria unidade
RN-07	O cap nunca aumenta o prazo já calculado (aplicado no motor interno)	ver Motor de cálculo — não é uma regra desta rota, mas do consumo do valor cadastrado aqui
RN-08	Toda escrita audita antes/depois com ator, IP e versão resultante	eventos `diagnosis.sla-policy.tenant-protocol-replaced`, `unit-protocol-replaced` e `unit-protocol-restored`

Divergência confirmada com a especificação de legado. A especificação de legado (BR-SLA-057) limitava o prazo do protocolo habilitado a no máximo 59 minutos. O código atual usa o mesmo limite das regras normais de SLA (1 a 59.999 minutos) — não há teto de 59 minutos nesta validação. Ver nota na visão geral do módulo.

Compliance

A confirmar — responsável: time de Compliance/Diagnosis; data: 24/09/2026. O card de legado F-003 registra parecer de compliance sobre a feature de produto (LGPD, HIPAA e ANVISA, todos com observações sobre trilha de auditoria do achado crítico e change control) — não foi possível confirmar no código atual se essas exigências (ex.: trilha append-only do achado crítico) estão implementadas neste contrato reescrito, além do registro de auditoria confirmado em Regras de negócio (RN-08). A marcação efetiva de achado crítico acontece no motor de cálculo interno (ApplyDiagnosisSlaProtocolService), não nesta rota.

Variáveis de ambiente

Nenhuma variável de ambiente específica desta política. O limite de duração (1–59999 minutos) e a exigência de exatamente dois protocolos são constantes no código.

Tempo médio de resposta

A confirmar — responsável: time de Diagnosis; data: 24/09/2026. Não há medição publicada; não foi executado neste levantamento.

Requisitos não funcionais

Requisito	Definição
Idempotência	`PUT` é idempotente para o mesmo `expectedVersion` + mesmo corpo (repetir após sucesso muda a versão e falha com `409`)
Paginação	Não se aplica — sempre as duas regras
Rate limit	Não confirmado neste levantamento — não há decorator de throttling neste controller
Cache	Não
Auditoria	Sim — ver tabela de eventos na visão geral do módulo

Relacionado

📂 Módulo: SLA
🔙 Base do prazo: Política de SLA por prioridade e modalidade

Funcionamento​

Endpoints​

Permissões​

Headers​

Path parameters​

Query parameters​

Body​

Response​

Erros​

Regras de negócio​

Compliance​

Variáveis de ambiente​

Tempo médio de resposta​

Requisitos não funcionais​

Relacionado​