# Dados e contrato de ligação para a equipa de TI

## Natureza deste documento

Este é um contrato de referência para adaptar a interface ao sistema existente. Os nomes de campos, rotas e valores de erro são sugestões. Não existe API implementada neste pacote e não é necessário criar uma nova base de dados se o sistema atual já tiver as entidades equivalentes.

## Entidades necessárias à interface

| Entidade              | Informação utilizada                                                        | Origem operacional                        |
| --------------------- | --------------------------------------------------------------------------- | ----------------------------------------- |
| Sessão do colaborador | ID do utilizador, nome apresentado, empresa, local e bloqueio               | Autenticação e permissões do sistema      |
| Empresa               | ID e nome, locais autorizados e eventual agrupamento                        | Cadastro corporativo                      |
| Local de entrega      | ID, nome, grupo CUF quando aplicável e disponibilidade                      | Cadastro de locais e catálogo da campanha |
| Instituição           | ID e nome                                                                   | Cadastro de instituições                  |
| Criança               | ID, nome apresentado, idade, género, instituição, pedido e disponibilidade  | Catálogo autorizado da campanha           |
| Apadrinhamento        | ID próprio, criança, padrinho, local, referência, prazo e estado de entrega | Reserva e acompanhamento persistidos      |
| Consentimento         | Utilizador, versão do texto e data do registo                               | Processo de consentimento do sistema      |

Um apadrinhamento precisa de um ID diferente do ID da criança. No protótipo, `child.id` também identifica a linha apadrinhada para simplificar os exemplos. Ao integrar, atualizar os handlers de nome e cancelamento para usar o ID do apadrinhamento.

## Correspondência com os objetos do protótipo

| Campo atual   | Significado                           | Adaptação recomendada                                              |
| ------------- | ------------------------------------- | ------------------------------------------------------------------ |
| `id`          | Identificador de exemplo, como `ana`  | ID persistido da criança                                           |
| `name`        | Nome apresentado no cartão            | Texto autorizado para apresentação ao colaborador                  |
| `age`         | Idade entre 0 e 17 nos filtros atuais | Idade fornecida pelo cadastro da campanha                          |
| `gender`      | `girl` ou `boy`                       | Mapear os códigos existentes para os rótulos e ícones da interface |
| `institution` | Nome em texto                         | ID para filtrar e nome para apresentar                             |
| `gift`        | Pedido do presente                    | Texto do catálogo                                                  |
| `reference`   | Código a colocar no presente          | Código emitido/persistido pelo sistema na reserva                  |
| `location`    | Nome de entrega em texto              | ID validado e nome apresentado                                     |
| `sponsor`     | Nome do padrinho                      | Campo editável segundo as permissões do sistema                    |
| `delivered`   | Booleano para o estado de entrega     | Mapear o estado administrativo real                                |
| `deadline`    | Texto de data em `data.js`            | Data da campanha/reserva, formatada em português na interface      |

O prazo e a referência devem acompanhar o registo real. Não usar um único prazo hardcoded se o sistema admitir campanhas ou locais com datas distintas.

## Exemplo de resposta do catálogo

Exemplo fictício de estrutura, sem representar uma rota existente:

```json
{
  "location": { "id": "local-exemplo", "name": "Local de demonstração" },
  "availableTotal": 4,
  "filteredTotal": 1,
  "page": 1,
  "pageSize": 4,
  "items": [
    {
      "id": "crianca-exemplo",
      "name": "CRIANÇA DE EXEMPLO",
      "age": 11,
      "gender": "girl",
      "institution": {
        "id": "instituicao-exemplo",
        "name": "Instituição de exemplo"
      },
      "gift": "Livros"
    }
  ]
}
```

`availableTotal` alimenta o contador de crianças por apadrinhar no local. `filteredTotal` alimenta a paginação depois dos filtros. Os nomes podem ser adaptados ao contrato já existente. A numeração de página deste exemplo começa em 1; a variável interna `filters.page` do protótipo começa em 0.

## Reserva e resposta de confirmação

A interface envia a identificação da criança selecionada. O servidor determina o colaborador pela sessão e valida empresa, local e disponibilidade. O servidor devolve o ID do apadrinhamento, a referência, o local, o prazo e o estado de envio da notificação.

Exemplo fictício:

```json
{
  "sponsorship": {
    "id": "apadrinhamento-exemplo",
    "childId": "crianca-exemplo",
    "reference": "CODIGO-DE-EXEMPLO",
    "location": { "id": "local-exemplo", "name": "Local de demonstração" },
    "deliveryDeadline": "2026-12-05",
    "sponsorName": "Padrinho de demonstração",
    "deliveryStatus": "pending"
  },
  "notification": { "emailStatus": "queued" }
}
```

`queued` indica uma notificação em fila, não um email enviado. A mensagem apresentada deve refletir o resultado real do serviço. Uma falha no envio depois da reserva não deve criar outro apadrinhamento ao repetir o pedido.

## Estados de interface a tratar na integração

| Situação                              | Resultado esperado na interface                                      |
| ------------------------------------- | -------------------------------------------------------------------- |
| Consulta a carregar                   | Indicação de carregamento sem apresentar uma lista antiga como atual |
| Sem resultados                        | Mensagem de ausência e possibilidade de limpar filtros               |
| Falha de consulta                     | Mensagem de erro e tentativa novamente                               |
| Sessão expirada                       | Regresso ao fluxo de autenticação, sem apresentar reserva confirmada |
| Local não autorizado                  | Mensagem e recarregamento dos locais permitidos                      |
| Local bloqueado                       | Aviso e manutenção do local já definido                              |
| Criança já reservada por outra pessoa | Atualizar lista/contadores e permitir outra escolha                  |
| Confirmação em curso                  | Impedir submissões simultâneas e aguardar o resultado                |
| Reserva confirmada                    | Acrescentar o afilhado e apresentar resumo emitido pelo servidor     |
| Alteração/cancelamento recusado       | Manter os dados anteriores e apresentar a razão disponível           |
| Email pendente ou com falha           | Manter o apadrinhamento válido e informar o estado da notificação    |

Carregamento, falhas de rede e conflitos de servidor são requisitos da integração futura. O protótipo local não simula todos esses estados. Os códigos de erro e os métodos de idempotência devem seguir o padrão da aplicação existente.

## Catálogo de locais

O protótipo contém os nomes em `data-location` e a disponibilidade desenhada no JPG. Para produção, o sistema deve fornecer os IDs e a disponibilidade atual. Manter a ordem de apresentação aprovada e os grupos CUF sempre visíveis. A associação real entre crianças, locais e instituições precisa de vir do cadastro da campanha.

## Decisões a confirmar pela organização

- Permissões e autenticação aplicáveis à variante Família José de Mello.
- Possibilidade de alterar o local depois de cancelar todos os apadrinhamentos. A versão local conserva o bloqueio.
- Validação final dos dados divergentes dos modelos e calendário da campanha.
- Operação responsável por assinalar o presente como entregue.
- Regra de notificação e texto a apresentar quando o email estiver pendente ou falhar.

Estas confirmações não impedem o recebimento do pacote visual pela equipa de TI.