# Guia de passagem para a equipa de TI

## Finalidade da entrega

Este pacote fornece os layouts e os comportamentos de interface da Árvore do Apadrinhamento para integração no sistema existente do Grupo José de Mello. A equipa de TI pode aproveitar os HTML diretamente ou convertê-los em templates/componentes da aplicação, preservando a apresentação e as regras funcionais fornecidas.

A entrega não define a linguagem do servidor, o framework, o motor de base de dados ou o fornecedor de alojamento. As rotas e os contratos sugeridos nesta documentação servem de referência de ligação e podem ser adaptados à arquitetura existente.

## Ordem de leitura e revisão

1. `README.md`: execução local e inventário geral.
2. `docs/apresentacao/Arvore-do-Apadrinhamento-Guia-TI.pdf`: explicação visual da entrega. O PPTX na mesma pasta é editável.
3. `apresentacao.html`: índice navegável dos layouts e estados de exemplo. Este HTML é um índice de revisão, não a apresentação de diapositivos.
4. `docs/MAPA-DOS-MODELOS.md`: correspondência com os JPG, recursos e divergências das fontes.
5. Este guia: módulos, dependências e pontos de substituição.
6. `docs/CONTRATOS-DE-DADOS.md`: campos e comportamentos esperados das respostas do sistema.
7. `docs/INTEGRACAO.md`: serviços necessários e rotas sugeridas.
8. `docs/CENARIOS-DE-ACEITACAO.md`: cenários para homologação da integração.
9. `docs/VALIDACAO.md`: limites e verificações locais já registadas.

Os JPG de referência e os Word de texto acompanham o pacote em `docs/referencias`. Os Illustrator permanecem na pasta original do projeto e não são dependência da implementação.

## Estrutura das páginas

O site funcional tem três páginas-base: login, empresa/local e escolhas. A landing pública é uma página adicional de scroll vertical. Os cinco HTML de empresa são variantes da mesma página-base, cada um com o conteúdo da respetiva empresa. Os modais e dropdowns permanecem sobre a página à qual pertencem.

| Entrada                  | Função                                         | Ligação ao sistema                                              |
| ------------------------ | ---------------------------------------------- | --------------------------------------------------------------- |
| `index.html`             | Landing e chamada para participar              | A ligação de login pode apontar para a rota existente           |
| `login.html`             | Formulário e consentimento                     | Substituir o acesso de demonstração pela autenticação existente |
| `empresa-jm.html`        | Local José de Mello                            | Validar empresa e locais autorizados no servidor                |
| `empresa-familia.html`   | Local Família José de Mello                    | Associar a identidade ao perfil autorizado pela organização     |
| `empresa-bondalti.html`  | Três locais Bondalti                           | Botões diretos, sem subescolhas                                 |
| `empresa-winestone.html` | Quatro locais WineStone                        | Botões diretos, sem subescolhas                                 |
| `empresa-cuf.html`       | Centros, clínicas, hospitais e contact centers | Listas sempre abertas, locais indisponíveis sem ação            |
| `escolhas.html`          | Filtros, crianças disponíveis e afilhados      | Substituir os registos e as mutações locais por serviços reais  |
| `apresentacao.html`      | Índice de revisão                              | Excluir da navegação pública da versão operacional              |

Os nomes dos HTML são nomes de entrega. A TI pode mapear essas entradas para as rotas do sistema sem ter de preservar a extensão `.html`.

## Camada visual

A ordem das folhas de estilo nos HTML é `base.css`, `pages.css`, `components.css`. As regras mais específicas são carregadas por último.

| Ficheiro                    | Responsabilidade                                                                                 |
| --------------------------- | ------------------------------------------------------------------------------------------------ |
| `assets/css/base.css`       | `@font-face`, variáveis de cor, largura central, tipografia, cabeçalho, contactos, rodapé e foco |
| `assets/css/pages.css`      | Landing, login, variantes de empresa e índice de revisão                                         |
| `assets/css/components.css` | Filtros, cartões, paginação, lista de afilhados e dialog                                         |
| `assets/images/`            | Fotografias fornecidas, convertidas para WebP                                                    |
| `assets/icons/`             | SVG fornecidos e recorte vetorial do logo de cabeçalho                                           |
| `assets/fonts/`             | Montserrat local e pesos fornecidos                                                              |

