> ⚠️ **Aviso:**
Este documento tem caráter apenas de apoio e referência técnica.
As informações aqui descritas — incluindo entradas, saídas, estruturas de dados, fluxos e validações — não são definitivas e podem ser alteradas conforme evolução do entendimento do negócio, ajustes da arquitetura, revisões de API ou decisões de implementação.

### Design (alto nível) — RF2431 Conversão de data/hora de saída e listagem de Pré‑Atendimentos

#### Objetivo
Documentar a implementação da listagem de Pré‑Atendimentos neste projeto (arquitetura hexagonal):
- Listagem paginada com filtros por status (`REQUESTED`, `CREATED`, `UNDER_REVIEW`, `DONE`)
- Apresentação do nome e nome social do paciente
- Conversão de data/hora de saída considerando o fuso horário (RF2431) — pendente

#### Contexto de fuso horário (síntese do RF2431)
- Todos os datetime são armazenados no fuso "0" do sistema (base do servidor principal).
- Ao apresentar em outro fuso, converter aplicando: `dataArmazenada - fusoAplicado`.
- Ex.: base 0 (São Paulo) → Cuiabá (-1): `14:48:55 - (-1h) = 13:48:55`.
- Ex.: base 0 → Fernando de Noronha (+1): `14:48:55 - (+1h) = 15:48:55`.
- Conversão de entrada (RF2430) é outro requisito e fora deste escopo; aqui tratamos saída.

---

### Arquitetura hexagonal — visão

Portas e Adaptadores implementados:
- Domínio
- `PreAtendimento`: modelo principal do pré-atendimento.
- `PreAtendimentoPaginacao`: modelo para listagem paginada.
- `BeanParamListarPreAtendimentos`: parâmetros de filtro e paginação no domínio.
- `StatusEnum`: enum com valores `REQUESTED`, `CREATED`, `UNDER_REVIEW`, `DONE`.
- Portas de Aplicação (in)
- `ListarPreAtendimentosPaginacaoUseCase`: contrato para listar e contar pré-atendimentos com paginação e filtros.
- Serviços de Aplicação
- `ListarPreAtendimentosPaginacaoQueryService`: implementa `ListarPreAtendimentosPaginacaoUseCase`, orquestra busca via porta de saída.
- Portas de Saída (out)
- `PreAtendimentoPaginacaoPort`: contrato com métodos `listar()` e `contar()` retornando modelos de domínio.
- Adaptadores
- IN (REST): `PreAtendimentoResource` expõe endpoints `GET /requests` e `GET /requests/count`.
- OUT (DB): `PaginacaoPreAtendimentoDbAdapter` implementa `PreAtendimentoPaginacaoPort`.

---

### Fluxo (alto nível)
1. REST recebe `GET /requests` com parâmetros de paginação e filtro via `BeanParamListarPreAtendimentosDto`.
2. Resource chama `ListarPreAtendimentosPaginacaoUseCase.listar()` passando os parâmetros convertidos para domínio.
3. O serviço `ListarPreAtendimentosPaginacaoQueryService` delega para `PreAtendimentoPaginacaoPort.listar()`.
4. O adapter `PaginacaoPreAtendimentoDbAdapter` executa a consulta no banco e retorna lista de `PreAtendimentoPaginacao`.
5. O resultado é mapeado para `PreAtendimentoPaginacaoDto` e retornado ao cliente.
6. Para contagem, o fluxo é similar usando `GET /requests/count` e método `contar()`.

---

### REST (adapter in) — Padrão de Listagem e Contagem

Implementação atual do Resource com métodos `listar` e `contar`:

@PublicResource
@Path("/requests")
public class PreAtendimentoResource {

  @Inject
  ListarPreAtendimentosPaginacaoUseCase listarPreAtendimentosPaginacaoUseCase;

  @WithSpan
  @GET
  @APIResponse(
      responseCode = "200",
      description = "Lista de pré-atendimentos paginada.",
      content = @Content(
          mediaType = "application/json",
          schema = @Schema(implementation = PreAtendimentoPaginacaoDto.class)
      )
  )
  public List<PreAtendimentoPaginacaoDto> listar(
      @BeanParam BeanParamListarPreAtendimentosDto beanParamListarPreAtendimentosDto) {

    return listarPreAtendimentosPaginacaoUseCase.listar(
            beanParamListarPreAtendimentosDto.toDomain())
        .stream().map(PreAtendimentoPaginacaoDto::fromDomain).toList();
  }

  @WithSpan
  @GET
  @Path("/count")
  @APIResponse(
      responseCode = "200",
      description = "Contagem de pré-atendimentos.",
      content = @Content(
          mediaType = "application/json",
          schema = @Schema(implementation = CountPreAtendimentoDto.class)
      )
  )
  public CountPreAtendimentoDto contar(
      @BeanParam BeanParamListarPreAtendimentosDto beanParamListarPreAtendimentosDto) {
    Long count = listarPreAtendimentosPaginacaoUseCase
        .contar(beanParamListarPreAtendimentosDto.toDomain());

    return CountPreAtendimentoDto.builder().count(count).build();
  }
}

