Ler, substituir e remover a busca padrão pessoal — API

A busca padrão é a configuração (colunas visíveis, ordenação, filtros, tamanho de página e algumas preferências de apresentação) que o Portal aplica automaticamente quando o usuário abre a worklist de exames, sem precisar reaplicar filtros a cada sessão. É um recurso único por usuário — existe no máximo um registro por ator autenticado.

Funcionamento

1. Valida o token e a permissão EXAM_READ, sempre com escopo current-user.
2. GET: devolve a busca padrão do usuário, ou data: null se ele nunca salvou uma.
3. PUT: substitui integralmente a busca padrão do usuário (não existe PATCH aqui — é sempre um "full replace"; se não existir ainda, cria). Valida columns (lista fechada de colunas), no máximo um critério de sort, os filters (mesmo modelo dos favoritos — DiagnosisSavedWorklistFilterRequest), openPriorExams e pageSize (1–100).
4. DELETE: remove (soft delete) a busca padrão do usuário; se ele não tinha nenhuma, a operação é um no-op silencioso (204 de qualquer forma).
5. Toda substituição e remoção grava um evento de auditoria com o estado anterior/novo.

Achado no código. showFavoriteBar (mostrar ou não a barra de favoritos na tela de Exames) está definido no modelo (DiagnosisWorklistDefaultSearchSettings) e no toSettings() do DTO, mas o campo showFavoriteBar em ReplaceDiagnosisWorklistDefaultSearchRequest (replace-diagnosis-worklist-default-search.request.ts:71) não tem nenhum decorator de class-validator. Como o ValidationPipe global usa whitelist: true, qualquer propriedade sem decorator é removida do corpo antes de chegar ao controller — na prática, hoje não há como o cliente enviar showFavoriteBar: true por esta rota; o valor persistido é sempre false, independentemente do que for enviado. Vale confirmar com o time de Diagnosis se isso é uma lacuna pendente ou um decorator esquecido.

Endpoints

Método	Rota	Descrição
GET	/v1/worklist-preferences/default-search	Lê a busca padrão do usuário autenticado
PUT	/v1/worklist-preferences/default-search	Cria ou substitui integralmente a busca padrão
DELETE	/v1/worklist-preferences/default-search	Remove a busca padrão do usuário

Versão: v1

Swagger: GET /worklist-preferences/default-search · Rota (Dev): http://localhost:3000/v1/worklist-preferences/default-search

Permissões

Rota	Guards	Permissão	Escopo
GET/PUT/DELETE /default-search	JwtAuthenticationGuard, AuthorizationGuard	EXAM_READ (any)	current-user

Não há identificador de recurso no path: o escopo current-user já resolve para o registro do próprio ator, então não existe o conceito de acessar a busca padrão de outra pessoa por esta rota.

Headers

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

Path parameters

Nenhum.

Query parameters

Nenhum.

Body

PUT /default-search — ReplaceDiagnosisWorklistDefaultSearchRequest:

json
{
  "columns": ["patientName", "status", "priority", "transferredAt"],
  "sort": [{ "field": "transferredAt", "direction": "DESC" }],
  "filters": { "statuses": ["TO_PREPARE"] },
  "openPriorExams": false,
  "pageSize": 20,
  "maskIntegrationSharingBlocked": false,
  "showFavoriteBar": true
}

Campo	Tipo	Obrigatório	Validação
columns	string[]	Sim	cada item deve estar em accessionNumber, modality, patientCode, patientName, priority, slaExpirationDate, status, studyDescription, transferredAt
sort	array	Sim	no máximo 1 item; cada item { field, direction } com field em createdAt, performedAt, slaExpirationDate, transferredAt e direction em ASC/DESC
filters	objeto	Sim	mesmo mapa de campos de favoritos de busca
openPriorExams	boolean	Sim	—
pageSize	int	Sim	1–100
maskIntegrationSharingBlocked	boolean	Não	default false quando omitido
showFavoriteBar	boolean	Não (e hoje sem efeito prático — ver achado acima)	default false; valor enviado é descartado pelo whitelist da validação antes de chegar ao serviço

Response

200 — GET /default-search ({ data: DiagnosisDefaultSearchResponse | null }):

json
{
  "data": {
    "id": "a1b2....",
    "userId": "8f2a....",
    "settings": {
      "columns": ["patientName", "priority", "status", "transferredAt"],
      "sort": [{ "field": "transferredAt", "direction": "DESC" }],
      "filters": { "statuses": ["TO_PREPARE"] },
      "openPriorExams": false,
      "pageSize": 20,
      "maskIntegrationSharingBlocked": false,
      "showFavoriteBar": false
    },
    "createdAt": "2026-09-01T12:00:00.000Z",
    "updatedAt": "2026-09-01T12:00:00.000Z"
  }
}

data é null quando o usuário nunca salvou uma busca padrão.

200 — PUT /default-search: mesmo formato de data acima, refletindo o que foi enviado.

204 — DELETE /default-search: sem corpo, mesmo quando não havia registro para remover.

Erros

Classe de erro	errorCode	Status	Quando ocorre
(guard)	UNAUTHENTICATED	401	token ausente, inválido ou expirado
(guard)	FORBIDDEN_ACTION	403	falta EXAM_READ
(validação)	BAD_REQUEST	400	columns fora da lista fechada, mais de um sort, pageSize fora de 1–100, corpo malformado
DiagnosisWorklistPreferenceInvalidError	INVALID_WORKLIST_PREFERENCE	400	sort/direction inválidos na reconstrução do modelo, filters com campo não suportado, intervalo de data invertido

Regras de negócio

ID	Regra	Comportamento esperado
RN-01	PUT é sempre substituição total	não existe merge parcial; um campo opcional omitido volta ao seu default (false), não ao valor anterior salvo
RN-02	No máximo uma coluna de ordenação	sort aceita 0 ou 1 item; nunca ordenação multi-coluna
RN-03	filters usa o mesmo modelo e as mesmas restrições dos favoritos	inclusive a normalização de interval: ALL → THIRTY_DAYS (ver favoritos de busca)
RN-04	DELETE sem registro existente não é erro	responde 204 mesmo que o usuário nunca tenha salvo uma busca padrão
RN-05	showFavoriteBar não é persistível hoje via PUT	ver achado no código acima; qualquer valor enviado é descartado antes da validação de negócio

Compliance

Não se aplica diretamente — mesma observação da página de favoritos de busca.

Variáveis de ambiente

Nenhuma encontrada para esta rota.

Tempo médio de resposta

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

Requisitos não funcionais

Requisito	Definição
Idempotência	Sim para PUT (mesmo corpo produz o mesmo estado) e para DELETE
Paginação	Não se aplica (recurso único por usuário)
Rate limit	Limite global padrão da API (ver visão geral)
Cache	Não
Auditoria	Sim — diagnosis.worklist.default-search-replaced/deleted, com snapshot antes/depois

Relacionado

• 🖥️ Tela: A confirmar — responsável: time de frontend; data: 24/09/2026.
• 📂 Módulo: Busca
• 🔎 Relacionado: Busca avançada de exames, Favoritos de busca