Os HTML não contêm blocos `<style>`, eventos `onclick` ou JavaScript inline. Os SVG originais podem conter estilos internos próprios do desenho, independentes das folhas de estilo da interface.

Preservar na integração: Montserrat, proporções dos logos, conteúdo central limitado, hover com 80% de opacidade, adaptação mobile, estados desativados, foco visível e comportamento dos modais. A TI pode reorganizar CSS em módulos se conservar o resultado visual.

## Ordem dos scripts e dependências

Cada HTML carrega os scripts com `defer` nesta ordem:

1. `assets/js/data.js` publica `window.ArvoresData` com exemplos.
2. `assets/js/common.js` publica `window.Arvores` com utilitários de modais e estado local.
3. O script da página executa depois dessas dependências.

| Script da página | HTML que o utiliza                                         |
| ---------------- | ---------------------------------------------------------- |
| `landing.js`     | `index.html`, sem lógica necessária além dos links nativos |
| `login.js`       | `login.html`                                               |
| `company.js`     | Todos os HTML `empresa-*.html`                             |
| `choices.js`     | `escolhas.html`                                            |
| `review.js`      | `apresentacao.html`                                        |

A TI pode substituir estes globais pelo mecanismo de módulos do sistema. Se mantiver os ficheiros como estão, deve conservar a ordem de carregamento. O código utiliza APIs de navegador como `dialog.showModal()`, `structuredClone`, `sessionStorage` e encadeamento opcional. A matriz de navegadores suportados deve ser confirmada pela equipa.

## Pontos de ligação no código atual

| Módulo e função/controlo                      | Comportamento atual                                         | Substituição na integração                                                          |
| --------------------------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `common.js`: `fresh()`, `save()` e `reset()`  | Estado fictício em `sessionStorage`, chave `arvore-demo:v1` | Sessão e dados emitidos pelo servidor. Remover a reposição de demonstração          |
| `common.js`: `modal()`, `close()`, `notice()` | Apresentação de modais, foco e fecho                        | Reutilizar a interface ou o componente modal do sistema                             |
| `login.js`: submit de `#login-form`           | Encaminha pelo domínio de um email fictício                 | Autenticação real. A autorização vem da sessão validada                             |
| `login.js`: `register()` e `okta()`           | Validação visual e aviso de falta de integração             | Fluxos reais de registo/recuperação e OKTA, quando aplicáveis                       |
| `company.js`: `[data-location]`               | Guarda o texto do local e navega para escolhas              | Enviar identificador do local, validar autorização e receber a sessão atualizada    |
| `choices.js`: `available()` e `matches()`     | Filtram quatro exemplos em memória                          | Consultar catálogo do local e aplicar os filtros no serviço ou na camada apropriada |
| `choices.js`: `renderChildren()`              | Desenha os cartões e contadores                             | Receber a lista, total disponível e total filtrado reais                            |
| `choices.js`: `confirmChild()`                | Acrescenta um afilhado localmente                           | Solicitar a reserva ao servidor e aguardar confirmação                              |
| `choices.js`: `renderSponsored()`             | Desenha as linhas de afilhados                              | Consultar os apadrinhamentos do utilizador autenticado                              |
| `choices.js`: `rename()` e `cancel()`         | Alteram o objeto local                                      | Persistir com autorização e tratar falhas sem apresentar sucesso antecipado         |
| `choices.js`: `thanks()`                      | Mostra resumo e nota de demonstração                        | Mostrar a referência devolvida pelo sistema e o estado real do email                |
| `choices.js`: parâmetro `estado`              | Abre exemplos de revisão                                    | Retirar os atalhos de demonstração da versão operacional                            |

As funções internas estão fechadas em IIFEs. São referências de localização para manutenção, não uma API pública já exportada. Para integrar por serviços, a TI pode extrair a camada de acesso a dados ou adaptar os pontos acima ao padrão existente.