---

### BeanParams — Parâmetros de Paginação e Filtro

Implementação atual dos parâmetros de paginação e filtro:

@Builder
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
public class BeanParamListarPreAtendimentosDto {
  @QueryParam("pageStartIndex")
  @DefaultValue("0")
  private String pageIndex;

  @QueryParam("pageSize")
  @DefaultValue("15")
  private String pageSize;

  @QueryParam("search")
  private String search;

  @QueryParam("status")
  private List<StatusEnum> status;

  public BeanParamListarPreAtendimentos toDomain() {
    return BeanParamListarPreAtendimentos.builder()
        .pageIndex(this.pageIndex)
        .pageSize(this.pageSize)
        .search(this.search)
        .status(this.status)
        .build();
  }
}

#### Parâmetros de Query

| Parâmetro | Tipo | Padrão | Descrição |
|-----------|------|--------|-----------|
| `pageStartIndex` | String | `"0"` | Índice inicial da página |
| `pageSize` | String | `"15"` | Tamanho da página |
| `search` | String | - | Termo de busca |
| `status` | List\<StatusEnum\> | - | Filtro por status (valores: `REQUESTED`, `CREATED`, `UNDER_REVIEW`, `DONE`) |

---

### DTOs de Saída

#### PreAtendimentoPaginacaoDto (resposta do endpoint `listar`)

Implementação atual do DTO de saída para listagem:

@Value
@Builder
public class PreAtendimentoPaginacaoDto {
  @JsonProperty("id")
  String id;
  @JsonProperty("externalId")
  String idExterno;
  @JsonProperty("creationDate")
  LocalDateTime dataCriacao;
  @JsonProperty("status")
  String status;
  @JsonProperty("viewed")
  Boolean visualizado;
  @JsonProperty("name")
  String nome;
  @JsonProperty("socialName")
  String nomeSocial;
  @JsonProperty("code")
  String codigo;

  public static PreAtendimentoPaginacaoDto fromDomain(
      PreAtendimentoPaginacao domain) {
    return PreAtendimentoPaginacaoDto.builder()
        .id(domain.getId())
        .idExterno(domain.getIdExterno())
        .dataCriacao(domain.getDataCriacao())
        .status(domain.getStatus().name())
        .visualizado(domain.getVisualizado())
        .nome(domain.getNome())
        .nomeSocial(domain.getNomeSocial())
        .codigo(domain.getCodigo())
        .build();
  }
}

#### Campos de Resposta (listar)

| Campo JSON | Tipo | Descrição |
|------------|------|-----------|
| `id` | String | ID interno do pré-atendimento |
| `externalId` | String | ID externo do pré-atendimento |
| `creationDate` | LocalDateTime | Data de criação |
| `status` | String | Status atual (`REQUESTED`, `CREATED`, `UNDER_REVIEW`, `DONE`) |
| `viewed` | Boolean | Indica se foi visualizado |
| `name` | String | Nome do paciente |
| `socialName` | String | Nome social do paciente |
| `code` | String | Código do pré-atendimento |

#### CountPreAtendimentoDto (resposta do endpoint `contar`)

@Value
@Builder
public class CountPreAtendimentoDto {
  Long count;
}

| Campo JSON | Tipo | Descrição |
|------------|------|-----------|
| `count` | Long | Total de pré-atendimentos que correspondem aos filtros |

---

### Regras de nome (RF1366/RU2642) — Requisito pendente
- A API retorna os campos `name` (nome) e `socialName` (nome social) para o frontend aplicar a lógica de exibição.
- Regra de exibição (responsabilidade do frontend):
- Se `socialName` não estiver vazio: exibir nome social como principal.
- Caso contrário: exibir nome civil.

---

### Persistência e filtro (status)
- Valores disponíveis de `StatusEnum`: `REQUESTED`, `CREATED`, `UNDER_REVIEW`, `DONE`.
- O filtro por status é passado via query parameter `status` (aceita múltiplos valores).
- Adapter DB (`PaginacaoPreAtendimentoDbAdapter`) implementa consulta com filtros e mapeia para o domínio.

---

### Estratégia de conversão (RF2431) — Pendente
- Não implementado ainda.
- Planejado: `DateTimeConversionService` que receba `ZonedDateTime` em base 0 (UTC do sistema) e aplique conversão de fuso.

---

### Backlog técnico

#### Implementado
- [x] `BeanParamListarPreAtendimentosDto` com parâmetros de paginação e filtro.
- [x] `PreAtendimentoPaginacaoDto` e `CountPreAtendimentoDto` para respostas.
- [x] `PreAtendimentoResource` com métodos `listar` e `contar`.
- [x] `ListarPreAtendimentosPaginacaoUseCase` (porta de entrada).
- [x] `ListarPreAtendimentosPaginacaoQueryService` (serviço de aplicação).
- [x] `PreAtendimentoPaginacaoPort` (porta de saída).
- [x] `PaginacaoPreAtendimentoDbAdapter` (adapter de banco).
- [x] Mapeamento para `PreAtendimentoPaginacaoDto` (data criação, nome, nome social, código, status, visualizado).