## Seletores e atributos relevantes

| Referência                                 | Uso                                                 |
| ------------------------------------------ | --------------------------------------------------- |
| `body[data-page]`                          | Identifica o tipo de página                         |
| `body[data-company]`                       | Identifica a variante de empresa no protótipo       |
| `[data-location]`                          | Texto do local selecionável no protótipo            |
| `.location-group`, `.location-list`        | Estrutura da CUF sem controlo de recolher/expandir  |
| `.unavailable`                             | Texto de local sem disponibilidade                  |
| `#selected-location`                       | Nome do local na página de escolhas                 |
| `[data-gender]`, `#min-age`, `#max-age`    | Filtros de género e intervalo de idades             |
| `#institution-toggle`, `#institution-menu` | Dropdown e filtros de instituição                   |
| `#available-count`                         | Total disponível no local, antes de aplicar filtros |
| `#children-grid`, `#pagination`            | Resultados filtrados e intervalo da página          |
| `#sponsored-list`, `#sponsored-count`      | Lista e número de afilhados                         |
| `[data-sponsor]`, `[data-options]`         | Identificam a criança/linha acionada                |
| `#modal`, `#modal-content`, `#modal-title` | Dialog partilhado                                   |
| `[data-close]`                             | Botão de fecho registado por `modal()`              |

Os `data-*` e os nomes apresentados não devem conceder autorização. Na integração, usar IDs estáveis emitidos pelo servidor para empresa, local, instituição, criança e apadrinhamento.

## Regras que a integração deve preservar

- A CUF apresenta todos os grupos e locais de imediato. Não adicionar accordions aos cabeçalhos.
- As restantes empresas utilizam botões únicos sem subescolhas.
- Locais sem crianças disponíveis ficam a cinzento e não podem ser selecionados.
- A lista de crianças corresponde ao local escolhido e autorizado para o colaborador.
- O local fica bloqueado depois do primeiro apadrinhamento. O protótipo mantém esse bloqueio mesmo após cancelamento, conforme a interpretação registada da regra. A organização deve confirmar essa situação antes da homologação.
- Género, idade e instituições são filtros cumulativos. O contador do local e o total filtrado têm significados diferentes.
- O modal de confirmação utiliza a criança efetivamente selecionada e os dados atuais do servidor.
- O cancelamento e a mudança de nome aplicam-se apenas a apadrinhamentos autorizados. A interface atual não oferece cancelamento de um presente entregue.
- O estado de entrega pertence ao processo administrativo existente. Não existe um ecrã de administração nesta entrega.
- Um conflito de reserva deve atualizar a disponibilidade e permitir nova escolha. A interface só mostra sucesso depois de o servidor confirmar.

## Elementos exclusivamente demonstrativos

`data.js`, a chave `arvore-demo:v1`, o encaminhamento por domínio de email, as duas linhas iniciais CUF, as referências fictícias e os parâmetros de revisão não representam dados ou serviços de produção. O catálogo de quatro cartões é o mesmo em todos os locais apenas para revisão visual. O logout local altera um marcador e navega para login, sem invalidar uma sessão real.

A chave contém empresa, local, bloqueio, lista de afilhados e listas auxiliares de demonstração (`returned`, `removed`, `seeded`). `loggedIn` é outro marcador local usado pelo fluxo. Nenhum desses valores prova identidade ou permissão. A TI deve retirar a origem local dos dados ao integrar.

## Sequência de integração sugerida

1. Importar os recursos e validar visualmente a adaptação às rotas/templates do sistema.
2. Ligar a sessão autenticada e carregar empresa e locais permitidos.
3. Ligar catálogo, filtros e paginação com dados reais de homologação.
4. Ligar reserva atómica, alteração de padrinho e cancelamento.
5. Ligar resumo, referência, email e estado administrativo de entrega.
6. Retirar os atalhos e dados de demonstração. Executar os cenários de aceitação.

A entrega dos layouts pode ser recebida pela TI desde já. O acesso à base de dados existente só será necessário na fase de integração conduzida pela própria equipa.